honertia 0.1.21 → 0.1.22

package/dist/effect/error-context.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Error Context Capture for Honertia
+ *
+ * Utilities for capturing request, route, and handler context
+ * when errors occur.
+ */
+import type { Context as HonoContext, Env } from 'hono';
+import type { ErrorContext, SourceLocation, CodeSnippet } from './error-types.js';
+/**
+ * Capture error context from a Hono request context.
+ *
+ * Extracts route information (method, path, params) and request details
+ * (URL, safe headers) for inclusion in structured errors. Sensitive headers
+ * like Authorization and Cookie are automatically filtered out.
+ *
+ * @param c - The Hono request context.
+ * @returns An ErrorContext object with route and request information.
+ *
+ * @example
+ * ```ts
+ * app.use('*', async (c, next) => {
+ *   try {
+ *     await next()
+ *   } catch (err) {
+ *     const context = captureErrorContext(c)
+ *     const structured = toStructuredError(err, context)
+ *     // ...
+ *   }
+ * })
+ * ```
+ */
+export declare function captureErrorContext<E extends Env>(c: HonoContext<E>): ErrorContext;
+/**
+ * Parse a V8 stack trace into structured frames.
+ */
+export interface StackFrame {
+    /** Function name if available */
+    functionName?: string;
+    /** File path */
+    file: string;
+    /** Line number */
+    line: number;
+    /** Column number */
+    column: number;
+    /** Whether this is from node_modules or framework code */
+    isInternal: boolean;
+}
+/**
+ * Parse a stack trace string into frames.
+ */
+export declare function parseStackTrace(stack: string): StackFrame[];
+/**
+ * Find the first user code frame (non-internal).
+ */
+export declare function findUserFrame(frames: StackFrame[]): StackFrame | undefined;
+/**
+ * Create a source location from an error.
+ * Attempts to find the relevant user code location.
+ */
+export declare function createSourceLocation(error: Error): SourceLocation | undefined;
+/**
+ * Create a code snippet from source code.
+ * Used when source code is available (e.g., in development).
+ *
+ * @param sourceCode - The full source code content.
+ * @param line - The 1-indexed line number where the error occurred.
+ * @param contextLines - Number of lines to include before/after the error line.
+ * @param highlightStart - Optional start column for highlighting.
+ * @param highlightEnd - Optional end column for highlighting.
+ * @returns A CodeSnippet with before/after context.
+ */
+export declare function createCodeSnippet(sourceCode: string, line: number, contextLines?: number, highlightStart?: number, highlightEnd?: number): CodeSnippet;
+/**
+ * Enhanced error context with source location.
+ */
+export interface EnhancedErrorContext extends ErrorContext {
+    source?: SourceLocation;
+}
+/**
+ * Capture enhanced error context including source location.
+ */
+export declare function captureEnhancedContext<E extends Env>(c: HonoContext<E>, error?: Error): EnhancedErrorContext;
+/**
+ * Add handler context to an error context.
+ */
+export declare function withHandlerContext(context: ErrorContext, file?: string, functionName?: string): ErrorContext;
+/**
+ * Add service context to an error context.
+ */
+export declare function withServiceContext(context: ErrorContext, serviceName: string, operation?: string): ErrorContext;
+/**
+ * Merge error contexts, with later values taking precedence.
+ */
+export declare function mergeContexts(...contexts: Partial<ErrorContext>[]): ErrorContext;
+/**
+ * Create an empty error context.
+ */
+export declare function emptyContext(): ErrorContext;
+//# sourceMappingURL=error-context.d.ts.map

package/dist/effect/error-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-context.d.ts","sourceRoot":"","sources":["../../src/effect/error-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,IAAI,WAAW,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAmCjF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,YAAY,CA4BlF;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAA;CACpB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,CA2B3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,GAAG,SAAS,CAE1E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,KAAK,GAAG,cAAc,GAAG,SAAS,CAc7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,MAAU,EACxB,cAAc,CAAC,EAAE,MAAM,EACvB,YAAY,CAAC,EAAE,MAAM,GACpB,WAAW,CA0Bb;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,GAAG,EAClD,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EACjB,KAAK,CAAC,EAAE,KAAK,GACZ,oBAAoB,CAQtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,IAAI,CAAC,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,YAAY,CAQd;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,YAAY,CAQd;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,QAAQ,EAAE,OAAO,CAAC,YAAY,CAAC,EAAE,GAAG,YAAY,CAmBhF;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAE3C"}

