@veloxts/core 0.3.3 → 0.3.5

package/dist/di/providers.js

@@ -0,0 +1,380 @@
+/**
+ * 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 { VeloxError } from '../errors.js';
+import { getDefaultScope, isValidScope, Scope } from './scope.js';
+import { getTokenName, validateToken } from './tokens.js';
+// ============================================================================
+// Provider Type Guards
+// ============================================================================
+/**
+ * Type guard for class providers
+ */
+export function isClassProvider(provider) {
+    return 'useClass' in provider && typeof provider.useClass === 'function';
+}
+/**
+ * Type guard for factory providers
+ */
+export function isFactoryProvider(provider) {
+    return 'useFactory' in provider && typeof provider.useFactory === 'function';
+}
+/**
+ * Type guard for value providers
+ */
+export function isValueProvider(provider) {
+    return 'useValue' in provider;
+}
+/**
+ * Type guard for existing/alias providers
+ */
+export function isExistingProvider(provider) {
+    return 'useExisting' in provider;
+}
+// ============================================================================
+// Provider Validation
+// ============================================================================
+/**
+ * Validates a provider configuration
+ *
+ * @param provider - The provider to validate
+ * @throws {VeloxError} If the provider is invalid
+ */
+export function validateProvider(provider) {
+    // Check provider is an object
+    if (typeof provider !== 'object' || provider === null) {
+        throw new VeloxError('Provider must be an object', 500, 'INVALID_PROVIDER');
+    }
+    // Check 'provide' token exists
+    if (!('provide' in provider)) {
+        throw new VeloxError('Provider must have a "provide" token', 500, 'INVALID_PROVIDER');
+    }
+    // Validate the token
+    validateToken(provider.provide);
+    const typedProvider = provider;
+    // Check that exactly one of the provider type properties exists
+    const providerTypes = ['useClass', 'useFactory', 'useValue', 'useExisting'];
+    const definedTypes = providerTypes.filter((type) => type in typedProvider);
+    if (definedTypes.length === 0) {
+        throw new VeloxError('Provider must specify one of: useClass, useFactory, useValue, or useExisting', 500, 'INVALID_PROVIDER');
+    }
+    if (definedTypes.length > 1) {
+        throw new VeloxError(`Provider cannot have multiple types. Found: ${definedTypes.join(', ')}`, 500, 'INVALID_PROVIDER');
+    }
+    // Validate scope if provided
+    if ('scope' in typedProvider && typedProvider.scope !== undefined) {
+        if (!isValidScope(typedProvider.scope)) {
+            throw new VeloxError(`Invalid scope: ${String(typedProvider.scope)}. Must be one of: singleton, transient, request`, 500, 'INVALID_PROVIDER');
+        }
+    }
+    // Validate specific provider types
+    if ('useClass' in typedProvider) {
+        if (typeof typedProvider.useClass !== 'function') {
+            throw new VeloxError('useClass must be a class constructor', 500, 'INVALID_PROVIDER');
+        }
+    }
+    if ('useFactory' in typedProvider) {
+        if (typeof typedProvider.useFactory !== 'function') {
+            throw new VeloxError('useFactory must be a function', 500, 'INVALID_PROVIDER');
+        }
+        if ('inject' in typedProvider && typedProvider.inject !== undefined) {
+            if (!Array.isArray(typedProvider.inject)) {
+                throw new VeloxError('Factory inject must be an array of injection tokens', 500, 'INVALID_PROVIDER');
+            }
+            // Validate each inject token
+            for (const token of typedProvider.inject) {
+                validateToken(token);
+            }
+        }
+    }
+    if ('useExisting' in typedProvider) {
+        validateToken(typedProvider.useExisting);
+    }
+}
+/**
+ * Normalizes a provider to a consistent internal format
+ *
+ * @param provider - The provider to normalize
+ * @returns The normalized provider
+ *
+ * @internal
+ */
+export function normalizeProvider(provider) {
+    const scope = provider.scope ?? getDefaultScope();
+    if (isClassProvider(provider)) {
+        return {
+            provide: provider.provide,
+            scope,
+            type: 'class',
+            implementation: {
+                class: provider.useClass,
+            },
+        };
+    }
+    if (isFactoryProvider(provider)) {
+        return {
+            provide: provider.provide,
+            scope,
+            type: 'factory',
+            implementation: {
+                factory: provider.useFactory,
+                inject: provider.inject,
+            },
+        };
+    }
+    if (isValueProvider(provider)) {
+        // Value providers are always effectively singleton since they use the same value
+        return {
+            provide: provider.provide,
+            scope: Scope.SINGLETON,
+            type: 'value',
+            implementation: {
+                value: provider.useValue,
+            },
+        };
+    }
+    if (isExistingProvider(provider)) {
+        return {
+            provide: provider.provide,
+            scope, // Inherit scope from the aliased provider at resolution time
+            type: 'existing',
+            implementation: {
+                existing: provider.useExisting,
+            },
+        };
+    }
+    // This should never happen due to validation, but TypeScript needs it
+    throw new VeloxError('Unknown provider type', 500, 'INVALID_PROVIDER');
+}
+// ============================================================================
+// Convenience Provider Builders
+// ============================================================================
+/**
+ * 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 function asClass(cls, scope = Scope.SINGLETON) {
+    return {
+        provide: cls,
+        useClass: cls,
+        scope,
+    };
+}
+/**
+ * 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 function asFactory(token, factory, options = {}) {
+    return {
+        provide: token,
+        useFactory: factory,
+        inject: options.inject,
+        scope: options.scope ?? Scope.SINGLETON,
+    };
+}
+/**
+ * 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 function asValue(token, value) {
+    return {
+        provide: token,
+        useValue: value,
+    };
+}
+/**
+ * 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 function asExisting(token, existing) {
+    return {
+        provide: token,
+        useExisting: existing,
+    };
+}
+// ============================================================================
+// Succinct Scope Helpers
+// ============================================================================
+/**
+ * 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 function singleton(cls) {
+    return {
+        provide: cls,
+        useClass: cls,
+        scope: Scope.SINGLETON,
+    };
+}
+/**
+ * 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 function scoped(cls) {
+    return {
+        provide: cls,
+        useClass: cls,
+        scope: Scope.REQUEST,
+    };
+}
+/**
+ * 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 function transient(cls) {
+    return {
+        provide: cls,
+        useClass: cls,
+        scope: Scope.TRANSIENT,
+    };
+}
+/**
+ * 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 function value(token, val) {
+    return {
+        provide: token,
+        useValue: val,
+    };
+}
+/**
+ * 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 function factory(token, factoryFn, deps) {
+    return {
+        provide: token,
+        useFactory: factoryFn,
+        inject: deps,
+        scope: Scope.SINGLETON,
+    };
+}
+// ============================================================================
+// Provider Description (for debugging)
+// ============================================================================
+/**
+ * Gets a human-readable description of a provider
+ *
+ * @param provider - The provider to describe
+ * @returns A string description
+ *
+ * @internal
+ */
+export function describeProvider(provider) {
+    const tokenName = getTokenName(provider.provide);
+    const scope = provider.scope ?? 'singleton';
+    if (isClassProvider(provider)) {
+        const className = provider.useClass.name || 'AnonymousClass';
+        return `ClassProvider(${tokenName} => ${className}, ${scope})`;
+    }
+    if (isFactoryProvider(provider)) {
+        const deps = provider.inject?.map(getTokenName).join(', ') ?? 'none';
+        return `FactoryProvider(${tokenName}, deps=[${deps}], ${scope})`;
+    }
+    if (isValueProvider(provider)) {
+        return `ValueProvider(${tokenName})`;
+    }
+    if (isExistingProvider(provider)) {
+        const existing = getTokenName(provider.useExisting);
+        return `ExistingProvider(${tokenName} => ${existing})`;
+    }
+    return `Provider(${tokenName})`;
+}
+//# sourceMappingURL=providers.js.map

