@zudojs/errors 0.1.0 → 1.0.0

package/dist/infrastructure/network/routePattern.error.d.ts

@@ -1,18 +1,19 @@
-import { BaseError } from "../../base/core/baseError.core.js";
-import type { BaseErrorOptions } from "../../base/types/baseError.type.js";
-import { ErrorCategory } from "../../base/types/errorCategory.type.js";
+import { HttpRouterError, type HttpRouterErrorOptions } from "./httpRouterError.base.js";
 /**
  * Options for creating a route pattern error.
  */
-export interface RoutePatternErrorOptions extends Omit<BaseErrorOptions, "category"> {
-    readonly category?: ErrorCategory;
+export interface RoutePatternErrorOptions extends HttpRouterErrorOptions {
     readonly pattern?: string;
     readonly position?: number;
 }
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Route patterns are authored by developers, not clients, so this is a
+ * server-side configuration error: 500, not exposed, non-operational.
+ * `InvalidRoutePatternError` (in `httpRouterError.types`) extends this class.
  */
-export declare class RoutePatternError extends BaseError {
+export declare class RoutePatternError extends HttpRouterError {
     /**
      * The route pattern that caused the error.
      */

package/dist/infrastructure/network/routePattern.error.js

@@ -1,11 +1,14 @@
-import { BaseError } from "../../base/core/baseError.core.js";
 import { ErrorCode } from "../../base/types/errorCode.type.js";
-import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+import { HttpRouterError, } from "./httpRouterError.base.js";
 /**
  * Error thrown when a route pattern is invalid.
+ *
+ * Route patterns are authored by developers, not clients, so this is a
+ * server-side configuration error: 500, not exposed, non-operational.
+ * `InvalidRoutePatternError` (in `httpRouterError.types`) extends this class.
  */
-export class RoutePatternError extends BaseError {
+export class RoutePatternError extends HttpRouterError {
     /**
      * The route pattern that caused the error.
      */
@@ -18,12 +21,18 @@ export class RoutePatternError extends BaseError {
         super(message, {
             ...options,
             code: options.code ?? ErrorCode.HTTP_ROUTE_PATTERN,
-            category: options.category ?? ErrorCategory.VALIDATION,
             severity: options.severity ?? ErrorSeverity.ERROR,
-            statusCode: options.statusCode ?? 400,
-            expose: options.expose ?? true,
+            statusCode: options.statusCode ?? 500,
+            expose: options.expose ?? false,
+            isOperational: options.isOperational ?? false,
+            metadata: {
+                ...options.metadata,
+                ...(options.pattern !== undefined ? { pattern: options.pattern } : {}),
+                ...(options.position !== undefined
+                    ? { position: options.position }
+                    : {}),
+            },
         });
-        this.name = "RoutePatternError";
         this.pattern = options.pattern ?? "";
         this.position = options.position;
     }
@@ -44,7 +53,6 @@ export class DuplicateRouteParameterError extends RoutePatternError {
                 paramName,
             },
         });
-        this.name = "DuplicateRouteParameterError";
         this.paramName = paramName;
     }
 }

package/dist/infrastructure/network/timeoutError.base.d.ts

@@ -51,4 +51,11 @@ export declare class TimeoutError extends BaseError {
 export declare function createTimeoutError(message?: string, options?: TimeoutErrorOptions): TimeoutError;
 /** Determines whether an unknown value is a TimeoutError. */
 export declare function isTimeoutError(value: unknown): value is TimeoutError;
+/**
+ * Returns whether a timeout operation may expose its message (and target) to
+ * clients. Only request-level timeouts are public by default; database,
+ * cache, queue, lock, network and external-service timeouts describe internal
+ * resources and stay internal.
+ */
+export declare function isPublicTimeoutOperation(operation: TimeoutOperation | undefined): boolean;
 //# sourceMappingURL=timeoutError.base.d.ts.map

package/dist/infrastructure/network/timeoutError.base.js

@@ -31,7 +31,7 @@ export class TimeoutError extends BaseError {
             category: options.category ?? ErrorCategory.TIMEOUT,
             severity: options.severity ?? ErrorSeverity.WARNING,
             statusCode: options.statusCode ?? 504,
-            expose: options.expose ?? true,
+            expose: options.expose ?? isPublicTimeoutOperation(options.operation),
             isOperational: options.isOperational ?? true,
             metadata: {
                 ...options.metadata,
@@ -65,6 +65,17 @@ export function createTimeoutError(message = "The operation timed out.", options
 export function isTimeoutError(value) {
     return value instanceof TimeoutError;
 }
+/**
+ * Returns whether a timeout operation may expose its message (and target) to
+ * clients. Only request-level timeouts are public by default; database,
+ * cache, queue, lock, network and external-service timeouts describe internal
+ * resources and stay internal.
+ */
+export function isPublicTimeoutOperation(operation) {
+    return (operation === undefined ||
+        operation === TimeoutOperation.UNKNOWN ||
+        operation === TimeoutOperation.REQUEST);
+}
 /** Validates a timeout duration. */
 function validateTimeout(timeoutMs) {
     if (timeoutMs === undefined) {

package/dist/infrastructure/network/timeoutError.factory.d.ts

@@ -1,13 +1,27 @@
 /**
  * Timeout error factory functions for specific operations.
+ *
+ * Every factory accepts either an options object `{ timeoutMs, target }` or
+ * the legacy positional arguments. The positional order differs between the
+ * request/database factories (`timeoutMs, target`) and the service/lock
+ * factories (`target, timeoutMs`); the object form is recommended.
  */
 import { TimeoutError } from "./timeoutError.base.js";
+/** Arguments shared by the timeout factories. */
+export interface TimeoutFactoryOptions {
+    readonly timeoutMs?: number;
+    readonly target?: string;
+}
 /** Creates a request timeout error. */
+export declare function requestTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function requestTimeoutError(timeoutMs?: number, target?: string): TimeoutError;
 /** Creates a database timeout error. */
+export declare function databaseTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function databaseTimeoutError(timeoutMs?: number, target?: string): TimeoutError;
 /** Creates an external-service timeout error. */
+export declare function serviceTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function serviceTimeoutError(target?: string, timeoutMs?: number): TimeoutError;
 /** Creates a lock acquisition timeout error. */
+export declare function lockTimeoutError(options?: TimeoutFactoryOptions): TimeoutError;
 export declare function lockTimeoutError(target?: string, timeoutMs?: number): TimeoutError;
 //# sourceMappingURL=timeoutError.factory.d.ts.map

package/dist/infrastructure/network/timeoutError.factory.js

@@ -1,11 +1,25 @@
 /**
  * Timeout error factory functions for specific operations.
+ *
+ * Every factory accepts either an options object `{ timeoutMs, target }` or
+ * the legacy positional arguments. The positional order differs between the
+ * request/database factories (`timeoutMs, target`) and the service/lock
+ * factories (`target, timeoutMs`); the object form is recommended.
  */
 import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { TimeoutError, TimeoutOperation } from "./timeoutError.base.js";
-/** Creates a request timeout error. */
-export function requestTimeoutError(timeoutMs, target) {
+function resolveTimeoutArgs(first, second, order) {
+    if (first !== undefined && typeof first === "object")
+        return first;
+    const [timeoutMs, target] = order === "timeoutFirst" ? [first, second] : [second, first];
+    return {
+        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+        ...(typeof target === "string" ? { target } : {}),
+    };
+}
+export function requestTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "timeoutFirst");
     return new TimeoutError(target ? `The request to ${target} timed out.` : "The request timed out.", {
         code: ErrorCode.TIMEOUT,
         operation: TimeoutOperation.REQUEST,
@@ -13,11 +27,9 @@ export function requestTimeoutError(timeoutMs, target) {
         target,
     });
 }
-/** Creates a database timeout error. */
-export function databaseTimeoutError(timeoutMs, target) {
-    return new TimeoutError(target
-        ? `The database operation on ${target} timed out.`
-        : "The database operation timed out.", {
+export function databaseTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "timeoutFirst");
+    return new TimeoutError("The database operation timed out.", {
         code: ErrorCode.DATABASE_TIMEOUT,
         category: ErrorCategory.DATABASE,
         operation: TimeoutOperation.DATABASE,
@@ -25,11 +37,9 @@ export function databaseTimeoutError(timeoutMs, target) {
         target,
     });
 }
-/** Creates an external-service timeout error. */
-export function serviceTimeoutError(target, timeoutMs) {
-    return new TimeoutError(target
-        ? `The request to ${target} timed out.`
-        : "The external service request timed out.", {
+export function serviceTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "targetFirst");
+    return new TimeoutError("The external service request timed out.", {
         code: ErrorCode.EXTERNAL_SERVICE_TIMEOUT,
         category: ErrorCategory.EXTERNAL_SERVICE,
         operation: TimeoutOperation.EXTERNAL_SERVICE,
@@ -37,11 +47,9 @@ export function serviceTimeoutError(target, timeoutMs) {
         target,
     });
 }
-/** Creates a lock acquisition timeout error. */
-export function lockTimeoutError(target, timeoutMs) {
-    return new TimeoutError(target
-        ? `Timed out while waiting for lock "${target}".`
-        : "Timed out while waiting for a lock.", {
+export function lockTimeoutError(first, second) {
+    const { timeoutMs, target } = resolveTimeoutArgs(first, second, "targetFirst");
+    return new TimeoutError("Timed out while waiting for a lock.", {
         code: ErrorCode.LOCK_TIMEOUT,
         category: ErrorCategory.CONFLICT,
         operation: TimeoutOperation.LOCK,

package/dist/infrastructure/service/externalService.error.d.ts

@@ -3,5 +3,5 @@
  */
 export { ExternalServiceError, createExternalServiceError, isExternalServiceError, } from "./externalServiceError.base.js";
 export type { ExternalServiceErrorOptions } from "./externalServiceError.base.js";
-export { externalServiceTimeoutError, externalServiceUnavailable, } from "./externalServiceError.factory.js";
+export { externalServiceTimeoutError, externalServiceUnavailable, externalServiceUnavailableError, } from "./externalServiceError.factory.js";
 //# sourceMappingURL=externalService.error.d.ts.map

package/dist/infrastructure/service/externalService.error.js

@@ -2,5 +2,5 @@
  * External service error classes — re-exports from focused files.
  */
 export { ExternalServiceError, createExternalServiceError, isExternalServiceError, } from "./externalServiceError.base.js";
-export { externalServiceTimeoutError, externalServiceUnavailable, } from "./externalServiceError.factory.js";
+export { externalServiceTimeoutError, externalServiceUnavailable, externalServiceUnavailableError, } from "./externalServiceError.factory.js";
 //# sourceMappingURL=externalService.error.js.map

package/dist/infrastructure/service/externalServiceError.base.d.ts

@@ -42,4 +42,12 @@ export declare class ExternalServiceError extends BaseError {
 export declare function createExternalServiceError(service: string, message?: string, options?: Omit<ExternalServiceErrorOptions, "service">): ExternalServiceError;
 /** Determines whether an unknown value is an ExternalServiceError. */
 export declare function isExternalServiceError(value: unknown): value is ExternalServiceError;
+/**
+ * Maps a remote response status into an appropriate local HTTP status.
+ *
+ * An upstream failure is our problem, not our caller's: every upstream status
+ * maps to 502 Bad Gateway except 429, which is passed through so that callers
+ * can back off. Pass an explicit `statusCode` option to override.
+ */
+export declare function mapResponseStatus(responseStatus: number | undefined): number;
 //# sourceMappingURL=externalServiceError.base.d.ts.map

package/dist/infrastructure/service/externalServiceError.base.js

@@ -61,20 +61,17 @@ export function createExternalServiceError(service, message = "An external servi
 export function isExternalServiceError(value) {
     return value instanceof ExternalServiceError;
 }
-/** Maps a remote response status into an appropriate local HTTP status. */
-function mapResponseStatus(responseStatus) {
-    if (responseStatus === undefined) {
-        return 502;
-    }
-    if (responseStatus >= 500) {
-        return 502;
-    }
+/**
+ * Maps a remote response status into an appropriate local HTTP status.
+ *
+ * An upstream failure is our problem, not our caller's: every upstream status
+ * maps to 502 Bad Gateway except 429, which is passed through so that callers
+ * can back off. Pass an explicit `statusCode` option to override.
+ */
+export function mapResponseStatus(responseStatus) {
     if (responseStatus === 429) {
         return 429;
     }
-    if (responseStatus >= 400) {
-        return responseStatus;
-    }
     return 502;
 }
 //# sourceMappingURL=externalServiceError.base.js.map

package/dist/infrastructure/service/externalServiceError.factory.d.ts

@@ -5,5 +5,7 @@ import { ExternalServiceError } from "./externalServiceError.base.js";
 /** Creates an external service timeout error. */
 export declare function externalServiceTimeoutError(service: string, operation?: string): ExternalServiceError;
 /** Creates an external service unavailable error. */
-export declare function externalServiceUnavailable(service: string, operation?: string): ExternalServiceError;
+export declare function externalServiceUnavailableError(service: string, operation?: string): ExternalServiceError;
+/** @deprecated Use `externalServiceUnavailableError`. */
+export declare const externalServiceUnavailable: typeof externalServiceUnavailableError;
 //# sourceMappingURL=externalServiceError.factory.d.ts.map

package/dist/infrastructure/service/externalServiceError.factory.js

@@ -18,7 +18,7 @@ export function externalServiceTimeoutError(service, operation) {
     });
 }
 /** Creates an external service unavailable error. */
-export function externalServiceUnavailable(service, operation) {
+export function externalServiceUnavailableError(service, operation) {
     return new ExternalServiceError(`${service} is currently unavailable.`, {
         service,
         operation,
@@ -29,4 +29,6 @@ export function externalServiceUnavailable(service, operation) {
         expose: false,
     });
 }
+/** @deprecated Use `externalServiceUnavailableError`. */
+export const externalServiceUnavailable = externalServiceUnavailableError;
 //# sourceMappingURL=externalServiceError.factory.js.map

package/dist/infrastructure/storage/databaseError.factory.js

@@ -31,7 +31,7 @@ export function databaseTransactionError(message = "The database transaction fai
 export function databaseMigrationError(message = "The database migration failed.", options = {}) {
     return new DatabaseError(message, {
         ...options,
-        code: ErrorCode.DATABASE,
+        code: ErrorCode.DATABASE_MIGRATION,
         operation: DatabaseOperation.MIGRATION,
     });
 }

package/dist/infrastructure/storage/storageError.factory.js

@@ -2,7 +2,7 @@
  * Storage error factory functions.
  */
 import { ErrorCode } from "../../base/types/errorCode.type.js";
-import { StorageError, StorageOperation, } from "./storageError.base.js";
+import { StorageError, StorageOperation } from "./storageError.base.js";
 /** Creates a storage read error. */
 export function storageReadError(resource, provider, cause) {
     return new StorageError(`Failed to read "${resource}".`, {
@@ -56,7 +56,7 @@ export function storageDeleteError(resource, provider, cause) {
 /** Creates a storage not found error. */
 export function storageNotFoundError(resource, provider) {
     return new StorageError(`Resource "${resource}" was not found.`, {
-        code: ErrorCode.NOT_FOUND,
+        code: ErrorCode.STORAGE_NOT_FOUND,
         operation: StorageOperation.READ,
         provider,
         resource,

package/dist/system/cryptoError.factory.js

@@ -20,8 +20,11 @@ export function cryptoCipherError(message = "Cryptographic encryption or decrypt
     });
 }
 /** Creates a cryptographic signature error. */
-export function cryptoSignatureError(message = "Cryptographic signature verification failed.", operation = CryptoOperation.VERIFY_SIGNATURE, algorithm) {
-    return new CryptoError(message, {
+export function cryptoSignatureError(message, operation = CryptoOperation.VERIFY_SIGNATURE, algorithm) {
+    const defaultMessage = operation === CryptoOperation.SIGN
+        ? "Cryptographic signing failed."
+        : "Cryptographic signature verification failed.";
+    return new CryptoError(message ?? defaultMessage, {
         code: ErrorCode.CRYPTO_SIGNATURE,
         operation,
         algorithm,

package/dist/system/runtimeError.base.js

@@ -11,7 +11,7 @@ export class RuntimeError extends BaseError {
     constructor(message, options = {}) {
         super(message, {
             ...options,
-            code: options.code ?? ErrorCode.SYSTEM_ERROR,
+            code: options.code ?? ErrorCode.RUNTIME,
             category: options.category ?? ErrorCategory.RUNTIME,
             severity: options.severity ?? ErrorSeverity.ERROR,
             statusCode: options.statusCode ?? 500,

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

@@ -1,30 +1,64 @@
 /**
  * Centralized error normalization, serialization, and reporting service.
  */
-import { BaseError } from "../base/core/baseError.core.js";
-import type { ErrorHandlerOptions, ErrorHandlerResult, ErrorHandlerContext, NormalizedError } from "./errorHandler.types.js";
-export type { ErrorHandlerOptions, ErrorHandlerResult, ErrorHandlerContext, ErrorReporter, NormalizedError, } from "./errorHandler.types.js";
+import type { BaseError } from "../base/core/baseError.core.js";
+import type { ErrorHandlerOptions, ErrorHandlerResult, ErrorHandlerContext, NormalizedError, PublicErrorHandlerResult } from "./errorHandler.types.js";
+export type { ErrorHandlerOptions, ErrorHandlerResult, ErrorHandlerContext, ErrorReporter, ErrorReporterFailureHandler, NormalizedError, PublicErrorHandlerResult, } from "./errorHandler.types.js";
 export { createErrorHandler, normalizeError, isHandledError, } from "./errorHandler.factory.js";
 /** Centralized error normalization, serialization, and reporting service. */
 export declare class ErrorHandler {
     private readonly reporter?;
+    private readonly onReporterError?;
     private readonly defaultStatusCode;
     private readonly defaultMessage;
     private readonly includeStack;
+    private readonly publicMetadataKeys;
+    private readonly sensitiveKeyPattern;
     constructor(options?: ErrorHandlerOptions);
     /** Converts an unknown thrown value into a BaseError. */
     normalize(value: unknown): NormalizedError;
-    /** 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.
+     */
     handle(value: unknown, context?: ErrorHandlerContext): Promise<ErrorHandlerResult>;
-    /** Converts a BaseError into a safe response object. */
+    /** Handles an unknown error and returns the client-safe representation. */
+    handlePublic(value: unknown, context?: ErrorHandlerContext): Promise<PublicErrorHandlerResult>;
+    /**
+     * Converts a BaseError into the internal result object.
+     *
+     * Metadata is redacted recursively; the stack is never included.
+     */
     toResult(error: BaseError, context?: ErrorHandlerContext): ErrorHandlerResult;
+    /**
+     * 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: BaseError, context?: ErrorHandlerContext): PublicErrorHandlerResult;
     /** Reports an error without producing a response. */
     report(value: unknown, context?: ErrorHandlerContext): Promise<BaseError>;
     /** Determines whether an error should expose its message to clients. */
     shouldExpose(error: BaseError): boolean;
-    /** 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: BaseError, context?: ErrorHandlerContext): Record<string, unknown>;
-    /** Removes obviously sensitive fields from metadata before serialization. */
-    private sanitizeMetadata;
+    /**
+     * Returns the full internal representation for logging, including the
+     * (redacted) cause chain and, when `includeStack` is enabled, stack traces.
+     */
+    toLogObject(error: BaseError, context?: ErrorHandlerContext): Record<string, unknown>;
+    /** Invokes the reporter without letting its failure escape. */
+    private reportSafely;
+    /** Removes obviously sensitive fields from metadata (recursively). */
+    private redact;
 }
 //# sourceMappingURL=errorHandler.core.d.ts.map