@veloxts/core 0.3.3 → 0.3.5

package/dist/errors/catalog.js

@@ -0,0 +1,492 @@
+/**
+ * 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 Domains
+// ============================================================================
+/**
+ * Error code domain prefixes
+ */
+export const ERROR_DOMAINS = {
+    CORE: 1,
+    ROUTER: 2,
+    AUTH: 3,
+    ORM: 4,
+    VALIDATION: 5,
+    CLIENT: 6,
+};
+// ============================================================================
+// Error Catalog Registry
+// ============================================================================
+/**
+ * The complete error catalog
+ * Organized by domain for easy navigation
+ */
+export const ERROR_CATALOG = {
+    // ==========================================================================
+    // CORE ERRORS (1XXX)
+    // ==========================================================================
+    'VELOX-1001': {
+        code: 'VELOX-1001',
+        title: 'Server Already Running',
+        description: 'Attempted to start a VeloxTS server that is already running.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Stop the existing server before starting a new one, or check if another process is using the port.',
+            example: `// Stop the server before restarting
+await app.stop();
+await app.start();
+
+// Or check if you're calling start() multiple times
+const app = await veloxApp({ port: 3000 });
+await app.start(); // Call only once`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-1001',
+    },
+    'VELOX-1002': {
+        code: 'VELOX-1002',
+        title: 'Server Not Running',
+        description: 'Attempted to stop a VeloxTS server that is not running.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Ensure the server is started before attempting to stop it.',
+            example: `const app = await veloxApp({ port: 3000 });
+await app.start(); // Must call start() first
+// ... handle requests
+await app.stop();  // Now safe to stop`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-1002',
+    },
+    'VELOX-1003': {
+        code: 'VELOX-1003',
+        title: 'Plugin Registration Failed',
+        description: 'A plugin failed to register with the VeloxTS application.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Check that the plugin is correctly configured and all required dependencies are available.',
+            example: `// Ensure plugin is awaited and properly configured
+await app.register(databasePlugin({
+  client: prisma  // Required: pass Prisma client
+}));
+
+// Check plugin order - some plugins depend on others
+await app.register(databasePlugin({ client: prisma }));
+await app.register(authPlugin(authConfig)); // Auth needs database`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-1003',
+    },
+    'VELOX-1004': {
+        code: 'VELOX-1004',
+        title: 'Configuration Error',
+        description: 'The VeloxTS application configuration is invalid or incomplete.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Review your configuration options and ensure all required fields are provided.',
+            example: `// Correct configuration
+const app = await veloxApp({
+  port: parseInt(process.env.PORT || '3000'),
+  host: process.env.HOST || '0.0.0.0',
+  logger: process.env.NODE_ENV !== 'test',
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-1004',
+    },
+    'VELOX-1005': {
+        code: 'VELOX-1005',
+        title: 'Invalid Plugin Metadata',
+        description: 'A plugin was registered without required metadata (name, version).',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Ensure your plugin exports proper metadata.',
+            example: `// Plugin must have name property
+const myPlugin: VeloxPlugin = {
+  name: 'my-plugin',
+  version: '1.0.0',  // Optional but recommended
+  register: async (app) => {
+    // Plugin logic
+  }
+};`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-1005',
+    },
+    // ==========================================================================
+    // ROUTER ERRORS (2XXX)
+    // ==========================================================================
+    'VELOX-2001': {
+        code: 'VELOX-2001',
+        title: 'Procedure Missing Input Schema',
+        description: 'A procedure was defined without an input schema, but receives input data.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Add .input() to your procedure definition with a Zod schema.',
+            example: `export const getUser = procedure()
+  .input(z.object({ id: z.string().uuid() }))  // Add input schema
+  .query(async ({ input, ctx }) => {
+    return ctx.db.user.findUnique({ where: { id: input.id } });
+  });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-2001',
+        seeAlso: ['VELOX-2002'],
+    },
+    'VELOX-2002': {
+        code: 'VELOX-2002',
+        title: 'Procedure Missing Output Schema',
+        description: 'A procedure was defined without an output schema. Output schemas ensure type safety.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Add .output() to your procedure definition for type-safe responses.',
+            example: `export const getUser = procedure()
+  .input(z.object({ id: z.string().uuid() }))
+  .output(UserSchema)  // Add output schema
+  .query(async ({ input, ctx }) => {
+    return ctx.db.user.findUnique({ where: { id: input.id } });
+  });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-2002',
+        seeAlso: ['VELOX-2001'],
+    },
+    'VELOX-2003': {
+        code: 'VELOX-2003',
+        title: 'Guard Authorization Failed',
+        description: 'A guard prevented access to a procedure. The user lacks required permissions.',
+        statusCode: 403,
+        fix: {
+            suggestion: 'Ensure the user is authenticated and has the required roles/permissions.',
+            example: `// Using built-in guards
+const protectedProcedure = procedure()
+  .guard(authenticated)  // Requires valid auth
+  .query(({ ctx }) => ctx.user);
+
+// Check user has required role
+const adminProcedure = procedure()
+  .guard(hasRole('admin'))
+  .mutation(({ input }) => { /* ... */ });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-2003',
+    },
+    'VELOX-2004': {
+        code: 'VELOX-2004',
+        title: 'Duplicate Procedure Name',
+        description: 'Two procedures in the same collection have the same name.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Ensure all procedure names within a collection are unique.',
+            example: `// Wrong: duplicate names
+const userProcedures = defineProcedures('users', {
+  getUser: procedure()...,
+  getUser: procedure()...,  // Error: duplicate!
+});
+
+// Correct: unique names
+const userProcedures = defineProcedures('users', {
+  getUser: procedure()...,
+  getUserProfile: procedure()...,  // Different name
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-2004',
+    },
+    'VELOX-2005': {
+        code: 'VELOX-2005',
+        title: 'Invalid REST Method Override',
+        description: 'The .rest() configuration contains an invalid HTTP method.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Use a valid HTTP method: GET, POST, PUT, PATCH, or DELETE.',
+            example: `// Correct usage
+const updateUser = procedure()
+  .rest({ method: 'PUT', path: '/users/:id' })
+  .input(UpdateUserSchema)
+  .mutation(({ input }) => { /* ... */ });`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-2005',
+    },
+    // ==========================================================================
+    // AUTH ERRORS (3XXX)
+    // ==========================================================================
+    'VELOX-3001': {
+        code: 'VELOX-3001',
+        title: 'Invalid JWT Secret',
+        description: 'The JWT secret is missing, too short, or lacks sufficient entropy.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Provide a strong secret with at least 64 characters and 16 unique characters.',
+            example: `# Generate a secure secret
+openssl rand -base64 64
+
+# Set in environment
+JWT_SECRET=<your-64-char-secret>
+JWT_REFRESH_SECRET=<another-64-char-secret>`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3001',
+    },
+    'VELOX-3002': {
+        code: 'VELOX-3002',
+        title: 'Token Expired',
+        description: 'The JWT access token has expired and cannot be used for authentication.',
+        statusCode: 401,
+        fix: {
+            suggestion: 'Refresh the access token using your refresh token, or re-authenticate.',
+            example: `// Client-side token refresh
+const response = await fetch('/api/auth/refresh', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ refreshToken: storedRefreshToken }),
+});
+const { accessToken } = await response.json();`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3002',
+    },
+    'VELOX-3003': {
+        code: 'VELOX-3003',
+        title: 'Invalid Credentials',
+        description: 'The provided email or password is incorrect.',
+        statusCode: 401,
+        fix: {
+            suggestion: 'Verify the email and password are correct. Passwords are case-sensitive.',
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3003',
+    },
+    'VELOX-3004': {
+        code: 'VELOX-3004',
+        title: 'Rate Limit Exceeded',
+        description: 'Too many authentication attempts. Please wait before trying again.',
+        statusCode: 429,
+        fix: {
+            suggestion: 'Wait for the rate limit window to reset before retrying.',
+            example: `// The response includes retry timing
+// Retry-After: 900 (seconds until reset)
+
+// Client should wait before retrying
+if (response.status === 429) {
+  const retryAfter = response.headers.get('Retry-After');
+  await delay(parseInt(retryAfter) * 1000);
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3004',
+    },
+    'VELOX-3005': {
+        code: 'VELOX-3005',
+        title: 'Session Secret Invalid',
+        description: 'The session secret is missing or has insufficient entropy.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Provide a session secret with at least 32 characters and 16 unique characters.',
+            example: `# Generate a secure session secret
+openssl rand -base64 32
+
+# Set in environment
+SESSION_SECRET=<your-32-char-secret>`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3005',
+    },
+    'VELOX-3006': {
+        code: 'VELOX-3006',
+        title: 'CSRF Token Invalid',
+        description: 'The CSRF token is missing, expired, or does not match.',
+        statusCode: 403,
+        fix: {
+            suggestion: 'Include a valid CSRF token in your request.',
+            example: `// Get CSRF token from cookie or meta tag
+const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content;
+
+// Include in request headers
+fetch('/api/users', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-CSRF-Token': csrfToken,
+  },
+  body: JSON.stringify(data),
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3006',
+    },
+    'VELOX-3007': {
+        code: 'VELOX-3007',
+        title: 'Token Revoked',
+        description: 'This token has been revoked and can no longer be used.',
+        statusCode: 401,
+        fix: {
+            suggestion: 'Re-authenticate to obtain new tokens.',
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-3007',
+    },
+    // ==========================================================================
+    // ORM ERRORS (4XXX)
+    // ==========================================================================
+    'VELOX-4001': {
+        code: 'VELOX-4001',
+        title: 'Database Connection Failed',
+        description: 'Could not establish a connection to the database.',
+        statusCode: 503,
+        fix: {
+            suggestion: 'Verify DATABASE_URL is correct and the database server is running.',
+            example: `# Check your .env file
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+
+# For SQLite
+DATABASE_URL="file:./dev.db"
+
+# Ensure database server is running
+docker ps  # Check if database container is up`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-4001',
+    },
+    'VELOX-4002': {
+        code: 'VELOX-4002',
+        title: 'Database Already Connected',
+        description: 'Attempted to connect to a database that is already connected.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'The database client is already connected. Avoid calling connect() multiple times.',
+            example: `// Connection is typically managed automatically
+// Only call connect manually if needed
+if (!isConnected) {
+  await prisma.$connect();
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-4002',
+    },
+    'VELOX-4003': {
+        code: 'VELOX-4003',
+        title: 'Missing Database Plugin',
+        description: 'Attempted to access ctx.db without registering the database plugin.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Register the database plugin before accessing ctx.db.',
+            example: `import { databasePlugin } from '@veloxts/velox';
+import { prisma } from './database/index.js';
+
+const app = await veloxApp({ port: 3000 });
+await app.register(databasePlugin({ client: prisma }));
+
+// Now ctx.db is available in procedures`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-4003',
+    },
+    // ==========================================================================
+    // VALIDATION ERRORS (5XXX)
+    // ==========================================================================
+    'VELOX-5001': {
+        code: 'VELOX-5001',
+        title: 'Validation Failed',
+        description: 'The request data failed schema validation.',
+        statusCode: 400,
+        fix: {
+            suggestion: 'Check the fields property for specific validation errors.',
+            example: `// Response includes field-specific errors
+{
+  "error": "ValidationError",
+  "message": "Validation failed",
+  "statusCode": 400,
+  "code": "VELOX-5001",
+  "fields": {
+    "email": "Invalid email format",
+    "age": "Must be at least 18"
+  }
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-5001',
+    },
+    'VELOX-5002': {
+        code: 'VELOX-5002',
+        title: 'Invalid Schema Definition',
+        description: 'The Zod schema definition is invalid.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Check your Zod schema for syntax errors or invalid chaining.',
+            example: `// Correct schema definition
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  age: z.number().min(0).max(150),
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-5002',
+    },
+    // ==========================================================================
+    // CLIENT ERRORS (6XXX)
+    // ==========================================================================
+    'VELOX-6001': {
+        code: 'VELOX-6001',
+        title: 'Network Request Failed',
+        description: 'The HTTP request could not be completed due to a network error.',
+        statusCode: 0,
+        fix: {
+            suggestion: 'Check your internet connection and ensure the API server is reachable.',
+            example: `// Handle network errors gracefully
+try {
+  const data = await api.users.list();
+} catch (error) {
+  if (isNetworkError(error)) {
+    console.log('Network unavailable, using cached data');
+    return getCachedData();
+  }
+  throw error;
+}`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-6001',
+    },
+    'VELOX-6002': {
+        code: 'VELOX-6002',
+        title: 'API Base URL Not Configured',
+        description: 'The VeloxTS client was created without a base URL.',
+        statusCode: 500,
+        fix: {
+            suggestion: 'Provide a baseUrl when creating the client.',
+            example: `import { createClient } from '@veloxts/client';
+
+const api = createClient({
+  baseUrl: process.env.API_URL || 'http://localhost:3000/api',
+});`,
+        },
+        docsUrl: 'https://veloxts.dev/errors/VELOX-6002',
+    },
+};
+// ============================================================================
+// Catalog Access Functions
+// ============================================================================
+/**
+ * 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 function getErrorEntry(code) {
+    return ERROR_CATALOG[code];
+}
+/**
+ * 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 function getErrorsByDomain(domain) {
+    const prefix = `VELOX-${ERROR_DOMAINS[domain]}`;
+    return Object.keys(ERROR_CATALOG).filter((code) => code.startsWith(prefix));
+}
+/**
+ * Check if an error code exists in the catalog
+ *
+ * @param code - The error code to check
+ * @returns true if the code exists
+ */
+export function isKnownErrorCode(code) {
+    return code in ERROR_CATALOG;
+}
+/**
+ * Get the documentation URL for an error code
+ *
+ * @param code - The error code
+ * @returns The documentation URL or undefined
+ */
+export function getDocsUrl(code) {
+    return ERROR_CATALOG[code]?.docsUrl;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/errors/catalog.js.map

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

package/dist/errors/formatter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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
+ */
+/**
+ * Extracted error location from stack trace
+ */
+export interface ErrorLocation {
+    file: string;
+    line: number;
+    column?: number;
+    functionName?: string;
+}
+/**
+ * Parse stack trace to extract error location
+ *
+ * @param error - The error to parse
+ * @returns Location info or undefined
+ */
+export declare function extractErrorLocation(error: Error): ErrorLocation | undefined;
+/**
+ * Options for error formatting
+ */
+export interface FormatErrorOptions {
+    /** Include the stack trace (default: false in production) */
+    includeStack?: boolean;
+    /** Include the fix suggestion (default: true) */
+    includeFix?: boolean;
+    /** Include documentation link (default: true) */
+    includeDocs?: boolean;
+    /** Include related error codes (default: true) */
+    includeSeeAlso?: boolean;
+    /** Maximum width for text wrapping */
+    maxWidth?: number;
+}
+/**
+ * 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 declare function formatError(error: Error, catalogCode?: string, options?: FormatErrorOptions): string;
+/**
+ * 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 declare function formatErrorForApi(error: Error & {
+    statusCode?: number;
+    code?: string;
+    fields?: Record<string, string>;
+}, catalogCode?: string): Record<string, unknown>;
+/**
+ * Format a short one-line error summary
+ *
+ * @param error - The error
+ * @param catalogCode - Optional catalog code
+ * @returns One-line error string
+ */
+export declare function formatErrorOneLine(error: Error, catalogCode?: string): string;
+/**
+ * Log an error with pretty formatting
+ *
+ * @param error - The error to log
+ * @param catalogCode - Optional catalog error code
+ */
+export declare function logError(error: Error, catalogCode?: string): void;
+/**
+ * Log a warning with pretty formatting
+ *
+ * @param message - Warning message
+ * @param suggestion - Optional fix suggestion
+ */
+export declare function logWarning(message: string, suggestion?: string): void;
+/**
+ * Log a deprecation warning
+ *
+ * @param oldApi - The deprecated API
+ * @param newApi - The replacement API
+ * @param removeVersion - Version when it will be removed
+ */
+export declare function logDeprecation(oldApi: string, newApi: string, removeVersion?: string): void;
+//# sourceMappingURL=formatter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../src/errors/formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+FH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,aAAa,GAAG,SAAS,CAyB5E;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,iDAAiD;IACjD,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,kDAAkD;IAClD,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,KAAK,EACZ,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,kBAAuB,GAC/B,MAAM,CAyHR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,KAAK,GAAG;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EACtF,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0BzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CASrE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAM3F"}