@tsed/di 8.18.2 → 8.19.0

package/lib/types/common/decorators/injectable.d.ts

@@ -1,20 +1,40 @@
 import type { ProviderOpts } from "../interfaces/ProviderOpts.js";
 /**
- * The decorators `@Injectable()` declare a new service can be injected in other service, controller, interceptor, etc.. on there `constructor`.
- * All classes annotated with `@Injectable()` are built one time, excepted if you change the default provider configuration.
+ * Declare a class as an injectable provider in the DI system.
  *
- * ::: tip
- * `@Injectable()` use the `reflect-metadata` to collect and inject the built provided to other services.
- * :::
+ * Registers a class as a provider that can be injected into other services, controllers, or interceptors.
+ * By default, providers are singleton-scoped and built once during application initialization.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable} from "@tsed/di";
+ *
+ * @Injectable()
+ * export class MyService {
+ *   getData() {
+ *     return "data";
+ *   }
+ * }
+ *
+ * // With options
+ * @Injectable({
+ *   scope: ProviderScope.REQUEST,
+ *   type: ProviderType.PROVIDER
+ * })
+ * export class RequestScopedService {}
+ * ```
  *
  * ### Options
  *
- * - type (@@ProviderType@@  or `string`): Kind of provider. (Default: `ProviderType.PROVIDER`)
- * - scope (@@ProviderScope@@): Kind of provider. (Default: `ProviderScope.SINGLETON`)
- * - token (@@TokenProvider@@): An injection token (Note: This option override default metadata generated by Typescript).
- * - deps (`Type<any>`): List of class or provider which will be injected to the constructor (Note: This options override default metadata generated by Typescript).
+ * - `type`: Provider category (default: `ProviderType.PROVIDER`)
+ * - `scope`: Instance lifecycle scope (default: `ProviderScope.SINGLETON`)
+ * - `token`: Custom injection token (overrides class reference)
+ * - `deps`: Explicit constructor dependencies (overrides TypeScript metadata)
  *
- * @returns {Function}
+ * @param options Provider configuration options
+ * @returns Class decorator function
+ * @public
  * @decorator
  */
 export declare function Injectable(options?: Partial<ProviderOpts>): ClassDecorator;

package/lib/types/common/decorators/intercept.d.ts

@@ -4,10 +4,48 @@ import type { TokenProvider } from "../interfaces/TokenProvider.js";
 export declare function getInterceptorOptions<T>(target: Type<any>, propertyKey: string | symbol): T;
 export declare function bindIntercept(target: any, propertyKey: string | symbol, token: TokenProvider, options: Record<string, unknown>): TypedPropertyDescriptor<any> | undefined;
 /**
- * Attaches interceptor to method call and executes the before and after methods
+ * Apply an interceptor to a method or all methods of a class.
  *
- * @param interceptor
- * @param options
+ * Wraps method execution with interceptor logic for cross-cutting concerns like logging,
+ * validation, caching, or error handling. Can be applied to individual methods or entire classes.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, Intercept, Interceptor, InterceptorContext, InterceptorMethods} from "@tsed/di";
+ *
+ * @Interceptor()
+ * class LogInterceptor implements InterceptorMethods {
+ *   intercept(context: InterceptorContext) {
+ *     console.log("Before:", context.propertyKey);
+ *     const result = context.next();
+ *     console.log("After:", result);
+ *     return result;
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class UserService {
+ *   @Intercept(LogInterceptor)
+ *   async findById(id: string) {
+ *     return {id, name: "User"};
+ *   }
+ * }
+ *
+ * // Apply to all methods
+ * @Injectable()
+ * @Intercept(LogInterceptor)
+ * class ProductService {
+ *   getAll() {}
+ *   getById(id: string) {}
+ * }
+ * ```
+ *
+ * @typeParam T The interceptor class type
+ * @param interceptor The interceptor class token
+ * @param options Optional configuration passed to the interceptor
+ * @returns Method or class decorator function
+ * @public
  * @decorator
  */
 export declare function Intercept<T extends InterceptorMethods>(interceptor: Type<T>, options?: any): any;

package/lib/types/common/decorators/interceptor.d.ts

