@veloxts/core 0.3.3 → 0.3.4

package/dist/di/scope.js

@@ -0,0 +1,262 @@
+/**
+ * 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 { VeloxError } from '../errors.js';
+// ============================================================================
+// Scope Enum
+// ============================================================================
+/**
+ * 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 var Scope;
+(function (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
+     */
+    Scope["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
+     */
+    Scope["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.
+     */
+    Scope["REQUEST"] = "request";
+})(Scope || (Scope = {}));
+// ============================================================================
+// Scope Manager
+// ============================================================================
+/**
+ * Request-scoped instance store key
+ * Using a symbol prevents collision with user-defined properties
+ */
+const REQUEST_SCOPE_KEY = Symbol('velox:di:request-scope');
+/**
+ * Manages service instance lifecycles
+ *
+ * Handles creation, caching, and cleanup of service instances
+ * based on their configured scope.
+ *
+ * @internal
+ */
+export class ScopeManager {
+    /**
+     * Singleton instance cache
+     * Maps tokens to their singleton instances
+     */
+    singletonCache = new Map();
+    /**
+     * Whether request scope hooks have been set up
+     */
+    requestScopeInitialized = false;
+    /**
+     * 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) {
+        if (this.requestScopeInitialized) {
+            return;
+        }
+        // Initialize request scope cache on each request
+        server.addHook('onRequest', async (request) => {
+            request[REQUEST_SCOPE_KEY] = new Map();
+        });
+        // Clean up request scope cache after response
+        server.addHook('onResponse', async (request) => {
+            const cache = request[REQUEST_SCOPE_KEY];
+            if (cache) {
+                cache.clear();
+                delete request[REQUEST_SCOPE_KEY];
+            }
+        });
+        this.requestScopeInitialized = true;
+    }
+    /**
+     * Gets a singleton instance from cache
+     *
+     * @param token - The service token
+     * @returns The cached instance or undefined
+     */
+    getSingleton(token) {
+        return this.singletonCache.get(token);
+    }
+    /**
+     * Stores a singleton instance in cache
+     *
+     * @param token - The service token
+     * @param instance - The instance to cache
+     */
+    setSingleton(token, instance) {
+        this.singletonCache.set(token, instance);
+    }
+    /**
+     * Checks if a singleton instance exists
+     *
+     * @param token - The service token
+     * @returns true if a singleton instance is cached
+     */
+    hasSingleton(token) {
+        return this.singletonCache.has(token);
+    }
+    /**
+     * 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(token, request) {
+        const cache = request[REQUEST_SCOPE_KEY];
+        if (!cache) {
+            return undefined;
+        }
+        return cache.get(token);
+    }
+    /**
+     * 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(token, instance, request) {
+        const cache = request[REQUEST_SCOPE_KEY];
+        if (!cache) {
+            throw new VeloxError('Request scope cache not initialized. Ensure ScopeManager is attached to Fastify.', 500, 'REQUEST_SCOPE_UNAVAILABLE');
+        }
+        cache.set(token, instance);
+    }
+    /**
+     * 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, request) {
+        const cache = request[REQUEST_SCOPE_KEY];
+        return cache?.has(token) ?? false;
+    }
+    /**
+     * 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) {
+        if (!request) {
+            throw new VeloxError('Cannot resolve request-scoped service outside of request context. ' +
+                'Ensure you are resolving within a request handler or middleware.', 500, 'REQUEST_SCOPE_UNAVAILABLE');
+        }
+        if (!request[REQUEST_SCOPE_KEY]) {
+            throw new VeloxError('Request scope cache not initialized. Ensure ScopeManager is attached to Fastify.', 500, 'REQUEST_SCOPE_UNAVAILABLE');
+        }
+        return request;
+    }
+    /**
+     * Clears all singleton instances
+     *
+     * Useful for testing or application shutdown.
+     */
+    clearSingletons() {
+        this.singletonCache.clear();
+    }
+    /**
+     * Clears all cached instances and resets state
+     *
+     * @internal
+     */
+    reset() {
+        this.singletonCache.clear();
+        this.requestScopeInitialized = false;
+    }
+}
+// ============================================================================
+// Scope Utilities
+// ============================================================================
+/**
+ * Validates a scope value
+ *
+ * @param scope - The scope to validate
+ * @returns true if the scope is valid
+ */
+export function isValidScope(scope) {
+    return scope === Scope.SINGLETON || scope === Scope.TRANSIENT || scope === Scope.REQUEST;
+}
+/**
+ * Gets the default scope for a provider
+ *
+ * @returns The default scope (SINGLETON)
+ */
+export function getDefaultScope() {
+    return Scope.SINGLETON;
+}
+//# sourceMappingURL=scope.js.map

