@nextrush/di 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,517 @@
+/**
+ * @nextrush/di - Types
+ *
+ * Type definitions for the dependency injection container.
+ */
+/**
+ * Token used to identify a dependency in the container.
+ * Can be a class constructor, string, or symbol.
+ */
+type Token<T = unknown> = Constructor<T> | string | symbol;
+/**
+ * Constructor type for class-based tokens.
+ */
+type Constructor<T = unknown> = new (...args: unknown[]) => T;
+/**
+ * Provider that uses a class constructor.
+ */
+interface ClassProvider<T> {
+    useClass: Constructor<T>;
+}
+/**
+ * Provider that uses a factory function.
+ *
+ * Without `inject`: factory receives the container.
+ * With `inject`: factory receives resolved dependencies in order.
+ *
+ * @example Without inject
+ * ```typescript
+ * container.register('DB', {
+ *   useFactory: (c) => new Database(c.resolve(ConfigService).dbUrl),
+ * });
+ * ```
+ *
+ * @example With inject
+ * ```typescript
+ * container.register('DB', {
+ *   useFactory: (config: ConfigService) => new Database(config.dbUrl),
+ *   inject: [ConfigService],
+ * });
+ * ```
+ *
+ * @example Async factory (auto-resolved by bootstrap)
+ * ```typescript
+ * container.register('DB', {
+ *   useFactory: async (config: ConfigService) => {
+ *     const db = new Database(config.dbUrl);
+ *     await db.connect();
+ *     return db;
+ *   },
+ *   inject: [ConfigService],
+ * });
+ * // Controllers plugin calls bootstrap() automatically.
+ * // For functional mode: await container.bootstrap()
+ * ```
+ */
+interface FactoryProvider<T> {
+    useFactory: (...args: unknown[]) => T | Promise<T>;
+    inject?: Token[];
+}
+/**
+ * Provider that uses a constant value.
+ */
+interface ValueProvider<T> {
+    useValue: T;
+}
+/**
+ * Union of all provider types.
+ */
+type Provider<T> = ClassProvider<T> | FactoryProvider<T> | ValueProvider<T>;
+/**
+ * Lifecycle scope for registered services.
+ */
+type Scope = 'singleton' | 'transient';
+/**
+ * Options for service registration.
+ */
+interface ServiceOptions {
+    scope?: Scope;
+}
+/**
+ * Container interface for dependency injection operations.
+ */
+interface ContainerInterface {
+    /**
+     * Register a dependency with the container.
+     *
+     * @param token - The token to register
+     * @param provider - The provider (class, value, or factory)
+     * @param options - Optional registration options
+     */
+    register<T>(token: Token<T>, provider: Provider<T>, options?: RegisterOptions): void;
+    /**
+     * Resolve a dependency from the container (synchronous).
+     */
+    resolve<T>(token: Token<T>): T;
+    /**
+     * Resolve a dependency that may have been registered with an async factory.
+     * Awaits the result if the factory returns a Promise.
+     *
+     * Prefer `bootstrap()` over calling this for each async provider.
+     */
+    resolveAsync<T>(token: Token<T>): Promise<T>;
+    /**
+     * Bootstrap all factory providers.
+     *
+     * Resolves every factory-registered provider, awaiting any Promises,
+     * and caches results for synchronous access via `resolve()`.
+     *
+     * Called automatically by the controllers plugin during `install()`.
+     * For functional mode, call once before handling requests.
+     *
+     * @example
+     * ```typescript
+     * container.register('DB', {
+     *   useFactory: async () => { const db = new Database(); await db.connect(); return db; },
+     * });
+     * await container.bootstrap(); // All async providers resolved
+     * container.resolve('DB');     // Works synchronously now
+     * ```
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Resolve all dependencies registered under a token.
+     */
+    resolveAll<T>(token: Token<T>): T[];
+    /**
+     * Check if a token is registered.
+     */
+    isRegistered<T>(token: Token<T>): boolean;
+    /**
+     * Clear all registered instances (useful for testing).
+     */
+    clearInstances(): void;
+    /**
+     * Reset the container completely (useful for testing).
+     */
+    reset(): void;
+    /**
+     * Create a child container with isolated scope.
+     */
+    createChild(): ContainerInterface;
+}
+/**
+ * Metadata key constants.
+ */
+declare const METADATA_KEYS: {
+    readonly SERVICE_TYPE: "di:type";
+    readonly SERVICE_SCOPE: "di:scope";
+    readonly INJECT_TOKEN: "di:inject";
+    readonly PARAM_TYPES: "design:paramtypes";
+    readonly CONFIG_PREFIX: "di:config:prefix";
+    readonly OPTIONAL_PARAMS: "di:optional";
+};
+/**
+ * Options for @Config decorator.
+ */
+interface ConfigOptions {
+    /**
+     * Environment variable prefix.
+     *
+     * When set, the configuration class can be used with prefix-based env loading.
+     *
+     * @example
+     * ```typescript
+     * @Config({ prefix: 'DB' })
+     * class DatabaseConfig {
+     *   readonly host = 'localhost';  // reads DB_HOST
+     *   readonly port = 5432;         // reads DB_PORT
+     * }
+     * ```
+     */
+    prefix?: string;
+}
+/**
+ * Registration options for container.register().
+ */
+interface RegisterOptions {
+    /** Lifecycle scope — defaults to 'transient' if not specified */
+    scope?: Scope;
+}
+
+/**
+ * @nextrush/di - Container
+ *
+ * Lightweight wrapper around tsyringe with enhanced error handling.
+ */
+
+/**
+ * The global DI container instance.
+ *
+ * Use this for registering and resolving dependencies throughout your application.
+ *
+ * @example
+ * ```typescript
+ * // Register a service
+ * container.register(UserService, { useClass: UserService });
+ *
+ * // Resolve a service
+ * const userService = container.resolve(UserService);
+ *
+ * // Register with value
+ * container.register('CONFIG', { useValue: { port: 3000 } });
+ * ```
+ */
+declare const container: ContainerInterface;
+/**
+ * Create a new isolated container.
+ *
+ * Useful for testing or creating scoped containers.
+ * Note: Creates a child container from the global tsyringe container.
+ * For truly isolated containers, reset the child before use.
+ *
+ * @example
+ * ```typescript
+ * const testContainer = createContainer();
+ * testContainer.register(UserService, { useClass: MockUserService });
+ * ```
+ */
+declare function createContainer(): ContainerInterface;
+
+/** Decorator-compatible constructor type. Uses `never[]` so any class is structurally assignable. */
+type DecoratorTarget = new (...args: never[]) => unknown;
+/**
+ * Mark a class as injectable service.
+ *
+ * Services are singletons by default - one instance shared across the application.
+ *
+ * @param options - Optional configuration for the service
+ *
+ * @example
+ * ```typescript
+ * @Service()
+ * export class UserService {
+ *   async findAll() {
+ *     return [{ id: 1, name: 'Alice' }];
+ *   }
+ * }
+ *
+ * // With transient scope (new instance each time)
+ * @Service({ scope: 'transient' })
+ * export class RequestLogger {
+ *   constructor() {
+ *     this.timestamp = Date.now();
+ *   }
+ * }
+ * ```
+ */
+declare function Service(options?: ServiceOptions): (target: DecoratorTarget) => void;
+/**
+ * Mark a class as a repository (data access layer).
+ *
+ * Semantically identical to @Service(), but indicates the class is for data access.
+ * Repositories are singletons by default.
+ *
+ * @param options - Optional configuration for the repository
+ *
+ * @example
+ * ```typescript
+ * @Repository()
+ * export class UserRepository {
+ *   async findById(id: string) {
+ *     return db.users.findUnique({ where: { id } });
+ *   }
+ * }
+ * ```
+ */
+declare function Repository(options?: ServiceOptions): (target: DecoratorTarget) => void;
+/**
+ * Explicitly inject a dependency by token.
+ *
+ * Use this when:
+ * - Injecting an interface (TypeScript can't infer interface types at runtime)
+ * - Using string or symbol tokens
+ * - The automatic type inference doesn't work
+ *
+ * @param token - The token to inject (class, string, or symbol)
+ *
+ * @example
+ * ```typescript
+ * @Service()
+ * export class UserService {
+ *   constructor(
+ *     // Inject by interface token
+ *     @inject('IUserRepository') private repo: IUserRepository,
+ *
+ *     // Inject by string token
+ *     @inject('DATABASE_URL') private dbUrl: string
+ *   ) {}
+ * }
+ * ```
+ */
+declare function inject(token: unknown): ParameterDecorator;
+/**
+ * Make a class injectable without singleton scope.
+ *
+ * Unlike @Service() which defaults to singleton, @Injectable() creates
+ * a transient registration that can be resolved from the container.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class FeatureService {
+ *   constructor(private logger: Logger) {}
+ * }
+ *
+ * // Resolve from container
+ * const service = container.resolve(FeatureService);
+ * ```
+ */
+declare function Injectable(): (target: DecoratorTarget) => void;
+/**
+ * @deprecated Use `@Injectable()` instead. Will be removed in v4.
+ */
+declare const AutoInjectable: typeof Injectable;
+/**
+ * Make a class resolvable by the DI container without adding service metadata.
+ *
+ * Used internally by `@Controller()` to enable constructor injection
+ * without marking the class as a service. This is the abstraction boundary
+ * that prevents `@nextrush/decorators` from depending directly on tsyringe.
+ *
+ * @param target - The class constructor to make injectable
+ *
+ * @internal
+ */
+declare function markInjectable(target: Constructor): void;
+/**
+ * Delay resolution of a dependency.
+ *
+ * Use this to break circular dependencies by lazily resolving the dependency.
+ *
+ * @param token - Factory function returning the class to inject
+ *
+ * @example
+ * ```typescript
+ * @Service()
+ * class UserService {
+ *   constructor(
+ *     @inject(delay(() => OrderService)) private orderService: OrderService
+ *   ) {}
+ * }
+ *
+ * @Service()
+ * class OrderService {
+ *   constructor(
+ *     @inject(delay(() => UserService)) private userService: UserService
+ *   ) {}
+ * }
+ * ```
+ */
+declare function delay(tokenFactory: () => Constructor): unknown;
+/**
+ * Check if a class has DI metadata (is decorated with @Service or @Repository).
+ *
+ * @param target - The class to check
+ * @returns True if the class has DI metadata
+ */
+declare function hasServiceMetadata(target: object): boolean;
+/**
+ * Get the service type from a decorated class.
+ *
+ * @param target - The class to check
+ * @returns The service type ('service' | 'repository') or undefined
+ */
+declare function getServiceType(target: object): string | undefined;
+/**
+ * Get the scope from a decorated class.
+ *
+ * @param target - The class to check
+ * @returns The scope ('singleton' | 'transient') or undefined
+ */
+declare function getServiceScope(target: object): Scope | undefined;
+/**
+ * Mark a class as a configuration holder.
+ *
+ * Configuration classes are always singletons and serve as centralized
+ * configuration containers for your application. Similar to Spring Boot's
+ * `@Configuration` / `@ConfigurationProperties`.
+ *
+ * @param options - Optional configuration (e.g., env prefix)
+ *
+ * @example
+ * ```typescript
+ * // Simple configuration class
+ * @Config()
+ * export class AppConfig {
+ *   readonly port = Number(process.env.PORT ?? 3000);
+ *   readonly host = process.env.HOST ?? 'localhost';
+ * }
+ *
+ * // With env prefix — documents that this config reads DB_* vars
+ * @Config({ prefix: 'DB' })
+ * export class DatabaseConfig {
+ *   readonly host = process.env.DB_HOST ?? 'localhost';
+ *   readonly port = Number(process.env.DB_PORT ?? 5432);
+ *   readonly name = process.env.DB_NAME ?? 'mydb';
+ * }
+ *
+ * // Inject into services
+ * @Service()
+ * export class UserService {
+ *   constructor(private config: DatabaseConfig) {}
+ *
+ *   getConnectionString() {
+ *     return `postgres://${this.config.host}:${this.config.port}/${this.config.name}`;
+ *   }
+ * }
+ * ```
+ */
+declare function Config(options?: ConfigOptions): (target: DecoratorTarget) => void;
+/**
+ * Get the config prefix from a @Config-decorated class.
+ *
+ * @param target - The class to check
+ * @returns The prefix string or undefined
+ */
+declare function getConfigPrefix(target: object): string | undefined;
+/**
+ * Mark a constructor parameter as optional.
+ *
+ * When a dependency marked `@Optional()` cannot be resolved, the container
+ * injects `undefined` instead of throwing a `DependencyResolutionError`.
+ *
+ * @example
+ * ```typescript
+ * // Optional dependency - if 'MAILER' is not registered, `mailer` will be undefined
+ * @Service()
+ * class NotificationService {
+ *   constructor(
+ *     @Optional() @inject('MAILER') private mailer?: MailerService,
+ *   ) {}
+ *
+ *   send(message: string) {
+ *     if (this.mailer) {
+ *       this.mailer.send(message);
+ *     } else {
+ *       console.log('No mailer configured, skipping:', message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function Optional(): ParameterDecorator;
+/**
+ * Check whether a specific constructor parameter is marked `@Optional()`.
+ */
+declare function isParameterOptional(target: object, parameterIndex: number): boolean;
+/**
+ * Get the set of optional parameter indices for a class constructor.
+ */
+declare function getOptionalParams(target: object): ReadonlySet<number>;
+
+/**
+ * @nextrush/di - Errors
+ *
+ * Production-grade error classes with actionable messages.
+ */
+/**
+ * Base error class for all DI-related errors.
+ */
+declare class DIError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when a dependency cannot be resolved.
+ *
+ * Provides clear guidance on how to fix the issue.
+ */
+declare class DependencyResolutionError extends DIError {
+    readonly chain: string[];
+    readonly missingDependency: string;
+    constructor(chain: string[], missing: string);
+}
+/**
+ * Error thrown when a circular dependency is detected.
+ *
+ * Provides strategies to break the cycle.
+ */
+declare class CircularDependencyError extends DIError {
+    readonly cycle: string[];
+    constructor(cycle: string[]);
+}
+/**
+ * Error thrown when TypeScript cannot infer constructor parameter types.
+ *
+ * Usually caused by missing type annotations or incorrect tsconfig.
+ */
+declare class TypeInferenceError extends DIError {
+    readonly className: string;
+    readonly parameterIndex: number;
+    constructor(className: string, parameterIndex: number);
+}
+/**
+ * Error thrown when an invalid provider configuration is given.
+ */
+declare class InvalidProviderError extends DIError {
+    readonly token: string;
+    constructor(token: string);
+}
+/**
+ * Error thrown when trying to resolve from a disposed container.
+ */
+declare class ContainerDisposedError extends DIError {
+    constructor();
+}
+/**
+ * Error thrown when a required dependency is not found.
+ *
+ * @deprecated Use {@link DependencyResolutionError} instead — it provides
+ * the same information plus the resolution chain context.
+ */
+declare class MissingDependencyError extends DIError {
+    readonly token: string;
+    constructor(token: string);
+}
+
+export { AutoInjectable, CircularDependencyError, type ClassProvider, Config, type ConfigOptions, type Constructor, ContainerDisposedError, type ContainerInterface, DIError, DependencyResolutionError, type FactoryProvider, Injectable, InvalidProviderError, METADATA_KEYS, MissingDependencyError, Optional, type Provider, type RegisterOptions, Repository, type Scope, Service, type ServiceOptions, type Token, TypeInferenceError, type ValueProvider, container, createContainer, delay, getConfigPrefix, getOptionalParams, getServiceScope, getServiceType, hasServiceMetadata, inject, isParameterOptional, markInjectable };