@veloxts/core 0.3.2 → 0.3.4

package/dist/di/container.js

@@ -0,0 +1,693 @@
+/**
+ * Dependency Injection Container
+ *
+ * The VeloxTS DI container provides:
+ * - Service registration with multiple provider types
+ * - Automatic constructor injection via reflect-metadata
+ * - Lifecycle management (singleton, transient, request-scoped)
+ * - Circular dependency detection
+ * - Integration with Fastify for request-scoped services
+ *
+ * @module di/container
+ */
+import { VeloxError } from '../errors.js';
+import { getConstructorTokens, getInjectableScope, getOptionalParams, isInjectable, } from './decorators.js';
+import { normalizeProvider, validateProvider } from './providers.js';
+import { Scope, ScopeManager } from './scope.js';
+import { getTokenName, isClassToken, validateToken } from './tokens.js';
+// ============================================================================
+// Container Implementation
+// ============================================================================
+/**
+ * Dependency Injection Container
+ *
+ * The central hub for service registration and resolution.
+ * Manages service lifecycles and dependencies.
+ *
+ * @example
+ * ```typescript
+ * // Create a container
+ * const container = new Container();
+ *
+ * // Register services
+ * container.register({ provide: UserService, useClass: UserService });
+ * container.register({
+ *   provide: DATABASE,
+ *   useFactory: (config) => createDb(config.dbUrl),
+ *   inject: [ConfigService]
+ * });
+ *
+ * // Resolve services
+ * const userService = container.resolve(UserService);
+ * const db = container.resolve(DATABASE);
+ * ```
+ */
+export class Container {
+    /**
+     * Registered providers indexed by token
+     */
+    providers = new Map();
+    /**
+     * Manages singleton and request-scoped instance caches
+     */
+    scopeManager = new ScopeManager();
+    /**
+     * Parent container for hierarchical lookup
+     */
+    parent;
+    /**
+     * Whether to auto-register @Injectable classes
+     */
+    autoRegister;
+    /**
+     * Resolution stack for circular dependency detection
+     */
+    resolutionStack = new Set();
+    /**
+     * Creates a new DI container
+     *
+     * @param options - Container configuration options
+     *
+     * @example
+     * ```typescript
+     * // Standalone container
+     * const container = new Container();
+     *
+     * // Child container (inherits from parent)
+     * const childContainer = new Container({ parent: container });
+     *
+     * // With auto-registration enabled
+     * const autoContainer = new Container({ autoRegister: true });
+     * ```
+     */
+    constructor(options = {}) {
+        this.parent = options.parent;
+        this.autoRegister = options.autoRegister ?? false;
+    }
+    // ==========================================================================
+    // Registration
+    // ==========================================================================
+    /**
+     * Registers a service provider
+     *
+     * @param provider - The provider configuration
+     * @returns The container (for chaining)
+     * @throws {VeloxError} If the provider is invalid
+     *
+     * @example
+     * ```typescript
+     * // Class provider
+     * container.register({
+     *   provide: UserService,
+     *   useClass: UserService,
+     *   scope: Scope.REQUEST
+     * });
+     *
+     * // Factory provider
+     * container.register({
+     *   provide: DATABASE,
+     *   useFactory: (config: ConfigService) => createDb(config.dbUrl),
+     *   inject: [ConfigService]
+     * });
+     *
+     * // Value provider
+     * container.register({
+     *   provide: CONFIG,
+     *   useValue: { port: 3210, debug: true }
+     * });
+     *
+     * // Existing/alias provider
+     * container.register({
+     *   provide: LOGGER,
+     *   useExisting: ConsoleLogger
+     * });
+     * ```
+     */
+    register(provider) {
+        validateProvider(provider);
+        const normalized = normalizeProvider(provider);
+        this.providers.set(provider.provide, normalized);
+        return this;
+    }
+    /**
+     * Registers multiple providers at once
+     *
+     * @param providers - Array of provider configurations
+     * @returns The container (for chaining)
+     *
+     * @example
+     * ```typescript
+     * container.registerMany([
+     *   { provide: UserService, useClass: UserService },
+     *   { provide: PostService, useClass: PostService },
+     *   { provide: CONFIG, useValue: appConfig }
+     * ]);
+     * ```
+     */
+    registerMany(providers) {
+        for (const provider of providers) {
+            this.register(provider);
+        }
+        return this;
+    }
+    /**
+     * Checks if a token is registered
+     *
+     * @param token - The token to check
+     * @returns true if the token is registered
+     */
+    isRegistered(token) {
+        return this.providers.has(token) || (this.parent?.isRegistered(token) ?? false);
+    }
+    /**
+     * Gets the provider for a token (without resolving)
+     *
+     * @param token - The token to get the provider for
+     * @returns The normalized provider or undefined
+     */
+    getProvider(token) {
+        const local = this.providers.get(token);
+        if (local) {
+            return local;
+        }
+        return this.parent?.getProvider(token);
+    }
+    // ==========================================================================
+    // Resolution
+    // ==========================================================================
+    /**
+     * Resolves a service from the container
+     *
+     * @param token - The token to resolve
+     * @param context - Optional resolution context (for request scope)
+     * @returns The resolved service instance
+     * @throws {VeloxError} If the service cannot be resolved
+     *
+     * @example
+     * ```typescript
+     * // Basic resolution
+     * const userService = container.resolve(UserService);
+     *
+     * // With request context (for request-scoped services)
+     * const userContext = container.resolve(UserContext, { request });
+     * ```
+     */
+    resolve(token, context) {
+        validateToken(token);
+        // Check for circular dependencies
+        if (this.resolutionStack.has(token)) {
+            const stack = [...this.resolutionStack].map((t) => getTokenName(t));
+            const current = getTokenName(token);
+            throw new VeloxError(`Circular dependency detected: ${[...stack, current].join(' -> ')}`, 500, 'CIRCULAR_DEPENDENCY');
+        }
+        // Get provider (local or from parent)
+        let provider = this.getProvider(token);
+        // Handle unregistered tokens
+        if (!provider) {
+            // Try auto-registration if enabled and token is a class
+            if (this.autoRegister && isClassToken(token)) {
+                provider = this.tryAutoRegister(token);
+            }
+            if (!provider) {
+                throw new VeloxError(`No provider found for: ${getTokenName(token)}`, 500, 'SERVICE_NOT_FOUND');
+            }
+        }
+        // Resolve based on scope
+        return this.resolveWithScope(token, provider, context);
+    }
+    /**
+     * Resolves a service, returning undefined if not found
+     *
+     * @param token - The token to resolve
+     * @param context - Optional resolution context
+     * @returns The resolved service or undefined
+     */
+    resolveOptional(token, context) {
+        try {
+            return this.resolve(token, context);
+        }
+        catch (error) {
+            if (error instanceof VeloxError && error.code === 'SERVICE_NOT_FOUND') {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Resolves all services registered for a token
+     *
+     * Useful for multi-injection patterns where multiple implementations
+     * are registered for the same token.
+     *
+     * @param token - The token to resolve
+     * @param context - Optional resolution context
+     * @returns Array of resolved service instances
+     *
+     * @example
+     * ```typescript
+     * // Register multiple validators
+     * container.register({ provide: VALIDATOR, useClass: EmailValidator });
+     * container.register({ provide: VALIDATOR, useClass: PhoneValidator });
+     *
+     * // Resolve all validators
+     * const validators = container.resolveAll(VALIDATOR);
+     * ```
+     *
+     * Note: Currently returns single instance. Multi-injection to be
+     * implemented in v1.1 with a separate multi-provider registration API.
+     */
+    resolveAll(token, context) {
+        const instance = this.resolveOptional(token, context);
+        return instance !== undefined ? [instance] : [];
+    }
+    /**
+     * Resolves with scope management
+     *
+     * @internal
+     */
+    resolveWithScope(token, provider, context) {
+        switch (provider.scope) {
+            case Scope.SINGLETON: {
+                // Check cache first
+                if (this.scopeManager.hasSingleton(token)) {
+                    return this.scopeManager.getSingleton(token);
+                }
+                // Create and cache
+                const instance = this.createInstance(token, provider, context);
+                this.scopeManager.setSingleton(token, instance);
+                return instance;
+            }
+            case Scope.TRANSIENT: {
+                // Always create new instance
+                return this.createInstance(token, provider, context);
+            }
+            case Scope.REQUEST: {
+                // Validate and get request context
+                const request = this.scopeManager.ensureRequestScope(context?.request);
+                // Check request cache first
+                if (this.scopeManager.hasRequestScoped(token, request)) {
+                    return this.scopeManager.getRequestScoped(token, request);
+                }
+                // Create and cache in request scope
+                const instance = this.createInstance(token, provider, context);
+                this.scopeManager.setRequestScoped(token, instance, request);
+                return instance;
+            }
+            default: {
+                throw new VeloxError(`Unknown scope: ${provider.scope}`, 500, 'SCOPE_MISMATCH');
+            }
+        }
+    }
+    /**
+     * Creates an instance based on provider type
+     *
+     * @internal
+     */
+    createInstance(token, provider, context) {
+        // Track resolution for circular dependency detection
+        this.resolutionStack.add(token);
+        try {
+            switch (provider.type) {
+                case 'class':
+                    return this.instantiateClass(provider.implementation.class, context);
+                case 'factory':
+                    return this.invokeFactory(provider, context);
+                case 'value':
+                    return provider.implementation.value;
+                case 'existing':
+                    return this.resolve(provider.implementation.existing, context);
+                default:
+                    throw new VeloxError(`Unknown provider type: ${provider.type}`, 500, 'INVALID_PROVIDER');
+            }
+        }
+        finally {
+            this.resolutionStack.delete(token);
+        }
+    }
+    /**
+     * Instantiates a class with automatic dependency injection
+     *
+     * @internal
+     */
+    instantiateClass(cls, context) {
+        // Get constructor dependency tokens
+        const tokens = getConstructorTokens(cls);
+        const optionalParams = getOptionalParams(cls);
+        // Resolve all dependencies
+        const dependencies = [];
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            const isOptional = optionalParams.has(i);
+            try {
+                // Handle Object type (unresolved interface)
+                if (token === Object) {
+                    if (isOptional) {
+                        dependencies.push(undefined);
+                        continue;
+                    }
+                    throw new VeloxError(`Cannot resolve dependency at index ${i} for ${cls.name}: ` +
+                        'Type resolved to Object. Use @Inject() decorator for interfaces.', 500, 'MISSING_INJECTABLE_DECORATOR');
+                }
+                const dependency = isOptional
+                    ? this.resolveOptional(token, context)
+                    : this.resolve(token, context);
+                dependencies.push(dependency);
+            }
+            catch (error) {
+                if (isOptional && error instanceof VeloxError && error.code === 'SERVICE_NOT_FOUND') {
+                    dependencies.push(undefined);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        // Instantiate the class
+        // Note: We need to spread the dependencies array into the constructor
+        // TypeScript doesn't know the exact number of parameters, so we use the
+        // constructor with a spread of unknown[]
+        return new cls(...dependencies);
+    }
+    /**
+     * Invokes a factory function with dependencies
+     *
+     * @internal
+     */
+    invokeFactory(provider, context) {
+        const factory = provider.implementation.factory;
+        const injectTokens = provider.implementation.inject ?? [];
+        // Resolve factory dependencies
+        const dependencies = injectTokens.map((token) => this.resolve(token, context));
+        // Invoke factory
+        const result = factory(...dependencies);
+        // Handle async factories (should be avoided in sync resolution)
+        if (result instanceof Promise) {
+            throw new VeloxError('Async factory returned from sync resolve(). Use resolveAsync() for async factories.', 500, 'INVALID_PROVIDER');
+        }
+        return result;
+    }
+    /**
+     * Tries to auto-register a class if it's injectable
+     *
+     * @internal
+     */
+    tryAutoRegister(cls) {
+        if (!isInjectable(cls)) {
+            return undefined;
+        }
+        const scope = getInjectableScope(cls);
+        const provider = {
+            provide: cls,
+            useClass: cls,
+            scope,
+        };
+        this.register(provider);
+        return this.getProvider(cls);
+    }
+    // ==========================================================================
+    // Async Resolution
+    // ==========================================================================
+    /**
+     * Resolves a service asynchronously
+     *
+     * Use this method when your providers include async factories.
+     *
+     * @param token - The token to resolve
+     * @param context - Optional resolution context
+     * @returns Promise resolving to the service instance
+     *
+     * @example
+     * ```typescript
+     * container.register({
+     *   provide: DATABASE,
+     *   useFactory: async (config) => {
+     *     const client = createClient(config.dbUrl);
+     *     await client.connect();
+     *     return client;
+     *   },
+     *   inject: [ConfigService]
+     * });
+     *
+     * const db = await container.resolveAsync(DATABASE);
+     * ```
+     */
+    async resolveAsync(token, context) {
+        validateToken(token);
+        // Check for circular dependencies
+        if (this.resolutionStack.has(token)) {
+            const stack = [...this.resolutionStack].map((t) => getTokenName(t));
+            const current = getTokenName(token);
+            throw new VeloxError(`Circular dependency detected: ${[...stack, current].join(' -> ')}`, 500, 'CIRCULAR_DEPENDENCY');
+        }
+        // Get provider
+        let provider = this.getProvider(token);
+        if (!provider) {
+            if (this.autoRegister && isClassToken(token)) {
+                provider = this.tryAutoRegister(token);
+            }
+            if (!provider) {
+                throw new VeloxError(`No provider found for: ${getTokenName(token)}`, 500, 'SERVICE_NOT_FOUND');
+            }
+        }
+        return this.resolveWithScopeAsync(token, provider, context);
+    }
+    /**
+     * Async scope resolution
+     *
+     * @internal
+     */
+    async resolveWithScopeAsync(token, provider, context) {
+        switch (provider.scope) {
+            case Scope.SINGLETON: {
+                if (this.scopeManager.hasSingleton(token)) {
+                    return this.scopeManager.getSingleton(token);
+                }
+                const instance = await this.createInstanceAsync(token, provider, context);
+                this.scopeManager.setSingleton(token, instance);
+                return instance;
+            }
+            case Scope.TRANSIENT: {
+                return this.createInstanceAsync(token, provider, context);
+            }
+            case Scope.REQUEST: {
+                // Validate and get request context
+                const request = this.scopeManager.ensureRequestScope(context?.request);
+                if (this.scopeManager.hasRequestScoped(token, request)) {
+                    return this.scopeManager.getRequestScoped(token, request);
+                }
+                const instance = await this.createInstanceAsync(token, provider, context);
+                this.scopeManager.setRequestScoped(token, instance, request);
+                return instance;
+            }
+            default: {
+                throw new VeloxError(`Unknown scope: ${provider.scope}`, 500, 'SCOPE_MISMATCH');
+            }
+        }
+    }
+    /**
+     * Async instance creation
+     *
+     * @internal
+     */
+    async createInstanceAsync(token, provider, context) {
+        this.resolutionStack.add(token);
+        try {
+            switch (provider.type) {
+                case 'class':
+                    return await this.instantiateClassAsync(provider.implementation.class, context);
+                case 'factory':
+                    return await this.invokeFactoryAsync(provider, context);
+                case 'value':
+                    return provider.implementation.value;
+                case 'existing':
+                    return await this.resolveAsync(provider.implementation.existing, context);
+                default:
+                    throw new VeloxError(`Unknown provider type: ${provider.type}`, 500, 'INVALID_PROVIDER');
+            }
+        }
+        finally {
+            this.resolutionStack.delete(token);
+        }
+    }
+    /**
+     * Async class instantiation
+     *
+     * @internal
+     */
+    async instantiateClassAsync(cls, context) {
+        const tokens = getConstructorTokens(cls);
+        const optionalParams = getOptionalParams(cls);
+        const dependencies = [];
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            const isOptional = optionalParams.has(i);
+            try {
+                if (token === Object) {
+                    if (isOptional) {
+                        dependencies.push(undefined);
+                        continue;
+                    }
+                    throw new VeloxError(`Cannot resolve dependency at index ${i} for ${cls.name}: ` +
+                        'Type resolved to Object. Use @Inject() decorator for interfaces.', 500, 'MISSING_INJECTABLE_DECORATOR');
+                }
+                const dependency = isOptional
+                    ? await this.resolveAsync(token, context).catch(() => undefined)
+                    : await this.resolveAsync(token, context);
+                dependencies.push(dependency);
+            }
+            catch (error) {
+                if (isOptional) {
+                    dependencies.push(undefined);
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        return new cls(...dependencies);
+    }
+    /**
+     * Async factory invocation
+     *
+     * @internal
+     */
+    async invokeFactoryAsync(provider, context) {
+        const factory = provider.implementation.factory;
+        const injectTokens = provider.implementation.inject ?? [];
+        const dependencies = await Promise.all(injectTokens.map((token) => this.resolveAsync(token, context)));
+        const result = factory(...dependencies);
+        return result instanceof Promise ? result : result;
+    }
+    // ==========================================================================
+    // Fastify Integration
+    // ==========================================================================
+    /**
+     * Attaches the container to a Fastify server
+     *
+     * Sets up the request lifecycle hooks needed for request-scoped services.
+     * Must be called before resolving request-scoped services.
+     *
+     * @param server - Fastify server instance
+     * @returns The container (for chaining)
+     *
+     * @example
+     * ```typescript
+     * const app = await createVeloxApp();
+     * container.attachToFastify(app.server);
+     * ```
+     */
+    attachToFastify(server) {
+        this.scopeManager.attachToFastify(server);
+        return this;
+    }
+    /**
+     * Creates a resolution context from a Fastify request
+     *
+     * @param request - The Fastify request
+     * @returns Resolution context for request-scoped services
+     */
+    static createContext(request) {
+        return { request };
+    }
+    // ==========================================================================
+    // Container Management
+    // ==========================================================================
+    /**
+     * Creates a child container
+     *
+     * Child containers inherit from this container but can override registrations.
+     * Useful for testing or creating scoped containers.
+     *
+     * @param options - Options for the child container
+     * @returns New child container
+     *
+     * @example
+     * ```typescript
+     * const childContainer = container.createChild();
+     *
+     * // Override a service for testing
+     * childContainer.register({
+     *   provide: UserRepository,
+     *   useClass: MockUserRepository
+     * });
+     * ```
+     */
+    createChild(options = {}) {
+        return new Container({ ...options, parent: this });
+    }
+    /**
+     * Clears all singleton instances
+     *
+     * Useful for testing or application shutdown.
+     * Does not clear registrations.
+     */
+    clearInstances() {
+        this.scopeManager.clearSingletons();
+    }
+    /**
+     * Clears all registrations and instances
+     *
+     * @internal
+     */
+    reset() {
+        this.providers.clear();
+        this.scopeManager.reset();
+        this.resolutionStack.clear();
+    }
+    /**
+     * Gets debug information about the container
+     *
+     * @returns Object with container statistics and registered providers
+     */
+    getDebugInfo() {
+        return {
+            providerCount: this.providers.size,
+            providers: [...this.providers.values()].map((p) => {
+                const tokenName = getTokenName(p.provide);
+                return `${p.type}(${tokenName}, ${p.scope})`;
+            }),
+            hasParent: this.parent !== undefined,
+            autoRegister: this.autoRegister,
+        };
+    }
+}
+// ============================================================================
+// Global Container
+// ============================================================================
+/**
+ * Default global container instance
+ *
+ * For convenience, VeloxTS provides a default container.
+ * You can also create your own containers for testing or isolation.
+ *
+ * @example
+ * ```typescript
+ * import { container } from '@veloxts/core';
+ *
+ * container.register({
+ *   provide: UserService,
+ *   useClass: UserService
+ * });
+ *
+ * const userService = container.resolve(UserService);
+ * ```
+ */
+export const container = new Container();
+// ============================================================================
+// Container Factory
+// ============================================================================
+/**
+ * Creates a new DI container
+ *
+ * @param options - Container configuration options
+ * @returns New container instance
+ *
+ * @example
+ * ```typescript
+ * const appContainer = createContainer({ autoRegister: true });
+ * ```
+ */
+export function createContainer(options) {
+    return new Container(options);
+}
+//# sourceMappingURL=container.js.map