@@ -1,10 +1,37 @@
 /**
- * The decorators `@Interceptor()` declare a new service can be injected in other service or controller on there `constructor`.
- * All services annotated with `@Interceptor()` are constructed one time.
+ * Declare an interceptor class for cross-cutting concerns.
  *
- * > `@Service()` use the `reflect-metadata` to collect and inject service on controllers or other services.
+ * Registers a class as an interceptor provider that can modify method execution behavior.
+ * Interceptors must implement the `InterceptorMethods` interface.
+ * All interceptors are singleton-scoped and constructed once.
  *
- * @returns {Function}
+ * ### Usage
+ *
+ * ```typescript
+ * import {Interceptor, InterceptorContext, InterceptorMethods} from "@tsed/di";
+ *
+ * @Interceptor()
+ * export class LogInterceptor implements InterceptorMethods {
+ *   intercept(context: InterceptorContext) {
+ *     console.log("Before:", context.propertyKey);
+ *     const result = context.next();
+ *     console.log("After:", result);
+ *     return result;
+ *   }
+ * }
+ *
+ * // Use with @Intercept decorator
+ * @Injectable()
+ * class MyService {
+ *   @Intercept(LogInterceptor)
+ *   async fetchData() {
+ *     return "data";
+ *   }
+ * }
+ * ```
+ *
+ * @returns Class decorator function
+ * @public
  * @decorator
  */
 export declare function Interceptor(): ClassDecorator;

package/lib/types/common/decorators/lazyInject.d.ts

