DOCSEARCHbyAlgolia
Submit Docs

NestJS CLS

repository·main·Indexed 20 days ago

https://github.com/papooch/nestjs-cls

A continuation-local storage module for NestJS applications built on Node.js AsyncLocalStorage. It enables state propagation across asynchronous boundaries—such as web requests—without manual parameter passing. Key use cases include request ID logging, user context tracking, multi-tenancy, and database transaction management via the @nestjs-cls/transactional plugin, which provides adapters for TypeORM, Prisma, Mongoose, MongoDB, Kysely, Knex, pg-promise, and Drizzle ORM.

Tokens
52.4K
Snippets
146
Records
209
Agent score
68%

What's inside nestjs-cls

  1. Overview of NestJS CLS (Async Context)

    main

    NestJS CLS is a continuation-local storage module designed for NestJS applications. It is built on top of Node.js AsyncLocalStorage and allows you to store state and propagate it throughout callbacks, promise chains, and asynchronous durations (such as the lifetime of a web request). This is functionally similar to thread-local storage in other programming languages.

    Common use cases include:

    • Logging: Tracking Request IDs and other metadata.
    • User Context: Keeping track of the current user throughout a request.
    • Multi-tenancy: Making dynamic tenant database connections available globally.
    • Security: Propagating authentication levels or roles.
    • Database Transactions: Seamlessly propagating transactions across services using the Transactional plugin without manual parameter passing.
    • Context Access: Using request context in environments where standard NestJS REQUEST-scoped providers are not supported (e.g., Passport strategies, Cron controllers, WebSocket gateways, or Queue consumers).

  3. Use the MongoDB adapter for @nestjs-cls/transactional

    main
    The @nestjs-cls/transactional-adapter-mongodb package provides a MongoDB-specific implementation for the @nestjs-cls/transactional plugin. It allows you to manage MongoDB transactions using the CLS (Continuation Local Storage) pattern within a NestJS application, ensuring that database operations within a specific context are automatically wrapped in a transaction.

  4. Use the TypeORM adapter for @nestjs-cls/transactional

    main
    @nestjs-cls/transactional-adapter-typeorm is a specialized adapter designed to integrate TypeORM with the @nestjs-cls/transactional plugin. This allows you to manage database transactions automatically using Async Context (CLS), ensuring that all database operations within a specific execution context share the same transaction without manually passing transaction objects through your service layers.

  5. Use the pg-promise adapter for @nestjs-cls/transactional

    main
    The @nestjs-cls/transactional-adapter-pg-promise package provides a specialized adapter that allows the @nestjs-cls/transactional plugin to manage database transactions using the pg-promise library. This enables the use of the @Transactional() decorator to automatically handle transaction lifecycle (begin, commit, rollback) within a NestJS application using pg-promise.

  9. Use the Kysely adapter for @nestjs-cls/transactional

    main
    The @nestjs-cls/transactional-adapter-kysely package provides a Kysely-specific adapter for the @nestjs-cls/transactional plugin. This allows you to integrate Kysely transaction management with NestJS CLS-based transactional logic. For detailed configuration and implementation steps, refer to the official documentation website.

  10. Use the Drizzle ORM adapter for @nestjs-cls/transactional

    main

    The @nestjs-cls/transactional-adapter-drizzle-orm package provides an adapter that allows the @nestjs-cls/transactional plugin to manage database transactions using Drizzle ORM. This enables seamless transaction propagation across your NestJS application using Async Context.

    For detailed configuration and implementation steps, refer to the official documentation website.

  11. What is NestJS CLS?

    main

    NestJS CLS is a continuation-local storage module designed for NestJS applications. It is built on top of Node.js's native AsyncLocalStorage and allows you to store state and propagate it throughout callbacks and promise chains.

    This enables you to maintain data throughout the lifetime of an asynchronous duration (like a web request) without explicitly passing parameters through every function call. It is conceptually similar to thread-local storage in other programming languages.

  12. What is the CLS context and how does it work?

    main

    The CLS (Async Context) context is a storage mechanism that wraps around a chain of function calls. It allows you to store and retrieve data that is accessible anywhere during the lifecycle of that specific chain.

    In a NestJS HTTP application, ClsMiddleware initializes this context at the start of a request. Because the context is tied to the asynchronous execution chain, you can access request-specific data in any service or component without having to pass that data through every function argument or making your services request-scoped.