@nest-boot/request-context 7.4.1 → 7.4.3

package/dist/create-request-context.decorator.d.ts

@@ -1,4 +1,59 @@
 import { RequestContext } from "./request-context";
-type MethodArgs<T, M extends keyof T> = T[M] extends (...args: infer A) => any ? A : never;
+/**
+ * Helper type that extracts the argument types of a method.
+ */
+export type MethodArgs<T, M extends keyof T> = T[M] extends (...args: infer A) => any ? A : never;
+/**
+ * Method decorator that wraps the method execution in a new request context.
+ *
+ * This is useful for creating request contexts for background jobs, event handlers,
+ * or any other code that runs outside of HTTP request handling.
+ *
+ * @typeParam T - The class type containing the method
+ * @typeParam P - The property key of the method
+ * @param fn - A function that creates the RequestContext, receiving the class instance and method arguments
+ * @returns A method decorator
+ *
+ * @example Basic usage with a job processor
+ * ```typescript
+ * import { CreateRequestContext, RequestContext } from '@nest-boot/request-context';
+ *
+ * class JobProcessor {
+ *   @CreateRequestContext((instance, jobData) =>
+ *     new RequestContext({ type: 'job', id: jobData.id })
+ *   )
+ *   async processJob(jobData: { id: string; payload: any }) {
+ *     // This code runs within a request context
+ *     console.log(`Processing job ${RequestContext.id}`);
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @example With service injection
+ * ```typescript
+ * import { Injectable } from '@nestjs/common';
+ * import { CreateRequestContext, RequestContext } from '@nest-boot/request-context';
+ *
+ * @Injectable()
+ * class EventHandler {
+ *   @CreateRequestContext((instance, event) =>
+ *     new RequestContext({
+ *       type: 'event',
+ *       id: event.correlationId,
+ *     })
+ *   )
+ *   async handleEvent(event: { correlationId: string; data: any }) {
+ *     // Access context within the handler
+ *     RequestContext.set('eventType', event.data.type);
+ *     await this.processEvent(event);
+ *   }
+ *
+ *   private async processEvent(event: any) {
+ *     // Context is still available here
+ *     const eventType = RequestContext.get('eventType');
+ *   }
+ * }
+ * ```
+ */
 export declare function CreateRequestContext<T extends object, P extends keyof T>(fn: (instance: T, ...args: MethodArgs<T, P>) => RequestContext): (_target: T, _propertyKey: P, descriptor: PropertyDescriptor) => PropertyDescriptor;
-export {};

package/dist/create-request-context.decorator.js

@@ -2,6 +2,59 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateRequestContext = CreateRequestContext;
 const request_context_1 = require("./request-context");
