@veloxts/core 0.3.3 → 0.3.4

package/dist/di/index.js

@@ -0,0 +1,73 @@
+/**
+ * Dependency Injection Module
+ *
+ * VeloxTS provides a powerful, type-safe dependency injection container
+ * inspired by Angular and NestJS, designed for the VeloxTS framework.
+ *
+ * Features:
+ * - Class, factory, value, and alias providers
+ * - Singleton, transient, and request-scoped lifecycles
+ * - Automatic constructor injection via decorators
+ * - Circular dependency detection
+ * - Fastify integration for request-scoped services
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   Container,
+ *   Injectable,
+ *   Inject,
+ *   Scope,
+ *   token
+ * } from '@veloxts/core';
+ *
+ * // Create tokens for interfaces
+ * const DATABASE = token<DatabaseClient>('DATABASE');
+ * const LOGGER = token.symbol<Logger>('LOGGER');
+ *
+ * // Define injectable services
+ * @Injectable({ scope: Scope.REQUEST })
+ * class UserService {
+ *   constructor(
+ *     @Inject(DATABASE) private db: DatabaseClient,
+ *     private config: ConfigService,
+ *   ) {}
+ * }
+ *
+ * // Register providers
+ * const container = new Container();
+ * container.register({
+ *   provide: DATABASE,
+ *   useFactory: () => createDatabaseClient(),
+ *   scope: Scope.SINGLETON
+ * });
+ * container.register({
+ *   provide: UserService,
+ *   useClass: UserService,
+ *   scope: Scope.REQUEST
+ * });
+ *
+ * // Resolve services
+ * const userService = container.resolve(UserService, { request });
+ * ```
+ *
+ * @module di
+ */
+export { Container, container, createContainer } from './container.js';
+export { getConstructorTokens, getExplicitInjectTokens, getInjectableScope, getOptionalParams, INJECT_METADATA_KEY, INJECTABLE_METADATA_KEY, Inject, Injectable, isInjectable, makeInjectable, OPTIONAL_METADATA_KEY, Optional, SCOPE_METADATA_KEY, setInjectTokens, } from './decorators.js';
+export { 
+// Succinct scope helpers (preferred)
+singleton, scoped, transient, value, factory, 
+// Legacy helpers (still supported)
+asClass, asExisting, asFactory, asValue, 
+// Type guards
+isClassProvider, isExistingProvider, isFactoryProvider, isValueProvider, validateProvider, } from './providers.js';
+export { Scope, ScopeManager } from './scope.js';
+export { 
+// Succinct API (preferred)
+token, 
+// Legacy (deprecated) - keep for backwards compatibility
+createStringToken, createSymbolToken, 
+// Utilities
+getTokenName, isClassToken, isStringToken, isSymbolToken, validateToken, } from './tokens.js';
+//# sourceMappingURL=index.js.map

