Skip to main content

Module Options

forRoot(Async)

The ClsModule.forRoot() method takes the following ClsModuleOptions:

  • middleware?:ClsMiddlewareOptions
    An object with additional options for the ClsMiddleware, see below.

  • guard?:ClsGuardOptions
    An object with additional options for the ClsGuard, see below.

  • interceptor?:ClsInterceptorOptions
    An object with additional options for the ClsInterceptor, see below.

  • global?:boolean** (default false)
    Whether to make the module global, so you do not have to import ClsModule.forFeature() in other modules.

  • proxyProviders?:Type[]
    Array of Proxy Providers that should be registered in the root module. Currently only accepts sync class Proxy providers, use ClsModule.forFeatureAsync() for more complex use-cases.

ClsModule.forRootAsync() is also available. You can supply the usual imports, inject and useFactory parameters as usual.

info

Please note: If you intend to use multiple enhancers at the same time (e.g. initialize the CLS context in a middleware and then set some additional CLS variables in an interceptor), be aware that the only the first one in the chain will set the Request ID.

forFeature(Async)

The ClsModule.forFeature() method can be used to register a Proxy Providers. The Sync method only accepts Class Proxy providers.

The ClsModule.forFeatureAsync() method accepts either ClsModuleProxyClassProviderOptions or ClsModuleProxyFactoryProviderOptions that both accept these options:

  • provide?:any
    Custom injection token to use for the provider. In case of a class provider, this parameter is optional, as the class reference passed to useClass will be used by default.

  • imports?any[]
    Optional list of imported modules that export the providers which are required for the provider.

  • extraProviders?:Provider[]
    Optional list of additional providers that should be available to the Proxy. Useful for passing configuration from a parent dynamic module.

The ClsModuleProxyClassProviderOptions interface further accepts:

  • useClass:Type
    The target class that will be used by this Proxy Provider. Make sure it is decorated with @InjectableProxy.

The ClsModuleProxyFactoryProviderOptions interface further accepts:

  • inject:any[]
    An array of injection tokens for providers used in the useFactory.

  • useFactory:(...args: any[]) => any
    Factory function that accepts an array of providers in the order of the according tokens in the inject array. Returns (or resolves with) an object (or a function) that will be used by this Proxy Provider.

  • type?:'function' | 'object'
    Whether the Proxy Provider should be a function or an object. Defaults to 'object'. See Caveats for more information.

  • strict?:boolean
    Whether to register this Proxy Provider in strict mode. Defaults to false.

Middleware & Enhancer options

All of the Cls{Middleware,Guard,Interceptor}Options take the following parameters (either in ClsModuleOptions or directly when instantiating them manually):

  • mount?:boolean (default false)
    Whether to automatically mount the middleware/guard/interceptor to every route (not applicable when instantiating them manually)

  • generateId?:boolean (default false)
    Whether to automatically generate a request ID. It will be available under the CLS_ID key.

  • idGenerator?:(req: Request) => string | Promise<string>
    idGenerator?:(ctx: ExecutionContext) => string | Promise<string>
    An optional function for generating the request ID. It takes the Request object (or the ExecutionContext in case of a Guard or Interceptor) as an argument and (synchronously or asynchronously) returns a string. The default implementation uses Math.random() to generate a string of 8 characters.

  • setup?:(cls: ClsService, req: Request) => void | Promise<void>;
    setup?:(cls: ClsService, ctx: ExecutionContext) => void | Promise<void>;
    Function that executes after the CLS context had been initialised. It can be used to put additional variables in the CLS context.

  • resolveProxyProviders?:boolean (default true)
    Whether to automatically resolve Proxy Providers in the enhancer (if any are registered).

  • initializePlugins?:boolean (default true)
    Whether to run the onClsInit hook for plugins as a part of the CLS context registration (runs before resolveProxyProviders just after setup).

The ClsMiddlewareOptions additionally takes the following parameters:

  • saveReq?:boolean (default true)
    Whether to store the Request object to the context. It will be available under the CLS_REQ key.

  • saveRes?:boolean (default false)
    Whether to store the Response object to the context. It will be available under the CLS_RES key

  • useEnterWith?:boolean (default false)
    Set to true to set up the context using a call to AsyncLocalStorage#enterWith instead of wrapping the next() call with the safer AsyncLocalStorage#run. Most of the time this should not be necessary, but some frameworks are known to lose the context with run.