@veloxts/core 0.3.2 → 0.3.4

package/dist/di/container.d.ts

@@ -0,0 +1,406 @@
+/**
+ * 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 type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { NormalizedProvider, Provider } from './providers.js';
+import type { InjectionToken } from './tokens.js';
+/**
+ * Options for creating a DI container
+ */
+export interface ContainerOptions {
+    /**
+     * Parent container for hierarchical injection
+     *
+     * If a service is not found in this container, it will be looked up
+     * in the parent container.
+     */
+    parent?: Container;
+    /**
+     * Whether to allow auto-registration of classes
+     *
+     * If true, when resolving a class that isn't registered,
+     * the container will attempt to instantiate it directly
+     * (only for @Injectable classes).
+     *
+     * @default false
+     */
+    autoRegister?: boolean;
+}
+/**
+ * Context for resolution, including request for request-scoped services
+ */
+export interface ResolutionContext {
+    /**
+     * The current Fastify request (for request-scoped services)
+     */
+    request?: FastifyRequest;
+}
+/**
+ * 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 declare class Container {
+    /**
+     * Registered providers indexed by token
+     */
+    private readonly providers;
+    /**
+     * Manages singleton and request-scoped instance caches
+     */
+    private readonly scopeManager;
+    /**
+     * Parent container for hierarchical lookup
+     */
+    private readonly parent?;
+    /**
+     * Whether to auto-register @Injectable classes
+     */
+    private readonly autoRegister;
+    /**
+     * Resolution stack for circular dependency detection
+     */
+    private readonly resolutionStack;
+    /**
+     * 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?: ContainerOptions);
+    /**
+     * 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<T>(provider: Provider<T>): 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: Provider[]): this;
+    /**
+     * Checks if a token is registered
+     *
+     * @param token - The token to check
+     * @returns true if the token is registered
+     */
+    isRegistered(token: InjectionToken): boolean;
+    /**
+     * Gets the provider for a token (without resolving)
+     *
+     * @param token - The token to get the provider for
+     * @returns The normalized provider or undefined
+     */
+    getProvider<T>(token: InjectionToken<T>): NormalizedProvider<T> | undefined;
+    /**
+     * 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<T>(token: InjectionToken<T>, context?: ResolutionContext): T;
+    /**
+     * 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<T>(token: InjectionToken<T>, context?: ResolutionContext): T | undefined;
+    /**
+     * 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<T>(token: InjectionToken<T>, context?: ResolutionContext): T[];
+    /**
+     * Resolves with scope management
+     *
+     * @internal
+     */
+    private resolveWithScope;
+    /**
+     * Creates an instance based on provider type
+     *
+     * @internal
+     */
+    private createInstance;
+    /**
+     * Instantiates a class with automatic dependency injection
+     *
+     * @internal
+     */
+    private instantiateClass;
+    /**
+     * Invokes a factory function with dependencies
+     *
+     * @internal
+     */
+    private invokeFactory;
+    /**
+     * Tries to auto-register a class if it's injectable
+     *
+     * @internal
+     */
+    private tryAutoRegister;
+    /**
+     * 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);
+     * ```
+     */
+    resolveAsync<T>(token: InjectionToken<T>, context?: ResolutionContext): Promise<T>;
+    /**
+     * Async scope resolution
+     *
+     * @internal
+     */
+    private resolveWithScopeAsync;
+    /**
+     * Async instance creation
+     *
+     * @internal
+     */
+    private createInstanceAsync;
+    /**
+     * Async class instantiation
+     *
+     * @internal
+     */
+    private instantiateClassAsync;
+    /**
+     * Async factory invocation
+     *
+     * @internal
+     */
+    private invokeFactoryAsync;
+    /**
+     * 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: FastifyInstance): this;
+    /**
+     * Creates a resolution context from a Fastify request
+     *
+     * @param request - The Fastify request
+     * @returns Resolution context for request-scoped services
+     */
+    static createContext(request: FastifyRequest): ResolutionContext;
+    /**
+     * 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?: Omit<ContainerOptions, 'parent'>): Container;
+    /**
+     * Clears all singleton instances
+     *
+     * Useful for testing or application shutdown.
+     * Does not clear registrations.
+     */
+    clearInstances(): void;
+    /**
+     * Clears all registrations and instances
+     *
+     * @internal
+     */
+    reset(): void;
+    /**
+     * Gets debug information about the container
+     *
+     * @returns Object with container statistics and registered providers
+     */
+    getDebugInfo(): {
+        providerCount: number;
+        providers: string[];
+        hasParent: boolean;
+        autoRegister: boolean;
+    };
+}
+/**
+ * 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 declare const container: Container;
+/**
+ * Creates a new DI container
+ *
+ * @param options - Container configuration options
+ * @returns New container instance
+ *
+ * @example
+ * ```typescript
+ * const appContainer = createContainer({ autoRegister: true });
+ * ```
+ */
+export declare function createContainer(options?: ContainerOptions): Container;
+//# sourceMappingURL=container.d.ts.map

package/dist/di/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/di/container.ts"],"names":[],"mappings":"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"}