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.

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.

:::