@tsed/di 8.18.1 → 8.19.0

package/lib/types/common/interfaces/AlterRunInContext.d.ts

@@ -1,3 +1,29 @@
+/**
+ * Interface for customizing the execution context of asynchronous operations.
+ *
+ * Implement this interface to wrap or modify the async context in which operations run,
+ * enabling custom context management, async local storage, or execution wrapping.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, AlterRunInContext} from "@tsed/di";
+ * import {AsyncLocalStorage} from "async_hooks";
+ *
+ * @Injectable()
+ * class CustomContextProvider implements AlterRunInContext {
+ *   private storage = new AsyncLocalStorage();
+ *
+ *   $alterRunInContext(next: Function) {
+ *     return () => {
+ *       return this.storage.run({requestId: generateId()}, next);
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface AlterRunInContext {
     $alterRunInContext(next: (...args: unknown[]) => unknown): () => unknown | Promise<() => unknown>;
 }

package/lib/types/common/interfaces/DILogger.d.ts

@@ -1,3 +1,39 @@
+/**
+ * Logger interface for the Dependency Injection system.
+ *
+ * Defines the contract for logging implementations used throughout Ts.ED's DI framework.
+ * Custom logger implementations must conform to this interface to be compatible with the DI system.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {DILogger} from "@tsed/di";
+ *
+ * class CustomLogger implements DILogger {
+ *   info(...args: any[]) {
+ *     console.log("[INFO]", ...args);
+ *   }
+ *
+ *   warn(...args: any[]) {
+ *     console.warn("[WARN]", ...args);
+ *   }
+ *
+ *   debug(...args: any[]) {
+ *     console.debug("[DEBUG]", ...args);
+ *   }
+ *
+ *   error(...args: any[]) {
+ *     console.error("[ERROR]", ...args);
+ *   }
+ *
+ *   trace(...args: any[]) {
+ *     console.trace("[TRACE]", ...args);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface DILogger {
     info(...args: any[]): void | any;
     warn(...args: any[]): void | any;

package/lib/types/common/interfaces/DILoggerOptions.d.ts

@@ -1,3 +1,26 @@
+/**
+ * Configuration options for the DI Logger.
+ *
+ * Controls logging behavior, formatting, and filtering for the Ts.ED logging system.
+ * These options can be set in the application configuration under the `logger` property.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Configuration} from "@tsed/di";
+ *
+ * @Configuration({
+ *   logger: {
+ *     level: "debug",
+ *     format: "%d{yyyy-MM-dd HH:mm:ss} %p %m",
+ *     disableRoutesSummary: false
+ *   }
+ * })
+ * class Server {}
+ * ```
+ *
+ * @public
+ */
 export interface DILoggerOptions {
     /**
      * Enable debug mode. By default debug is false.

package/lib/types/common/interfaces/ImportTokenProviderOpts.d.ts

@@ -1,19 +1,62 @@
 import type { AbstractType, Type } from "@tsed/core";
 import type { TokenProvider } from "./TokenProvider.js";
+/**
+ * Options for importing a provider with a predefined instance.
+ *
+ * @public
+ */
 export type UseImportTokenProviderOpts = {
     token: TokenProvider;
     use: unknown;
 };
+/**
+ * Options for importing a provider using a class constructor.
+ *
+ * @public
+ */
 export type UseClassImportTokenProviderOpts = {
     token: TokenProvider;
     useClass: Type | AbstractType<any>;
 };
+/**
+ * Options for importing a provider using a synchronous factory function.
+ *
+ * @public
+ */
 export type UseFactoryImportTokenProviderOpts = {
     token: TokenProvider;
     useFactory: (...args: unknown[]) => unknown;
 };
+/**
+ * Options for importing a provider using an asynchronous factory function.
+ *
+ * @public
+ */
 export type UseAsyncFactoryImportTokenProviderOpts = {
     token: TokenProvider;
     useAsyncFactory: (...args: unknown[]) => Promise<unknown>;
 };
+/**
+ * Union type representing all valid import provider configuration options.
+ *
+ * Specifies how an imported provider should be created when listed in module imports or configuration.
+ * Supports multiple creation strategies: predefined instances, class constructors, and factory functions.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Configuration} from "@tsed/di";
+ *
+ * @Configuration({
+ *   imports: [
+ *     {token: MyService, useClass: MyServiceImpl},
+ *     {token: "CONFIG", useFactory: () => loadConfig()},
+ *     {token: DatabaseService, useAsyncFactory: async () => await connectDB()}
+ *   ]
+ * })
+ * class Server {}
+ * ```
+ *
+ * @public
+ */
 export type ImportTokenProviderOpts = UseImportTokenProviderOpts | UseClassImportTokenProviderOpts | UseFactoryImportTokenProviderOpts | UseAsyncFactoryImportTokenProviderOpts;

package/lib/types/common/interfaces/InterceptorContext.d.ts

@@ -1,7 +1,42 @@
 import type { Type } from "@tsed/core";
+/**
+ * Function signature for proceeding to the next interceptor or method.
+ *
+ * Call this function in an interceptor to continue the interceptor chain.
+ * Pass an error to short-circuit execution and propagate the error.
+ *
+ * @typeParam T - The return type of the intercepted method
+ * @public
+ */
 export interface InterceptorNext {
     <T>(err?: Error): T;
 }
+/**
+ * Context object passed to interceptors during method execution.
+ *
+ * Provides access to the target instance, method name, arguments, and control flow
+ * for intercepting and modifying method behavior.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {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;
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam Klass - The type of the target class
+ * @typeParam Opts - The type of interceptor options
+ * @public
+ */
 export interface InterceptorContext<Klass = Type, Opts = any> {
     target: Klass;
     propertyKey: string | symbol;

package/lib/types/common/interfaces/InterceptorMethods.d.ts

@@ -1,4 +1,31 @@
 import type { InterceptorContext, InterceptorNext } from "./InterceptorContext.js";
+/**
+ * Interface for implementing method interceptors.
+ *
+ * Interceptors can modify method behavior, add logging, handle errors, or implement cross-cutting concerns.
+ * Classes decorated with `@Interceptor()` must implement this interface.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Interceptor, InterceptorContext, InterceptorMethods} from "@tsed/di";
+ *
+ * @Interceptor()
+ * class CacheInterceptor implements InterceptorMethods {
+ *   intercept(context: InterceptorContext) {
+ *     const cacheKey = `${context.propertyKey.toString()}:${JSON.stringify(context.args)}`;
+ *     if (cache.has(cacheKey)) {
+ *       return cache.get(cacheKey);
+ *     }
+ *     const result = context.next();
+ *     cache.set(cacheKey, result);
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface InterceptorMethods {
     intercept(context: InterceptorContext, next?: InterceptorNext): any;
 }

package/lib/types/common/interfaces/InvokeOptions.d.ts

@@ -1,5 +1,13 @@
 import type { LocalsContainer } from "../domain/LocalsContainer.js";
 import { TokenProvider } from "./TokenProvider.js";
+/**
+ * Options for invoking and building a provider instance.
+ *
+ * Controls how the injector resolves dependencies, handles imports, and constructs provider instances.
+ * Used when manually invoking the injector to create instances with specific configuration.
+ *
+ * @public
+ */
 export interface InvokeOptions {
     /**
      * Define dependencies to build the provider and inject them in the constructor.

package/lib/types/common/interfaces/OnDestroy.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Lifecycle hook interface for cleanup logic.
+ *
+ * Implement this interface to execute custom cleanup code when a provider instance is destroyed by the DI container.
+ * The `$onDestroy` method is called automatically during application shutdown or when the provider scope ends.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, OnDestroy} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyService implements OnDestroy {
+ *   async $onDestroy() {
+ *     // Close connections, release resources, etc.
+ *     await this.disconnect();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface OnDestroy {
     $onDestroy(): Promise<any> | void;
 }

package/lib/types/common/interfaces/OnInit.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Lifecycle hook interface for initialization logic.
+ *
+ * Implement this interface to execute custom initialization code when a provider instance is created by the DI container.
+ * The `$onInit` method is called automatically after the instance is constructed and dependencies are injected.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * import {Injectable, OnInit} from "@tsed/di";
+ *
+ * @Injectable()
+ * class MyService implements OnInit {
+ *   async $onInit() {
+ *     // Initialize database connection, load configuration, etc.
+ *     await this.connect();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface OnInit {
     $onInit(): Promise<any> | void;
 }

package/lib/types/common/interfaces/ProviderOpts.d.ts

@@ -2,6 +2,37 @@ import type { Type } from "@tsed/core";
 import type { ProviderScope } from "../domain/ProviderScope.js";
 import type { ProviderType } from "../domain/ProviderType.js";
 import type { TokenProvider } from "./TokenProvider.js";
+/**
+ * Configuration options for registering a provider in the DI container.
+ *
+ * Defines how a provider should be created, managed, and resolved by the injector.
+ * Supports multiple creation strategies including class instantiation, factory functions, and predefined values.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // Using a class
+ * const opts1: ProviderOpts = {
+ *   token: MyService,
+ *   useClass: MyService
+ * };
+ *
+ * // Using a factory
+ * const opts2: ProviderOpts = {
+ *   token: "CONFIG",
+ *   useFactory: () => loadConfig()
+ * };
+ *
+ * // Using a value
+ * const opts3: ProviderOpts = {
+ *   token: "API_KEY",
+ *   useValue: "secret-key"
+ * };
+ * ```
+ *
+ * @typeParam T - The type of instance provided by this provider
+ * @public
+ */
 export interface ProviderOpts<T = any> {
     /**
      * An injection token. (Typically an instance of `Type` or `InjectionToken`, but can be `any`).

package/lib/types/common/interfaces/ResolvedInvokeOptions.d.ts

@@ -1,6 +1,15 @@
 import type { LocalsContainer } from "../domain/LocalsContainer.js";
 import type { Provider } from "../domain/Provider.js";
 import type { TokenProvider } from "./TokenProvider.js";
+/**
+ * Resolved invocation options used internally by the injector.
+ *
+ * Contains fully resolved dependencies, provider metadata, and construction logic
+ * prepared by the injector before instantiating a provider.
+ *
+ * @internal
+ * @public
+ */
 export interface ResolvedInvokeOptions {
     token: TokenProvider;
     parent?: TokenProvider;

package/lib/types/common/interfaces/TokenProvider.d.ts

@@ -1,9 +1,39 @@
 import type { AbstractType, Type } from "@tsed/core";
 /**
- * A token is a unique identifier for a provider in the dependency injection system.
- * It solves the inference problem when using `inject()` function.
+ * Factory token type with type inference support.
+ *
+ * A branded type that enables type inference when using the `inject()` function.
+ * This token type carries runtime type information to solve TypeScript's inference limitations in DI scenarios.
+ *
+ * @typeParam T - The type of value provided by this token
+ * @public
  */
 export type FactoryTokenProvider<T = any> = T & {
     readonly __type: "token_factory";
 };
+/**
+ * Union type representing all valid provider tokens in the DI system.
+ *
+ * A token uniquely identifies a provider in the dependency injection container.
+ * Tokens can be strings, symbols, class constructors, or factory tokens with type inference.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * // String token
+ * const token1: TokenProvider = "MY_SERVICE";
+ *
+ * // Symbol token
+ * const token2: TokenProvider = Symbol.for("MY_SERVICE");
+ *
+ * // Class token
+ * const token3: TokenProvider = MyService;
+ *
+ * // Factory token with inference
+ * const token4 = inject<MyService>();
+ * ```
+ *
+ * @typeParam T - The type of value provided by this token
+ * @public
+ */
 export type TokenProvider<T = any> = string | symbol | Type<T> | AbstractType<T> | FactoryTokenProvider<T>;

package/lib/types/common/interfaces/TokenRoute.d.ts

@@ -1,4 +1,20 @@
 import { TokenProvider } from "./TokenProvider.js";
+/**
+ * Associates a provider token with a route path.
+ *
+ * Used to map controllers or route handlers to specific URL paths in the routing system.
+ *
+ * ### Usage
+ *
+ * ```typescript
+ * const route: TokenRoute = {
+ *   token: MyController,
+ *   route: "/api/users"
+ * };
+ * ```
+ *
+ * @public
+ */
 export interface TokenRoute {
     token: TokenProvider;
     route: string;

package/lib/types/common/services/DIConfiguration.d.ts

@@ -3,6 +3,30 @@ import type { DILoggerOptions } from "../interfaces/DILoggerOptions.js";
 import type { ImportTokenProviderOpts } from "../interfaces/ImportTokenProviderOpts.js";
 import type { TokenProvider } from "../interfaces/TokenProvider.js";
 import type { TokenRoute } from "../interfaces/TokenRoute.js";
+/**
+ * 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 declare class DIConfiguration {
     readonly default: Map<string, any>;
     protected map: Map<string, any>;

package/lib/types/common/services/DILogger.d.ts

@@ -1,3 +1,31 @@
 import { DILogger } from "../interfaces/DILogger.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 declare const LOGGER: unique symbol;
+/**
+ * Type alias for the injected logger instance.
+ *
+ * @public
+ */
 export type LOGGER = DILogger;