package/dist/di/scope.js.map

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

package/dist/di/tokens.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Service tokens for dependency injection
+ *
+ * Tokens are unique identifiers used to register and resolve services.
+ * VeloxTS supports three token types:
+ * - Class tokens: The class constructor itself
+ * - String tokens: String literals for named services
+ * - Symbol tokens: Unique symbols for collision-free tokens
+ *
+ * @module di/tokens
+ */
+/**
+ * Abstract class token type
+ *
+ * Represents a class constructor that can be used as a service token.
+ * Supports both concrete classes and abstract classes.
+ *
+ * @template T - The type that the class constructs
+ */
+export interface AbstractClass<T = unknown> {
+    prototype: T;
+}
+/**
+ * Concrete class constructor type
+ *
+ * Represents a class that can be instantiated with `new`.
+ * The constructor accepts any arguments and returns an instance of T.
+ *
+ * @template T - The type that the class constructs
+ */
+export interface ClassConstructor<T = unknown> extends AbstractClass<T> {
+    new (...args: never[]): T;
+}
+/**
+ * Unique brand symbol for string tokens (compile-time only)
+ * @internal
+ */
+declare const StringTokenBrand: unique symbol;
+/**
+ * Unique brand symbol for symbol tokens (compile-time only)
+ * @internal
+ */
+declare const SymbolTokenBrand: unique symbol;
+/**
+ * String token type for named services
+ *
+ * Branded type to distinguish service tokens from regular strings at compile time.
+ * The brand is purely a compile-time construct for type safety.
+ *
+ * @example
+ * ```typescript
+ * const DATABASE = createStringToken<DatabaseClient>('DATABASE');
+ * container.register({ provide: DATABASE, useFactory: () => createDb() });
+ * ```
+ */
+export type StringToken<T = unknown> = string & {
+    readonly [StringTokenBrand]: T;
+};
+/**
+ * Symbol token type for unique service identifiers
+ *
+ * Branded type that carries the service type information.
+ * The brand is purely a compile-time construct for type safety.
+ *
+ * @example
+ * ```typescript
+ * const LOGGER = createSymbolToken<Logger>('LOGGER');
+ * container.register({ provide: LOGGER, useClass: ConsoleLogger });
+ * ```
+ */
+export type SymbolToken<T = unknown> = symbol & {
+    readonly [SymbolTokenBrand]: T;
+};
+/**
+ * Union of all valid injection token types
+ *
+ * A token can be:
+ * - A class constructor (for automatic injection)
+ * - A string token (for named services)
+ * - A symbol token (for unique identifiers)
+ *
+ * @template T - The type of service the token represents
+ */
+export type InjectionToken<T = unknown> = ClassConstructor<T> | AbstractClass<T> | StringToken<T> | SymbolToken<T>;
+/**
+ * Extract the type from an injection token
+ *
+ * @template T - The injection token type
+ *
+ * @example
+ * ```typescript
+ * type UserServiceType = TokenType<typeof UserService>; // UserService
+ * type DbType = TokenType<typeof DATABASE>; // DatabaseClient
+ * ```
+ */
+export type TokenType<T> = T extends InjectionToken<infer U> ? U : never;
+/**
+ * Creates a typed string token for service registration
+ *
+ * String tokens are useful when you want human-readable identifiers.
+ * The type parameter ensures type safety when resolving the service.
+ *
+ * @template T - The type of service this token represents
+ * @param name - The string identifier for this token
+ * @returns A typed string token
+ *
+ * @example
+ * ```typescript
+ * interface DatabaseClient {
+ *   query(sql: string): Promise<unknown>;
+ * }
+ *
+ * const DATABASE = createStringToken<DatabaseClient>('DATABASE');
+ *
+ * // Registration
+ * container.register({
+ *   provide: DATABASE,
+ *   useFactory: () => createDatabaseClient()
+ * });
+ *
+ * // Resolution - type is inferred as DatabaseClient
+ * const db = container.resolve(DATABASE);
+ * await db.query('SELECT * FROM users');
+ * ```
+ */
+export declare function createStringToken<T>(name: string): StringToken<T>;
+/**
+ * Creates a typed symbol token for service registration
+ *
+ * Symbol tokens guarantee uniqueness across the application,
+ * preventing name collisions between different modules.
+ *
+ * @template T - The type of service this token represents
+ * @param description - Optional description for debugging
+ * @returns A typed symbol token
+ *
+ * @example
+ * ```typescript
+ * interface Logger {
+ *   log(message: string): void;
+ * }
+ *
+ * const LOGGER = createSymbolToken<Logger>('Logger');
+ *
+ * // Registration
+ * container.register({
+ *   provide: LOGGER,
+ *   useClass: ConsoleLogger
+ * });
+ *
+ * // Resolution - type is inferred as Logger
+ * const logger = container.resolve(LOGGER);
+ * logger.log('Hello, world!');
+ * ```
+ */
+export declare function createSymbolToken<T>(description?: string): SymbolToken<T>;
+/**
+ * Creates a typed string token for service registration
+ *
+ * This is the preferred API for creating tokens. String tokens are
+ * useful when you want human-readable identifiers.
+ *
+ * @template T - The type of service this token represents
+ * @param name - The string identifier for this token
+ * @returns A typed string token
+ *
+ * @example
+ * ```typescript
+ * const DATABASE = token<DatabaseClient>('DATABASE');
+ * const CONFIG = token<AppConfig>('CONFIG');
+ *
+ * container.register({ provide: DATABASE, useFactory: createDb });
+ * ```
+ */
+export declare function token<T>(name: string): StringToken<T>;
+export declare namespace token {
+    var symbol: <T>(description?: string) => SymbolToken<T>;
+}
+/**
+ * Gets a human-readable name for a token
+ *
+ * @param token - The token to get the name for
+ * @returns A string representation of the token
+ *
+ * @internal
+ */
+export declare function getTokenName(token: InjectionToken): string;
+/**
+ * Type guard for class constructor tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a class constructor
+ */
+export declare function isClassToken(token: InjectionToken): token is ClassConstructor;
+/**
+ * Type guard for string tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a string token
+ */
+export declare function isStringToken(token: InjectionToken): token is StringToken;
+/**
+ * Type guard for symbol tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a symbol token
+ */
+export declare function isSymbolToken(token: InjectionToken): token is SymbolToken;
+/**
+ * Validates that a token is a valid injection token
+ *
+ * @param token - The value to validate
+ * @throws {VeloxError} If the token is not valid
+ *
+ * @internal
+ */
+export declare function validateToken(token: unknown): asserts token is InjectionToken;
+/**
+ * Extend the error code registry for DI-related errors
+ */
+declare module '../errors.js' {
+    interface VeloxErrorCodeRegistry {
+        di: 'INVALID_INJECTION_TOKEN' | 'SERVICE_NOT_FOUND' | 'CIRCULAR_DEPENDENCY' | 'MISSING_INJECTABLE_DECORATOR' | 'INVALID_PROVIDER' | 'SCOPE_MISMATCH' | 'REQUEST_SCOPE_UNAVAILABLE';
+    }
+}
+export {};
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/di/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,SAAS,EAAE,CAAC,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACrE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;CAC3B;AAED;;;GAGG;AACH,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C;;;GAGG;AACH,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEnF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAClC,gBAAgB,CAAC,CAAC,CAAC,GACnB,aAAa,CAAC,CAAC,CAAC,GAChB,WAAW,CAAC,CAAC,CAAC,GACd,WAAW,CAAC,CAAC,CAAC,CAAC;AAEnB;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAMzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAEzE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAErD;yBAFe,KAAK;iBAkBe,CAAC,gBAAgB,MAAM,KAAG,WAAW,CAAC,CAAC,CAAC;;AAQ5E;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAkB1D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,gBAAgB,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,WAAW,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,IAAI,WAAW,CAGzE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAkB7E;AAMD;;GAEG;AACH,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,sBAAsB;QAC9B,EAAE,EACE,yBAAyB,GACzB,mBAAmB,GACnB,qBAAqB,GACrB,8BAA8B,GAC9B,kBAAkB,GAClB,gBAAgB,GAChB,2BAA2B,CAAC;KACjC;CACF"}

