@veloxts/core 0.3.3 → 0.3.5

package/dist/errors/formatter.js

@@ -0,0 +1,330 @@
+/**
+ * Error Formatter - Pretty terminal output with fix suggestions
+ *
+ * Inspired by Laravel's Ignition error pages, this module provides
+ * beautiful, informative error messages with actionable suggestions.
+ *
+ * @module errors/formatter
+ */
+import { getErrorEntry } from './catalog.js';
+// ============================================================================
+// ANSI Color Codes (for terminal output)
+// ============================================================================
+const COLORS = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    // Text colors
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+    // Background colors
+    bgRed: '\x1b[41m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+};
+/**
+ * Check if colors should be enabled
+ * Respects NO_COLOR env var and TTY detection
+ */
+function shouldUseColors() {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return process.stdout.isTTY ?? false;
+}
+/**
+ * Apply color to text if colors are enabled
+ */
+function color(text, ...codes) {
+    if (!shouldUseColors())
+        return text;
+    const prefix = codes.map((c) => COLORS[c]).join('');
+    return `${prefix}${text}${COLORS.reset}`;
+}
+// ============================================================================
+// Formatting Helpers
+// ============================================================================
+/**
+ * Create a horizontal divider line
+ */
+function divider(char = '─', length = 70) {
+    return char.repeat(length);
+}
+/**
+ * Indent text by a number of spaces
+ */
+function indent(text, spaces = 2) {
+    const pad = ' '.repeat(spaces);
+    return text
+        .split('\n')
+        .map((line) => `${pad}${line}`)
+        .join('\n');
+}
+/**
+ * Wrap text to a maximum width
+ */
+function wrapText(text, maxWidth = 68) {
+    const words = text.split(' ');
+    const lines = [];
+    let currentLine = '';
+    for (const word of words) {
+        if (currentLine.length + word.length + 1 <= maxWidth) {
+            currentLine += (currentLine ? ' ' : '') + word;
+        }
+        else {
+            if (currentLine)
+                lines.push(currentLine);
+            currentLine = word;
+        }
+    }
+    if (currentLine)
+        lines.push(currentLine);
+    return lines.join('\n');
+}
+/**
+ * Parse stack trace to extract error location
+ *
+ * @param error - The error to parse
+ * @returns Location info or undefined
+ */
+export function extractErrorLocation(error) {
+    if (!error.stack)
+        return undefined;
+    // Skip the first line (error message) and internal frames
+    const lines = error.stack.split('\n').slice(1);
+    for (const line of lines) {
+        // Skip internal node_modules frames
+        if (line.includes('node_modules'))
+            continue;
+        if (line.includes('node:internal'))
+            continue;
+        // Match V8 stack trace format: "at functionName (file:line:col)"
+        // or "at file:line:col"
+        const match = line.match(/at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?/);
+        if (match) {
+            return {
+                functionName: match[1],
+                file: match[2],
+                line: parseInt(match[3], 10),
+                column: parseInt(match[4], 10),
+            };
+        }
+    }
+    return undefined;
+}
+// ============================================================================
+// Main Formatting Functions
+// ============================================================================
+/**
+ * Format an error for terminal output with fix suggestions
+ *
+ * @param error - The error to format
+ * @param catalogCode - Optional catalog error code
+ * @param options - Formatting options
+ * @returns Formatted error string for terminal display
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   // ... code that throws
+ * } catch (error) {
+ *   console.error(formatError(error, 'VELOX-1001'));
+ * }
+ * ```
+ */
+export function formatError(error, catalogCode, options = {}) {
+    const { includeStack = process.env.NODE_ENV !== 'production', includeFix = true, includeDocs = true, includeSeeAlso = true, maxWidth = 68, } = options;
+    const entry = catalogCode ? getErrorEntry(catalogCode) : undefined;
+    const location = extractErrorLocation(error);
+    const lines = [];
+    // Header
+    lines.push('');
+    lines.push(color(divider('═'), 'red'));
+    lines.push('');
+    // Error code and title
+    if (entry) {
+        lines.push(`  ${color(entry.code, 'red', 'bold')}  ${color(entry.title, 'white', 'bold')}`);
+    }
+    else {
+        lines.push(`  ${color(error.name, 'red', 'bold')}`);
+    }
+    lines.push('');
+    // Error message
+    lines.push(indent(wrapText(error.message, maxWidth)));
+    lines.push('');
+    // Location
+    if (location) {
+        lines.push(color(divider('─'), 'gray'));
+        lines.push('');
+        lines.push(`  ${color('Location:', 'cyan', 'bold')}`);
+        lines.push('');
+        const loc = `${location.file}:${location.line}${location.column ? `:${location.column}` : ''}`;
+        lines.push(`  ${color('→', 'yellow')} ${color(loc, 'white')}`);
+        if (location.functionName) {
+            lines.push(`    ${color('in', 'gray')} ${color(location.functionName, 'cyan')}`);
+        }
+        lines.push('');
+    }
+    // Description from catalog
+    if (entry?.description) {
+        lines.push(color(divider('─'), 'gray'));
+        lines.push('');
+        lines.push(`  ${color('Why this happens:', 'cyan', 'bold')}`);
+        lines.push('');
+        lines.push(indent(wrapText(entry.description, maxWidth)));
+        lines.push('');
+    }
+    // Fix suggestion
+    if (includeFix && entry?.fix) {
+        lines.push(color(divider('─'), 'gray'));
+        lines.push('');
+        lines.push(`  ${color('How to fix:', 'green', 'bold')}`);
+        lines.push('');
+        lines.push(indent(wrapText(entry.fix.suggestion, maxWidth)));
+        if (entry.fix.example) {
+            lines.push('');
+            lines.push(`  ${color('Example:', 'yellow')}`);
+            lines.push('');
+            // Format code example with syntax highlighting hint
+            const exampleLines = entry.fix.example.split('\n');
+            for (const exLine of exampleLines) {
+                if (exLine.trim().startsWith('#') || exLine.trim().startsWith('//')) {
+                    lines.push(`  ${color(exLine, 'gray')}`);
+                }
+                else if (exLine.trim().startsWith('+')) {
+                    lines.push(`  ${color(exLine, 'green')}`);
+                }
+                else if (exLine.trim().startsWith('-')) {
+                    lines.push(`  ${color(exLine, 'red')}`);
+                }
+                else {
+                    lines.push(`  ${color(exLine, 'white')}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    // Documentation link
+    if (includeDocs && entry?.docsUrl) {
+        lines.push(color(divider('─'), 'gray'));
+        lines.push('');
+        lines.push(`  ${color('Documentation:', 'blue', 'bold')}`);
+        lines.push(`  ${color(entry.docsUrl, 'cyan')}`);
+        lines.push('');
+    }
+    // Related errors
+    if (includeSeeAlso && entry?.seeAlso && entry.seeAlso.length > 0) {
+        lines.push(`  ${color('See also:', 'gray')} ${entry.seeAlso.map((c) => color(c, 'yellow')).join(', ')}`);
+        lines.push('');
+    }
+    // Stack trace (development only)
+    if (includeStack && error.stack) {
+        lines.push(color(divider('─'), 'gray'));
+        lines.push('');
+        lines.push(`  ${color('Stack trace:', 'gray', 'bold')}`);
+        lines.push('');
+        const stackLines = error.stack.split('\n').slice(1, 8); // First 7 frames
+        for (const stackLine of stackLines) {
+            lines.push(`  ${color(stackLine.trim(), 'gray')}`);
+        }
+        if (error.stack.split('\n').length > 8) {
+            lines.push(`  ${color('... more frames hidden', 'dim')}`);
+        }
+        lines.push('');
+    }
+    // Footer
+    lines.push(color(divider('═'), 'red'));
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Format an error for JSON API response
+ * Includes catalog metadata but not stack traces
+ *
+ * @param error - The error to format
+ * @param catalogCode - Optional catalog error code
+ * @returns JSON-serializable error object
+ */
+export function formatErrorForApi(error, catalogCode) {
+    const entry = catalogCode ? getErrorEntry(catalogCode) : undefined;
+    const response = {
+        error: error.name,
+        message: error.message,
+        statusCode: error.statusCode ?? entry?.statusCode ?? 500,
+        code: catalogCode ?? error.code,
+    };
+    // Include field errors for validation
+    if (error.fields) {
+        response.fields = error.fields;
+    }
+    // Include fix suggestion in development
+    if (process.env.NODE_ENV !== 'production' && entry?.fix) {
+        response.fix = entry.fix.suggestion;
+    }
+    // Include docs link
+    if (entry?.docsUrl) {
+        response.docs = entry.docsUrl;
+    }
+    return response;
+}
+/**
+ * Format a short one-line error summary
+ *
+ * @param error - The error
+ * @param catalogCode - Optional catalog code
+ * @returns One-line error string
+ */
+export function formatErrorOneLine(error, catalogCode) {
+    const entry = catalogCode ? getErrorEntry(catalogCode) : undefined;
+    if (entry) {
+        return `${color(entry.code, 'red')}: ${error.message}`;
+    }
+    return `${color(error.name, 'red')}: ${error.message}`;
+}
+// ============================================================================
+// Error Logging Helpers
+// ============================================================================
+/**
+ * Log an error with pretty formatting
+ *
+ * @param error - The error to log
+ * @param catalogCode - Optional catalog error code
+ */
+export function logError(error, catalogCode) {
+    console.error(formatError(error, catalogCode));
+}
+/**
+ * Log a warning with pretty formatting
+ *
+ * @param message - Warning message
+ * @param suggestion - Optional fix suggestion
+ */
+export function logWarning(message, suggestion) {
+    const lines = [];
+    lines.push('');
+    lines.push(`${color('⚠', 'yellow')}  ${color('Warning:', 'yellow', 'bold')} ${message}`);
+    if (suggestion) {
+        lines.push(`   ${color('→', 'gray')} ${suggestion}`);
+    }
+    lines.push('');
+    console.warn(lines.join('\n'));
+}
+/**
+ * Log a deprecation warning
+ *
+ * @param oldApi - The deprecated API
+ * @param newApi - The replacement API
+ * @param removeVersion - Version when it will be removed
+ */
+export function logDeprecation(oldApi, newApi, removeVersion) {
+    const removal = removeVersion ? ` (will be removed in ${removeVersion})` : '';
+    logWarning(`${color(oldApi, 'white')} is deprecated${removal}`, `Use ${color(newApi, 'green')} instead`);
+}
+//# sourceMappingURL=formatter.js.map

package/dist/errors/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../src/errors/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,+EAA+E;AAC/E,yCAAyC;AACzC,+EAA+E;AAE/E,MAAM,MAAM,GAAG;IACb,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;IAEd,cAAc;IACd,GAAG,EAAE,UAAU;IACf,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,UAAU;IAChB,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,UAAU;IAEhB,oBAAoB;IACpB,KAAK,EAAE,UAAU;IACjB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,UAAU;CACV,CAAC;AAEX;;;GAGG;AACH,SAAS,eAAe;IACtB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,IAAY,EAAE,GAAG,KAA8B;IAC5D,IAAI,CAAC,eAAe,EAAE;QAAE,OAAO,IAAI,CAAC;IACpC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,OAAO,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;AAC3C,CAAC;AAED,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;GAEG;AACH,SAAS,OAAO,CAAC,IAAI,GAAG,GAAG,EAAE,MAAM,GAAG,EAAE;IACtC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAS,MAAM,CAAC,IAAY,EAAE,MAAM,GAAG,CAAC;IACtC,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC/B,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,IAAI,EAAE,CAAC;SAC9B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,QAAQ,GAAG,EAAE;IAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,WAAW,GAAG,EAAE,CAAC;IAErB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,WAAW,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,EAAE,CAAC;YACrD,WAAW,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,IAAI,WAAW;gBAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YACzC,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;IACD,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAEzC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAgBD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,IAAI,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAEnC,0DAA0D;IAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE/C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,oCAAoC;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC;YAAE,SAAS;QAC5C,IAAI,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC;YAAE,SAAS;QAE7C,iEAAiE;QACjE,wBAAwB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QACrE,IAAI,KAAK,EAAE,CAAC;YACV,OAAO;gBACL,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC;gBACtB,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;gBACd,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBAC5B,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;aAC/B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AA0BD,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,WAAW,CACzB,KAAY,EACZ,WAAoB,EACpB,UAA8B,EAAE;IAEhC,MAAM,EACJ,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EACpD,UAAU,GAAG,IAAI,EACjB,WAAW,GAAG,IAAI,EAClB,cAAc,GAAG,IAAI,EACrB,QAAQ,GAAG,EAAE,GACd,GAAG,OAAO,CAAC;IAEZ,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,SAAS;IACT,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,uBAAuB;IACvB,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IAC9F,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,gBAAgB;IAChB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,WAAW;IACX,IAAI,QAAQ,EAAE,CAAC;QACb,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,MAAM,GAAG,GAAG,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC/F,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/D,IAAI,QAAQ,CAAC,YAAY,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,2BAA2B;IAC3B,IAAI,KAAK,EAAE,WAAW,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,mBAAmB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC9D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC1D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,iBAAiB;IACjB,IAAI,UAAU,IAAI,KAAK,EAAE,GAAG,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QAE7D,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,oDAAoD;YACpD,MAAM,YAAY,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;gBAClC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;oBACpE,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;gBAC3C,CAAC;qBAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;gBAC5C,CAAC;qBAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;gBAC1C,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;gBAC5C,CAAC;YACH,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,IAAI,WAAW,IAAI,KAAK,EAAE,OAAO,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,iBAAiB;IACjB,IAAI,cAAc,IAAI,KAAK,EAAE,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,KAAK,CAAC,IAAI,CACR,KAAK,KAAK,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7F,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,iCAAiC;IACjC,IAAI,YAAY,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACzD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,iBAAiB;QACzE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,SAAS;IACT,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAsF,EACtF,WAAoB;IAEpB,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,MAAM,QAAQ,GAA4B;QACxC,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,KAAK,EAAE,UAAU,IAAI,GAAG;QACxD,IAAI,EAAE,WAAW,IAAI,KAAK,CAAC,IAAI;KAChC,CAAC;IAEF,sCAAsC;IACtC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IACjC,CAAC;IAED,wCAAwC;IACxC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,KAAK,EAAE,GAAG,EAAE,CAAC;QACxD,QAAQ,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC;IACtC,CAAC;IAED,oBAAoB;IACpB,IAAI,KAAK,EAAE,OAAO,EAAE,CAAC;QACnB,QAAQ,CAAC,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC;IAChC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAY,EAAE,WAAoB;IACnE,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACzD,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AACzD,CAAC;AAED,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAY,EAAE,WAAoB;IACzD,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,UAAmB;IAC7D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,QAAQ,CAAC,KAAK,KAAK,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IACzF,IAAI,UAAU,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,MAAc,EAAE,aAAsB;IACnF,MAAM,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,wBAAwB,aAAa,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,UAAU,CACR,GAAG,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,OAAO,EAAE,EACnD,OAAO,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CACxC,CAAC;AACJ,CAAC"}

package/dist/errors/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * VeloxTS Error System
+ *
+ * Provides enhanced error handling with:
+ * - Numbered error codes (VELOX-XXXX)
+ * - Fix suggestions with code examples
+ * - Pretty terminal formatting
+ * - Documentation links
+ *
+ * @module errors
+ */
+export { ERROR_CATALOG, ERROR_DOMAINS, type ErrorCatalogEntry, type ErrorDomain, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, } from './catalog.js';
+export { type ErrorLocation, extractErrorLocation, type FormatErrorOptions, formatError, formatErrorForApi, formatErrorOneLine, logDeprecation, logError, logWarning, } from './formatter.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,KAAK,aAAa,EAClB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1,16 @@
+/**
+ * VeloxTS Error System
+ *
+ * Provides enhanced error handling with:
+ * - Numbered error codes (VELOX-XXXX)
+ * - Fix suggestions with code examples
+ * - Pretty terminal formatting
+ * - Documentation links
+ *
+ * @module errors
+ */
+// Re-export catalog
+export { ERROR_CATALOG, ERROR_DOMAINS, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, } from './catalog.js';
+// Re-export formatter
+export { extractErrorLocation, formatError, formatErrorForApi, formatErrorOneLine, logDeprecation, logError, logWarning, } from './formatter.js';
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,aAAa,EAGb,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,sBAAsB;AACtB,OAAO,EAEL,oBAAoB,EAEpB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,UAAU,GACX,MAAM,gBAAgB,CAAC"}

package/dist/errors.d.ts

@@ -3,6 +3,7 @@
  * Provides base error classes with HTTP status codes and discriminated unions
  * @module errors
  */
+export { ERROR_CATALOG, ERROR_DOMAINS, type ErrorCatalogEntry, type ErrorDomain, type ErrorLocation, extractErrorLocation, type FormatErrorOptions, formatError, formatErrorForApi, formatErrorOneLine, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, logDeprecation, logError, logWarning, } from './errors/index.js';
 /**
  * Known error codes in the VeloxTS framework core
  * Can be extended via declaration merging by plugins
@@ -104,11 +105,19 @@ export declare function isNotFoundErrorResponse(response: ErrorResponse): respon
  *
  * @example
  * ```typescript
+ * // Basic usage
  * throw new VeloxError('Something went wrong', 500);
  * ```
  *
  * @example
  * ```typescript
+ * // With catalog code for rich error details
+ * throw new VeloxError('Database connection failed', 503, 'VELOX-4001');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With legacy string code
  * throw new VeloxError('Database connection failed', 503, 'DB_CONNECTION_ERROR');
  * ```
  */
@@ -118,23 +127,45 @@ export declare class VeloxError<TCode extends string = string> extends Error {
      */
     readonly statusCode: number;
     /**
-     * Optional error code for programmatic error handling
+     * Error code for programmatic error handling
+     * Can be a catalog code (VELOX-XXXX) or legacy string code
      */
     readonly code?: TCode;
+    /**
+     * Fix suggestion for developers (populated from catalog)
+     */
+    readonly fix?: string;
+    /**
+     * Documentation URL for this error
+     */
+    readonly docsUrl?: string;
     /**
      * Creates a new VeloxError instance
      *
      * @param message - Human-readable error message
      * @param statusCode - HTTP status code (default: 500)
-     * @param code - Optional error code for programmatic handling
+     * @param code - Optional error code (VELOX-XXXX catalog code or legacy string)
      */
     constructor(message: string, statusCode?: number, code?: TCode);
     /**
      * Converts error to JSON format for API responses
      *
-     * @returns Error response object
+     * @returns Error response object with optional fix suggestion in development
+     */
+    toJSON(): GenericErrorResponse & {
+        fix?: string;
+        docs?: string;
+    };
+    /**
+     * Format error for terminal display with colors and fix suggestions
+     *
+     * @returns Formatted error string
+     */
+    format(): string;
+    /**
+     * Log this error with pretty formatting
      */
-    toJSON(): GenericErrorResponse;
+    log(): void;
 }
 /**
  * Validation error for invalid user input
@@ -294,5 +325,4 @@ export declare function isConfigurationError(error: unknown): error is Configura
  * ```
  */
 export declare function assertNever(value: never): never;
-export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -3,6 +3,11 @@
  * Provides base error classes with HTTP status codes and discriminated unions
  * @module errors
  */
+// Import catalog for use in error classes
+import { ERROR_CATALOG } from './errors/catalog.js';
+import { formatError as _formatError } from './errors/formatter.js';
+// Re-export the enhanced error catalog and formatter
+export { ERROR_CATALOG, ERROR_DOMAINS, extractErrorLocation, formatError, formatErrorForApi, formatErrorOneLine, getDocsUrl, getErrorEntry, getErrorsByDomain, isKnownErrorCode, logDeprecation, logError, logWarning, } from './errors/index.js';
 /**
  * Type guard for validation error responses
  */
@@ -28,11 +33,19 @@ export function isNotFoundErrorResponse(response) {
  *
  * @example
  * ```typescript
+ * // Basic usage
  * throw new VeloxError('Something went wrong', 500);
  * ```
  *
  * @example
  * ```typescript
+ * // With catalog code for rich error details
+ * throw new VeloxError('Database connection failed', 503, 'VELOX-4001');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With legacy string code
  * throw new VeloxError('Database connection failed', 503, 'DB_CONNECTION_ERROR');
  * ```
  */
@@ -42,21 +55,38 @@ export class VeloxError extends Error {
      */
     statusCode;
     /**
-     * Optional error code for programmatic error handling
+     * Error code for programmatic error handling
+     * Can be a catalog code (VELOX-XXXX) or legacy string code
      */
     code;
+    /**
+     * Fix suggestion for developers (populated from catalog)
+     */
+    fix;
+    /**
+     * Documentation URL for this error
+     */
+    docsUrl;
     /**
      * Creates a new VeloxError instance
      *
      * @param message - Human-readable error message
      * @param statusCode - HTTP status code (default: 500)
-     * @param code - Optional error code for programmatic handling
+     * @param code - Optional error code (VELOX-XXXX catalog code or legacy string)
      */
     constructor(message, statusCode = 500, code) {
         super(message);
         this.name = 'VeloxError';
         this.statusCode = statusCode;
         this.code = code;
+        // Look up catalog entry for enhanced error info
+        if (code && typeof code === 'string' && code.startsWith('VELOX-')) {
+            const entry = ERROR_CATALOG[code];
+            if (entry) {
+                this.fix = entry.fix?.suggestion;
+                this.docsUrl = entry.docsUrl;
+            }
+        }
         // Maintains proper stack trace for where error was thrown (V8 only)
         if (Error.captureStackTrace) {
             Error.captureStackTrace(this, VeloxError);
@@ -65,15 +95,38 @@ export class VeloxError extends Error {
     /**
      * Converts error to JSON format for API responses
      *
-     * @returns Error response object
+     * @returns Error response object with optional fix suggestion in development
      */
     toJSON() {
-        return {
+        const response = {
             error: this.name,
             message: this.message,
             statusCode: this.statusCode,
             code: this.code,
         };
+        // Include fix suggestion in development only
+        if (process.env.NODE_ENV !== 'production' && this.fix) {
+            response.fix = this.fix;
+        }
+        // Always include docs URL if available
+        if (this.docsUrl) {
+            response.docs = this.docsUrl;
+        }
+        return response;
+    }
+    /**
+     * Format error for terminal display with colors and fix suggestions
+     *
+     * @returns Formatted error string
+     */
+    format() {
+        return _formatError(this, this.code);
+    }
+    /**
+     * Log this error with pretty formatting
+     */
+    log() {
+        console.error(this.format());
     }
 }
 /**

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,0CAA0C;AAC1C,OAAO,EAAmC,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,EAAE,WAAW,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEpE,qDAAqD;AACrD,OAAO,EACL,aAAa,EACb,aAAa,EAIb,oBAAoB,EAEpB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,QAAQ,EACR,UAAU,GACX,MAAM,mBAAmB,CAAC;AA8G3B;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAAuB;IAEvB,OAAO,QAAQ,CAAC,KAAK,KAAK,iBAAiB,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAAuB;IAEvB,OAAO,QAAQ,CAAC,KAAK,KAAK,eAAe,CAAC;AAC5C,CAAC;AAED,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,UAA0C,SAAQ,KAAK;IAClE;;OAEG;IACa,UAAU,CAAS;IAEnC;;;OAGG;IACa,IAAI,CAAS;IAE7B;;OAEG;IACa,GAAG,CAAU;IAE7B;;OAEG;IACa,OAAO,CAAU;IAEjC;;;;;;OAMG;IACH,YAAY,OAAe,EAAE,aAAqB,GAAG,EAAE,IAAY;QACjE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QAEjB,gDAAgD;QAChD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClE,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAClC,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC;gBACjC,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;YAC/B,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,MAAM,QAAQ,GAA2D;YACvE,KAAK,EAAE,IAAI,CAAC,IAAI;YAChB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC;QAEF,6CAA6C;QAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;YACtD,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QAC1B,CAAC;QAED,uCAAuC;QACvC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC;QAC/B,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAO,eAAgB,SAAQ,UAA8B;IACjE;;;OAGG;IACa,MAAM,CAA0B;IAEhD;;;;;OAKG;IACH,YAAY,OAAe,EAAE,MAA+B;QAC1D,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,kBAAkB,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED;;;;OAIG;IACM,MAAM;QACb,OAAO;YACL,KAAK,EAAE,iBAAiB;YACxB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,GAAG;YACf,IAAI,EAAE,kBAAkB;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,kBAAmB,SAAQ,UAAiC;IACvE;;;;OAIG;IACH,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,qBAAqB,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QAEjC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAuB;IACxD;;OAEG;IACa,QAAQ,CAAS;IAEjC;;OAEG;IACa,UAAU,CAAU;IAEpC;;;;;OAKG;IACH,YAAY,QAAgB,EAAE,UAAmB;QAC/C,MAAM,OAAO,GAAG,UAAU;YACxB,CAAC,CAAC,GAAG,QAAQ,YAAY,UAAU,YAAY;YAC/C,CAAC,CAAC,GAAG,QAAQ,YAAY,CAAC;QAE5B,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACM,MAAM;QACb,OAAO;YACL,KAAK,EAAE,eAAe;YACtB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,UAAU,EAAE,GAAG;YACf,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC;IACJ,CAAC;CACF;AAED,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,IAAI,IAAI,IAAI,KAAK,YAAY,UAAU,CAAC;AACtD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,KAAK,YAAY,eAAe,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,KAAK,YAAY,aAAa,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,KAAK,YAAY,kBAAkB,CAAC;AAC7C,CAAC;AAED,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,KAAY;IACtC,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/dist/index.d.ts

@@ -1,24 +1,28 @@
 /**
  * @veloxts/core - Foundation package for the VeloxTS framework
  *
- * Provides the core Fastify wrapper, plugin system, and base context
- * that all other framework packages build upon.
+ * Provides the core Fastify wrapper, plugin system, base context,
+ * and dependency injection container that all other framework
+ * packages build upon.
  *
  * @example
  * ```typescript
- * import { createVeloxApp, definePlugin } from '@veloxts/core';
+ * import { veloxApp, definePlugin, Container, Injectable } from '@veloxts/core';
  *
- * const app = await createVeloxApp({ port: 3210 });
+ * const app = await veloxApp({ port: 3210 });
  * await app.start();
  * ```
  *
  * @module @veloxts/core
  */
+import 'reflect-metadata';
 /** VeloxTS framework version */
 export declare const VELOX_VERSION: string;
-export { createVeloxApp, VeloxApp } from './app.js';
+export { createVeloxApp, VeloxApp, veloxApp } from './app.js';
 export type { BaseContext } from './context.js';
-export { createContext, isContext } from './context.js';
+export { createContext, isContext, setupTestContext } from './context.js';
+export type { AbstractClass, ClassConstructor, ClassProvider, ContainerOptions, ExistingProvider, FactoryProvider, InjectableOptions, InjectionToken, Provider, ResolutionContext, StringToken, SymbolToken, TokenType, ValueProvider, } from './di/index.js';
+export { asClass, asExisting, asFactory, asValue, Container, container, createContainer, createStringToken, createSymbolToken, factory, getConstructorTokens, getExplicitInjectTokens, getInjectableScope, getOptionalParams, getTokenName, Inject, Injectable, isClassProvider, isClassToken, isExistingProvider, isFactoryProvider, isInjectable, isStringToken, isSymbolToken, isValueProvider, makeInjectable, Optional, Scope, ScopeManager, scoped, setInjectTokens, singleton, token, transient, validateProvider, validateToken, value, } from './di/index.js';
 export type { ErrorResponse, GenericErrorResponse, NotFoundErrorResponse, ValidationErrorResponse, VeloxCoreErrorCode, VeloxErrorCode, VeloxErrorCodeRegistry, } from './errors.js';
 export { assertNever, ConfigurationError, isConfigurationError, isNotFoundError, isNotFoundErrorResponse, isValidationError, isValidationErrorResponse, isVeloxError, NotFoundError, ValidationError, VeloxError, } from './errors.js';
 export type { InferPluginOptions, PluginMetadata, PluginOptions, VeloxPlugin } from './plugin.js';