Parameter Logging

NestLogged included some decorators to add parameter to function call log message.

• @Logged - basic parameter logging

• @LoggedParam - @Logged + NestJS's @Param

• @LoggedHeaders - @Logged + NestJS's @Headers

• @LoggedBody - @Logged + NestJS's @Body

• @LoggedQuery - @Logged + NestJS's @Query

Logged

Logged decorator is the logging decorator which will mostly be used in the service, that has general methods.

import { Injectable } from '@nestjs/common';
import { LoggedFunction, Logged } from 'nestlogged';

@Injectable()
export class CatsService {
    @LoggedFunction
    public async findCatByName(
        @Logged('name') name: string,
    ) {
        // ...
    }
}

/*
example: catsService.findCatByName('Baba')

... LOG [CatsService] CALL findCatByName WITH name=Baba
                                         ^^^^^^^^^^^^^^
                                           Parameter logging
... LOG [CatsService] RETURNED findCatByName
*/

Like above, Logged decorator adds parameter name and value in log printed at function call time.

Parameter without Logged decorator will not be included in the log.

Shared Parameters

All decorators in this page are based on the Logged decorator, it also share same parameters.

Therefore, Explaining parameters of Logged decorator will also explains all decorators' parameters.

Logged decorator's parameter is name(required) and options(optional) in order.

name

In TypeScript / JavaScript, decorator gets information about parameter when applying decorator to parameter.

But there is no parameter's name in the information that decorator got (because argument is transferred in form of array), so decorator cannot know what is the name of this parameter and how to print the name of the parameter.

Because of that, you should give parameter's name to decorator to set the name of parameter in log.

If we bring the example above and change the name of Logged to 'catName', the log will include WITH catName=Baba.

import { Injectable } from '@nestjs/common';
import { LoggedFunction, Logged } from 'nestlogged';

@Injectable()
export class CatsService {
    @LoggedFunction
    public async findCatByName(
        @Logged('catName') name: string,
    ) {
        // ...
    }
}

/*
example: catsService.findCatByName('Baba')

... LOG [CatsService] CALL findCatByName WITH catName=Baba
                                         ^^^^^^^^^^^^^^^^^
                                      Parameter's name is changed
... LOG [CatsService] RETURNED findCatByName
*/

options

If parameter with Logged decorator applied has value of object, NestLogged uses JSON.stringify to print inside of the object instead of printing [object Object].

But what if the object includes the value that has to be hidden? like, user's password or something..

Logged decorator solves this problem with include and exclude of options parameter.

Type of options is IncludeExcludePath interface, and that is defined like below.

type Path = string | string[];
type Paths = Path[];

interface IncludeExcludePath {
    includePath?: Paths;
    excludePath?: Paths;
}

const Logged = (name: string, options?: IncludeExcludePath) => ...

Now, there is a example below explaining how to use options well.

interface UserData {
    displayName: string;
    email: string;
    auth: {
        loginName: string;
        password: string;
    }
}

@Injectable()
export class AuthService {
    @LoggedFunction
    public async createNewUser(
        @Logged('newUserData', { excludePath: ['auth.password'] })
        newUserData: UserData,
    ) {
        // ...
    }
}
/*
... LOG [CatsService] CALL createNew WITH newUserData={"displayName":"testUser","email":"[e-mail]","auth":{"loginName":"testUser1234"}}
... LOG [CatsService] RETURNED createNew
*/

Also, you can provide path as string[] format, not dot path.

@Logged('newUserData', { excludePath: [['auth', 'password']] }) newUserData: UserData

Or you can include only displayName and email using includePath.

@Logged('newUserData', { includePath: ['displayName', 'email'] }) newUserData: UserData

name and options parameter will be act same as above regardless of any parameter logging decorator.

Logged + NestJS

LoggedParam, LoggedHeaders, LoggedBody, LoggedQuery decorators are result of merge of @Logged decorator and @Param, @Headers, @Body, @Query decorator provided by @nestjs/common package.

That means, using LoggedParam has the same result as using @Logged decorator and @Param decorator at the same single parameter.

But I thought the separated decorator cause the complex code, so I made a one decorator merged the two decorator.

If you want, you can still use separated @Logged and @Param decorator.

Merged decorator's usage is little bit weird, because it has to pass the two configuration.

type Pipe = Type<PipeTransform> | PipeTransform

// NestJS decorator type & usage
export function Query(): ParameterDecorator;
export function Query(
  ...pipes: Pipe[]
): ParameterDecorator;
export function Query(
  property: string,
  ...pipes: Pipe[]
): ParameterDecorator;
export function Query(
  property?: string | Pipe,
  ...pipes: Pipe[]
): ParameterDecorator;

// Logged + NestJS decorator type & usage
type LoggedType = (name: string, options?: IncludeExcludePath) => ParameterDecorator

export function LoggedQuery(): LoggedType;
export function LoggedQuery(
  ...pipes: Pipe[]
): LoggedType;
export function LoggedQuery(
  property: string,
  ...pipes: Pipe[]
): LoggedType;
export function LoggedQuery(
  property?: string | Pipe,
  ...pipes: Pipe[]
): LoggedType;

In short:

export function LoggedQuery(...nestjsDecoratorParams)(name: string, options?: IncludeExcludePath) => ParameterDecorator

Therefore, If you were bringing Query like @Query('id'), You can add log with two different ways.

@Logged('queryId')
@Query('id')
id: number,

// Or

@LoggedQuery('id')('queryId')
id: number