@tsed/di 8.18.2 → 8.19.0

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

@@ -1,10 +1,39 @@
 import { TokenProvider } from "../interfaces/TokenProvider.js";
 import { Provider } from "./Provider.js";
+/**
+ * Middleware configuration for a controller.
+ *
+ * Defines middleware tokens to be applied at different stages of request processing.
+ *
+ * @public
+ */
 export interface ControllerMiddlewares {
     useBefore: TokenProvider[];
     use: TokenProvider[];
     useAfter: TokenProvider[];
 }
+/**
+ * Specialized provider for HTTP controllers.
+ *
+ * Extends the base `Provider` class with controller-specific metadata like middleware configuration
+ * and routing information. Used internally to manage HTTP route controllers in the DI system.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {ControllerProvider} from "@tsed/di";
+ *
+ * const provider = new ControllerProvider(MyController);
+ * provider.middlewares = {
+ *   useBefore: [AuthMiddleware],
+ *   use: [ValidationMiddleware],
+ *   useAfter: [LoggingMiddleware]
+ * };
+ * ```
+ *
+ * @typeParam T - The type of controller class
+ * @public
+ */
 export declare class ControllerProvider<T = any> extends Provider<T> {
     tokenRouter: string;
     constructor(token: TokenProvider, options?: Partial<Provider>);

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

@@ -1,9 +1,36 @@
 import { InjectorService, LocalsContainer } from "../index.js";
 import { ContextLogger, ContextLoggerOptions } from "./ContextLogger.js";
+/**
+ * Options for creating a DI context instance.
+ *
+ * @public
+ */
 export interface DIContextOptions extends Omit<ContextLoggerOptions, "dateStart"> {
     id: string;
     platform?: string;
 }
+/**
+ * Execution context for dependency injection operations.
+ *
+ * Represents a single execution scope (typically an HTTP request) with its own
+ * scoped provider instances, logger, and lifecycle management. Provides access to
+ * request-scoped services and context-specific data.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {DIContext} from "@tsed/di";
+ *
+ * const context = new DIContext({id: "req-123"});
+ *
+ * context.logger.info("Processing request");
+ * const service = await context.injector.invoke(MyService, context.container);
+ *
+ * await context.destroy(); // Cleanup when done
+ * ```
+ *
+ * @public
+ */
 export declare class DIContext {
     #private;
     opts: DIContextOptions;

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

@@ -1,3 +1,19 @@
+/**
+ * Enumeration defining types of injectable properties and decorators.
+ *
+ * Used internally to track and classify different kinds of injected dependencies
+ * and decorated members within a class.
+ *
+ * ### Types
+ *
+ * - `METHOD`: Injectable method parameter
+ * - `PROPERTY`: Injectable class property
+ * - `CONSTANT`: Injected constant value
+ * - `VALUE`: Injected configured value
+ * - `INTERCEPTOR`: Interceptor applied to a method
+ *
+ * @public
+ */
 export declare enum InjectablePropertyType {
     METHOD = "method",
     PROPERTY = "property",

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

@@ -1,5 +1,26 @@
 import { Hooks } from "@tsed/hooks";
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
+/**
+ * Container for request-scoped and instance-scoped provider instances.
+ *
+ * Stores instances created within a specific execution context (like an HTTP request).
+ * Manages lifecycle hooks and destruction of scoped instances when the context ends.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {LocalsContainer} from "@tsed/di";
+ *
+ * const locals = new LocalsContainer();
+ * locals.set(MyService, serviceInstance);
+ *
+ * const instance = locals.get(MyService);
+ *
+ * await locals.destroy(); // Cleanup when context ends
+ * ```
+ *
+ * @public
+ */
 export declare class LocalsContainer extends Map<TokenProvider, any> {
     readonly hooks: Hooks;
     destroy(): Promise<void>;

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

@@ -4,7 +4,32 @@ import type { ProviderOpts } from "../interfaces/ProviderOpts.js";
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 import { ProviderScope } from "./ProviderScope.js";
 import { ProviderType } from "./ProviderType.js";
+/**
+ * Callback function type for provider lifecycle hooks.
+ *
+ * @typeParam T - The type of provider instance
+ * @public
+ */
 export type ProviderHookCallback<T = any> = (instance: T, ...args: unknown[]) => Promise<void> | void;
+/**
+ * Provider metadata class managing dependency injection configuration.
+ *
+ * Encapsulates all information needed to create, configure, and manage a provider instance
+ * within the DI container. Tracks dependencies, lifecycle hooks, creation strategies, and metadata.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Provider, ProviderType} from "@tsed/di";
+ *
+ * const provider = new Provider(MyService);
+ * provider.type = ProviderType.PROVIDER;
+ * provider.deps = [DatabaseService, LoggerService];
+ * ```
+ *
+ * @typeParam T - The type of instance this provider creates
+ * @public
+ */
 export declare class Provider<T = any> implements ProviderOpts<T> {
     #private;
     /**

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

@@ -1,3 +1,28 @@
+/**
+ * Enumeration defining the lifecycle scopes for provider instances.
+ *
+ * Determines when and how provider instances are created and shared across the application.
+ *
+ * ### Scopes
+ *
+ * - `SINGLETON`: One instance shared across the entire application (default)
+ * - `REQUEST`: New instance created for each request/context
+ * - `INSTANCE`: New instance created on every injection
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, Scope, ProviderScope} from "@tsed/di";
+ *
+ * @Injectable()
+ * @Scope(ProviderScope.REQUEST)
+ * class RequestScopedService {
+ *   // New instance per request
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare enum ProviderScope {
     SINGLETON = "singleton",
     REQUEST = "request",

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

@@ -1,3 +1,28 @@
+/**
+ * Enumeration categorizing different types of providers in the DI system.
+ *
+ * Used to classify and filter providers based on their role in the application architecture.
+ * Each type represents a distinct pattern or responsibility within the framework.
+ *
+ * ### Types
+ *
+ * - `VALUE`: Simple value providers (constants, configuration)
+ * - `PROVIDER`: Standard service providers
+ * - `MODULE`: Module providers organizing related functionality
+ * - `CONTROLLER`: HTTP route controllers
+ * - `INTERCEPTOR`: Method interceptors for cross-cutting concerns
+ * - `MIDDLEWARE`: Request/response middleware
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {ProviderType} from "@tsed/di";
+ *
+ * const providers = container.getProviders(ProviderType.CONTROLLER);
+ * ```
+ *
+ * @public
+ */
 export declare enum ProviderType {
     VALUE = "value",
     PROVIDER = "provider",

package/lib/types/common/errors/InjectionError.d.ts

@@ -1,4 +1,28 @@
 import { TokenProvider } from "../interfaces/TokenProvider.js";
+/**
+ * Error thrown when dependency injection fails.
+ *
+ * Provides detailed information about the failed injection including the dependency chain
+ * and the original error. Helps diagnose circular dependencies, missing providers, and
+ * configuration issues in the DI system.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {InjectionError} from "@tsed/di";
+ *
+ * try {
+ *   injector.invoke(MyService);
+ * } catch (error) {
+ *   if (error instanceof InjectionError) {
+ *     console.log("Dependency chain:", error.tokens);
+ *     console.log("Original error:", error.origin);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export declare class InjectionError extends Error {
     name: string;
     tokens: TokenProvider[];

package/lib/types/common/errors/InvalidPropertyTokenError.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Error thrown when an invalid token is used for property injection.
+ *
+ * Typically indicates a circular reference, missing import, or undefined token
+ * in property decorators like `@Inject()` or `@Constant()`.
+ *
+ * ### Common causes
+ *
+ * - Circular dependency between classes
+ * - Missing or incorrect import statement
+ * - Using `undefined` as a token
+ * - Forward reference not properly handled
+ *
+ * @public
+ */
 export declare class InvalidPropertyTokenError extends Error {
     name: string;
     constructor(target: any, propertyKey: string);

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

@@ -1,5 +1,36 @@
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 import { DIConfiguration } from "../services/DIConfiguration.js";
+/**
+ * Get or set configuration for a provider or the global injector settings.
+ *
+ * ### Overloads
+ *
+ * - `configuration()` - Returns the global DI configuration
+ * - `configuration(token)` - Returns the stored configuration for a provider
+ * - `configuration(token, config)` - Sets and returns configuration for a provider
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {configuration, Injectable} from "@tsed/di";
+ *
+ * // Get global configuration
+ * const settings = configuration();
+ *
+ * // Set provider configuration
+ * @Injectable()
+ * class MyService {}
+ * configuration(MyService, {custom: "value"});
+ *
+ * // Get provider configuration
+ * const config = configuration(MyService);
+ * ```
+ *
+ * @param token Optional provider token to get/set configuration for
+ * @param configuration Optional configuration to set
+ * @returns The configuration object
+ * @public
+ */
 export declare function configuration(): TsED.Configuration & DIConfiguration;
 export declare function configuration(token: TokenProvider): Partial<TsED.Configuration>;
 export declare function configuration(token: TokenProvider, configuration: Partial<TsED.Configuration>): Partial<TsED.Configuration>;

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

@@ -1,2 +1,24 @@
+/**
+ * Get a constant value from the injector configuration settings.
+ *
+ * Retrieves a configuration value using dot notation path syntax.
+ * Useful for accessing environment variables, configuration constants, or settings.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {constant} from "@tsed/di";
+ *
+ * const apiKey = constant<string>("api.key");
+ * const port = constant<number>("server.port", 3000);
+ * const debug = constant<boolean>("logger.debug", false);
+ * ```
+ *
+ * @typeParam Type The expected type of the constant value
+ * @param expression Dot-notation path to the configuration value (e.g., "logger.level")
+ * @param defaultValue Optional default value if the expression is not found
+ * @returns The configuration value or undefined
+ * @public
+ */
 export declare function constant<Type>(expression: string): Type | undefined;
 export declare function constant<Type>(expression: string, defaultValue: Type | undefined): Type;

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

@@ -1,20 +1,33 @@
 import type { InvokeOptions } from "../interfaces/InvokeOptions.js";
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 /**
- * Inject a provider to another provider.
+ * Programmatically inject a provider instance.
  *
- * Use this function to inject a custom provider on constructor parameter or property.
+ * Resolves and returns a provider instance using the global injector.
+ * Useful for injecting dependencies outside of decorators or in property initializers.
+ *
+ * ### Usage
  *
  * ```typescript
+ * import {inject, Injectable} from "@tsed/di";
+ *
  * @Injectable()
  * export class MyService {
+ *   // Property injection
  *   connection = inject(CONNECTION);
+ *
+ *   // Function injection
+ *   getData() {
+ *     const api = inject(ApiService);
+ *     return api.fetch();
+ *   }
  * }
  * ```
  *
- * @param token A token provider or token provider group
- * @param opts
- * @returns {Function}
- * @decorator
+ * @typeParam TokenType The type of the injected provider
+ * @param token The provider token to resolve
+ * @param opts Optional invocation options (locals, rebuild, useOpts)
+ * @returns The resolved provider instance
+ * @public
  */
 export declare function inject<TokenType>(token: TokenProvider<TokenType>, opts?: Partial<Pick<InvokeOptions, "useOpts" | "rebuild" | "locals">>): TokenType;

package/lib/types/common/fn/injectMany.d.ts

@@ -1,11 +1,29 @@
 import type { InvokeOptions } from "../interfaces/InvokeOptions.js";
 /**
- * Injects multiple instances of a given token using the injector service.
- * @param token - The injection token to resolve
- * @param opts - Optional configuration for the injection
- * @param opts.useOpts - Options for instance creation
- * @param opts.rebuild - Whether to rebuild the instance
- * @param opts.locals - Local container overrides
+ * Inject all providers matching a given token type.
+ *
+ * Resolves multiple provider instances that share the same type or group token.
+ * Useful for getting all providers of a specific category (e.g., all controllers, all middleware).
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {injectMany, ProviderType} from "@tsed/di";
+ *
+ * // Get all controllers
+ * const controllers = injectMany(ProviderType.CONTROLLER);
+ *
+ * // Get all providers of a custom type
+ * const plugins = injectMany(Symbol.for("PLUGIN"));
+ * ```
+ *
+ * @typeParam T The type of instances to return
+ * @param token The injection token or type to resolve
+ * @param opts Optional invocation options
+ * @param opts.useOpts Options passed to instance creation
+ * @param opts.rebuild Whether to rebuild instances
+ * @param opts.locals Local container overrides
  * @returns Array of resolved instances
+ * @public
  */
 export declare function injectMany<T>(token: string | symbol, opts?: Partial<Pick<InvokeOptions, "useOpts" | "rebuild" | "locals">>): T[];

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

@@ -1,7 +1,64 @@
 import { ControllerProvider } from "../domain/ControllerProvider.js";
 import type { Provider } from "../domain/Provider.js";
 type PickedProps = "scope" | "path" | "alias" | "hooks" | "deps" | "imports" | "configuration" | "priority";
+/**
+ * Fluent builder for registering providers programmatically.
+ *
+ * Creates or configures a provider with the specified options.
+ * Can be chained with additional configuration methods.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {injectable} from "@tsed/di";
+ *
+ * injectable(MyService)
+ *   .scope(ProviderScope.REQUEST)
+ *   .deps([DatabaseService])
+ *   .build();
+ *
+ * // With factory
+ * injectable("CONFIG")
+ *   .factory(() => loadConfig())
+ *   .build();
+ * ```
+ *
+ * @public
+ */
 export declare const injectable: import("../utils/providerBuilder.js").ProviderBuilderFn<Provider<any>, "type" | PickedProps>;
+/**
+ * Fluent builder for registering interceptor providers.
+ *
+ * Specialized version of `injectable` that automatically sets the provider type to `INTERCEPTOR`.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {interceptor} from "@tsed/di";
+ *
+ * interceptor(LogInterceptor).build();
+ * ```
+ *
+ * @public
+ */
 export declare const interceptor: import("../utils/providerBuilder.js").ProviderBuilderFn<Provider<any>, "type" | PickedProps>;
+/**
+ * Fluent builder for registering controller providers.
+ *
+ * Specialized version of `injectable` that automatically sets the provider type to `CONTROLLER`
+ * and supports controller-specific options like middlewares.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {controller} from "@tsed/di";
+ *
+ * controller(UsersController)
+ *   .middlewares({useBefore: [AuthMiddleware]})
+ *   .build();
+ * ```
+ *
+ * @public
+ */
 export declare const controller: import("../utils/providerBuilder.js").ProviderBuilderFn<ControllerProvider<any>, "children" | "middlewares" | PickedProps>;
 export {};

package/lib/types/common/fn/injector.d.ts

@@ -1,8 +1,11 @@
 import { InjectorService } from "../services/InjectorService.js";
 /**
- * Return the existing injector service.
+ * Get the global injector service instance.
  *
- * Example:
+ * Returns the singleton instance of `InjectorService` managing all registered providers.
+ * Use this to access the DI container programmatically.
+ *
+ * ### Usage
  *
  * ```typescript
  * import {injector, Injectable} from "@tsed/di";
@@ -10,8 +13,24 @@ import { InjectorService } from "../services/InjectorService.js";
  * @Injectable()
  * class MyService {
  *   injector = injector();
+ *
+ *   getService() {
+ *     return injector().get(OtherService);
+ *   }
  * }
  * ```
+ *
+ * @returns The global injector service instance
+ * @public
  */
 export declare function injector(): InjectorService;
+/**
+ * Destroy the current injector and create a fresh instance.
+ *
+ * Calls the `destroy()` lifecycle hook on all providers and resets the global injector.
+ * Primarily used in testing to reset the DI container between tests.
+ *
+ * @returns Promise that resolves when destruction is complete
+ * @public
+ */
 export declare function destroyInjector(): Promise<void>;

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

@@ -1,10 +1,57 @@
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 /**
- * Lazy load a provider from his package and invoke only when the provider is used.
+ * Lazily load and inject a provider from a dynamic import.
+ *
+ * Loads the provider module asynchronously, registers it if needed, calls `$onInit` if present,
+ * and returns the resolved instance. Useful for code splitting and lazy loading dependencies.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {lazyInject} from "@tsed/di";
+ *
+ * // Lazy load a service
+ * const service = await lazyInject(() => import("./HeavyService"));
+ *
+ * // Use in a method
+ * async loadPlugin() {
+ *   const plugin = await lazyInject(() => import("./plugins/MyPlugin"));
+ *   return plugin.initialize();
+ * }
+ * ```
+ *
+ * @typeParam Token The type of the provider to inject
+ * @param factory Function returning a dynamic import promise with a default export
+ * @returns Promise resolving to the provider instance
+ * @public
  */
 export declare function lazyInject<Token>(factory: () => Promise<{
     default: TokenProvider<Token>;
 }>): Promise<Token>;
+/**
+ * Attempt to lazily load and inject a provider, returning undefined on failure.
+ *
+ * Similar to `lazyInject` but catches errors and returns undefined instead of throwing.
+ * Useful for optional dependencies that may not be available.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {optionalLazyInject} from "@tsed/di";
+ *
+ * // Try to load optional plugin
+ * const plugin = await optionalLazyInject(() => import("./optional/Plugin"));
+ *
+ * if (plugin) {
+ *   plugin.activate();
+ * }
+ * ```
+ *
+ * @typeParam Token The type of the provider to inject
+ * @param factory Function returning a dynamic import promise with a default export
+ * @returns Promise resolving to the provider instance or undefined if loading fails
+ * @public
+ */
 export declare function optionalLazyInject<Token>(factory: () => Promise<{
     default: TokenProvider;
 }>): Promise<Token | undefined>;

package/lib/types/common/fn/localsContainer.d.ts

@@ -1,7 +1,31 @@
 import { LocalsContainer } from "../domain/LocalsContainer.js";
 import type { UseImportTokenProviderOpts } from "../interfaces/ImportTokenProviderOpts.js";
 /**
- * Get the locals container initiated by DITest or .bootstrap() method.
+ * Get or create the current locals container for request-scoped providers.
+ *
+ * Returns the global locals container used for storing request-scoped provider instances.
+ * Can optionally create a new container with custom providers.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {localsContainer} from "@tsed/di";
+ *
+ * // Get current locals
+ * const locals = localsContainer();
+ *
+ * // Create with custom providers
+ * const locals = localsContainer({
+ *   providers: [{token: MyService, use: mockInstance}],
+ *   rebuild: true
+ * });
+ * ```
+ *
+ * @param options Configuration options
+ * @param options.providers Optional array of provider overrides
+ * @param options.rebuild Whether to mark providers for rebuilding
+ * @returns The locals container instance
+ * @public
  */
 export declare function localsContainer({ providers, rebuild }?: {
     providers?: UseImportTokenProviderOpts[];
@@ -9,7 +33,12 @@ export declare function localsContainer({ providers, rebuild }?: {
 }): LocalsContainer;
 export declare function invokeOptions(): any;
 /**
- * Reset the locals container.
+ * Detach and stage the current locals container.
+ *
+ * Removes the global locals reference and saves it for cleanup.
+ * Used internally to manage request scope lifecycle.
+ *
+ * @public
  */
 export declare function detachLocalsContainer(): void;
 export declare function cleanAllLocalsContainer(): void;

package/lib/types/common/fn/logger.d.ts

@@ -1,4 +1,18 @@
 /**
- * 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 declare function logger(): import("../index.js").DILogger;

package/lib/types/common/fn/refValue.d.ts

@@ -1,21 +1,30 @@
 /**
- * Get a value from the `injector.settings`.
+ * Create a reactive reference to a configuration value.
  *
- * ## Example
+ * Returns an object with a `value` getter that always fetches the current configuration value.
+ * Useful for creating properties that stay synchronized with configuration changes.
  *
- * ```ts
+ * ### Usage
+ *
+ * ```typescript
  * import {refValue, Injectable} from "@tsed/di";
  *
  * @Injectable()
  * class Test {
- *   test = refValue("logger.level", "default value");
+ *   logLevel = refValue<string>("logger.level", "info");
+ *   port = refValue<number>("server.port");
  *
  *   constructor() {
- *     console.log(this.test.value); // "off"
+ *     console.log(this.logLevel.value); // Always current value
  *   }
  * }
+ * ```
  *
- * @param expression The expression to get the value from the `injector.settings`.
+ * @typeParam Type The expected type of the value
+ * @param expression Dot-notation path to the configuration value
+ * @param defaultValue Optional default value if the expression is not found
+ * @returns A frozen object with a reactive `value` property
+ * @public
  */
 export declare function refValue<Type>(expression: string): {
     value: Type | undefined;