@@ -1,19 +1,36 @@
 /**
- * Lazy load a provider from his package and invoke only when the provider is used
+ * Lazily inject a provider from a dynamic import.
+ *
+ * Defers loading and injection of a provider until the property is first accessed.
+ * Useful for code splitting, optional dependencies, or reducing initial bundle size.
+ *
+ * ### Usage
  *
  * ```typescript
  * import type {PlatformException} from "@tsed/platform-exceptions";
+ * import {Injectable, LazyInject} from "@tsed/di";
  *
  * @Injectable()
  * export class MyService {
+ *   // Import default export
  *   @LazyInject(() => import("@tsed/platform-exceptions"))
  *   exceptions: Promise<PlatformException>;
+ *
+ *   // Import named export
+ *   @LazyInject("MyPlugin", () => import("./plugins"))
+ *   plugin: Promise<MyPlugin>;
+ *
+ *   async handleError(error: Error) {
+ *     const handler = await this.exceptions;
+ *     handler.handle(error);
+ *   }
  * }
  * ```
  *
- * @param key - The named export to import from the module.
- * @param resolver - A function that returns a promise resolving to the module.
- * @returns {Function}
+ * @param key Optional named export to extract from the module
+ * @param resolver Function returning a promise resolving to the module
+ * @returns Property decorator function
+ * @public
  * @decorator
  */
 export declare function LazyInject(resolver: () => Promise<{
@@ -23,20 +40,37 @@ export declare function LazyInject(key: string, resolver: () => Promise<{
     default: unknown;
 }>): PropertyDecorator;
 /**
- * Optionally Lazy load a provider from his package and invoke only when the provider is used
+ * Optionally inject a provider from a dynamic import, returning undefined on failure.
+ *
+ * Similar to `@LazyInject` but gracefully handles import failures by returning undefined.
+ * Useful for truly optional dependencies that may not be available in all environments.
+ *
+ * ### Usage
  *
  * ```typescript
  * import type {PlatformException} from "@tsed/platform-exceptions";
+ * import {Injectable, OptionalLazyInject} from "@tsed/di";
  *
  * @Injectable()
  * export class MyService {
  *   @OptionalLazyInject(() => import("@tsed/platform-exceptions"))
- *   exceptions: Promise<PlatformException>;
+ *   exceptions?: Promise<PlatformException>;
+ *
+ *   async handleError(error: Error) {
+ *     const handler = await this.exceptions;
+ *     if (handler) {
+ *       handler.handle(error);
+ *     } else {
+ *       console.error("Exception handler not available:", error);
+ *     }
+ *   }
  * }
  * ```
- * @param key - The named export to import from the module.
- * @param resolver - A function that returns a promise resolving to the module.
- * @decorator
+ *
+ * @param key Optional named export to extract from the module
+ * @param resolver Function returning a promise resolving to the module
+ * @returns Property decorator function
+ * @public
  */
 export declare function OptionalLazyInject(resolver: () => Promise<{
     default: unknown;

package/lib/types/common/decorators/module.d.ts

@@ -19,13 +19,44 @@ export interface ModuleOptions extends Omit<TsED.Configuration, "scopes"> {
     [key: string]: any;
 }
 /**
- * Declare a new Ts.ED module
+ * Declare a Ts.ED module to organize related providers and configuration.
  *
- * ## Options
- * - imports: List of Provider which must be built by injector before invoking the module
- * - deps: List of provider must be injected to the module constructor (explicit declaration)
+ * Modules group related functionality together, manage provider dependencies,
+ * and configure application settings. They are singleton-scoped by default.
  *
- * @param options
+ * ### Usage
+ *
+ * ```typescript
+ * import {Module} from "@tsed/di";
+ *
+ * @Module({
+ *   imports: [DatabaseService, CacheService],
+ *   mount: {
+ *     "/api": [UserController, ProductController]
+ *   }
+ * })
+ * export class AppModule {
+ *   constructor(private db: DatabaseService) {
+ *     // Dependencies injected
+ *   }
+ *
+ *   $onInit() {
+ *     this.db.connect();
+ *   }
+ * }
+ * ```
+ *
+ * ### Options
+ *
+ * - `imports`: Providers to initialize before this module
+ * - `deps`: Constructor dependencies (explicit declaration)
+ * - `mount`: Route mappings for controllers
+ * - `scope`: Provider scope (default: singleton)
+ * - Additional properties are stored as module configuration
+ *
+ * @param options Module configuration options
+ * @returns Class decorator function
+ * @public
  * @decorator
  */
 export declare function Module(options?: Partial<ModuleOptions>): any;

package/lib/types/common/decorators/opts.d.ts

@@ -1,5 +1,10 @@
 /**
- * Get instance options. This options depending on his invocation context.
+ * Inject custom options passed to a provider instance.
+ *
+ * Used in configurable providers to receive options from the injection context.
+ * Automatically changes the provider scope to `INSTANCE` since each invocation may have different options.
+ *
+ * ### Usage
  *
  * ```typescript
  * import {Injectable, Opts, UseOpts} from "@tsed/di";
@@ -7,35 +12,38 @@
  * @Injectable()
  * class MyConfigurableService {
  *   source: string;
- *   constructor(@Opts options: any = {}) {
- *      console.log("Hello ", options.source); // log: Hello Service1 then Hello Service2
  *
- *      this.source = options.source;
+ *   constructor(@Opts options: any = {}) {
+ *     console.log("Hello", options.source);
+ *     this.source = options.source;
  *   }
  * }
  *
  * @Injectable()
  * class MyService1 {
  *   constructor(@UseOpts({source: 'Service1'}) service: MyConfigurableService) {
- *     console.log(service.source) // log: Service1
+ *     console.log(service.source); // "Service1"
  *   }
  * }
  *
  * @Injectable()
  * class MyService2 {
  *   constructor(@UseOpts({source: 'Service2'}) service: MyConfigurableService) {
- *     console.log(service.source) // log: Service2
+ *     console.log(service.source); // "Service2"
  *   }
  * }
  * ```
  *
- * ::: warning
- * Using @@Opts@@ decorator on a constructor parameter change the Scope of the provider to `ProviderScope.INSTANCE`.
- * :::
+ * ### Warning
+ *
+ * Using `@Opts` changes the provider scope to `ProviderScope.INSTANCE`,
+ * meaning a new instance is created for each injection.
  *
- * @param target
- * @param propertyKey
- * @param index
+ * @param target The target class
+ * @param propertyKey The constructor method name
+ * @param index The parameter index
+ * @returns Parameter decorator
+ * @public
  * @decorator
  */
 export declare function Opts(target: any, propertyKey: string | symbol | undefined, index: number): void;

package/lib/types/common/decorators/overrideProvider.d.ts

@@ -1,8 +1,42 @@
 import type { Type } from "@tsed/core/types/Type.js";
 /**
- * Override a provider which is already registered in ProviderRegistry.
- * @returns {Function}
- * @decorators
- * @param originalProvider
+ * Override an existing provider registration with a new implementation.
+ *
+ * Replaces the implementation class of a registered provider while keeping the same token.
+ * Useful for testing, plugin systems, or providing alternative implementations.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, OverrideProvider} from "@tsed/di";
+ *
+ * @Injectable()
+ * class OriginalService {
+ *   getData() {
+ *     return "original";
+ *   }
+ * }
+ *
+ * // Override with new implementation
+ * @OverrideProvider(OriginalService)
+ * class MockService {
+ *   getData() {
+ *     return "mocked";
+ *   }
+ * }
+ *
+ * // Injected instances will now use MockService
+ * @Injectable()
+ * class UserService {
+ *   constructor(private service: OriginalService) {
+ *     console.log(this.service.getData()); // "mocked"
+ *   }
+ * }
+ * ```
+ *
+ * @param originalProvider The provider class to override
+ * @returns Class decorator function
+ * @public
+ * @decorator
  */
 export declare function OverrideProvider(originalProvider: Type<any>): Function;

package/lib/types/common/decorators/scope.d.ts

@@ -1,8 +1,37 @@
 import { ProviderScope } from "../domain/ProviderScope.js";
 /**
+ * Define the lifecycle scope of a provider.
  *
- * @param {"request" | "singleton" | ProviderScope} scope
- * @returns {Function}
- * @constructor
+ * Controls when and how provider instances are created and shared.
+ * Can be combined with `@Injectable()`, `@Service()`, or other provider decorators.
+ *
+ * ### Scopes
+ *
+ * - `SINGLETON`: One instance shared across the application (default)
+ * - `REQUEST`: New instance per request/context
+ * - `INSTANCE`: New instance on every injection
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, Scope, ProviderScope} from "@tsed/di";
+ *
+ * @Injectable()
+ * @Scope(ProviderScope.REQUEST)
+ * export class RequestScopedService {
+ *   // New instance created for each request
+ * }
+ *
+ * @Injectable()
+ * @Scope("singleton")
+ * export class SingletonService {
+ *   // Same instance shared across the app
+ * }
+ * ```
+ *
+ * @param scope The provider scope to set (default: REQUEST)
+ * @returns Class decorator function
+ * @public
+ * @decorator
  */
 export declare function Scope(scope?: "request" | "singleton" | ProviderScope): Function;

package/lib/types/common/decorators/service.d.ts

@@ -1,10 +1,30 @@
 /**
- * The decorators `@Service()` declare a new service can be injected in other service or controller on there `constructor`.
- * All services annotated with `@Service()` are constructed one time.
+ * Declare a service class that can be injected into other components.
  *
- * > `@Service()` use the `reflect-metadata` to collect and inject service on controllers or other services.
+ * Alias for `@Injectable()` decorator with default settings.
+ * Services are singleton-scoped and instantiated once during application startup.
  *
- * @returns {Function}
+ * ### Usage
+ *
+ * ```typescript
+ * import {Service} from "@tsed/di";
+ *
+ * @Service()
+ * export class UserService {
+ *   async findById(id: string) {
+ *     // Service logic
+ *   }
+ * }
+ *
+ * // Use in another service or controller
+ * @Service()
+ * export class AuthService {
+ *   constructor(private userService: UserService) {}
+ * }
+ * ```
+ *
+ * @returns Class decorator function
+ * @public
  * @decorator
  */
 export declare function Service(): Function;

package/lib/types/common/decorators/useOpts.d.ts

@@ -1,5 +1,10 @@
 /**
- * Add options to invoke the Service.
+ * Pass custom options to an injected provider.
+ *
+ * Supplies configuration options when injecting a provider that accepts `@Opts`.
+ * Works with constructor parameters and property injection.
+ *
+ * ### Usage
  *
  * ```typescript
  * import {Injectable, Opts, UseOpts} from "@tsed/di";
@@ -7,35 +12,38 @@
  * @Injectable()
  * class MyConfigurableService {
  *   source: string;
- *   constructor(@Opts options: any = {}) {
- *      console.log("Hello ", options.source); // log: Hello Service1 then Hello Service2
  *
- *      this.source = options.source;
+ *   constructor(@Opts options: any = {}) {
+ *     this.source = options.source;
  *   }
  * }
  *
  * @Injectable()
  * class MyService1 {
+ *   // Constructor parameter with options
  *   constructor(@UseOpts({source: 'Service1'}) service: MyConfigurableService) {
- *     console.log(service.source) // log: Service1
+ *     console.log(service.source); // "Service1"
  *   }
  * }
  *
  * @Injectable()
  * class MyService2 {
- *   constructor(@UseOpts({source: 'Service2'}) service: MyConfigurableService) {
- *     console.log(service.source) // log: Service2
- *   }
+ *   // Property injection with options
+ *   @Inject(MyConfigurableService)
+ *   @UseOpts({source: 'Service2'})
+ *   service: MyConfigurableService;
  * }
  * ```
  *
- * ::: warning
- * Using @@Opts@@ decorator on a constructor parameter change the Scope of the provider to `ProviderScope.INSTANCE`.
- * :::
+ * ### Warning
+ *
+ * The injected provider must use `@Opts` to receive these options.
+ * Using `@Opts` automatically sets the provider scope to `INSTANCE`.
  *
- * @returns {Function}
+ * @param options Configuration object to pass to the provider
+ * @returns Decorator function (parameter or property)
+ * @public
  * @decorator
- * @param options
  */
 export declare function UseOpts(options: {
     [key: string]: any;

package/lib/types/common/decorators/value.d.ts

@@ -1,37 +1,43 @@
 export declare function bindValue(target: any, propertyKey: string | symbol, expression: string, defaultValue?: any): void;
 /**
- * Return value from Configuration.
+ * Inject a reactive configuration value into a property.
  *
- * ## Example
+ * Creates a getter/setter that always reflects the current configuration value.
+ * Unlike `@Constant()`, the value is not frozen and can change at runtime.
  *
- * ```typescript
- * import {Env} from "@tsed/core/domain/Env.js";
- * import {Constant, Value} from "@tsed/di";
- *
- * export class MyClass {
+ * ### Usage
  *
- *    @Constant("env")
- *    env: Env;
+ * ```typescript
+ * import {Injectable, Value} from "@tsed/di";
  *
- *    @Value("swagger.path")
- *    swaggerPath: string;
+ * @Injectable()
+ * export class MyService {
+ *   @Value("swagger.path")
+ *   swaggerPath: string;
  *
- *    @Value("swagger.path", "defaultValue")
- *    swaggerPath: string;
+ *   @Value("api.port", 3000)
+ *   port: number;
  *
- *    constructor() {
- *       console.log(this.swaggerPath) // undefined. Not available on constructor
- *    }
+ *   constructor() {
+ *     // Not available yet - undefined
+ *   }
  *
- *    $onInit() {
- *      console.log(this.swaggerPath)  // something
- *    }
+ *   $onInit() {
+ *     console.log(this.swaggerPath); // Current value
+ *     this.swaggerPath = "/new-path"; // Can be modified
+ *   }
  * }
  * ```
  *
- * @param expression
- * @param defaultValue
- * @returns {(targetClass: any, attributeName: string) => any}
+ * ### Difference from @Constant
+ *
+ * - `@Constant`: Frozen immutable value (deep clone)
+ * - `@Value`: Reactive value (always reads current config)
+ *
+ * @param expression Dot-notation path to the configuration value
+ * @param defaultValue Optional default value if not found
+ * @returns Property decorator function
+ * @public
  * @decorator
  */
 export declare function Value(expression: string, defaultValue?: unknown): PropertyDecorator;

package/lib/types/common/domain/Container.d.ts

@@ -2,6 +2,26 @@ import type { ProviderOpts } from "../interfaces/ProviderOpts.js";
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 import { Provider } from "./Provider.js";
 import type { ProviderType } from "./ProviderType.js";
+/**
+ * Provider container managing registered providers and their metadata.
+ *
+ * Extends `Map` to provide specialized methods for adding, retrieving, and managing providers
+ * within the dependency injection system. Acts as a registry for all injectable classes and values.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Container} from "@tsed/di";
+ *
+ * const container = new Container();
+ * container.add(MyService, {scope: ProviderScope.SINGLETON});
+ *
+ * const provider = container.getProvider(MyService);
+ * const controllers = container.getProviders(ProviderType.CONTROLLER);
+ * ```
+ *
+ * @public
+ */
 export declare class Container extends Map<TokenProvider, Provider> {
     /**
      *

package/lib/types/common/domain/ContextLogger.d.ts

@@ -1,6 +1,11 @@
 import { Hooks } from "@tsed/hooks";
 import { LogLevel } from "@tsed/logger";
 import { DILogger } from "../../common/index.js";
+/**
+ * Options for creating a context logger instance.
+ *
+ * @public
+ */
 export interface ContextLoggerOptions extends Record<string, any> {
     id: string;
     logger?: DILogger;
@@ -8,6 +13,27 @@ export interface ContextLoggerOptions extends Record<string, any> {
     maxStackSize?: number;
     additionalProps?: Record<any, any>;
 }
+/**
+ * Context-aware logger for scoped logging within a request or execution context.
+ *
+ * Buffers log messages and associates them with a specific context (like an HTTP request).
+ * Supports log level filtering, buffering, and automatic flushing when the context ends.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {ContextLogger} from "@tsed/di";
+ *
+ * const logger = new ContextLogger({id: "req-123"});
+ *
+ * logger.info("Processing request");
+ * logger.debug("Debug info");
+ *
+ * await logger.flush(); // Write buffered logs
+ * ```
+ *
+ * @public
+ */
 export declare class ContextLogger {
     #private;
     readonly dateStart: Date;