stacks-error-handling

# Stacks Error Handling Type-safe error handling with Result types, error pages, and structured logging. ## Key Paths - Core package: `storage/framework/core/error-handling/src/` - Configuration: `config/errors.ts` - Error model: `storage/framework/defaults/app/Models/Error.ts` ## Result Type (from ts-error-handling) ```typescript import { ok, err, fromPromise } from '@stacksjs/error-handling' import type { Result, Ok, Err, ResultAsync } from '@stacksjs/error-handling' // Create results const success: Ok<string> = ok('data') const failure: Err<Error> = err(new Error('failed')) // From promises const result: ResultAsync<Data, Error> = fromPromise(fetchData()) // Pattern matching if (result.isOk()) { console.log(result.value) } else { console.error(result.error) } ``` ## Error Handler ```typescript import { handleError, ErrorHandler } from '@stacksjs/error-handling' // Function-based handleError(error) handleError(error, { shouldExit: true }) // Class-based ErrorHandler.handle(error) ErrorHandler.handleError(error, { shouldExit: true }) ErrorHandler.writeErrorToFile(error) ErrorHandler.writeErrorToConsole(error) ``` ## Log File Writing ```typescript import { writeToLogFile, setLogPath } from '@stacksjs/error-handling' setLogPath('/custom/log/path') await writeToLogFile('Error message', { path: '/custom/path' }) ``` Default log path: `storage/logs/stacks.log` ## Error Page Rendering ```typescript import { ErrorPageHandler, renderError, renderErrorPage, renderProductionErrorPage, createErrorHandler, errorResponse } from '@stacksjs/error-handling' // Development: shows stack trace, source code, file paths const devPage = renderErrorPage(error, request) // Production: friendly error message, no internals const prodPage = renderProductionErrorPage(error, request) // Auto-detect environment const page = renderError(error, request) // Create handler for routes const handler = createErrorHandler() const response = errorResponse(error, request) ``` ## HTTP Error Mapping ```typescript import { HTTP_ERRORS } from '@stacksjs/error-handling' // Maps status codes to error details HTTP_ERRORS[400] // { title: 'Bad Request', ... } HTTP_ERRORS[401] // { title: 'Unauthorized', ... } HTTP_ERRORS[403] // { title: 'Forbidden', ... } HTTP_ERRORS[404] // { title: 'Not Found', ... } HTTP_ERRORS[500] // { title: 'Internal Server Error', ... } ``` ## Custom Exceptions ```typescript import { ModelNotFoundException } from '@stacksjs/error-handling' throw new ModelNotFoundException('User not found') ``` ## Error Page Types ```typescript interface HttpError { status: number, title: string, message: string } interface StackFrame { file: string, line: number, column: number, function?: string } interface CodeSnippet { line: number, code: string, isHighlighted: boolean } ``` ## Error Model (storage/framework/defaults/app/Models/Error.ts) Fields: type, message, stack (stacktrace), status, additional_info Seeder: 10 records for testing ## config/errors.ts Contains comprehensive validation error messages for all field types: - String validation: required, minLength, maxLength, email, url, uuid, etc. - Number validation: required, min, max, positive, negative, integer, etc. - Enum validation: invalid value messages - Date validation: format, before, after, etc. - File validation: size, type, dimensions, etc. ## Gotchas - Use `Result<T, E>` types instead of try/catch for recoverable errors - `ok()` and `err()` are from `ts-error-handling` (neverthrow-compatible) - Error pages automatically detect environment (dev shows stack traces, prod doesn't) - `handleError()` logs to both console and file - `ModelNotFoundException` is thrown by `findOrFail()` and `firstOrFail()` ORM methods - The Error model persists errors to the database for tracking - `config/errors.ts` is a comprehensive i18n-ready error message catalog - `ErrorHandler.isTestEnvironment` prevents process exit during tests - `ERROR_PAGE_CSS` contains built-in styling for error pages