package/dist/di/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/di/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAGH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,uBAAuB,EACvB,MAAM,EACN,UAAU,EACV,YAAY,EACZ,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,kBAAkB,EAClB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAQzB,OAAO;AACL,qCAAqC;AACrC,SAAS,EACT,MAAM,EACN,SAAS,EACT,KAAK,EACL,OAAO;AACP,mCAAmC;AACnC,OAAO,EACP,UAAU,EACV,SAAS,EACT,OAAO;AACP,cAAc;AACd,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AASjD,OAAO;AACL,2BAA2B;AAC3B,KAAK;AACL,yDAAyD;AACzD,iBAAiB,EACjB,iBAAiB;AACjB,YAAY;AACZ,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/di/providers.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Provider types and registration interfaces for dependency injection
+ *
+ * Providers define how services are created and configured.
+ * VeloxTS supports four provider types:
+ * - Class providers: Instantiate a class
+ * - Factory providers: Use a factory function
+ * - Value providers: Use an existing value
+ * - Existing providers: Alias another token
+ *
+ * @module di/providers
+ */
+import { Scope } from './scope.js';
+import type { ClassConstructor, InjectionToken } from './tokens.js';
+/**
+ * Base provider interface
+ *
+ * All providers must specify the token they provide
+ * and optionally their lifecycle scope.
+ *
+ * @template T - The type of service being provided
+ */
+interface BaseProvider<T = unknown> {
+    /**
+     * The token that identifies this service
+     */
+    provide: InjectionToken<T>;
+    /**
+     * The lifecycle scope for this service
+     * @default Scope.SINGLETON
+     */
+    scope?: Scope;
+}
+/**
+ * Class provider
+ *
+ * Creates instances by calling `new` on the specified class.
+ * Constructor dependencies are automatically injected.
+ *
+ * @template T - The type of service being provided
+ *
+ * @example
+ * ```typescript
+ * container.register({
+ *   provide: UserService,
+ *   useClass: UserService,
+ *   scope: Scope.REQUEST
+ * });
+ *
+ * // Or with a different implementation
+ * container.register({
+ *   provide: IUserRepository,
+ *   useClass: PrismaUserRepository
+ * });
+ * ```
+ */
+export interface ClassProvider<T = unknown> extends BaseProvider<T> {
+    /**
+     * The class to instantiate
+     */
+    useClass: ClassConstructor<T>;
+}
+/**
+ * Factory provider
+ *
+ * Creates instances using a factory function.
+ * Dependencies can be injected into the factory via the `inject` array.
+ *
+ * @template T - The type of service being provided
+ *
+ * @example
+ * ```typescript
+ * container.register({
+ *   provide: DATABASE,
+ *   useFactory: (config: ConfigService) => {
+ *     return createDatabaseClient(config.databaseUrl);
+ *   },
+ *   inject: [ConfigService],
+ *   scope: Scope.SINGLETON
+ * });
+ * ```
+ */
+export interface FactoryProvider<T = unknown> extends BaseProvider<T> {
+    /**
+     * The factory function that creates the service
+     *
+     * Receives resolved dependencies in order matching the `inject` array.
+     */
+    useFactory: (...args: never[]) => T | Promise<T>;
+    /**
+     * Tokens for dependencies to inject into the factory
+     *
+     * Dependencies are resolved and passed to the factory in order.
+     */
+    inject?: InjectionToken[];
+}
+/**
+ * Value provider
+ *
+ * Uses an existing value directly without any instantiation.
+ * Useful for configuration objects, constants, or pre-created instances.
+ *
+ * @template T - The type of service being provided
+ *
+ * @example
+ * ```typescript
+ * container.register({
+ *   provide: CONFIG,
+ *   useValue: {
+ *     port: 3210,
+ *     host: 'localhost',
+ *     debug: true
+ *   }
+ * });
+ * ```
+ */
+export interface ValueProvider<T = unknown> extends BaseProvider<T> {
+    /**
+     * The value to use as the service instance
+     */
+    useValue: T;
+}
+/**
+ * Existing provider (alias)
+ *
+ * Aliases one token to another, allowing multiple tokens
+ * to resolve to the same service.
+ *
+ * @template T - The type of service being provided
+ *
+ * @example
+ * ```typescript
+ * // Register the concrete implementation
+ * container.register({
+ *   provide: ConsoleLogger,
+ *   useClass: ConsoleLogger
+ * });
+ *
+ * // Create an alias using the interface token
+ * container.register({
+ *   provide: LOGGER,
+ *   useExisting: ConsoleLogger
+ * });
+ *
+ * // Both resolve to the same instance
+ * const logger1 = container.resolve(LOGGER);
+ * const logger2 = container.resolve(ConsoleLogger);
+ * // logger1 === logger2
+ * ```
+ */
+export interface ExistingProvider<T = unknown> extends BaseProvider<T> {
+    /**
+     * The token to alias to
+     *
+     * Resolving the `provide` token will resolve this token instead.
+     */
+    useExisting: InjectionToken<T>;
+}
+/**
+ * Union of all provider types
+ */
+export type Provider<T = unknown> = ClassProvider<T> | FactoryProvider<T> | ValueProvider<T> | ExistingProvider<T>;
+/**
+ * Type guard for class providers
+ */
+export declare function isClassProvider<T>(provider: Provider<T>): provider is ClassProvider<T>;
+/**
+ * Type guard for factory providers
+ */
+export declare function isFactoryProvider<T>(provider: Provider<T>): provider is FactoryProvider<T>;
+/**
+ * Type guard for value providers
+ */
+export declare function isValueProvider<T>(provider: Provider<T>): provider is ValueProvider<T>;
+/**
+ * Type guard for existing/alias providers
+ */
+export declare function isExistingProvider<T>(provider: Provider<T>): provider is ExistingProvider<T>;
+/**
+ * Validates a provider configuration
+ *
+ * @param provider - The provider to validate
+ * @throws {VeloxError} If the provider is invalid
+ */
+export declare function validateProvider(provider: unknown): asserts provider is Provider;
+/**
+ * Normalized provider with all optional fields filled in
+ *
+ * @internal
+ */
+export interface NormalizedProvider<T = unknown> {
+    provide: InjectionToken<T>;
+    scope: Scope;
+    type: 'class' | 'factory' | 'value' | 'existing';
+    implementation: {
+        class?: ClassConstructor<T>;
+        factory?: (...args: never[]) => T | Promise<T>;
+        inject?: InjectionToken[];
+        value?: T;
+        existing?: InjectionToken<T>;
+    };
+}
+/**
+ * Normalizes a provider to a consistent internal format
+ *
+ * @param provider - The provider to normalize
+ * @returns The normalized provider
+ *
+ * @internal
+ */
+export declare function normalizeProvider<T>(provider: Provider<T>): NormalizedProvider<T>;
+/**
+ * Creates a class provider with type inference
+ *
+ * @param cls - The class to provide
+ * @param scope - The lifecycle scope
+ * @returns A class provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(asClass(UserService, Scope.REQUEST));
+ * ```
+ */
+export declare function asClass<T>(cls: ClassConstructor<T>, scope?: Scope): ClassProvider<T>;
+/**
+ * Creates a factory provider with type inference
+ *
+ * @param token - The token to provide
+ * @param factory - The factory function
+ * @param options - Factory options (inject, scope)
+ * @returns A factory provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(asFactory(
+ *   DATABASE,
+ *   (config: ConfigService) => createDb(config.dbUrl),
+ *   { inject: [ConfigService] }
+ * ));
+ * ```
+ */
+export declare function asFactory<T>(token: InjectionToken<T>, factory: (...args: never[]) => T | Promise<T>, options?: {
+    inject?: InjectionToken[];
+    scope?: Scope;
+}): FactoryProvider<T>;
+/**
+ * Creates a value provider with type inference
+ *
+ * @param token - The token to provide
+ * @param value - The value to use
+ * @returns A value provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(asValue(CONFIG, { port: 3210 }));
+ * ```
+ */
+export declare function asValue<T>(token: InjectionToken<T>, value: T): ValueProvider<T>;
+/**
+ * Creates an existing/alias provider with type inference
+ *
+ * @param token - The token to provide (alias)
+ * @param existing - The token to alias to
+ * @returns An existing provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(asExisting(LOGGER, ConsoleLogger));
+ * ```
+ */
+export declare function asExisting<T>(token: InjectionToken<T>, existing: InjectionToken<T>): ExistingProvider<T>;
+/**
+ * Creates a singleton class provider
+ *
+ * Singleton services are instantiated once and shared across all requests.
+ * This is the default scope and the most common pattern.
+ *
+ * @param cls - The class to provide as a singleton
+ * @returns A class provider configured as singleton
+ *
+ * @example
+ * ```typescript
+ * container.register(singleton(ConfigService));
+ * container.register(singleton(DatabasePool));
+ * ```
+ */
+export declare function singleton<T>(cls: ClassConstructor<T>): ClassProvider<T>;
+/**
+ * Creates a request-scoped class provider
+ *
+ * Request-scoped services are instantiated once per HTTP request.
+ * Ideal for services that need request-specific state.
+ *
+ * @param cls - The class to provide with request scope
+ * @returns A class provider configured as request-scoped
+ *
+ * @example
+ * ```typescript
+ * container.register(scoped(RequestContext));
+ * container.register(scoped(UserSession));
+ * ```
+ */
+export declare function scoped<T>(cls: ClassConstructor<T>): ClassProvider<T>;
+/**
+ * Creates a transient class provider
+ *
+ * Transient services are instantiated every time they are resolved.
+ * Useful for stateful objects that should not be shared.
+ *
+ * @param cls - The class to provide as transient
+ * @returns A class provider configured as transient
+ *
+ * @example
+ * ```typescript
+ * container.register(transient(EmailBuilder));
+ * container.register(transient(RequestId));
+ * ```
+ */
+export declare function transient<T>(cls: ClassConstructor<T>): ClassProvider<T>;
+/**
+ * Creates a value provider (convenience alias)
+ *
+ * @param token - The token to provide
+ * @param val - The value to use
+ * @returns A value provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(value(CONFIG, { port: 3210 }));
+ * ```
+ */
+export declare function value<T>(token: InjectionToken<T>, val: T): ValueProvider<T>;
+/**
+ * Creates a factory provider (convenience alias)
+ *
+ * @param token - The token to provide
+ * @param factoryFn - The factory function
+ * @param deps - Dependencies to inject into the factory
+ * @returns A factory provider configuration
+ *
+ * @example
+ * ```typescript
+ * container.register(factory(DATABASE, createDb, [ConfigService]));
+ * ```
+ */
+export declare function factory<T>(token: InjectionToken<T>, factoryFn: (...args: never[]) => T | Promise<T>, deps?: InjectionToken[]): FactoryProvider<T>;
+/**
+ * Gets a human-readable description of a provider
+ *
+ * @param provider - The provider to describe
+ * @returns A string description
+ *
+ * @internal
+ */
+export declare function describeProvider(provider: Provider): string;
+export {};
+//# sourceMappingURL=providers.d.ts.map

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

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