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 :)