diff --git a/dist/README.md b/dist/README.md index a5106af..94e8fed 100644 --- a/dist/README.md +++ b/dist/README.md @@ -1,224 +1,20 @@ -# NestLoggedDecorators +# NestJS Logging Decorators This package provides some decorations to make NestJS logging simpler. It only uses Logger provided by @nestjs/common package and some dependencies required for nestjs. -> NOTE: I wrote new wiki in github: [Github Wiki](https://github.com/Worplo/nestlogged/wiki) +## Installation -## How to use - -### Route Logging - -```ts -import { Controller, Get } from "@nestjs/common"; -import { LoggedRoute } from "nlogdec"; - -@Controller('whatever') -export class WhateverController { - constructor() {} - - @Get('/you/like') - @LoggedRoute('/you/like') // Add this! - public async whateverYouLikeImpl() { - return 'Whatever You Like'; - } -} +```sh +npm install nestlogged ``` -```md -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] HIT HTTP WhateverController//you/like (whateverYouLikeImpl) -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] RETURNED RESPONSE WhateverController//you/like (whateverYouLikeImpl) +or + +```sh +yarn add nestlogged ``` -It will automatically log the call and response. +## More Info -If function throws any exception, it will also catch exception, log that, and throw it again. - -```ts -import { BadRequestException, Controller, Get } from "@nestjs/common"; -import { LoggedRoute } from "nlogdec"; - -@Controller('whatever') -export class WhateverController { - constructor() {} - - @Get('/you/like') - @LoggedRoute() - public async whateverYouLikeImpl() { - throw new BadRequestException("I don't like this") // Throwing HTTP exception here - } -} -``` - -```md -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] HIT HTTP WhateverController//you/like (whateverYouLikeImpl) -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] WHILE HTTP WhateverController//you/like (whateverYouLikeImpl) ERROR BadRequestException: I don't like this -``` - -Not only HTTP exception, it will also catch all exceptions and log it. - -If you want to provide another route instead of path you provided to method decorators like Get, Post, you can give a string to LoggedRoute decorator to replace it. - -```ts -import { BadRequestException, Controller, Get } from "@nestjs/common"; -import { LoggedRoute } from "nlogdec"; - -@Controller('whatever') -export class WhateverController { - constructor() {} - - @Get('/you/like') - @LoggedRoute('you/like') - public async whateverYouLikeImpl() { - throw new BadRequestException("I don't like this") // Throwing HTTP exception here - } -} -``` - -```md -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] HIT HTTP WhateverController/you/like (whateverYouLikeImpl) -[Nest] 000000 - 00/00/0000, 00:00:00 AM LOG [WhateverController] WHILE HTTP WhateverController/you/like (whateverYouLikeImpl) ERROR BadRequestException: I don't like this -``` - -You feel the change? - -Logged path is slightly changed from `WhateverController//you/like` to `WhateverController/you/like`. - -### Function Logging - -```ts -import { LoggedFunction } from "nlogdec"; - -@LoggedFunction // This decorator will do the magic for you -export async function doILikeThis(stuff: "apple" | "banana"): "yes" | "no" { - return stuff === "apple" ? "yes" : "no" -} -``` - -LoggedFunction decorator will log function calls and returns for you. - -> Note: This decorator is expected to be used with a class method. You can't use this outside of class - -Like `LoggedRoute` decorator, it will automatically catch all exceptions, log it, and throw it again. - -### Parameter Logging - -```ts -import { LoggedParam, LoggedFunction } from "nlogdec"; - -@LoggedFunction -export async function doILikeThis( - @LoggedParam("stuff") // It will add logs for parameter - stuff: "apple" | "banana" -): "yes" | "no" { - return stuff === "apple" ? "yes" : "no" -} - -doILikeThis("apple") -``` - -```md -HIT HTTP WhateverController//you/like (whateverYouLikeImpl) WITH stuff="apple" -``` - -It will add `WITH {param}={value}, {param2}={value2}` in log. -The name of parameter is decided by the first parameter of LoggedParam decorator. - -This decorator also can be used with `LoggedRoute`. - -### Class Logging - -You can make all method in injectable classes to logged function. - -```ts -import { LoggedInjectable } from "nlogdec"; - -@LoggedInjectable() -export class InjectableService { - constructor() {} - - public async getHello(@LoggedParam('name') name: string = 'world'): Promise { - return `Hello, ${name}!`; - } -} -``` - -It will make all methods to logged function, so it internally uses LoggedFunction decorator. - -You can do same thing with controller. - -```ts -import { Get, Query } from "@nestjs/common"; -import { LoggedController } from "nlogdec"; - -@LoggedController('path') -export class Controller { - constructor(private injectableService: InjectableService) {} - - @Get('/hello') - public async getHello(@LoggedParam('name') @Query() query: { name: string }): Promise { - return await this.injectableService.getHello(query.name); - } -} -``` - -It is exactly same using LoggedFunction and LoggedRoute, but it is much simpler because you don't have to write decorator to every method. - -But still, if you don't want to log every method, you can use LoggedFunction and LoggedRoute decorator. - -### Scoped Logging - -You can do scoped logging with `InjectLogger` decorator. - -Like tracebacks, it will add a scope and call stacks in log, so you can easily follow logs. - -```ts -import { - LoggedFunction, - LoggedParam, - InjectLogger, - ScopedLogger -} from "nlogdec"; - -@LoggedFunction -export async function doILikeThis( - @LoggedParam("stuff") stuff: string, - @InjectLogger logger: ScopedLogger // First of all, add this. - // Note: If this is planned to be called outside of controller route function, - // this can be optional. like: (@InjectLogger logger?: ScopedLogger) -): "yes" | "no" { - logger.log(`YAY we got ${stuff}`) - return stuff === "apple" ? "yes" : "no" -} -``` - -Then, in controller: - -```ts -import { BadRequestException, Controller, Get, Param } from "@nestjs/common"; -import { - LoggedRoute, - InjectLogger, - LoggedParam, - ScopedLogger -} from "./logged"; - -@Controller('you') -export class WhateverController { - constructor() { - } - - @Get('/like/:thing') - @LoggedRoute('/like/{thing}') - public async like( - @LoggedParam('thing') @Param('thing') thing: string, - @InjectLogger logger: ScopedLogger, - // When NestJS calls this function, decorator will automatically fills this logger parameter. - ) { - const likeThing = doILikeThis(thing, logger) === "yes" - if (!likeThing) throw BadRequestException("I don't like this") - } -} -``` - -The `@LoggedFunction` decorator that applied to `doILikeThis` function will intercept given logger, and make it scoped. +[Github Wiki](https://github.com/Worplo/nestlogged/wiki) diff --git a/dist/lib/functions.d.ts b/dist/lib/functions.d.ts index d48eee6..6e48a05 100644 --- a/dist/lib/functions.d.ts +++ b/dist/lib/functions.d.ts @@ -4,3 +4,4 @@ export default function objectContainedLogged(ocv: any, options?: { include?: string[]; exclude: string[]; }): Promise; +export declare function getItemByPath(obj: object, path: string | string[]): any; diff --git a/dist/lib/functions.js b/dist/lib/functions.js index ffa6768..2d5ab48 100644 --- a/dist/lib/functions.js +++ b/dist/lib/functions.js @@ -1,6 +1,6 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); -exports.includeOrExcludeObject = exports.notIncludedSymbol = void 0; +exports.getItemByPath = exports.includeOrExcludeObject = exports.notIncludedSymbol = void 0; exports.notIncludedSymbol = Symbol("notIncluded"); async function includeOrExcludeObject(ocv, paths, currentPath = [], include // or exclude ) { @@ -40,3 +40,12 @@ async function objectContainedLogged(ocv, options) { } } exports.default = objectContainedLogged; +async function getItemByPath(obj, path) { + const paths = Array.isArray(path) ? path : path.split("."); + return Object.keys(obj).includes(paths[0]) + ? typeof obj[paths[0]] === "object" + ? getItemByPath(obj[paths[0]], paths.slice(1)) + : obj[paths[0]] + : undefined; +} +exports.getItemByPath = getItemByPath; diff --git a/dist/lib/logged.d.ts b/dist/lib/logged.d.ts index 4ac125b..434484c 100644 --- a/dist/lib/logged.d.ts +++ b/dist/lib/logged.d.ts @@ -7,5 +7,5 @@ export declare function LoggedController(prefix: string | string[]): (target: an export declare function LoggedController(options: ControllerOptions & { verbose?: boolean; }): (target: any) => void; -export declare function LoggedFunction, R>(_target: any, key: string, descriptor: TypedPropertyDescriptor<(...args: F) => Promise>): void; -export declare function LoggedRoute, R>(route?: string): (_target: any, key: string, descriptor: TypedPropertyDescriptor<(...args: F) => Promise>) => void; +export declare function LoggedFunction, R>(_target: any, key: string, descriptor: TypedPropertyDescriptor<(...args: F) => Promise | R>): void; +export declare function LoggedRoute, R>(route?: string): (_target: any, key: string, descriptor: TypedPropertyDescriptor<(...args: F) => Promise | R>) => void; diff --git a/dist/lib/logged.js b/dist/lib/logged.js index 56fcccc..6df15b8 100644 --- a/dist/lib/logged.js +++ b/dist/lib/logged.js @@ -73,16 +73,16 @@ function LoggedController(param) { }; } exports.LoggedController = LoggedController; -function overrideBuild(originalFunction, baseLogger, metadatas, key, route) { +function overrideBuild(originalFunction, baseLogger, metadatas, key, returnsData, route) { return async function (...args) { let injectedLogger = baseLogger; if (typeof metadatas.scopedLoggerInjectableParam !== "undefined") { if (args.length <= metadatas.scopedLoggerInjectableParam || !(args[metadatas.scopedLoggerInjectableParam] instanceof logger_1.ScopedLogger)) { - args[metadatas.scopedLoggerInjectableParam] = new logger_1.ScopedLogger(baseLogger, key); + args[metadatas.scopedLoggerInjectableParam] = new logger_1.ScopedLogger(baseLogger, key, true); } else { - args[metadatas.scopedLoggerInjectableParam] = new logger_1.ScopedLogger(args[metadatas.scopedLoggerInjectableParam], key); + args[metadatas.scopedLoggerInjectableParam] = new logger_1.ScopedLogger(args[metadatas.scopedLoggerInjectableParam], key, false); } injectedLogger = args[metadatas.scopedLoggerInjectableParam]; if (Array.isArray(metadatas.scopeKeys)) { @@ -134,9 +134,24 @@ function overrideBuild(originalFunction, baseLogger, metadatas, key, route) { : ""}`); try { const r = await originalFunction.call(this, ...args); + const resultLogged = Array.isArray(returnsData) + ? typeof r === "object" + ? "WITH " + + (await Promise.all(returnsData.map(async ({ name, path }) => { + const value = await (0, functions_1.getItemByPath)(r, path); + return value !== undefined ? `${name}=${value}` : ""; + }))) + .filter((v) => v.length > 0) + .join(", ") + : "" + : returnsData + ? typeof r === "object" + ? "WITH " + JSON.stringify(r) + : "WITH " + r + : ""; injectedLogger.log(route - ? `RETURNED RESPONSE ${route.fullRoute} (${key})` - : `RETURNED ${key}`); + ? `RETURNED HTTP ${route.fullRoute} (${key}) ${resultLogged}` + : `RETURNED ${key} ${resultLogged}`); return r; } catch (e) { @@ -161,12 +176,13 @@ function LoggedFunction(_target, key, descriptor) { const loggedParams = Reflect.getOwnMetadata(reflected_2.loggedParam, _target, key); const scopeKeys = Reflect.getOwnMetadata(reflected_1.scopeKey, _target, key); const shouldScoped = Reflect.getOwnMetadata(reflected_1.forceScopeKey, fn); + const returnsData = Reflect.getOwnMetadata(reflected_1.returns, fn); const overrideFunction = overrideBuild(fn, logger, { scopedLoggerInjectableParam, loggedParams, scopeKeys, shouldScoped, - }, key); + }, key, returnsData); _target[key] = overrideFunction; descriptor.value = overrideFunction; all.forEach(([k, v]) => { @@ -195,12 +211,13 @@ function LoggedRoute(route) { const loggedParams = Reflect.getOwnMetadata(reflected_2.loggedParam, _target, key); const scopeKeys = Reflect.getOwnMetadata(reflected_1.scopeKey, _target, key); const shouldScoped = Reflect.getOwnMetadata(reflected_1.forceScopeKey, fn); + const returnsData = Reflect.getOwnMetadata(reflected_1.returns, fn); const overrideFunction = overrideBuild(fn, logger, { scopedLoggerInjectableParam, loggedParams, scopeKeys, shouldScoped, - }, key, { + }, key, returnsData, { fullRoute, }); _target[key] = overrideFunction; diff --git a/dist/lib/logger.d.ts b/dist/lib/logger.d.ts index 85bc481..9c1048d 100644 --- a/dist/lib/logger.d.ts +++ b/dist/lib/logger.d.ts @@ -2,8 +2,9 @@ import { Logger } from "@nestjs/common"; export declare class ScopedLogger extends Logger { private logger; private scope; - private scopeId?; - constructor(logger: Logger, scope: string, scopeId?: string); + private root; + scopeId?: string; + constructor(logger: Logger, scope: string, root?: boolean); addScope(scopeId: string): void; private scopedLog; debug: (message: string) => void; diff --git a/dist/lib/logger.js b/dist/lib/logger.js index f8db1eb..ae45aee 100644 --- a/dist/lib/logger.js +++ b/dist/lib/logger.js @@ -3,11 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true }); exports.ScopedLogger = void 0; const common_1 = require("@nestjs/common"); class ScopedLogger extends common_1.Logger { - constructor(logger, scope, scopeId) { + constructor(logger, scope, root = false) { super(); this.logger = logger; this.scope = scope; - this.scopeId = scopeId; + this.root = root; this.debug = this.scopedLog("debug"); this.log = this.scopedLog("log"); this.warn = this.scopedLog("warn"); @@ -20,7 +20,7 @@ class ScopedLogger extends common_1.Logger { } scopedLog(method) { return (message) => { - this.logger[method](`-> ${this.scope}${this.scopeId ? `(${this.scopeId})` : ""}: ${message}`); + this.logger[method](`${this.root ? "" : "-> "}${this.scope}${this.scopeId ? `(${this.scopeId})` : ""}: ${message}`); }; } } diff --git a/dist/lib/reflected.d.ts b/dist/lib/reflected.d.ts index 718c1d9..779a1a7 100644 --- a/dist/lib/reflected.d.ts +++ b/dist/lib/reflected.d.ts @@ -1,3 +1,9 @@ +export type Path = string | string[]; +export type Paths = Path[]; +export interface IncludeExcludePath { + includePath?: Paths; + excludePath?: Paths; +} export interface LoggedParamReflectData { name: string; index: number; @@ -10,17 +16,22 @@ export interface ScopeKeyReflectData { path?: string[]; priority?: number; } +export interface ReturnsReflectData { + name: string; + path: string; +} export declare const scopedLogger: unique symbol; export declare const loggedParam: unique symbol; export declare const scopeKey: unique symbol; export declare const forceScopeKey: unique symbol; +export declare const returns: unique symbol; export declare function InjectLogger(target: any, propertyKey: string | symbol, parameterIndex: number): void; -export declare function LoggedParam(name: string, options?: { - includePath?: (string | string[])[]; - excludePath?: (string | string[])[]; -}): (target: any, propertyKey: string | symbol, parameterIndex: number) => void; +export declare function LoggedParam(name: string, options?: IncludeExcludePath): (target: any, propertyKey: string | symbol, parameterIndex: number) => void; export declare function ScopeKey(name: string, options?: { - path?: string | string[]; + path?: Path; priority?: number; }): (target: any, propertyKey: string | symbol, parameterIndex: number) => void; +export declare function Returns, R>(namePaths?: { + [name: string]: string; +}): (_target: any, _key: string | symbol, descriptor: TypedPropertyDescriptor<(...args: F) => Promise>) => void; export declare function ShouldScoped(_target: any, _key: string, descriptor: TypedPropertyDescriptor<(...args: any[]) => Promise>): void; diff --git a/dist/lib/reflected.js b/dist/lib/reflected.js index 5104188..59601ff 100644 --- a/dist/lib/reflected.js +++ b/dist/lib/reflected.js @@ -1,10 +1,11 @@ "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); -exports.ShouldScoped = exports.ScopeKey = exports.LoggedParam = exports.InjectLogger = exports.forceScopeKey = exports.scopeKey = exports.loggedParam = exports.scopedLogger = void 0; +exports.ShouldScoped = exports.Returns = exports.ScopeKey = exports.LoggedParam = exports.InjectLogger = exports.returns = exports.forceScopeKey = exports.scopeKey = exports.loggedParam = exports.scopedLogger = void 0; exports.scopedLogger = Symbol("nlogdec-scopedLogger"); exports.loggedParam = Symbol("nlogdec-loggedParam"); exports.scopeKey = Symbol("nlogdec-scopeKey"); exports.forceScopeKey = Symbol("nlogdec-forceScopeKey"); +exports.returns = Symbol("nlogdec-returns"); function InjectLogger(target, propertyKey, parameterIndex) { Reflect.defineMetadata(exports.scopedLogger, parameterIndex, target, propertyKey); } @@ -43,6 +44,14 @@ function ScopeKey(name, options) { }; } exports.ScopeKey = ScopeKey; +function Returns(namePaths) { + return (_target, _key, descriptor) => { + Reflect.defineMetadata(exports.returns, namePaths + ? Object.entries(namePaths).reduce((prev, curr) => [...prev, { name: curr[0], path: curr[1] }], []) + : true, descriptor.value); + }; +} +exports.Returns = Returns; function ShouldScoped(_target, _key, descriptor) { Reflect.defineMetadata(exports.forceScopeKey, true, descriptor.value); }