package/dist/di/tokens.js

@@ -0,0 +1,192 @@
+/**
+ * Service tokens for dependency injection
+ *
+ * Tokens are unique identifiers used to register and resolve services.
+ * VeloxTS supports three token types:
+ * - Class tokens: The class constructor itself
+ * - String tokens: String literals for named services
+ * - Symbol tokens: Unique symbols for collision-free tokens
+ *
+ * @module di/tokens
+ */
+import { VeloxError } from '../errors.js';
+// ============================================================================
+// Token Creation Functions
+// ============================================================================
+/**
+ * Creates a typed string token for service registration
+ *
+ * String tokens are useful when you want human-readable identifiers.
+ * The type parameter ensures type safety when resolving the service.
+ *
+ * @template T - The type of service this token represents
+ * @param name - The string identifier for this token
+ * @returns A typed string token
+ *
+ * @example
+ * ```typescript
+ * interface DatabaseClient {
+ *   query(sql: string): Promise<unknown>;
+ * }
+ *
+ * const DATABASE = createStringToken<DatabaseClient>('DATABASE');
+ *
+ * // Registration
+ * container.register({
+ *   provide: DATABASE,
+ *   useFactory: () => createDatabaseClient()
+ * });
+ *
+ * // Resolution - type is inferred as DatabaseClient
+ * const db = container.resolve(DATABASE);
+ * await db.query('SELECT * FROM users');
+ * ```
+ */
+export function createStringToken(name) {
+    return name;
+}
+/**
+ * Creates a typed symbol token for service registration
+ *
+ * Symbol tokens guarantee uniqueness across the application,
+ * preventing name collisions between different modules.
+ *
+ * @template T - The type of service this token represents
+ * @param description - Optional description for debugging
+ * @returns A typed symbol token
+ *
+ * @example
+ * ```typescript
+ * interface Logger {
+ *   log(message: string): void;
+ * }
+ *
+ * const LOGGER = createSymbolToken<Logger>('Logger');
+ *
+ * // Registration
+ * container.register({
+ *   provide: LOGGER,
+ *   useClass: ConsoleLogger
+ * });
+ *
+ * // Resolution - type is inferred as Logger
+ * const logger = container.resolve(LOGGER);
+ * logger.log('Hello, world!');
+ * ```
+ */
+export function createSymbolToken(description) {
+    return Symbol(description);
+}
+// ============================================================================
+// Succinct Token API
+// ============================================================================
+/**
+ * Creates a typed string token for service registration
+ *
+ * This is the preferred API for creating tokens. String tokens are
+ * useful when you want human-readable identifiers.
+ *
+ * @template T - The type of service this token represents
+ * @param name - The string identifier for this token
+ * @returns A typed string token
+ *
+ * @example
+ * ```typescript
+ * const DATABASE = token<DatabaseClient>('DATABASE');
+ * const CONFIG = token<AppConfig>('CONFIG');
+ *
+ * container.register({ provide: DATABASE, useFactory: createDb });
+ * ```
+ */
+export function token(name) {
+    return name;
+}
+/**
+ * Token creation namespace with factory methods
+ *
+ * Provides a succinct, grouped API for creating different token types.
+ *
+ * @example
+ * ```typescript
+ * // String token (most common)
+ * const DATABASE = token<DatabaseClient>('DATABASE');
+ *
+ * // Symbol token (guaranteed unique)
+ * const LOGGER = token.symbol<Logger>('LOGGER');
+ * ```
+ */
+token.symbol = function symbolToken(description) {
+    return Symbol(description);
+};
+// ============================================================================
+// Token Utilities
+// ============================================================================
+/**
+ * Gets a human-readable name for a token
+ *
+ * @param token - The token to get the name for
+ * @returns A string representation of the token
+ *
+ * @internal
+ */
+export function getTokenName(token) {
+    // Cast to unknown for proper typeof narrowing without IDE warnings
+    // This is safe because InjectionToken runtime values are always string | symbol | function
+    const rawToken = token;
+    if (typeof rawToken === 'string') {
+        return rawToken;
+    }
+    if (typeof rawToken === 'symbol') {
+        return rawToken.description ?? 'Symbol()';
+    }
+    if (typeof rawToken === 'function') {
+        return rawToken.name || 'AnonymousClass';
+    }
+    return 'Unknown';
+}
+/**
+ * Type guard for class constructor tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a class constructor
+ */
+export function isClassToken(token) {
+    return typeof token === 'function';
+}
+/**
+ * Type guard for string tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a string token
+ */
+export function isStringToken(token) {
+    return typeof token === 'string';
+}
+/**
+ * Type guard for symbol tokens
+ *
+ * @param token - The token to check
+ * @returns true if the token is a symbol token
+ */
+export function isSymbolToken(token) {
+    // Cast to unknown for proper typeof narrowing without IDE warnings
+    return typeof token === 'symbol';
+}
+/**
+ * Validates that a token is a valid injection token
+ *
+ * @param token - The value to validate
+ * @throws {VeloxError} If the token is not valid
+ *
+ * @internal
+ */
+export function validateToken(token) {
+    if (token === null || token === undefined) {
+        throw new VeloxError('Injection token cannot be null or undefined', 500, 'INVALID_INJECTION_TOKEN');
+    }
+    const tokenType = typeof token;
+    if (tokenType !== 'string' && tokenType !== 'symbol' && tokenType !== 'function') {
+        throw new VeloxError(`Invalid injection token type: ${tokenType}. Expected string, symbol, or class constructor.`, 500, 'INVALID_INJECTION_TOKEN');
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/dist/di/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/di/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAmG1C,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,iBAAiB,CAAI,IAAY;IAC/C,OAAO,IAAsB,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,iBAAiB,CAAI,WAAoB;IACvD,OAAO,MAAM,CAAC,WAAW,CAAmB,CAAC;AAC/C,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,KAAK,CAAI,IAAY;IACnC,OAAO,IAAsB,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,KAAK,CAAC,MAAM,GAAG,SAAS,WAAW,CAAI,WAAoB;IACzD,OAAO,MAAM,CAAC,WAAW,CAAmB,CAAC;AAC/C,CAAC,CAAC;AAEF,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,mEAAmE;IACnE,2FAA2F;IAC3F,MAAM,QAAQ,GAAY,KAAK,CAAC;IAEhC,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QACjC,OAAO,QAAQ,CAAC,WAAW,IAAI,UAAU,CAAC;IAC5C,CAAC;IAED,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QACnC,OAAO,QAAQ,CAAC,IAAI,IAAI,gBAAgB,CAAC;IAC3C,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;AACnC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,mEAAmE;IACnE,OAAO,OAAQ,KAAiB,KAAK,QAAQ,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAClB,6CAA6C,EAC7C,GAAG,EACH,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAE/B,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QACjF,MAAM,IAAI,UAAU,CAClB,iCAAiC,SAAS,kDAAkD,EAC5F,GAAG,EACH,yBAAyB,CAC1B,CAAC;IACJ,CAAC;AACH,CAAC"}