package/dist/di/providers.js.map

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

package/dist/di/scope.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Lifecycle scope management for dependency injection
+ *
+ * Defines how service instances are created and shared:
+ * - Singleton: One instance for the entire application
+ * - Transient: New instance on every resolution
+ * - Request: One instance per HTTP request
+ *
+ * @module di/scope
+ */
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+/**
+ * Service lifecycle scope
+ *
+ * Determines how instances are created and shared across the application.
+ *
+ * @example
+ * ```typescript
+ * // Singleton - shared across all requests
+ * container.register({
+ *   provide: ConfigService,
+ *   useClass: ConfigService,
+ *   scope: Scope.SINGLETON
+ * });
+ *
+ * // Transient - new instance every time
+ * container.register({
+ *   provide: RequestIdGenerator,
+ *   useClass: RequestIdGenerator,
+ *   scope: Scope.TRANSIENT
+ * });
+ *
+ * // Request - shared within a single HTTP request
+ * container.register({
+ *   provide: UserContext,
+ *   useClass: UserContext,
+ *   scope: Scope.REQUEST
+ * });
+ * ```
+ */
+export declare enum Scope {
+    /**
+     * Singleton scope
+     *
+     * A single instance is created and shared across the entire application.
+     * The instance is created on first resolution and reused for all subsequent
+     * resolutions.
+     *
+     * Best for:
+     * - Configuration services
+     * - Database connection pools
+     * - Cache clients
+     * - Stateless utility services
+     */
+    SINGLETON = "singleton",
+    /**
+     * Transient scope
+     *
+     * A new instance is created every time the service is resolved.
+     * No caching or sharing occurs.
+     *
+     * Best for:
+     * - Services that maintain mutable state
+     * - Factories that produce unique objects
+     * - Services where isolation is critical
+     */
+    TRANSIENT = "transient",
+    /**
+     * Request scope
+     *
+     * A single instance is created and shared within the lifetime of an HTTP request.
+     * Different requests get different instances.
+     *
+     * Best for:
+     * - User context/session data
+     * - Request-specific caching
+     * - Transaction management
+     * - Audit logging with request context
+     *
+     * Note: Resolving request-scoped services outside of a request context
+     * will throw an error.
+     */
+    REQUEST = "request"
+}
+/**
+ * Request-scoped instance store key
+ * Using a symbol prevents collision with user-defined properties
+ */
+declare const REQUEST_SCOPE_KEY: unique symbol;
+/**
+ * Type augmentation for Fastify request to store scoped instances
+ */
+declare module 'fastify' {
+    interface FastifyRequest {
+        /**
+         * Request-scoped service instance cache
+         * @internal
+         */
+        [REQUEST_SCOPE_KEY]?: Map<unknown, unknown>;
+    }
+}
+/**
+ * Manages service instance lifecycles
+ *
+ * Handles creation, caching, and cleanup of service instances
+ * based on their configured scope.
+ *
+ * @internal
+ */
+export declare class ScopeManager {
+    /**
+     * Singleton instance cache
+     * Maps tokens to their singleton instances
+     */
+    private readonly singletonCache;
+    /**
+     * Whether request scope hooks have been set up
+     */
+    private requestScopeInitialized;
+    /**
+     * Attaches the scope manager to a Fastify server
+     *
+     * This sets up the request lifecycle hooks needed for request-scoped services.
+     * Must be called before resolving request-scoped services.
+     *
+     * @param server - Fastify server instance
+     */
+    attachToFastify(server: FastifyInstance): void;
+    /**
+     * Gets a singleton instance from cache
+     *
+     * @param token - The service token
+     * @returns The cached instance or undefined
+     */
+    getSingleton<T>(token: unknown): T | undefined;
+    /**
+     * Stores a singleton instance in cache
+     *
+     * @param token - The service token
+     * @param instance - The instance to cache
+     */
+    setSingleton<T>(token: unknown, instance: T): void;
+    /**
+     * Checks if a singleton instance exists
+     *
+     * @param token - The service token
+     * @returns true if a singleton instance is cached
+     */
+    hasSingleton(token: unknown): boolean;
+    /**
+     * Gets a singleton instance from cache, throwing if not found
+     *
+     * Use this when you've already verified with hasSingleton()
+     *
+     * @param token - The service token
+     * @returns The cached instance
+     * @throws {VeloxError} If no singleton is cached for this token
+     */
+    getSingletonOrThrow<T>(token: unknown): T;
+    /**
+     * Gets a request-scoped instance from the current request's cache
+     *
+     * @param token - The service token
+     * @param request - The current Fastify request
+     * @returns The cached instance or undefined
+     */
+    getRequestScoped<T>(token: unknown, request: FastifyRequest): T | undefined;
+    /**
+     * Stores a request-scoped instance in the current request's cache
+     *
+     * @param token - The service token
+     * @param instance - The instance to cache
+     * @param request - The current Fastify request
+     */
+    setRequestScoped<T>(token: unknown, instance: T, request: FastifyRequest): void;
+    /**
+     * Checks if a request-scoped instance exists
+     *
+     * @param token - The service token
+     * @param request - The current Fastify request
+     * @returns true if a request-scoped instance is cached
+     */
+    hasRequestScoped(token: unknown, request: FastifyRequest): boolean;
+    /**
+     * Gets a request-scoped instance from cache, throwing if not found
+     *
+     * Use this when you've already verified with hasRequestScoped()
+     *
+     * @param token - The service token
+     * @param request - The current Fastify request
+     * @returns The cached instance
+     * @throws {VeloxError} If no request-scoped instance is cached for this token
+     */
+    getRequestScopedOrThrow<T>(token: unknown, request: FastifyRequest): T;
+    /**
+     * Validates that request scope is available and returns the request
+     *
+     * @param request - The current request (may be undefined outside request context)
+     * @returns The validated FastifyRequest
+     * @throws {VeloxError} If request scope is not available
+     */
+    ensureRequestScope(request: FastifyRequest | undefined): FastifyRequest;
+    /**
+     * Clears all singleton instances
+     *
+     * Useful for testing or application shutdown.
+     */
+    clearSingletons(): void;
+    /**
+     * Clears all cached instances and resets state
+     *
+     * @internal
+     */
+    reset(): void;
+}
+/**
+ * Validates a scope value
+ *
+ * @param scope - The scope to validate
+ * @returns true if the scope is valid
+ */
+export declare function isValidScope(scope: unknown): scope is Scope;
+/**
+ * Gets the default scope for a provider
+ *
+ * @returns The default scope (SINGLETON)
+ */
+export declare function getDefaultScope(): Scope;
+export {};
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/di/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAQ/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,oBAAY,KAAK;IACf;;;;;;;;;;;;OAYG;IACH,SAAS,cAAc;IAEvB;;;;;;;;;;OAUG;IACH,SAAS,cAAc;IAEvB;;;;;;;;;;;;;;OAcG;IACH,OAAO,YAAY;CACpB;AAMD;;;GAGG;AACH,QAAA,MAAM,iBAAiB,eAAmC,CAAC;AAE3D;;GAEG;AACH,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB;;;WAGG;QACH,CAAC,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;KAC7C;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA+B;IAE9D;;OAEG;IACH,OAAO,CAAC,uBAAuB,CAAS;IAExC;;;;;;;OAOG;IACH,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAsB9C;;;;;OAKG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,SAAS;IAI9C;;;;;OAKG;IACH,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI;IAIlD;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAIrC;;;;;;;;OAQG;IACH,mBAAmB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC;IAOzC;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,CAAC,GAAG,SAAS;IAQ3E;;;;;;OAMG;IACH,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAY/E;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO;IAKlE;;;;;;;;;OASG;IACH,uBAAuB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,GAAG,CAAC;IAYtE;;;;;;OAMG;IACH,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,GAAG,cAAc;IAqBvE;;;;OAIG;IACH,eAAe,IAAI,IAAI;IAIvB;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAId;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,KAAK,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAEvC"}