@tsed/di 8.18.2 → 8.19.0

package/lib/esm/common/fn/logger.js

@@ -1,6 +1,20 @@
 import { injector } from "./injector.js";
 /**
- * Get the current `injector.logger` instance.
+ * Get the current logger instance from the injector.
+ *
+ * Returns the configured logger (defaults to console if not set).
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {logger} from "@tsed/di";
+ *
+ * logger().info("Application started");
+ * logger().error("An error occurred", error);
+ * ```
+ *
+ * @returns The logger instance
+ * @public
  */
 export function logger() {
     return injector().logger;

package/lib/esm/common/services/DIConfiguration.js

@@ -2,6 +2,30 @@ import { getValue } from "@tsed/core/utils/getValue.js";
 import { isFunction } from "@tsed/core/utils/isFunction.js";
 import { setValue } from "@tsed/core/utils/setValue.js";
 import { $alter } from "@tsed/hooks";
+/**
+ * Configuration management service for the DI system.
+ *
+ * Stores and manages application configuration settings including imports, routes, logger options,
+ * and custom properties. Provides type-safe accessors for common configuration keys and supports
+ * nested property access via `get()` and `set()`.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {DIConfiguration} from "@tsed/di";
+ *
+ * const config = new DIConfiguration({
+ *   rootDir: __dirname,
+ *   env: Env.PROD,
+ *   logger: {level: "info"}
+ * });
+ *
+ * config.set("custom.nested.key", "value");
+ * const value = config.get("custom.nested.key");
+ * ```
+ *
+ * @public
+ */
 export class DIConfiguration {
     constructor(initialProps = {}) {
         this.default = new Map();

package/lib/esm/common/services/DILogger.js

@@ -1,4 +1,27 @@
 import { injectable } from "../fn/injectable.js";
 import { injector } from "../fn/injector.js";
+/**
+ * Injection token for the DI logger service.
+ *
+ * Use this symbol to inject the configured logger instance into your services.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, Inject, LOGGER} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyService {
+ *   @Inject(LOGGER)
+ *   logger: LOGGER;
+ *
+ *   doSomething() {
+ *     this.logger.info("Doing something");
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const LOGGER = Symbol.for("LOGGER");
 injectable(LOGGER).factory(() => injector().logger);

package/lib/esm/common/services/InjectorService.js

@@ -21,24 +21,28 @@ import { getConstructorDependencies } from "../utils/getConstructorDependencies.
 import { DIConfiguration } from "./DIConfiguration.js";
 const EXCLUDED_CONFIGURATION_KEYS = ["mount", "imports"];
 /**
- * This service contain all services collected by `@Service` or services declared manually with `InjectorService.factory()` or `InjectorService.service()`.
+ * Core dependency injection orchestrator managing provider lifecycle and resolution.
  *
- * ### Example:
+ * The main service responsible for registering, resolving, and managing all injectable providers.
+ * Handles dependency graph resolution, instance caching, scope management, and lifecycle hooks.
+ *
+ * ### Usage
  *
  * ```typescript
  * import {InjectorService} from "@tsed/di";
  *
- * // Import the services (all services are decorated with @Service()";
+ * // Import the services (all services are decorated with @Service())
  * import MyService1 from "./services/service1.js";
  * import MyService2 from "./services/service2.js";
  * import MyService3 from "./services/service3.js";
  *
- * // When all services are imported, you can load InjectorService.
- *
+ * // When all services are imported, you can load InjectorService
  * await injector().load();
  *
  * const myService1 = injector.get<MyService1>(MyService1);
  * ```
+ *
+ * @public
  */
 export class InjectorService extends Container {
     #cache;
@@ -58,29 +62,34 @@ export class InjectorService extends Container {
         return this.#loaded;
     }
     /**
-     * Return a list of instance build by the injector.
+     * Return a list of all instances built by the injector.
+     *
+     * @returns An array of all cached provider instances
      */
     toArray() {
         return [...this.#cache.values()];
     }
     /**
-     * Get a service or factory already constructed from his symbol or class.
+     * Get a service or factory already constructed from its symbol or class.
      *
-     * #### Example
+     * Returns the cached instance if available, otherwise resolves and caches the provider.
+     *
+     * ### Usage
      *
      * ```typescript
      * import {InjectorService} from "@tsed/di";
      * import MyService from "./services.js";
      *
      * class OtherService {
-     *      constructor(injectorService: InjectorService) {
-     *          const myService = injectorService.get<MyService>(MyService);
-     *      }
+     *   constructor(injectorService: InjectorService) {
+     *     const myService = injectorService.get<MyService>(MyService);
+     *   }
      * }
      * ```
      *
-     * @param token The class or symbol registered in InjectorService.
-     * @param options
+     * @param token The class or symbol registered in InjectorService
+     * @param options Optional invocation options
+     * @returns The resolved provider instance
      */
     get(token, options) {
         if (!this.has(token)) {
@@ -89,7 +98,13 @@ export class InjectorService extends Container {
         return this.#cache.get(token);
     }
     /**
-     * Return all instance of the same provider type
+     * Return all instances of providers matching the specified type.
+     *
+     * Retrieves all providers of a given type and resolves their instances.
+     *
+     * @param type The provider type to filter by (e.g., ProviderType.CONTROLLER)
+     * @param options Optional invocation options
+     * @returns Array of resolved instances matching the type
      */
     getMany(type, options) {
         return this.getProviders(type).map((provider) => {
@@ -97,39 +112,49 @@ export class InjectorService extends Container {
         });
     }
     /**
-     * The has() method returns a boolean indicating whether an element with the specified key exists or not.
+     * Check if a provider instance exists in the cache.
+     *
+     * @param token The token to check for
+     * @returns `true` if the instance is cached, `false` otherwise
      */
     has(token) {
         return this.#cache.get(token) !== undefined;
     }
     /**
-     * Declare an alias for a given token.
+     * Create an alias for a provider token.
+     *
+     * Allows the same provider instance to be retrieved using a different token.
+     *
+     * @param token The original provider token
+     * @param alias The alias token to register
+     * @returns The injector instance for chaining
      */
     alias(token, alias) {
         this.#cache.set(alias, this.#cache.get(token));
         return this;
     }
     /**
-     * Resolve the token depending on his provider configuration.
+     * Resolve a provider token and return its instance.
      *
-     * If the token isn't cached, the injector will invoke the provider and cache the result.
+     * If the token isn't cached, the injector creates the instance according to the provider configuration
+     * and caches it based on the provider's scope (singleton, request, or instance).
      *
-     * #### Example
+     * ### Usage
      *
      * ```typescript
      * import {InjectorService} from "@tsed/di";
      * import MyService from "./services.js";
      *
      * class OtherService {
-     *     constructor(injectorService: InjectorService) {
-     *          const myService = injectorService.invoke<MyService>(MyService);
-     *      }
-     *  }
+     *   constructor(injectorService: InjectorService) {
+     *     const myService = injectorService.resolve<MyService>(MyService);
+     *   }
+     * }
      * ```
      *
-     * @param token The injectable class to invoke. Class parameters are injected according constructor signature.
-     * @param options {InvokeOptions} Optional options to invoke the class.
-     * @returns {Type} The class constructed.
+     * @param token The injectable class to invoke. Constructor parameters are injected automatically
+     * @param options Optional invocation options (locals, rebuild, useOpts, etc.)
+     * @returns The resolved provider instance
      */
     resolve(token, options = {}) {
         let instance = options.locals ? options.locals.get(token) : undefined;
@@ -173,33 +198,37 @@ export class InjectorService extends Container {
         return instance;
     }
     /**
-     * Resolve the token depending on his provider configuration.
+     * Invoke a provider token and return its instance.
      *
-     * If the token isn't cached, the injector will invoke the provider and cache the result.
+     * Alias for `resolve()`. If the token isn't cached, the injector creates the instance
+     * according to the provider configuration.
      *
-     * #### Example
+     * ### Usage
      *
      * ```typescript
      * import {InjectorService} from "@tsed/di";
      * import MyService from "./services.js";
      *
      * class OtherService {
-     *     constructor(injectorService: InjectorService) {
-     *          const myService = injectorService.invoke<MyService>(MyService);
-     *      }
-     *  }
+     *   constructor(injectorService: InjectorService) {
+     *     const myService = injectorService.invoke<MyService>(MyService);
+     *   }
+     * }
      * ```
      *
-     * @param token The injectable class to invoke. Class parameters are injected according constructor signature.
-     * @param options {InvokeOptions} Optional options to invoke the class.
-     * @returns {Type} The class constructed.
-     * @alias InjectorService.resolve
+     * @param token The injectable class to invoke. Constructor parameters are injected automatically
+     * @param options Optional invocation options (locals, rebuild, useOpts, etc.)
+     * @returns The resolved provider instance
+     * @see resolve
      */
     invoke(token, options = {}) {
         return this.resolve(token, options);
     }
     /**
-     * Build only providers which are asynchronous.
+     * Build all asynchronous providers.
+     *
+     * Resolves providers that have async factories or async initialization.
+     * Called automatically during the `load()` process.
      */
     async loadAsync() {
         for (const [, provider] of this) {
@@ -209,7 +238,10 @@ export class InjectorService extends Container {
         }
     }
     /**
-     * Build only providers which are synchronous.
+     * Build all synchronous singleton providers.
+     *
+     * Instantiates all singleton-scoped providers that haven't been cached yet.
+     * Called automatically during the `load()` process after async providers.
      */
     loadSync() {
         for (const [, provider] of this) {
@@ -220,9 +252,20 @@ export class InjectorService extends Container {
         }
     }
     /**
-     * Build all providers from given container (or GlobalProviders) and emit `$onInit` event.
+     * Load and initialize all registered providers.
      *
-     * @param container
+     * Bootstraps the DI system by resolving configuration, building provider instances,
+     * and triggering lifecycle hooks (`$beforeInit`, `$onInit`).
+     *
+     * ### Usage
+     *
+     * ```typescript
+     * import {injector} from "@tsed/di";
+     *
+     * await injector().load();
+     * ```
+     *
+     * @param container Optional container with additional providers to merge
      */
     async load(container = createContainer()) {
         // avoid provider registration in the GlobalContainer during the loading phase
@@ -237,8 +280,11 @@ export class InjectorService extends Container {
         await $asyncEmit("$onInit");
     }
     /**
-     * Load all configurations registered on providers via @Configuration decorator.
-     * It inspects for each provider some fields like imports, mount, etc. to resolve the configuration.
+     * Resolve and merge all provider configurations.
+     *
+     * Collects configuration from all providers decorated with `@Configuration`,
+     * merges them, and stores the result in the injector settings.
+     * Called automatically during the load process.
      */
     async resolveConfiguration() {
         if (this.resolvedConfiguration) {

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

@@ -1,23 +1,44 @@
 /**
- * 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 declare function AutoInjectable(): <T extends new (...args: any[]) => NonNullable<unknown>>(constr: T) => T;
+export declare function AutoInjectable(): <T extends {
+    new (...args: any[]): NonNullable<unknown>;
+}>(constr: T) => T;

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

@@ -1,8 +1,38 @@
 import { DIConfiguration } from "../services/DIConfiguration.js";
 /**
- * Get or set Configuration on a class.
+ * Associate configuration with a class or inject configuration into a constructor parameter.
  *
- * @decorator
+ * When used as a class decorator, stores configuration metadata on the provider.
+ * When used as a parameter decorator, injects the `DIConfiguration` instance.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Configuration, Module} from "@tsed/di";
+ *
+ * // As class decorator
+ * @Configuration({
+ *   rootDir: __dirname,
+ *   port: 3000,
+ *   mount: {
+ *     "/api": []
+ *   }
+ * })
+ * @Module({})
+ * export class Server {}
+ *
+ * // As parameter decorator
+ * @Injectable()
+ * export class MyService {
+ *   constructor(@Configuration() config: Configuration) {
+ *     console.log(config.get("port"));
+ *   }
+ * }
+ * ```
+ *
+ * @param settings Optional configuration object to associate with the class
+ * @returns Decorator function (class or parameter)
+ * @public
  */
 export declare function Configuration(): any;
 export declare function Configuration(settings: Partial<TsED.Configuration>): ClassDecorator;

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

@@ -1,37 +1,41 @@
 export declare function bindConstant(target: any, propertyKey: string | symbol, expression: string, defaultValue?: any): void;
 /**
- * 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 declare function Constant<Type = unknown>(expression: string, defaultValue?: Type): PropertyDecorator;

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

@@ -8,31 +8,51 @@ export interface ControllerOptions extends Partial<ProviderOpts<any>> {
     middlewares?: Partial<ControllerMiddlewares>;
 }
 /**
- * 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 declare function Controller(options: PathType | ControllerOptions): ClassDecorator;

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

@@ -11,22 +11,44 @@ export interface BindInjectablePropertyOpts<T = any> {
     transform?: TransformInjectedProviderCB<T>;
 }
 /**
- * Inject a provider to another provider.
+ * Inject a provider into a constructor parameter or property.
  *
- * Use this decorator to inject a custom provider on constructor parameter or property.
+ * Explicitly declares a dependency injection for constructor parameters or class properties.
+ * Supports custom tokens, transformations, and injection options.
+ *
+ * ### Usage
  *
  * ```typescript
+ * import {Injectable, Inject} from "@tsed/di";
+ *
+ * const CONNECTION = Symbol.for("CONNECTION");
+ *
  * @Injectable()
  * export class MyService {
+ *   // Property injection
  *   @Inject(CONNECTION)
- *   connection: CONNECTION;
+ *   connection: Database;
+ *
+ *   // Constructor injection
+ *   constructor(
+ *     @Inject(CONNECTION) private db: Database,
+ *     private otherService: OtherService // Auto-injected
+ *   ) {}
+ * }
+ *
+ * // With transformation
+ * @Injectable()
+ * export class ProcessorService {
+ *   @Inject(DataService, (service) => service.getData())
+ *   initialData: any[];
  * }
  * ```
  *
- * @param token A token provider or token provider group
- * @param transform
- * @returns {Function}
- * @decorator
+ * @typeParam T The type of the injected provider
+ * @param token The provider token to inject (optional for constructor params with TypeScript metadata)
+ * @param transform Optional transformation function or injection options
+ * @returns Decorator function (property or parameter)
+ * @public
  */
 export declare function Inject<T = any>(token?: TokenProvider<T> | (() => TokenProvider<T>), transform?: TransformInjectedProviderCB<T>): any;
 export declare function Inject<T = any>(token?: TokenProvider<T> | (() => TokenProvider<T>), opts?: Partial<Omit<BindInjectablePropertyOpts<T>, "token">>): any;