@zudojs/errors 0.1.0 → 1.0.0

package/dist/utils/errorHandler.core.js

@@ -1,67 +1,70 @@
 /**
  * Centralized error normalization, serialization, and reporting service.
  */
-import { BaseError } from "../base/core/baseError.core.js";
-import { ErrorCategory } from "../base/types/errorCategory.type.js";
-import { ErrorCode } from "../base/types/errorCode.type.js";
-import { ErrorSeverity } from "../base/types/errorSeverity.type.js";
+import { pickErrorMetadata, redactErrorMetadata, serializeErrorMetadata, } from "../base/core/errorMetadata.core.js";
+import { isBaseError, normalizeUnknownToBaseError, } from "../base/utils/baseError.utils.js";
+import { ErrorSerializer } from "./errorSerializer.core.js";
 export { createErrorHandler, normalizeError, isHandledError, } from "./errorHandler.factory.js";
 /** Centralized error normalization, serialization, and reporting service. */
 export class ErrorHandler {
     reporter;
+    onReporterError;
     defaultStatusCode;
     defaultMessage;
     includeStack;
+    publicMetadataKeys;
+    sensitiveKeyPattern;
     constructor(options = {}) {
         this.reporter = options.reporter;
+        this.onReporterError = options.onReporterError;
         this.defaultStatusCode = options.defaultStatusCode ?? 500;
         this.defaultMessage =
             options.defaultMessage ?? "An unexpected error occurred.";
         this.includeStack = options.includeStack ?? false;
+        this.publicMetadataKeys = options.publicMetadataKeys;
+        this.sensitiveKeyPattern = options.sensitiveKeyPattern;
     }
     /** Converts an unknown thrown value into a BaseError. */
     normalize(value) {
-        if (value instanceof BaseError) {
+        if (isBaseError(value)) {
             return { error: value, original: value };
         }
-        if (value instanceof Error) {
-            const error = new BaseError(value.message || this.defaultMessage, {
-                code: ErrorCode.INTERNAL_ERROR,
-                category: ErrorCategory.SYSTEM,
-                severity: ErrorSeverity.ERROR,
-                statusCode: this.defaultStatusCode,
-                expose: false,
-                isOperational: false,
-                cause: value,
-            });
-            return { error, original: value };
-        }
-        const message = typeof value === "string" ? value : this.defaultMessage;
-        const error = new BaseError(message, {
-            code: ErrorCode.INTERNAL_ERROR,
-            category: ErrorCategory.SYSTEM,
-            severity: ErrorSeverity.ERROR,
+        const error = normalizeUnknownToBaseError(value, {
             statusCode: this.defaultStatusCode,
-            expose: false,
-            isOperational: false,
-            metadata: { originalType: typeof value },
+            ...(value instanceof Error || typeof value === "string"
+                ? {}
+                : { message: this.defaultMessage }),
         });
         return { error, original: value };
     }
-    /** Handles and normalizes an unknown error. */
+    /**
+     * Handles and normalizes an unknown error.
+     *
+     * The reporter is isolated: if it throws or rejects, the failure is passed
+     * to `onReporterError` (or swallowed) and the original error's result is
+     * still returned.
+     */
     async handle(value, context) {
         const { error } = this.normalize(value);
-        if (this.reporter) {
-            await this.reporter(error, context);
-        }
+        await this.reportSafely(error, context);
         return this.toResult(error, context);
     }
-    /** Converts a BaseError into a safe response object. */
+    /** Handles an unknown error and returns the client-safe representation. */
+    async handlePublic(value, context) {
+        const { error } = this.normalize(value);
+        await this.reportSafely(error, context);
+        return this.toPublicResult(error, context);
+    }
+    /**
+     * Converts a BaseError into the internal result object.
+     *
+     * Metadata is redacted recursively; the stack is never included.
+     */
     toResult(error, context) {
-        const metadata = {
-            ...(error.toJSON().metadata ?? {}),
+        const metadata = this.redact({
+            ...serializeErrorMetadata(error.metadata),
             ...(context?.metadata ?? {}),
-        };
+        });
         return {
             code: error.code,
             message: error.expose ? error.message : this.defaultMessage,
@@ -74,51 +77,101 @@ export class ErrorHandler {
             ...(context?.correlationId
                 ? { correlationId: context.correlationId }
                 : {}),
-            ...(Object.keys(metadata).length > 0
-                ? { metadata: this.sanitizeMetadata(metadata) }
+            ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
+        };
+    }
+    /**
+     * Converts a BaseError into a client-safe result.
+     *
+     * Only `code`, `message`, `statusCode`, request/correlation ids and
+     * allow-listed metadata (`details`) are included. Internal classification
+     * fields and non-exposed metadata are never revealed.
+     */
+    toPublicResult(error, context) {
+        let details;
+        if (this.publicMetadataKeys !== undefined) {
+            details = this.redact(pickErrorMetadata(error.metadata, this.publicMetadataKeys));
+        }
+        else if (error.expose) {
+            details = this.redact(error.metadata);
+        }
+        return {
+            code: error.code,
+            message: error.expose ? error.message : this.defaultMessage,
+            statusCode: error.statusCode,
+            ...(context?.requestId ? { requestId: context.requestId } : {}),
+            ...(context?.correlationId
+                ? { correlationId: context.correlationId }
+                : {}),
+            ...(details !== undefined && Object.keys(details).length > 0
+                ? { details }
                 : {}),
         };
     }
     /** Reports an error without producing a response. */
     async report(value, context) {
         const { error } = this.normalize(value);
-        if (this.reporter) {
-            await this.reporter(error, context);
-        }
+        await this.reportSafely(error, context);
         return error;
     }
     /** Determines whether an error should expose its message to clients. */
     shouldExpose(error) {
         return error.expose;
     }
-    /** Returns a safe serialized error representation. */
+    /**
+     * Returns a safe serialized error representation (never includes a stack).
+     *
+     * Equivalent to `toPublicResult`; kept for backwards compatibility.
+     */
     serialize(error, context) {
-        const result = this.toResult(error, context);
-        if (this.includeStack && error.expose === false) {
-            return { ...result, stack: error.stack };
-        }
-        return result;
+        return this.toPublicResult(error, context);
     }
-    /** Removes obviously sensitive fields from metadata before serialization. */
-    sanitizeMetadata(metadata) {
-        const sensitiveKeys = new Set([
-            "password",
-            "passcode",
-            "token",
-            "accessToken",
-            "refreshToken",
-            "authorization",
-            "cookie",
-            "secret",
-            "privateKey",
-            "apiKey",
-            "credential",
-        ]);
-        const sanitized = {};
-        for (const [key, value] of Object.entries(metadata)) {
-            sanitized[key] = sensitiveKeys.has(key) ? "[REDACTED]" : value;
+    /**
+     * Returns the full internal representation for logging, including the
+     * (redacted) cause chain and, when `includeStack` is enabled, stack traces.
+     */
+    toLogObject(error, context) {
+        const serialized = new ErrorSerializer({
+            includeStack: this.includeStack,
+            includeCause: true,
+            includeMetadata: true,
+            redactSensitiveData: true,
+            sensitiveKeyPattern: this.sensitiveKeyPattern,
+        }).serialize(error);
+        return {
+            ...serialized,
+            ...(context?.requestId ? { requestId: context.requestId } : {}),
+            ...(context?.correlationId
+                ? { correlationId: context.correlationId }
+                : {}),
+            ...(context?.metadata
+                ? { context: this.redact(context.metadata) }
+                : {}),
+        };
+    }
+    /** Invokes the reporter without letting its failure escape. */
+    async reportSafely(error, context) {
+        if (!this.reporter)
+            return;
+        try {
+            await this.reporter(error, context);
+        }
+        catch (reporterError) {
+            if (this.onReporterError) {
+                try {
+                    this.onReporterError(reporterError, error, context);
+                }
+                catch {
+                    // A failing failure-handler must never break error handling.
+                }
+            }
         }
-        return sanitized;
+    }
+    /** Removes obviously sensitive fields from metadata (recursively). */
+    redact(metadata) {
+        return redactErrorMetadata(metadata, {
+            sensitiveKeyPattern: this.sensitiveKeyPattern,
+        });
     }
 }
 //# sourceMappingURL=errorHandler.core.js.map

package/dist/utils/errorHandler.factory.d.ts

@@ -1,7 +1,7 @@
 /**
  * Error handler factory functions.
  */
-import { BaseError } from "../base/core/baseError.core.js";
+import type { BaseError } from "../base/core/baseError.core.js";
 import { ErrorHandler } from "./errorHandler.core.js";
 import type { ErrorHandlerOptions } from "./errorHandler.types.js";
 /** Creates a default error handler. */

package/dist/utils/errorHandler.factory.js

@@ -1,7 +1,7 @@
 /**
  * Error handler factory functions.
  */
-import { BaseError } from "../base/core/baseError.core.js";
+import { isBaseError } from "../base/utils/baseError.utils.js";
 import { ErrorHandler } from "./errorHandler.core.js";
 /** Creates a default error handler. */
 export function createErrorHandler(options = {}) {
@@ -13,6 +13,6 @@ export function normalizeError(value) {
 }
 /** Determines whether an unknown value is a supported BaseError. */
 export function isHandledError(value) {
-    return value instanceof BaseError;
+    return isBaseError(value);
 }
 //# sourceMappingURL=errorHandler.factory.js.map

package/dist/utils/errorHandler.types.d.ts

@@ -18,7 +18,13 @@ export interface NormalizedError {
     readonly error: BaseError;
     readonly original: unknown;
 }
-/** Structured result returned by the error handler. */
+/**
+ * Structured result returned by the error handler.
+ *
+ * This is the INTERNAL representation (classification fields and redacted
+ * metadata included); use `ErrorHandler.toPublicResult` / `PublicErrorHandlerResult`
+ * for anything returned to an untrusted client.
+ */
 export interface ErrorHandlerResult {
     readonly code: string;
     readonly message: string;
@@ -31,13 +37,43 @@ export interface ErrorHandlerResult {
     readonly correlationId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Client-safe result returned by `ErrorHandler.toPublicResult`. */
+export interface PublicErrorHandlerResult {
+    readonly code: string;
+    readonly message: string;
+    readonly statusCode: number;
+    readonly requestId?: string;
+    readonly correlationId?: string;
+    /** Allow-listed, redacted metadata (see `ErrorHandlerOptions.publicMetadataKeys`). */
+    readonly details?: Readonly<Record<string, unknown>>;
+}
 /** Callback used to report errors to an external logger or monitoring system. */
 export type ErrorReporter = (error: BaseError, context?: ErrorHandlerContext) => void | Promise<void>;
+/** Callback invoked when the reporter itself fails. */
+export type ErrorReporterFailureHandler = (reporterError: unknown, originalError: BaseError, context?: ErrorHandlerContext) => void;
 /** Options for constructing an ErrorHandler. */
 export interface ErrorHandlerOptions {
     readonly reporter?: ErrorReporter;
+    /**
+     * Invoked when `reporter` throws or rejects. Reporter failures never
+     * propagate out of `handle`/`report`; when this hook is absent they are
+     * swallowed.
+     */
+    readonly onReporterError?: ErrorReporterFailureHandler;
     readonly defaultStatusCode?: number;
     readonly defaultMessage?: string;
+    /**
+     * Include the stack trace in `toLogObject` output. Stacks are never
+     * included in `toResult`, `toPublicResult` or `serialize`.
+     */
     readonly includeStack?: boolean;
+    /**
+     * Metadata keys copied into `PublicErrorHandlerResult.details`. When omitted,
+     * exposed errors contribute their (redacted) metadata and non-exposed errors
+     * contribute nothing.
+     */
+    readonly publicMetadataKeys?: readonly string[];
+    /** Pattern used to detect sensitive metadata keys. */
+    readonly sensitiveKeyPattern?: RegExp;
 }
 //# sourceMappingURL=errorHandler.types.d.ts.map

package/dist/utils/errorMapper.core.d.ts

@@ -3,5 +3,5 @@
  */
 export type { ErrorMapperContext, ErrorMapping, ErrorMapperPredicate, ErrorMapper, ErrorMappingRule, } from "./errorMapper.types.js";
 export { ErrorMapperRegistry, createErrorMapperRegistry, } from "./errorMapper.registry.js";
-export { mapNativeError, mapError, mapErrorType, createErrorMappingRule, } from "./errorMapper.mappers.js";
+export { mapNativeError, mapError, mapErrorType, createErrorMappingRule, applyErrorMapping, type ErrorConstructor, } from "./errorMapper.mappers.js";
 //# sourceMappingURL=errorMapper.core.d.ts.map

package/dist/utils/errorMapper.core.js

@@ -2,5 +2,5 @@
  * Error mapper — re-exports from focused files.
  */
 export { ErrorMapperRegistry, createErrorMapperRegistry, } from "./errorMapper.registry.js";
-export { mapNativeError, mapError, mapErrorType, createErrorMappingRule, } from "./errorMapper.mappers.js";
+export { mapNativeError, mapError, mapErrorType, createErrorMappingRule, applyErrorMapping, } from "./errorMapper.mappers.js";
 //# sourceMappingURL=errorMapper.core.js.map

package/dist/utils/errorMapper.mappers.d.ts

@@ -2,14 +2,35 @@
  * Error mapping functions — native error mapping, registry-based mapping, rule creation.
  */
 import { BaseError } from "../base/core/baseError.core.js";
-import type { ErrorMapperContext, ErrorMapper, ErrorMapperPredicate, ErrorMappingRule } from "./errorMapper.types.js";
+import type { ErrorMapperContext, ErrorMapper, ErrorMapperPredicate, ErrorMapping, ErrorMappingRule } from "./errorMapper.types.js";
 import type { ErrorMapperRegistry } from "./errorMapper.registry.js";
-/** Maps common native JavaScript errors. */
+/**
+ * Maps common native JavaScript errors.
+ *
+ * Native `TypeError`/`RangeError`/`SyntaxError` are overwhelmingly programmer
+ * bugs rather than client input problems, so they are classified as
+ * non-operational internal errors (500, not exposed). Register an explicit
+ * mapping rule to treat a specific error type as client input.
+ */
 export declare function mapNativeError(error: unknown): BaseError | undefined;
 /** Maps an error using a registry and falls back to native error mapping. */
 export declare function mapError(error: unknown, registry?: ErrorMapperRegistry, context?: ErrorMapperContext): BaseError;
-/** Creates a mapping rule for a specific error constructor. */
-export declare function mapErrorType<T extends Error>(name: string, errorType: new (...args: unknown[]) => T, mapper: (error: T, context?: ErrorMapperContext) => BaseError, priority?: number): ErrorMappingRule;
-/** Creates a mapping rule based on a predicate. */
-export declare function createErrorMappingRule(name: string, predicate: ErrorMapperPredicate, mapper: ErrorMapper, priority?: number): ErrorMappingRule;
+/** Any constructor whose instances are `T` (parameters are not constrained). */
+export type ErrorConstructor<T extends Error> = abstract new (...args: any[]) => T;
+/**
+ * Creates a mapping rule for a specific error constructor.
+ *
+ * `mapper` may be a function producing a `BaseError`, or a declarative
+ * `ErrorMapping` describing the resulting error.
+ */
+export declare function mapErrorType<T extends Error>(name: string, errorType: ErrorConstructor<T>, mapper: ((error: T, context?: ErrorMapperContext) => BaseError) | ErrorMapping, priority?: number): ErrorMappingRule;
+/**
+ * Creates a mapping rule based on a predicate.
+ *
+ * `mapper` may be a function producing a `BaseError`, or a declarative
+ * `ErrorMapping` describing the resulting error.
+ */
+export declare function createErrorMappingRule(name: string, predicate: ErrorMapperPredicate, mapper: ErrorMapper | ErrorMapping, priority?: number): ErrorMappingRule;
+/** Builds a BaseError from a declarative `ErrorMapping`. */
+export declare function applyErrorMapping(error: unknown, mapping: ErrorMapping, context?: ErrorMapperContext): BaseError;
 //# sourceMappingURL=errorMapper.mappers.d.ts.map

package/dist/utils/errorMapper.mappers.js

@@ -2,52 +2,29 @@
  * Error mapping functions — native error mapping, registry-based mapping, rule creation.
  */
 import { BaseError } from "../base/core/baseError.core.js";
-import { ErrorCategory } from "../base/types/errorCategory.type.js";
-import { ErrorCode } from "../base/types/errorCode.type.js";
-import { ErrorSeverity } from "../base/types/errorSeverity.type.js";
-/** Maps common native JavaScript errors. */
+import { isBaseError, normalizeUnknownToBaseError, } from "../base/utils/baseError.utils.js";
+/**
+ * Maps common native JavaScript errors.
+ *
+ * Native `TypeError`/`RangeError`/`SyntaxError` are overwhelmingly programmer
+ * bugs rather than client input problems, so they are classified as
+ * non-operational internal errors (500, not exposed). Register an explicit
+ * mapping rule to treat a specific error type as client input.
+ */
 export function mapNativeError(error) {
-    if (error instanceof BaseError) {
+    if (isBaseError(error)) {
         return error;
     }
-    if (error instanceof TypeError) {
-        return new BaseError(error.message, {
-            code: ErrorCode.INVALID_INPUT,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.WARNING,
-            statusCode: 400,
-            expose: true,
-            isOperational: true,
-            cause: error,
-        });
-    }
-    if (error instanceof RangeError) {
-        return new BaseError(error.message, {
-            code: ErrorCode.INVALID_INPUT,
-            category: ErrorCategory.VALIDATION,
-            severity: ErrorSeverity.WARNING,
-            statusCode: 400,
-            expose: true,
-            isOperational: true,
-            cause: error,
-        });
-    }
     if (error instanceof Error) {
-        return new BaseError(error.message || "An unexpected error occurred.", {
-            code: ErrorCode.INTERNAL_ERROR,
-            category: ErrorCategory.SYSTEM,
-            severity: ErrorSeverity.ERROR,
-            statusCode: 500,
-            expose: false,
-            isOperational: false,
-            cause: error,
+        return normalizeUnknownToBaseError(error, {
+            metadata: { nativeErrorName: error.name },
         });
     }
     return undefined;
 }
 /** Maps an error using a registry and falls back to native error mapping. */
 export function mapError(error, registry, context) {
-    if (error instanceof BaseError) {
+    if (isBaseError(error)) {
         return error;
     }
     const mapped = registry?.map(error, context);
@@ -58,27 +35,58 @@ export function mapError(error, registry, context) {
     if (native) {
         return native;
     }
-    return new BaseError("An unexpected error occurred.", {
-        code: ErrorCode.INTERNAL_ERROR,
-        category: ErrorCategory.SYSTEM,
-        severity: ErrorSeverity.ERROR,
-        statusCode: 500,
-        expose: false,
-        isOperational: false,
-        metadata: { originalType: typeof error },
-    });
+    return normalizeUnknownToBaseError(error);
 }
-/** Creates a mapping rule for a specific error constructor. */
+/**
+ * Creates a mapping rule for a specific error constructor.
+ *
+ * `mapper` may be a function producing a `BaseError`, or a declarative
+ * `ErrorMapping` describing the resulting error.
+ */
 export function mapErrorType(name, errorType, mapper, priority = 0) {
+    const mapFn = typeof mapper === "function"
+        ? (error, context) => mapper(error, context)
+        : (error, context) => applyErrorMapping(error, mapper, context);
     return {
         name,
         priority,
         predicate: (error) => error instanceof errorType,
-        mapper: (error, context) => mapper(error, context),
+        mapper: mapFn,
     };
 }
-/** Creates a mapping rule based on a predicate. */
+/**
+ * Creates a mapping rule based on a predicate.
+ *
+ * `mapper` may be a function producing a `BaseError`, or a declarative
+ * `ErrorMapping` describing the resulting error.
+ */
 export function createErrorMappingRule(name, predicate, mapper, priority = 0) {
-    return { name, predicate, mapper, priority };
+    const mapFn = typeof mapper === "function"
+        ? mapper
+        : (error, context) => applyErrorMapping(error, mapper, context);
+    return { name, predicate, mapper: mapFn, priority };
+}
+/** Builds a BaseError from a declarative `ErrorMapping`. */
+export function applyErrorMapping(error, mapping, context) {
+    const message = mapping.message ??
+        (error instanceof Error && error.message
+            ? error.message
+            : "An unexpected error occurred.");
+    return new BaseError(message, {
+        code: mapping.code,
+        category: mapping.category,
+        severity: mapping.severity,
+        statusCode: mapping.statusCode,
+        expose: mapping.expose,
+        isOperational: mapping.isOperational,
+        cause: error,
+        metadata: {
+            ...context?.metadata,
+            ...mapping.metadata,
+            ...(context?.requestId !== undefined
+                ? { requestId: context.requestId }
+                : {}),
+        },
+    });
 }
 //# sourceMappingURL=errorMapper.mappers.js.map

package/dist/utils/errorSerializer.core.d.ts

@@ -12,16 +12,35 @@ export declare class ErrorSerializer {
     private readonly includeMetadata;
     private readonly safeMessage;
     private readonly redactSensitiveData;
+    private readonly sensitiveKeyPattern;
+    private readonly publicMetadataKeys;
     constructor(options?: ErrorSerializerOptions);
-    /** Serializes an error for internal logging or monitoring. */
+    /**
+     * Serializes an error for internal logging or monitoring.
+     *
+     * `includeStack`, `includeCause` and `redactSensitiveData` are applied at
+     * every level of the cause chain.
+     */
     serialize(error: BaseError): InternalErrorResponse;
-    /** Serializes an error for an untrusted API client. */
+    /**
+     * Serializes an error for an untrusted API client.
+     *
+     * Never includes a stack or cause. Metadata is only included when the error
+     * is exposable (or when `publicMetadataKeys` allow-lists specific keys) and
+     * is always redacted.
+     */
     serializePublic(error: BaseError): PublicErrorResponse;
     /** Serializes an unknown thrown value. */
     serializeUnknown(value: unknown): InternalErrorResponse;
     /** Creates a public response from an unknown thrown value. */
     serializeUnknownPublic(value: unknown): PublicErrorResponse;
-    /** Removes commonly sensitive metadata fields. */
+    /** Applies the serializer options to one level of a serialized error. */
+    private serializeLevel;
+    /** Applies the serializer options recursively to a serialized cause. */
+    private serializeCause;
+    /** Computes the metadata allowed in a public response. */
+    private publicMetadata;
+    /** Removes commonly sensitive metadata fields (recursively). */
     private redactMetadata;
 }
 //# sourceMappingURL=errorSerializer.core.d.ts.map