@tsed/di 8.18.1 → 8.19.0

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

@@ -15,38 +15,44 @@ export function bindValue(target, propertyKey, expression, defaultValue) {
     catchError(() => Reflect.defineProperty(target, propertyKey, descriptor));
 }
 /**
- * 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 function Value(expression, defaultValue) {

package/lib/esm/common/domain/Container.js

@@ -1,5 +1,25 @@
 import { GlobalProviders } from "../registries/GlobalProviders.js";
 import { Provider } from "./Provider.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 class Container extends Map {
     /**
      *

package/lib/esm/common/domain/ContextLogger.js

@@ -2,6 +2,27 @@ import { Hooks } from "@tsed/hooks";
 import { levels } from "@tsed/logger";
 import { logger as injectLogger } from "../../common/index.js";
 const LEVELS = levels();
+/**
+ * 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 class ContextLogger {
     #additionalProps;
     #level;

package/lib/esm/common/domain/ControllerProvider.js

@@ -1,5 +1,27 @@
 import { Provider } from "./Provider.js";
 import { ProviderType } from "./ProviderType.js";
+/**
+ * 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 class ControllerProvider extends Provider {
     constructor(token, options = {}) {
         super(token, options);

package/lib/esm/common/domain/DIContext.js

@@ -1,5 +1,27 @@
 import { injector, LocalsContainer } from "../index.js";
 import { ContextLogger } from "./ContextLogger.js";
+/**
+ * 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 class DIContext {
     #container;
     #cache;

package/lib/esm/common/domain/InjectablePropertyType.js

@@ -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 var InjectablePropertyType;
 (function (InjectablePropertyType) {
     InjectablePropertyType["METHOD"] = "method";

package/lib/esm/common/domain/LocalsContainer.js

@@ -1,4 +1,25 @@
 import { Hooks } from "@tsed/hooks";
+/**
+ * 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 class LocalsContainer extends Map {
     constructor() {
         super(...arguments);

package/lib/esm/common/domain/Provider.js

@@ -7,6 +7,25 @@ import { DI_USE_PARAM_OPTIONS } from "../constants/constants.js";
 import { discoverHooks } from "../utils/discoverHooks.js";
 import { ProviderScope } from "./ProviderScope.js";
 import { ProviderType } from "./ProviderType.js";
+/**
+ * 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 class Provider {
     #useClass;
     #token;

package/lib/esm/common/domain/ProviderScope.js

@@ -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 var ProviderScope;
 (function (ProviderScope) {
     ProviderScope["SINGLETON"] = "singleton";

package/lib/esm/common/domain/ProviderType.js

@@ -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 var ProviderType;
 (function (ProviderType) {
     ProviderType["VALUE"] = "value";

package/lib/esm/common/errors/InjectionError.js

@@ -3,6 +3,30 @@ import { isClass } from "@tsed/core/utils/isClass.js";
 import { isString } from "@tsed/core/utils/isString.js";
 import { nameOf } from "@tsed/core/utils/nameOf.js";
 import { colors } from "../utils/colors.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 class InjectionError extends Error {
     constructor(token, origin) {
         super(isString(origin) ? origin : "");

package/lib/esm/common/errors/InvalidPropertyTokenError.js

@@ -1,5 +1,20 @@
 import { classOf } from "@tsed/core/utils/classOf.js";
 import { nameOf } from "@tsed/core/utils/nameOf.js";
+/**
+ * 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 class InvalidPropertyTokenError extends Error {
     constructor(target, propertyKey) {
         super(`Object isn't a valid token. Please check the token set on ${nameOf(classOf(target))}.${propertyKey}.\n- Check that it is not a circular reference.\n- Check that the token (class or symbol) exists`);

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

@@ -1,21 +1,34 @@
 import { injector } from "./injector.js";
 import { invokeOptions, localsContainer } from "./localsContainer.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 function inject(token, opts) {
     return injector().resolve(token, {

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

@@ -1,13 +1,31 @@
 import { injector } from "./injector.js";
 import { localsContainer } from "./localsContainer.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 function injectMany(token, opts) {
     return injector().getMany(token, { ...opts, locals: opts?.locals || localsContainer() });

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

@@ -1,10 +1,67 @@
 import { ProviderType } from "../domain/ProviderType.js";
 import { providerBuilder } from "../utils/providerBuilder.js";
 const Props = ["type", "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 const injectable = providerBuilder(Props);
+/**
+ * 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 const interceptor = providerBuilder(Props, {
     type: ProviderType.INTERCEPTOR
 });
+/**
+ * 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 const controller = providerBuilder([...Props, "middlewares"], {
     type: ProviderType.CONTROLLER
 });

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

@@ -1,9 +1,12 @@
 import { InjectorService } from "../services/InjectorService.js";
 let globalInjector = new InjectorService();
 /**
- * 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";
@@ -11,12 +14,28 @@ let globalInjector = new InjectorService();
  * @Injectable()
  * class MyService {
  *   injector = injector();
+ *
+ *   getService() {
+ *     return injector().get(OtherService);
+ *   }
  * }
  * ```
+ *
+ * @returns The global injector service instance
+ * @public
  */
 export function injector() {
     return globalInjector;
 }
+/**
+ * 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 async function destroyInjector() {
     await globalInjector.destroy();
     globalInjector = new InjectorService();

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

@@ -2,7 +2,30 @@ import { isFunction } from "@tsed/core/utils/isFunction.js";
 import { inject } from "./inject.js";
 import { injector } from "./injector.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 async function lazyInject(factory) {
     const { default: token } = await factory();
@@ -15,6 +38,30 @@ export async function lazyInject(factory) {
     }
     return injector().get(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 async function optionalLazyInject(factory) {
     try {
         return await lazyInject(factory);

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

@@ -5,7 +5,31 @@ let globalLocals;
 let globalInvOpts = {};
 const stagedLocals = [];
 /**
- * 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 function localsContainer({ providers, rebuild } = {}) {
     if (!globalLocals || providers) {
@@ -26,7 +50,12 @@ export function invokeOptions() {
     return { ...globalInvOpts };
 }
 /**
- * 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 function detachLocalsContainer() {
     globalLocals && stagedLocals.push(globalLocals);