+/**
+ * Method decorator that wraps the method execution in a new request context.
+ *
+ * This is useful for creating request contexts for background jobs, event handlers,
+ * or any other code that runs outside of HTTP request handling.
+ *
+ * @typeParam T - The class type containing the method
+ * @typeParam P - The property key of the method
+ * @param fn - A function that creates the RequestContext, receiving the class instance and method arguments
+ * @returns A method decorator
+ *
+ * @example Basic usage with a job processor
+ * ```typescript
+ * import { CreateRequestContext, RequestContext } from '@nest-boot/request-context';
+ *
+ * class JobProcessor {
+ *   @CreateRequestContext((instance, jobData) =>
+ *     new RequestContext({ type: 'job', id: jobData.id })
+ *   )
+ *   async processJob(jobData: { id: string; payload: any }) {
+ *     // This code runs within a request context
+ *     console.log(`Processing job ${RequestContext.id}`);
+ *     // ...
+ *   }
+ * }
+ * ```
+ *
+ * @example With service injection
+ * ```typescript
+ * import { Injectable } from '@nestjs/common';
+ * import { CreateRequestContext, RequestContext } from '@nest-boot/request-context';
+ *
+ * @Injectable()
+ * class EventHandler {
+ *   @CreateRequestContext((instance, event) =>
+ *     new RequestContext({
+ *       type: 'event',
+ *       id: event.correlationId,
+ *     })
+ *   )
+ *   async handleEvent(event: { correlationId: string; data: any }) {
+ *     // Access context within the handler
+ *     RequestContext.set('eventType', event.data.type);
+ *     await this.processEvent(event);
+ *   }
+ *
+ *   private async processEvent(event: any) {
+ *     // Context is still available here
+ *     const eventType = RequestContext.get('eventType');
+ *   }
+ * }
+ * ```
+ */
 function CreateRequestContext(fn) {
     return (_target, _propertyKey, descriptor) => {
         if (descriptor.value) {

package/dist/create-request-context.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-request-context.decorator.js","sourceRoot":"","sources":["../src/create-request-context.decorator.ts"],"names":[],"mappings":";;AAMA,oDAeC;AArBD,uDAAmD;AAMnD,SAAgB,oBAAoB,CAClC,EAA8D;IAE9D,OAAO,CAAC,OAAU,EAAE,YAAe,EAAE,UAA8B,EAAE,EAAE;QACrE,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;YAElC,UAAU,CAAC,KAAK,GAAG,UAAmB,GAAG,IAAsB;gBAC7D,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;gBAC9B,OAAO,gCAAc,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACnE,CAAC,CAAC;QACJ,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"create-request-context.decorator.js","sourceRoot":"","sources":["../src/create-request-context.decorator.ts"],"names":[],"mappings":";;AAgEA,oDAeC;AA/ED,uDAAmD;AAWnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,SAAgB,oBAAoB,CAClC,EAA8D;IAE9D,OAAO,CAAC,OAAU,EAAE,YAAe,EAAE,UAA8B,EAAE,EAAE;QACrE,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;YAElC,UAAU,CAAC,KAAK,GAAG,UAAmB,GAAG,IAAsB;gBAC7D,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;gBAC9B,OAAO,gCAAc,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACnE,CAAC,CAAC;QACJ,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/repl.d.ts

@@ -1,2 +1,44 @@
 import { DynamicModule, Type } from "@nestjs/common";
-export declare function repl(module: Type | DynamicModule): Promise<import("repl").REPLServer>;
+import type { REPLServer } from "repl";
+/**
+ * Starts a REPL (Read-Eval-Print Loop) session with request context support.
+ *
+ * This function creates a NestJS application context and starts an interactive
+ * REPL session where all commands run within a request context. This is useful
+ * for debugging and testing services that depend on request context.
+ *
+ * The REPL session:
+ * - Runs within a request context of type 'repl'
+ * - Has access to all NestJS providers
+ * - Maintains context across async operations
+ *
+ * @param module - The NestJS module (class or DynamicModule) to create the context from
+ * @returns A promise that resolves to the REPL server instance
+ *
+ * @example
+ * ```typescript
+ * // repl.ts
+ * import { repl } from '@nest-boot/request-context';
+ * import { AppModule } from './app.module';
+ *
+ * async function bootstrap() {
+ *   await repl(AppModule);
+ * }
+ *
+ * bootstrap();
+ * ```
+ *
+ * @example Running the REPL
+ * ```bash
+ * npx ts-node -r tsconfig-paths/register repl.ts
+ * ```
+ *
+ * @example Using services in REPL
+ * ```typescript
+ * // In the REPL session:
+ * > const userService = get(UserService)
+ * > await userService.findAll()
+ * > RequestContext.id  // Access current context ID
+ * ```
+ */
+export declare function repl(module: Type | DynamicModule): Promise<REPLServer>;

package/dist/repl.js

@@ -45,6 +45,47 @@ const repl_native_commands_1 = require("@nestjs/core/repl/repl-native-commands")
 const async_hooks_1 = require("async_hooks");
 const stream_1 = require("stream");
 const request_context_1 = require("./request-context");
+/**
+ * Starts a REPL (Read-Eval-Print Loop) session with request context support.
+ *
+ * This function creates a NestJS application context and starts an interactive
+ * REPL session where all commands run within a request context. This is useful
+ * for debugging and testing services that depend on request context.
+ *
+ * The REPL session:
+ * - Runs within a request context of type 'repl'
+ * - Has access to all NestJS providers
+ * - Maintains context across async operations
+ *
+ * @param module - The NestJS module (class or DynamicModule) to create the context from
+ * @returns A promise that resolves to the REPL server instance
+ *
+ * @example
+ * ```typescript
+ * // repl.ts
+ * import { repl } from '@nest-boot/request-context';
+ * import { AppModule } from './app.module';
+ *
+ * async function bootstrap() {
+ *   await repl(AppModule);
+ * }
+ *
+ * bootstrap();
+ * ```
+ *
+ * @example Running the REPL
+ * ```bash
+ * npx ts-node -r tsconfig-paths/register repl.ts
+ * ```
+ *
+ * @example Using services in REPL
+ * ```typescript
+ * // In the REPL session:
+ * > const userService = get(UserService)
+ * > await userService.findAll()
+ * > RequestContext.id  // Access current context ID
+ * ```
+ */
 async function repl(module) {
     const app = await core_1.NestFactory.createApplicationContext(module, {
         abortOnError: false,

package/dist/repl.js.map

@@ -1 +1 @@
-{"version":3,"file":"repl.js","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,oBA+CC;AA5DD,2CAA6D;AAC7D,0EAA2D;AAC3D,uCAA2C;AAC3C,mFAAyE;AACzE,2DAAuE;AACvE,iEAA6D;AAC7D,+DAA2D;AAC3D,iFAAqF;AACrF,6CAA4C;AAC5C,mCAAmC;AAEnC,uDAAmD;AAE5C,KAAK,UAAU,IAAI,CAAC,MAA4B;IACrD,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,wBAAwB,CAAC,MAAM,EAAE;QAC7D,YAAY,EAAE,KAAK;QACnB,MAAM,EAAE,IAAI,wBAAU,EAAE;KACzB,CAAC,CAAC;IAEH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAEjB,MAAM,WAAW,GAAG,IAAI,0BAAW,CAAC,GAAG,CAAC,CAAC;IACzC,eAAM,CAAC,GAAG,CAAC,oCAAwB,CAAC,CAAC;IAErC,OAAO,MAAM,gCAAc,CAAC,GAAG,CAC7B,IAAI,gCAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EACpC,KAAK,IAAI,EAAE;QACT,MAAM,aAAa,GAAG,IAAI,2BAAa,CAAC,MAAM,CAAC,CAAC;QAEhD,MAAM,UAAU,GAAG,CAAC,wDAAa,MAAM,GAAC,CAAC,CAAC,KAAK,CAAC;YAC9C,KAAK,EAAE,IAAI,KAAK,CACd,OAAO,CAAC,KAAK,CAAC,IAAI,CAChB,IAAI,kBAAS,CAAC;gBACZ,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ;oBACjC,aAAa,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC7D,CAAC;aACF,CAAC,CACH,EACD;gBACE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;oBACxB,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;wBACnB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;oBAC7C,CAAC;yBAAM,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;wBACjC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;oBACpD,CAAC;gBACH,CAAC;aACF,CACF;YACD,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,qBAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YACvB,eAAe,EAAE,IAAI;SACtB,CAAC,CAAC;QAEH,IAAA,sCAAc,EAAC,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;QAE5D,IAAA,kDAA2B,EAAC,UAAU,CAAC,CAAC;QAExC,OAAO,UAAU,CAAC;IACpB,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"repl.js","sourceRoot":"","sources":["../src/repl.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,oBA+CC;AAtGD,2CAA6D;AAC7D,0EAA2D;AAC3D,uCAA2C;AAC3C,mFAAyE;AACzE,2DAAuE;AACvE,iEAA6D;AAC7D,+DAA2D;AAC3D,iFAAqF;AACrF,6CAA4C;AAE5C,mCAAmC;AAEnC,uDAAmD;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACI,KAAK,UAAU,IAAI,CAAC,MAA4B;IACrD,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,wBAAwB,CAAC,MAAM,EAAE;QAC7D,YAAY,EAAE,KAAK;QACnB,MAAM,EAAE,IAAI,wBAAU,EAAE;KACzB,CAAC,CAAC;IAEH,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAEjB,MAAM,WAAW,GAAG,IAAI,0BAAW,CAAC,GAAG,CAAC,CAAC;IACzC,eAAM,CAAC,GAAG,CAAC,oCAAwB,CAAC,CAAC;IAErC,OAAO,MAAM,gCAAc,CAAC,GAAG,CAC7B,IAAI,gCAAc,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EACpC,KAAK,IAAI,EAAE;QACT,MAAM,aAAa,GAAG,IAAI,2BAAa,CAAC,MAAM,CAAC,CAAC;QAEhD,MAAM,UAAU,GAAG,CAAC,wDAAa,MAAM,GAAC,CAAC,CAAC,KAAK,CAAC;YAC9C,KAAK,EAAE,IAAI,KAAK,CACd,OAAO,CAAC,KAAK,CAAC,IAAI,CAChB,IAAI,kBAAS,CAAC;gBACZ,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ;oBACjC,aAAa,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC7D,CAAC;aACF,CAAC,CACH,EACD;gBACE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ;oBACxB,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;wBACnB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;oBAC7C,CAAC;yBAAM,IAAI,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;wBACjC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;oBACpD,CAAC;gBACH,CAAC;aACF,CACF;YACD,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,MAAM,EAAE,qBAAG,CAAC,KAAK,CAAC,IAAI,CAAC;YACvB,eAAe,EAAE,IAAI;SACtB,CAAC,CAAC;QAEH,IAAA,sCAAc,EAAC,UAAU,CAAC,OAAO,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;QAE5D,IAAA,kDAA2B,EAAC,UAAU,CAAC,CAAC;QAExC,OAAO,UAAU,CAAC;IACpB,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/request-context.constants.d.ts

@@ -1,2 +1,24 @@
+/**
+ * Token for storing the HTTP request object in the request context.
+ *
+ * @example
+ * ```typescript
+ * import { REQUEST } from '@nest-boot/request-context';
+ * import { Request } from 'express';
+ *
+ * const req = RequestContext.get<Request>(REQUEST);
+ * ```
+ */
 export declare const REQUEST = "REQUEST";
+/**
+ * Token for storing the HTTP response object in the request context.
+ *
+ * @example
+ * ```typescript
+ * import { RESPONSE } from '@nest-boot/request-context';
+ * import { Response } from 'express';
+ *
+ * const res = RequestContext.get<Response>(RESPONSE);
+ * ```
+ */
 export declare const RESPONSE = "RESPONSE";

package/dist/request-context.constants.js

@@ -1,6 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESPONSE = exports.REQUEST = void 0;
+/**
+ * Token for storing the HTTP request object in the request context.
+ *
+ * @example
+ * ```typescript
+ * import { REQUEST } from '@nest-boot/request-context';
+ * import { Request } from 'express';
+ *
+ * const req = RequestContext.get<Request>(REQUEST);
+ * ```
+ */
 exports.REQUEST = "REQUEST";
+/**
+ * Token for storing the HTTP response object in the request context.
+ *
+ * @example
+ * ```typescript
+ * import { RESPONSE } from '@nest-boot/request-context';
+ * import { Response } from 'express';
+ *
+ * const res = RequestContext.get<Response>(RESPONSE);
+ * ```
+ */
 exports.RESPONSE = "RESPONSE";
 //# sourceMappingURL=request-context.constants.js.map

package/dist/request-context.constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.constants.js","sourceRoot":"","sources":["../src/request-context.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,OAAO,GAAG,SAAS,CAAC;AACpB,QAAA,QAAQ,GAAG,UAAU,CAAC"}
+{"version":3,"file":"request-context.constants.js","sourceRoot":"","sources":["../src/request-context.constants.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACU,QAAA,OAAO,GAAG,SAAS,CAAC;AAEjC;;;;;;;;;;GAUG;AACU,QAAA,QAAQ,GAAG,UAAU,CAAC"}

package/dist/request-context.d.ts

@@ -1,33 +1,316 @@
 import { type Type } from "@nestjs/common";
-type RequestContextMiddleware = <T>(ctx: RequestContext, next: () => Promise<T>) => Promise<T>;
+/**
+ * Middleware function type for request context.
+ * Middlewares are executed in order when running a request context.
+ *
+ * @typeParam T - The return type of the middleware chain
+ * @param ctx - The current request context
+ * @param next - Function to call the next middleware in the chain
+ * @returns A promise resolving to the result of the middleware chain
+ */
+export type RequestContextMiddlewareType = <T>(ctx: RequestContext, next: () => Promise<T>) => Promise<T>;
+/**
+ * Options for creating a new RequestContext instance.
+ */
 export interface RequestContextCreateOptions {
+    /**
+     * Unique identifier for the request context.
+     * If not provided, a random UUID will be generated.
+     */
     id?: string;
+    /**
+     * The type of context (e.g., 'http', 'graphql', 'repl', 'job').
+     */
     type: string;
+    /**
+     * Parent context for creating nested/child contexts.
+     * Child contexts can access values from parent contexts.
+     */
     parent?: RequestContext;
 }
+/**
+ * RequestContext provides a way to store and access request-scoped data
+ * throughout the lifecycle of a request using AsyncLocalStorage.
+ *
+ * This is useful for storing data like the current user, request ID,
+ * database transactions, and other request-specific information that
+ * needs to be accessed across different parts of the application.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { RequestContext } from '@nest-boot/request-context';
+ *
+ * // Get the current request ID
+ * const requestId = RequestContext.id;
+ *
+ * // Store a value in the context
+ * RequestContext.set('userId', 123);
+ *
+ * // Retrieve a value from the context
+ * const userId = RequestContext.get<number>('userId');
+ * ```
+ *
+ * @example Running code in a new context
+ * ```typescript
+ * await RequestContext.run(
+ *   new RequestContext({ type: 'job' }),
+ *   async (ctx) => {
+ *     ctx.set('jobId', 'abc123');
+ *     await processJob();
+ *   }
+ * );
+ * ```
+ *
+ * @example Creating a child context
+ * ```typescript
+ * await RequestContext.child(async (childCtx) => {
+ *   // Child context inherits values from parent
+ *   // but can have its own values that don't affect parent
+ *   childCtx.set('tempValue', 'only in child');
+ * });
+ * ```
+ */
 export declare class RequestContext {
+    /**
+     * Unique identifier for this request context.
+     * Automatically generated as a UUID if not provided.
+     */
     readonly id: string;
+    /**
+     * The type of this context (e.g., 'http', 'graphql', 'repl', 'job').
+     */
     readonly type: string;
+    /**
+     * Parent context, if this is a child context.
+     * Values not found in this context will be looked up in the parent.
+     */
     readonly parent?: RequestContext;
+    /** Internal storage map for context values. @internal */
     private readonly container;
+    /** Async local storage backing the request context. @internal */
     private static readonly storage;
+    /** Registered middleware map keyed by name. @internal */
     private static readonly middlewares;
+    /** Dependency graph for middleware ordering. @internal */
     private static readonly middlewareDependencies;
+    /** Topologically-sorted middleware execution stack. @internal */
     private static middlewaresStack;
+    /** Creates a new RequestContext instance.
+     * @param options - Options for creating the request context (id, type, parent)
+     */
     constructor(options: RequestContextCreateOptions);
+    /**
+     * Gets a value from the context by its token.
+     * If not found in this context, looks up the parent context.
+     *
+     * @typeParam T - The expected type of the value
+     * @param token - The key to look up (string, symbol, function, or class)
+     * @returns The value if found, otherwise undefined
+     *
+     * @example
+     * ```typescript
+     * const ctx = RequestContext.current();
+     * const user = ctx.get<User>('currentUser');
+     * const service = ctx.get(MyService);
+     * ```
+     */
     get<T>(token: string | symbol | Function | Type<T>): T | undefined;
+    /**
+     * Sets a value in the context.
+     *
+     * @typeParam T - The type of the value
+     * @param typeOrToken - The key to store the value under
+     * @param value - The value to store
+     *
+     * @example
+     * ```typescript
+     * const ctx = RequestContext.current();
+     * ctx.set('userId', 123);
+     * ctx.set(UserService, userServiceInstance);
+     * ```
+     */
     set<T>(typeOrToken: string | symbol | Type<T>, value: T): void;
+    /**
+     * Gets a value from the context, or sets it if not present.
+     *
+     * @typeParam T - The type of the value
+     * @param typeOrToken - The key to look up or store under
+     * @param value - The value to set if not already present
+     * @returns The existing value or the newly set value
+     *
+     * @example
+     * ```typescript
+     * const ctx = RequestContext.current();
+     * const cache = ctx.getOrSet('cache', new Map());
+     * ```
+     */
     getOrSet<T>(typeOrToken: string | symbol | Type<T>, value: T): T;
+    /**
+     * Gets a value from the current context by its key.
+     * Static method that accesses the current context automatically.
+     *
+     * @typeParam T - The expected type of the value
+     * @param key - The key to look up
+     * @returns The value if found, otherwise undefined
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * const userId = RequestContext.get<number>('userId');
+     * ```
+     */
     static get<T>(key: string | symbol | Function | Type<T>): T | undefined;
+    /**
+     * Sets a value in the current context.
+     * Static method that accesses the current context automatically.
+     *
+     * @typeParam T - The type of the value
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * RequestContext.set('userId', 123);
+     * ```
+     */
     static set<T>(key: string | symbol | Type<T>, value: T): void;
+    /**
+     * Gets a value from the current context, or sets it if not present.
+     * Static method that accesses the current context automatically.
+     *
+     * @typeParam T - The type of the value
+     * @param key - The key to look up or store under
+     * @param value - The value to set if not already present
+     * @returns The existing value or the newly set value
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * const cache = RequestContext.getOrSet('cache', new Map());
+     * ```
+     */
     static getOrSet<T>(key: string | symbol | Type<T>, value: T): T;
+    /**
+     * Gets the ID of the current request context.
+     *
+     * @returns The unique identifier of the current context
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * console.log(`Processing request ${RequestContext.id}`);
+     * ```
+     */
     static get id(): string;
+    /**
+     * Gets the current request context.
+     *
+     * @returns The current RequestContext instance
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * const ctx = RequestContext.current();
+     * console.log(ctx.type); // 'http'
+     * ```
+     */
     static current(): RequestContext;
+    /**
+     * Checks if a request context is currently active.
+     *
+     * @returns true if a context is active, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (RequestContext.isActive()) {
+     *   const userId = RequestContext.get('userId');
+     * }
+     * ```
+     */
     static isActive(): boolean;
+    /**
+     * Runs a callback within a request context.
+     * All registered middlewares are executed before the callback.
+     *
+     * @typeParam T - The return type of the callback
+     * @param ctx - The request context to run within
+     * @param callback - The function to execute within the context
+     * @returns A promise resolving to the callback's return value
+     *
+     * @example
+     * ```typescript
+     * const result = await RequestContext.run(
+     *   new RequestContext({ type: 'job' }),
+     *   async (ctx) => {
+     *     ctx.set('jobId', 'abc123');
+     *     return await processJob();
+     *   }
+     * );
+     * ```
+     */
     static run<T>(ctx: RequestContext, callback: (ctx: RequestContext) => T | Promise<T>): Promise<T>;
+    /**
+     * Creates and runs a child context that inherits from the current context.
+     * Child contexts can read values from parent contexts but modifications
+     * are isolated to the child.
+     *
+     * @typeParam T - The return type of the callback
+     * @param callback - The function to execute within the child context
+     * @returns A promise resolving to the callback's return value
+     * @throws Error if no request context is active
+     *
+     * @example
+     * ```typescript
+     * // In parent context
+     * RequestContext.set('userId', 123);
+     *
+     * await RequestContext.child(async (childCtx) => {
+     *   // Can read parent values
+     *   const userId = childCtx.get('userId'); // 123
+     *
+     *   // Child-only values don't affect parent
+     *   childCtx.set('tempData', 'child only');
+     * });
+     *
+     * // Parent context unchanged
+     * RequestContext.get('tempData'); // undefined
+     * ```
+     */
     static child<T>(callback: (ctx: RequestContext) => T | Promise<T>): Promise<T>;
-    static registerMiddleware(name: string, middleware: RequestContextMiddleware, dependencies?: string[]): void;
+    /**
+     * Registers a middleware to be executed when running a request context.
+     * Middlewares are executed in dependency order.
+     *
+     * @param name - Unique name for the middleware
+     * @param middleware - The middleware function to register
+     * @param dependencies - Names of middlewares that must run before this one
+     *
+     * @example
+     * ```typescript
+     * RequestContext.registerMiddleware(
+     *   'auth',
+     *   async (ctx, next) => {
+     *     ctx.set('user', await loadUser());
+     *     return next();
+     *   }
+     * );
+     *
+     * // Middleware with dependencies
+     * RequestContext.registerMiddleware(
+     *   'permissions',
+     *   async (ctx, next) => {
+     *     const user = ctx.get('user');
+     *     ctx.set('permissions', await loadPermissions(user));
+     *     return next();
+     *   },
+     *   ['auth'] // Runs after 'auth' middleware
+     * );
+     * ```
+     */
+    static registerMiddleware(name: string, middleware: RequestContextMiddlewareType, dependencies?: string[]): void;
+    /** Resolves middleware dependencies via topological sort. @internal */
     private static resolveDependencies;
+    /** Rebuilds the middleware execution stack after registration changes. @internal */
     private static generateMiddlewaresStack;
 }
-export {};

package/dist/request-context.interceptor.d.ts

@@ -1,5 +1,35 @@
 import { type CallHandler, type ExecutionContext, type NestInterceptor } from "@nestjs/common";
 import { Observable } from "rxjs";
+/**
+ * NestJS interceptor that creates request context for HTTP and GraphQL requests.
+ *
+ * This interceptor serves as a fallback for cases where the middleware doesn't
+ * run (e.g., GraphQL resolvers). It:
+ * - Creates a new RequestContext if one doesn't already exist
+ * - Uses the `x-request-id` header as the context ID if provided
+ * - Supports both HTTP and GraphQL execution contexts
+ *
+ * The interceptor is automatically registered by RequestContextModule.
+ *
+ * @example
+ * The interceptor is typically used automatically, but can be applied manually:
+ * ```typescript
+ * import { Controller, UseInterceptors } from '@nestjs/common';
+ * import { RequestContextInterceptor } from '@nest-boot/request-context';
+ *
+ * @Controller()
+ * @UseInterceptors(RequestContextInterceptor)
+ * export class MyController {}
+ * ```
+ */
 export declare class RequestContextInterceptor implements NestInterceptor {
+    /**
+     * Intercepts the request and wraps execution in a request context.
+     *
+     * @typeParam T - The type of the response
+     * @param executionContext - The NestJS execution context
+     * @param next - The call handler for the next interceptor or handler
+     * @returns An observable of the response
+     */
     intercept<T>(executionContext: ExecutionContext, next: CallHandler<T>): Observable<T>;
 }

package/dist/request-context.interceptor.js

@@ -10,7 +10,37 @@ exports.RequestContextInterceptor = void 0;
 const common_1 = require("@nestjs/common");
 const rxjs_1 = require("rxjs");
 const request_context_1 = require("./request-context");
+/**
+ * NestJS interceptor that creates request context for HTTP and GraphQL requests.
+ *
+ * This interceptor serves as a fallback for cases where the middleware doesn't
+ * run (e.g., GraphQL resolvers). It:
+ * - Creates a new RequestContext if one doesn't already exist
+ * - Uses the `x-request-id` header as the context ID if provided
+ * - Supports both HTTP and GraphQL execution contexts
+ *
+ * The interceptor is automatically registered by RequestContextModule.
+ *
+ * @example
+ * The interceptor is typically used automatically, but can be applied manually:
+ * ```typescript
+ * import { Controller, UseInterceptors } from '@nestjs/common';
+ * import { RequestContextInterceptor } from '@nest-boot/request-context';
+ *
+ * @Controller()
+ * @UseInterceptors(RequestContextInterceptor)
+ * export class MyController {}
+ * ```
+ */
 let RequestContextInterceptor = class RequestContextInterceptor {
+    /**
+     * Intercepts the request and wraps execution in a request context.
+     *
+     * @typeParam T - The type of the response
+     * @param executionContext - The NestJS execution context
+     * @param next - The call handler for the next interceptor or handler
+     * @returns An observable of the response
+     */
     intercept(executionContext, next) {
         if (request_context_1.RequestContext.isActive() ||
             !["http", "graphql"].includes(executionContext.getType())) {