@nextrush/di 3.0.7 → 4.0.0-beta.0

package/dist/index.d.ts

@@ -1,145 +1,13 @@
+import { Container, ServiceOptions, Constructor, Scope } from '@nextrush/types';
+export { ClassProvider, Constructor, Container, FactoryProvider, Provider, RegisterOptions, Scope, ServiceOptions, Token, ValueProvider } from '@nextrush/types';
+
 /**
  * @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.
+ * The container contract now lives in `@nextrush/types` (shared, lowest
+ * package). This module re-exports it and adds the DI-specific metadata types.
  */
-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.
  */
@@ -158,8 +26,6 @@ interface ConfigOptions {
     /**
      * Environment variable prefix.
      *
-     * When set, the configuration class can be used with prefix-based env loading.
-     *
      * @example
      * ```typescript
      * @Config({ prefix: 'DB' })
@@ -171,13 +37,6 @@ interface ConfigOptions {
      */
     prefix?: string;
 }
-/**
- * Registration options for container.register().
- */
-interface RegisterOptions {
-    /** Lifecycle scope — defaults to 'transient' if not specified */
-    scope?: Scope;
-}
 
 /**
  * @nextrush/di - Container
@@ -199,10 +58,10 @@ interface RegisterOptions {
  * const userService = container.resolve(UserService);
  *
  * // Register with value
- * container.register('CONFIG', { useValue: { port: 3000 } });
+ * container.register('CONFIG', { useValue: { port: 8080 } });
  * ```
  */
-declare const container: ContainerInterface;
+declare const container: Container;
 /**
  * Create a new isolated container.
  *
@@ -216,10 +75,10 @@ declare const container: ContainerInterface;
  * testContainer.register(UserService, { useClass: MockUserService });
  * ```
  */
-declare function createContainer(): ContainerInterface;
+declare function createContainer(): Container;
 
 /** Decorator-compatible constructor type. Uses `never[]` so any class is structurally assignable. */
-type DecoratorTarget = new (...args: never[]) => unknown;
+type DecoratorTarget$1 = new (...args: never[]) => unknown;
 /**
  * Mark a class as injectable service.
  *
@@ -245,7 +104,7 @@ type DecoratorTarget = new (...args: never[]) => unknown;
  * }
  * ```
  */
-declare function Service(options?: ServiceOptions): (target: DecoratorTarget) => void;
+declare function Service(options?: ServiceOptions): (target: DecoratorTarget$1) => void;
 /**
  * Mark a class as a repository (data access layer).
  *
@@ -264,7 +123,54 @@ declare function Service(options?: ServiceOptions): (target: DecoratorTarget) =>
  * }
  * ```
  */
-declare function Repository(options?: ServiceOptions): (target: DecoratorTarget) => void;
+declare function Repository(options?: ServiceOptions): (target: DecoratorTarget$1) => void;
+/**
+ * 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 ?? 8080);
+ *   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$1) => void;
+
+/**
+ * @nextrush/di - Injection Decorators & Adapters
+ *
+ * Parameter decorators for injection, and adapters to tsyringe's internals.
+ */
+
+/** Decorator-compatible constructor type. Uses `never[]` so any class is structurally assignable. */
+type DecoratorTarget = new (...args: never[]) => unknown;
 /**
  * Explicitly inject a dependency by token.
  *
@@ -290,40 +196,6 @@ declare function Repository(options?: ServiceOptions): (target: DecoratorTarget)
  * ```
  */
 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.
  *
@@ -350,71 +222,35 @@ declare function markInjectable(target: Constructor): void;
  */
 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`.
+ * Make a class injectable without singleton scope.
  *
- * @param options - Optional configuration (e.g., env prefix)
+ * Unlike @Service() which defaults to singleton, @Injectable() creates
+ * a transient registration that can be resolved from the container.
  *
  * @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';
+ * @Injectable()
+ * export class FeatureService {
+ *   constructor(private logger: Logger) {}
  * }
  *
- * // Inject into services
- * @Service()
- * export class UserService {
- *   constructor(private config: DatabaseConfig) {}
- *
- *   getConnectionString() {
- *     return `postgres://${this.config.host}:${this.config.port}/${this.config.name}`;
- *   }
- * }
+ * // Resolve from container
+ * const service = container.resolve(FeatureService);
  * ```
  */
-declare function Config(options?: ConfigOptions): (target: DecoratorTarget) => void;
+declare function Injectable(): (target: DecoratorTarget) => void;
 /**
- * Get the config prefix from a @Config-decorated class.
+ * Make a class resolvable by the DI container without adding service metadata.
  *
- * @param target - The class to check
- * @returns The prefix string or undefined
+ * 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 getConfigPrefix(target: object): string | undefined;
+declare function markInjectable(target: Constructor): void;
 /**
  * Mark a constructor parameter as optional.
  *
@@ -450,6 +286,47 @@ declare function isParameterOptional(target: object, parameterIndex: number): bo
  */
 declare function getOptionalParams(target: object): ReadonlySet<number>;
 
+/**
+ * @nextrush/di - Service Metadata Readers
+ *
+ * Functions to read service metadata written by decorators.
+ */
+
+/**
+ * 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 declared scope of a class — the single source of truth for service scope.
+ *
+ * Scope defaults are unified on `'singleton'`: `@Service()`, `@Repository()`, and
+ * `@Config()` all declare `singleton` unless `{ scope: 'transient' }` is passed, and an
+ * undecorated class (no `di:scope` metadata) is treated as `singleton` too. The
+ * low-level {@link Container.register} reads this value so a class's declared scope —
+ * not the call site — decides singleton vs transient.
+ *
+ * @param target - The class to check
+ * @returns The declared scope (`'singleton'` | `'transient'`); `'singleton'` when undeclared
+ */
+declare function getServiceScope(target: object): Scope;
+/**
+ * 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;
+
 /**
  * @nextrush/di - Errors
  *
@@ -480,16 +357,6 @@ 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.
  */
@@ -497,21 +364,5 @@ 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 };
+export { CircularDependencyError, Config, type ConfigOptions, DIError, DependencyResolutionError, Injectable, InvalidProviderError, METADATA_KEYS, Optional, Repository, Service, container, createContainer, delay, getConfigPrefix, getOptionalParams, getServiceScope, getServiceType, hasServiceMetadata, inject, isParameterOptional, markInjectable };