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.

  • plugins?: ClsPlugin[]
    Array of registered plugins, see Plugins.

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.

registerPlugins​

The registerPlugins static method accepts an array of plugins. see Plugins.

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)

  • debug?:boolean (default true)
    Enable logging of debug messages in the middleware/guard/interceptor.

  • 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 have been known to lose the context with run.

The Cls{Guard,Interceptor}Options additionally takes the following parameters:

  • saveCtx?:boolean (default true) Since v5.1.0
    Whether to store the ExecutionContext object to the context. It will be available under the CLS_CTX key.