Service Interface

ClsService

The injectable ClsService provides the following API to manipulate the cls context:

The S type parameter is used as the type of custom ClsStore.

• get(): S
  Get the entire CLS context.

• get(key?: keyof S): S[key]
  Retrieve a value from the CLS context by key.

• getId(): string;
  Retrieve the request ID (a shorthand for cls.get(CLS_ID))

• has(key: keyof S): boolean
  Check if a key is in the CLS context.

• set(key: keyof S, value: S[key]): void
  Set a value on the CLS context.

• setIfUndefined(key: keyof S, value: S[key]): void
  Set a value on the CLS context only if it hasn't been already set. Useful for ensuring idempotence if you have multiple entry points.

• run(callback: () => T): T
run(options: ClsContextOptions, callback: () => T): T;
  Run the callback in a shared CLS context. Optionally takes an options object as the first parameter.

• runWith(store: S, callback: () => T): T
  Run the callback in a new CLS context (while supplying the default store).

• enter(): void;
enter(options: ClsContextOptions): void
  Run any following code in a shared CLS context. Optionally takes an options object as the first parameter.

• enterWith(store: S): void
  Run any following code in a new CLS context (while supplying the default store).

• exit(callback: () => T): T
  Run the callback without access to a shared CLS context.

• isActive(): boolean
  Whether the current code runs within an active CLS context.

The following methods only apply to the Proxy feature:

• getProxy(proxyToken: any): any
  Retrieve a Proxy provider from the CLS context based on its injection token.

• setProxy(proxyToken: any, value? any): any
  Replace an instance of a Proxy provider in the CLS context based on its injection token.

• resolveProxyProviders(proxyTokens?: any[]): Promise<void>
  Manually trigger resolution of registered Proxy Providers. If an array of injection tokens is provided, resolves only those Proxy Providers.

The following methods involve the plugin lifecycle:

• initializePlugins(): Promise<void>
  Manually trigger onClsInit hooks of registered plugins.

ClsContextOptions

The run and enter methods can take an additional options object with the following settings:

• ifNested?:'inherit' | 'reuse' | 'override'
  Sets the behavior of nested CLS context creation in case the method is invoked in an existing context. It has no effect if no parent context exist.
  • inherit (default) - Run the callback with a shallow copy of the parent context.
    Re-assignments of top-level properties will not be reflected in the parent context. However, modifications of existing properties will be reflected.
  • reuse - Reuse existing context without creating a new one. All modifications to the existing context will be reflected.
  • override - Run the callback with an new empty context.
    No values from the parent context will be accessible within the wrapped code.

::: Note

Until v4, the default behavior was override. This was changed to inherit since v4 to make the behavior more intuitive.

:::