@tsed/di 8.18.1 → 8.19.0

package/lib/esm/common/decorators/autoInjectable.js

@@ -26,26 +26,45 @@ function resolveAutoInjectableArgs(token, args) {
     return list;
 }
 /**
- * AutoInjectable decorator is used to automatically inject dependencies in the constructor.
+ * Enable automatic dependency injection for a class constructor.
+ *
+ * Automatically resolves and injects constructor dependencies while preserving
+ * the ability to manually pass arguments. Useful for classes that need both
+ * automatic DI and manual instantiation flexibility.
+ *
+ * ### Usage
  *
- * @example
  * ```typescript
+ * import {AutoInjectable} from "@tsed/di";
+ *
  * @AutoInjectable()
  * class UserService {
  *   constructor(
- *     private database: Database,  // automatically injected
- *     customConfig?: Config        // can be passed manually
+ *     private database: Database,     // Automatically injected
+ *     private logger: Logger,         // Automatically injected
+ *     customConfig?: Config           // Can be passed manually
  *   ) {}
  * }
+ *
+ * // Automatic injection
+ * const service1 = new UserService();
+ *
+ * // Manual override
+ * const service2 = new UserService(customDb, customLogger, {debug: true});
+ *
+ * // Partial override (remaining deps auto-injected)
+ * const service3 = new UserService(undefined, undefined, {debug: true});
  * ```
  *
- * @description
- * When applied to a class, this decorator:
- * - Automatically resolves and injects dependencies based on constructor parameter types
- * - Preserves the ability to manually pass arguments which override automatic injection
+ * ### Behavior
+ *
+ * - Automatically resolves dependencies based on TypeScript metadata
+ * - Manual arguments override automatic injection for that position
+ * - `undefined` arguments trigger automatic injection
  *
+ * @returns Class decorator function
+ * @public
  * @decorator
- * @returns {ClassDecorator} A class decorator that enables automatic dependency injection
  */
 export function AutoInjectable() {
     return (constr) => {

package/lib/esm/common/decorators/constant.js

@@ -24,39 +24,43 @@ export function bindConstant(target, propertyKey, expression, defaultValue) {
     });
 }
 /**
- * Return value from Configuration.
+ * Inject a frozen configuration value into a property.
  *
- * ## Example
+ * Retrieves a value from the injector configuration and freezes it (creates an immutable deep clone).
+ * The value is lazily loaded on first access and cached for subsequent accesses.
  *
- * ```typescript
- * import {Env} from "@tsed/core/domain/Env.js";
- * import {Constant, Value} from "@tsed/di";
+ * ### Usage
  *
- * export class MyClass {
+ * ```typescript
+ * import {Injectable, Constant} from "@tsed/di";
+ * import {Env} from "@tsed/core";
  *
- *    @Constant("env")
- *    env: Env;
+ * @Injectable()
+ * export class MyService {
+ *   @Constant("env")
+ *   env: Env;
  *
- *    @Value("swagger.path")
- *    swaggerPath: string;
+ *   @Constant("api.baseUrl")
+ *   apiUrl: string;
  *
- *    @Value("swagger.path", "defaultValue")
- *    swaggerPath: string;
+ *   @Constant("api.timeout", 5000)
+ *   timeout: 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.env); // Value is available
+ *   }
  * }
  * ```
  *
- * @param {string} expression
- * @param defaultValue
- * @returns {(targetClass: any, attributeName: string) => any}
- * @decorator
+ * @typeParam Type The expected type of the constant value
+ * @param expression Dot-notation path to the configuration value
+ * @param defaultValue Optional default value if not found
+ * @returns Property decorator function
+ * @public
  */
 export function Constant(expression, defaultValue) {
     return (target, propertyKey) => {

package/lib/esm/common/decorators/controller.js

@@ -12,32 +12,52 @@ function mapOptions(options) {
     return options;
 }
 /**
- * Declare a new controller with his Rest path. His methods annotated will be collected to build the routing list.
- * This routing listing will be built with the `express.Router` object.
+ * Declare a REST controller with a base path for routing.
  *
- * ::: tip
- * See [Controllers](/docs/controllers.md) section for more details
- * :::
+ * Registers a class as a controller provider that handles HTTP requests.
+ * Annotated methods define routes relative to the controller's base path.
+ *
+ * ### Usage
  *
  * ```typescript
- *  @Controller("/calendars")
- *  export class CalendarCtrl {
- *
- *    @Get("/:id")
- *    public get(
- *      @Req() request: Req,
- *      @Res() response: Res,
- *      @Next() next: Next
- *    ): void {
- *
- *    }
- *  }
+ * import {Controller, Get} from "@tsed/di";
+ *
+ * @Controller("/calendars")
+ * export class CalendarCtrl {
+ *   @Get("/:id")
+ *   get(@PathParams("id") id: string) {
+ *     return {id};
+ *   }
+ * }
+ *
+ * // With middleware
+ * @Controller({
+ *   path: "/users",
+ *   middlewares: {
+ *     useBefore: [AuthMiddleware]
+ *   }
+ * })
+ * export class UserCtrl {}
+ *
+ * // Nested controllers
+ * @Controller({
+ *   path: "/admin",
+ *   children: [UserAdminCtrl, ProductAdminCtrl]
+ * })
+ * export class AdminCtrl {}
  * ```
  *
- * @param options
- * @controller
+ * ### Options
+ *
+ * - `path`: Base route path (string, RegExp, or array)
+ * - `children`: Child controller classes for nested routing
+ * - `middlewares`: Middleware configuration (useBefore, use, useAfter)
+ * - Additional `ProviderOpts` options
+ *
+ * @param options Controller path or configuration object
+ * @returns Class decorator function
+ * @public
  * @decorator
- * @classDecorator
  */
 export function Controller(options) {
     const { children = [], path, ...opts } = mapOptions(options);

package/lib/esm/common/decorators/injectable.js

@@ -1,20 +1,40 @@
 import { injectable } from "../fn/injectable.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 function Injectable(options = {}) {

package/lib/esm/common/decorators/intercept.js

@@ -44,10 +44,48 @@ export function bindIntercept(target, propertyKey, token, options) {
     return descriptor;
 }
 /**
- * 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 function Intercept(interceptor, options) {

package/lib/esm/common/decorators/interceptor.js

@@ -1,11 +1,38 @@
 import { interceptor } from "../fn/injectable.js";
 /**
- * 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 function Interceptor() {

package/lib/esm/common/decorators/module.js

@@ -4,13 +4,44 @@ import { ProviderType } from "../domain/ProviderType.js";
 import { Configuration } from "./configuration.js";
 import { Injectable } from "./injectable.js";
 /**
- * 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 function Module(options = {}) {

package/lib/esm/common/decorators/opts.js

@@ -4,7 +4,12 @@ import { ProviderScope } from "../domain/ProviderScope.js";
 import { Inject } from "./inject.js";
 import { Scope } from "./scope.js";
 /**
- * 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";
@@ -12,35 +17,38 @@ import { Scope } from "./scope.js";
  * @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 function Opts(target, propertyKey, index) {

package/lib/esm/common/decorators/overrideProvider.js

@@ -1,9 +1,43 @@
 import { GlobalProviders } from "../registries/GlobalProviders.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 function OverrideProvider(originalProvider) {
     return (target) => {

package/lib/esm/common/decorators/scope.js

@@ -1,10 +1,39 @@
 import { StoreSet } from "@tsed/core/decorators/storeSet.js";
 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 function Scope(scope = ProviderScope.REQUEST) {
     return StoreSet("scope", scope);

package/lib/esm/common/decorators/service.js

@@ -1,11 +1,31 @@
 import { Injectable } from "./injectable.js";
 /**
- * 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 function Service() {

package/lib/esm/common/decorators/useOpts.js

@@ -4,7 +4,12 @@ import { Store } from "@tsed/core/types/Store.js";
 import { decoratorTypeOf } from "@tsed/core/utils/decoratorTypeOf.js";
 import { DI_USE_OPTIONS, DI_USE_PARAM_OPTIONS } from "../constants/constants.js";
 /**
- * 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";
@@ -12,35 +17,38 @@ import { DI_USE_OPTIONS, DI_USE_PARAM_OPTIONS } from "../constants/constants.js"
  * @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 function UseOpts(options) {
     return (target, propertyKey, index) => {