@veloxts/core 0.3.3 → 0.3.5

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"}

package/dist/errors/catalog.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Error Catalog - Centralized error definitions with fix suggestions
+ *
+ * Error codes follow the pattern: VELOX-XYYY
+ * - X: Domain (1=Core, 2=Router, 3=Auth, 4=ORM, 5=Validation, 6=Client)
+ * - YYY: Sequential number within domain
+ *
+ * @module errors/catalog
+ */
+/**
+ * Error code domain prefixes
+ */
+export declare const ERROR_DOMAINS: {
+    readonly CORE: 1;
+    readonly ROUTER: 2;
+    readonly AUTH: 3;
+    readonly ORM: 4;
+    readonly VALIDATION: 5;
+    readonly CLIENT: 6;
+};
+export type ErrorDomain = keyof typeof ERROR_DOMAINS;
+/**
+ * A single error catalog entry with all metadata for developer assistance
+ */
+export interface ErrorCatalogEntry {
+    /** Unique error code (e.g., 'VELOX-1001') */
+    code: string;
+    /** Short title for the error */
+    title: string;
+    /** Detailed explanation of why this error occurs */
+    description: string;
+    /** HTTP status code to use */
+    statusCode: number;
+    /** Suggested fix with code example */
+    fix?: {
+        /** What the developer should do */
+        suggestion: string;
+        /** Code example showing the fix (optional) */
+        example?: string;
+    };
+    /** Link to documentation page */
+    docsUrl?: string;
+    /** Related error codes */
+    seeAlso?: string[];
+}
+/**
+ * The complete error catalog
+ * Organized by domain for easy navigation
+ */
+export declare const ERROR_CATALOG: Record<string, ErrorCatalogEntry>;
+/**
+ * Get an error catalog entry by code
+ *
+ * @param code - The error code (e.g., 'VELOX-1001')
+ * @returns The catalog entry or undefined if not found
+ */
+export declare function getErrorEntry(code: string): ErrorCatalogEntry | undefined;
+/**
+ * Get all error codes for a specific domain
+ *
+ * @param domain - The error domain (e.g., 'CORE', 'AUTH')
+ * @returns Array of error codes in that domain
+ */
+export declare function getErrorsByDomain(domain: ErrorDomain): string[];
+/**
+ * Check if an error code exists in the catalog
+ *
+ * @param code - The error code to check
+ * @returns true if the code exists
+ */
+export declare function isKnownErrorCode(code: string): boolean;
+/**
+ * Get the documentation URL for an error code
+ *
+ * @param code - The error code
+ * @returns The documentation URL or undefined
+ */
+export declare function getDocsUrl(code: string): string | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/errors/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/errors/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;CAOhB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,aAAa,CAAC;AAMrD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IAEd,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IAEnB,sCAAsC;IACtC,GAAG,CAAC,EAAE;QACJ,mCAAmC;QACnC,UAAU,EAAE,MAAM,CAAC;QACnB,8CAA8C;QAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0BAA0B;IAC1B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAqc3D,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE3D"}