package/dist/effect/error-context.js

@@ -0,0 +1,230 @@
+/**
+ * Error Context Capture for Honertia
+ *
+ * Utilities for capturing request, route, and handler context
+ * when errors occur.
+ */
+/**
+ * Headers that are safe to include in error context.
+ * Excludes sensitive headers like Authorization, Cookie, etc.
+ */
+const SAFE_HEADERS = [
+    'accept',
+    'accept-language',
+    'content-type',
+    'content-length',
+    'x-inertia',
+    'x-inertia-version',
+    'x-requested-with',
+    'user-agent',
+    'referer',
+    'origin',
+];
+/**
+ * Extract safe headers from a request.
+ */
+function extractSafeHeaders(headers) {
+    const result = {};
+    for (const key of SAFE_HEADERS) {
+        const value = headers.get(key);
+        if (value) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Capture error context from a Hono request context.
+ *
+ * Extracts route information (method, path, params) and request details
+ * (URL, safe headers) for inclusion in structured errors. Sensitive headers
+ * like Authorization and Cookie are automatically filtered out.
+ *
+ * @param c - The Hono request context.
+ * @returns An ErrorContext object with route and request information.
+ *
+ * @example
+ * ```ts
+ * app.use('*', async (c, next) => {
+ *   try {
+ *     await next()
+ *   } catch (err) {
+ *     const context = captureErrorContext(c)
+ *     const structured = toStructuredError(err, context)
+ *     // ...
+ *   }
+ * })
+ * ```
+ */
+export function captureErrorContext(c) {
+    const context = {};
+    // Route context
+    try {
+        const routePath = c.req.routePath ?? c.req.path;
+        const params = c.req.param();
+        context.route = {
+            method: c.req.method,
+            path: routePath,
+            params: typeof params === 'string' ? {} : params,
+        };
+    }
+    catch {
+        // Ignore errors extracting route info
+    }
+    // Request context
+    try {
+        context.request = {
+            url: c.req.url,
+            headers: extractSafeHeaders(c.req.raw.headers),
+        };
+    }
+    catch {
+        // Ignore errors extracting request info
+    }
+    return context;
+}
+/**
+ * Parse a stack trace string into frames.
+ */
+export function parseStackTrace(stack) {
+    const frames = [];
+    const lines = stack.split('\n');
+    for (const line of lines) {
+        // Match V8 stack format: "    at functionName (file:line:col)"
+        // or "    at file:line:col"
+        const match = line.match(/^\s*at\s+(?:(.+?)\s+\()?(.+):(\d+):(\d+)\)?$/);
+        if (match) {
+            const file = match[2];
+            const isInternal = file.includes('node_modules') ||
+                file.includes('honertia/dist') ||
+                file.includes('effect/dist') ||
+                file.startsWith('node:');
+            frames.push({
+                functionName: match[1],
+                file,
+                line: parseInt(match[3], 10),
+                column: parseInt(match[4], 10),
+                isInternal,
+            });
+        }
+    }
+    return frames;
+}
+/**
+ * Find the first user code frame (non-internal).
+ */
+export function findUserFrame(frames) {
+    return frames.find((f) => !f.isInternal);
+}
+/**
+ * Create a source location from an error.
+ * Attempts to find the relevant user code location.
+ */
+export function createSourceLocation(error) {
+    if (!error.stack)
+        return undefined;
+    const frames = parseStackTrace(error.stack);
+    const userFrame = findUserFrame(frames);
+    if (!userFrame)
+        return undefined;
+    return {
+        file: userFrame.file,
+        line: userFrame.line,
+        column: userFrame.column,
+        functionName: userFrame.functionName,
+    };
+}
+/**
+ * Create a code snippet from source code.
+ * Used when source code is available (e.g., in development).
+ *
+ * @param sourceCode - The full source code content.
+ * @param line - The 1-indexed line number where the error occurred.
+ * @param contextLines - Number of lines to include before/after the error line.
+ * @param highlightStart - Optional start column for highlighting.
+ * @param highlightEnd - Optional end column for highlighting.
+ * @returns A CodeSnippet with before/after context.
+ */
+export function createCodeSnippet(sourceCode, line, contextLines = 2, highlightStart, highlightEnd) {
+    const lines = sourceCode.split('\n');
+    // Validate line number is within bounds
+    const validLine = Math.max(1, Math.min(line, lines.length));
+    const startLine = Math.max(0, validLine - 1 - contextLines);
+    const endLine = Math.min(lines.length, validLine + contextLines);
+    const before = lines.slice(startLine, validLine - 1);
+    const errorLine = lines[validLine - 1] ?? '';
+    const after = lines.slice(validLine, endLine);
+    const snippet = {
+        before,
+        line: errorLine,
+        after,
+    };
+    if (highlightStart !== undefined && highlightEnd !== undefined) {
+        snippet.highlight = {
+            start: highlightStart,
+            end: highlightEnd,
+        };
+    }
+    return snippet;
+}
+/**
+ * Capture enhanced error context including source location.
+ */
+export function captureEnhancedContext(c, error) {
+    const context = captureErrorContext(c);
+    if (error) {
+        context.source = createSourceLocation(error);
+    }
+    return context;
+}
+/**
+ * Add handler context to an error context.
+ */
+export function withHandlerContext(context, file, functionName) {
+    return {
+        ...context,
+        handler: {
+            file,
+            function: functionName,
+        },
+    };
+}
+/**
+ * Add service context to an error context.
+ */
+export function withServiceContext(context, serviceName, operation) {
+    return {
+        ...context,
+        service: {
+            name: serviceName,
+            operation,
+        },
+    };
+}
+/**
+ * Merge error contexts, with later values taking precedence.
+ */
+export function mergeContexts(...contexts) {
+    const result = {};
+    for (const ctx of contexts) {
+        if (ctx.route) {
+            result.route = { ...result.route, ...ctx.route };
+        }
+        if (ctx.handler) {
+            result.handler = { ...result.handler, ...ctx.handler };
+        }
+        if (ctx.request) {
+            result.request = { ...result.request, ...ctx.request };
+        }
+        if (ctx.service) {
+            result.service = { ...result.service, ...ctx.service };
+        }
+    }
+    return result;
+}
+/**
+ * Create an empty error context.
+ */
+export function emptyContext() {
+    return {};
+}

package/dist/effect/error-formatter.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Error Formatters for Honertia
+ *
+ * Multiple output formats for structured errors:
+ * - JSON for AI/API consumption
+ * - Terminal with ANSI colors for CLI
+ * - Inertia for browser rendering
+ */
+import type { HonertiaStructuredError } from './error-types.js';
+/**
+ * Interface for error formatters.
+ */
+export interface ErrorFormatter {
+    format(error: HonertiaStructuredError): string | object;
+}
+/**
+ * Options for JSON formatter.
+ */
+export interface JsonFormatterOptions {
+    /** Pretty print with indentation */
+    pretty?: boolean;
+    /** Include source location */
+    includeSource?: boolean;
+    /** Include request/route context */
+    includeContext?: boolean;
+    /** Include fix suggestions */
+    includeFixes?: boolean;
+    /** Include documentation links */
+    includeDocs?: boolean;
+}
+/**
+ * JSON formatter for AI/LLM and API consumption.
+ * Outputs machine-readable structured error data.
+ */
+export declare class JsonErrorFormatter implements ErrorFormatter {
+    private options;
+    constructor(options?: JsonFormatterOptions);
+    format(error: HonertiaStructuredError): object;
+    /**
+     * Format to JSON string.
+     */
+    formatString(error: HonertiaStructuredError): string;
+}
+/**
+ * Options for terminal formatter.
+ */
+export interface TerminalFormatterOptions {
+    /** Use ANSI colors */
+    useColors?: boolean;
+    /** Show source code snippet */
+    showSnippet?: boolean;
+    /** Show fix suggestions */
+    showFixes?: boolean;
+    /** Maximum number of fixes to show */
+    maxFixes?: number;
+}
+/**
+ * Terminal formatter with ANSI colors.
+ * Outputs Rust/Elm-style human-readable errors.
+ */
+export declare class TerminalErrorFormatter implements ErrorFormatter {
+    private options;
+    private c;
+    constructor(options?: TerminalFormatterOptions);
+    format(error: HonertiaStructuredError): string;
+}
+/**
+ * Options for Inertia formatter.
+ */
+export interface InertiaFormatterOptions {
+    /** Include fix suggestions */
+    includeFixes?: boolean;
+    /** Include source location */
+    includeSource?: boolean;
+    /** Development mode (shows more details) */
+    isDev?: boolean;
+}
+/**
+ * Inertia formatter for browser error pages.
+ * Outputs props for an Inertia error component.
+ */
+export declare class InertiaErrorFormatter implements ErrorFormatter {
+    private options;
+    constructor(options?: InertiaFormatterOptions);
+    format(error: HonertiaStructuredError): object;
+    /**
+     * Get a safe message for production (no sensitive details).
+     */
+    private getSafeMessage;
+}
+/**
+ * Output format types.
+ */
+export type OutputFormat = 'json' | 'terminal' | 'inertia';
+/**
+ * Request context for format detection.
+ */
+export interface FormatDetectionContext {
+    header: (name: string) => string | undefined;
+    method: string;
+    url: string;
+}
+/**
+ * Detect the appropriate output format based on request headers and environment.
+ *
+ * Detection priority:
+ * 1. AI/CLI User-Agents (claude-code, curl) → 'json'
+ * 2. Accept: application/json header → 'json'
+ * 3. X-Inertia: true header → 'inertia'
+ * 4. Content-Type: application/json → 'json'
+ * 5. Development environment → 'terminal'
+ * 6. Production browser requests → 'inertia'
+ *
+ * @param request - Request context with header accessor, method, and URL.
+ * @param env - Environment variables for detecting dev/prod mode.
+ * @returns The detected output format: 'json', 'terminal', or 'inertia'.
+ *
+ * @example
+ * ```ts
+ * const format = detectOutputFormat(
+ *   { header: (n) => c.req.header(n), method: c.req.method, url: c.req.url },
+ *   c.env
+ * )
+ * const formatter = createFormatter(format, isDev)
+ * ```
+ */
+export declare function detectOutputFormat(request: FormatDetectionContext, env?: Record<string, unknown>): OutputFormat;
+/**
+ * Create a formatter instance for the given output format.
+ *
+ * @param format - The output format: 'json', 'terminal', or 'inertia'.
+ * @param isDev - Whether to include dev-only details (source, context). Defaults to true.
+ * @returns An ErrorFormatter instance configured for the format.
+ *
+ * @example
+ * ```ts
+ * const format = detectOutputFormat(request, env)
+ * const formatter = createFormatter(format, isDev)
+ * const output = formatter.format(structuredError)
+ * ```
+ */
+export declare function createFormatter(format: OutputFormat, isDev?: boolean): ErrorFormatter;
+//# sourceMappingURL=error-formatter.d.ts.map

package/dist/effect/error-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.d.ts","sourceRoot":"","sources":["../../src/effect/error-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAkB,MAAM,kBAAkB,CAAA;AAE/E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM,GAAG,MAAM,CAAA;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,oCAAoC;IACpC,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,8BAA8B;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,kCAAkC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;GAGG;AACH,qBAAa,kBAAmB,YAAW,cAAc;IAC3C,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,oBAAyB;IAYtD,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM;IA+C9C;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM;CAIrD;AAoBD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sBAAsB;IACtB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAG/C,OAAO,CAAC,OAAO;IAF3B,OAAO,CAAC,CAAC,CAAqD;gBAE1C,OAAO,GAAE,wBAA6B;IAkB1D,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM;CAoH/C;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,8BAA8B;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC9C,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,uBAA4B;IASzD,MAAM,CAAC,KAAK,EAAE,uBAAuB,GAAG,MAAM;IAqC9C;;OAEG;IACH,OAAO,CAAC,cAAc;CAYvB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,EAC/B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAChC,YAAY,CA0Cd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,EACpB,KAAK,GAAE,OAAc,GACpB,cAAc,CA0BhB"}