nestjs-cls

NestJS CLS (Async Context)

A continuation-local storage module compatible with NestJS' dependency injection based on AsyncLocalStorage.

Notice: The documentation has been moved to a dedicated website.

Continuation-local storage allows to store state and propagate it throughout callbacks and promise chains. It allows storing data throughout the lifetime of a web request or any other asynchronous duration. It is similar to thread-local storage in other languages.

Some common use cases that this library enables include:

• Tracking the Request ID and other metadata for logging purposes
• Keeping track of the user throughout the whole request
• Making the dynamic Tenant database connection available everywhere in multi-tenant apps
• Propagating the authentication level or role to restrict access to resources
• Seamlessly propagating database transaction across services without breaking encapsulation and isolation by explicitly passing it around (Now available with the Transactional plugin)
• Using "request" context in cases where actual REQUEST-scoped providers are not supported (passport strategies, cron controllers, websocket gateways, queue consumers, ...)
  • Replace REQUEST-scoped providers with Proxy Providers.

Most of these are to some extent solvable using REQUEST-scoped providers or passing the context as a parameter, but these solutions are often clunky and come with a whole lot of other issues.

Documentation

➡️ Go to the documentation website 📖

Contributing

Contributing to a community project is always welcome, please see the Contributing guide :)

Similar packages

Other packages similar to nestjs-cls

cls-hooked

The 'cls-hooked' package provides a way to manage context-local storage using Node.js async_hooks. It is a lower-level library compared to 'nestjs-cls' and requires more manual setup, but it offers similar functionality for managing request-specific data.

async-local-storage

The 'async-local-storage' package is another library for managing context-local storage in Node.js applications. It provides a simple API for storing and retrieving data that is scoped to the current request, similar to 'nestjs-cls', but without the NestJS-specific integrations.

continuation-local-storage

The 'continuation-local-storage' package offers context-local storage using the continuation-local-storage API. It is an older library and has been largely replaced by 'cls-hooked', but it still provides similar functionality for managing request-specific data.