@zudojs/errors 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -11,25 +11,46 @@ npm install @zudojs/errors
 ## Quick Start
 
 ```typescript
-import { ApplicationError, ErrorCode } from "@zudojs/errors";
+import {
+  ApplicationError,
+  ErrorCode,
+  serializePublicError,
+  toBaseError,
+} from "@zudojs/errors";
 
 throw new ApplicationError("Something went wrong", {
-  code: ErrorCode.INTERNAL_SERVER_ERROR,
+  code: ErrorCode.INTERNAL_ERROR,
   statusCode: 500,
+  metadata: { orderId: "ord_123" },
 });
+
+// Anywhere you catch: normalize, enrich, and produce a client-safe body
+try {
+  await work();
+} catch (thrown) {
+  const error = toBaseError(thrown).withMetadata({ requestId });
+  logger.error(error.toLogObject()); // stack + cause chain, for trusted logs
+  res.status(error.statusCode).json(serializePublicError(error));
+  // -> { code, message, category, statusCode } — no stack, no cause,
+  //    and no metadata unless the error is exposable (or keys are allow-listed)
+}
 ```
 
 ## Features
 
-- Base error class with code and status code support
-- Error categories (validation, authentication, authorization, etc.)
-- Error code constants
-- Error context and metadata
-- Stack trace preservation
+- `BaseError` with stable `code`, `category`, `severity`, `statusCode`, `expose`, `isOperational`, deep-frozen `metadata` and `cause`
+- `ErrorCode`, `ErrorCategory` and `ErrorSeverity` enums with guards (`isErrorCode`, ...)
+- Domain, infrastructure and system error families (access, state, HTTP, database, network, container, adapter, crypto, ...) with factories and type guards
+- `withMetadata()` copies any error (including subclasses with custom constructors) with extra metadata
+- Serialization: `toJSON()`/`toLogObject()` for trusted logs (cycle-safe cause chains), `serializePublicError` / `ErrorSerializer` / `ErrorHandler.toPublicResult` for untrusted clients (recursive redaction, metadata allow-list)
+- Metadata utilities: `createErrorMetadata`, `mergeErrorMetadata`, `sanitizeErrorMetadata` (drops unsupported values) and `redactErrorMetadata` (removes secrets)
+- Normalization (`toBaseError`, `normalizeUnknownError`, `ErrorHandler.normalize`) that keeps the thrown value as `cause` and classifies unknown failures as internal, non-operational 500s
+- Error mapping registry (`ErrorMapperRegistry`, `mapErrorType`, declarative `ErrorMapping`)
+- Cross-package safe type guards (`isBaseError` recognises instances from another installed copy of the package)
 
 ## Use Cases
 
 - Consistent error handling across packages
 - HTTP status code mapping
 - Error categorization for monitoring
-- User-friendly error messages
+- User-friendly, non-leaking error responses

package/dist/base/core/baseError.core.d.ts

@@ -3,6 +3,12 @@ import { ErrorCode } from "../types/errorCode.type.js";
 import { ErrorSeverity } from "../types/errorSeverity.type.js";
 import type { ErrorMetadata } from "./errorMetadata.type.js";
 import type { BaseErrorOptions, SerializedBaseError } from "../types/baseError.type.js";
+/**
+ * Brand used to recognise BaseError instances across duplicated copies of
+ * this package (for example when two versions of `@zudojs/errors` are
+ * installed side by side and `instanceof` fails across the boundary).
+ */
+export declare const BASE_ERROR_BRAND: unique symbol;
 /**
  * Base error class shared by all Zudojs application errors.
  *
@@ -18,6 +24,8 @@ export declare class BaseError extends Error {
     readonly isOperational: boolean;
     readonly metadata: Readonly<ErrorMetadata>;
     readonly cause: unknown;
+    /** Brand marker; always `true` on BaseError instances (non-enumerable). */
+    readonly [BASE_ERROR_BRAND]: true;
     constructor(message: string, options?: BaseErrorOptions);
     /** Returns whether this error is safe to expose to clients. */
     isPublic(): boolean;
@@ -25,11 +33,20 @@ export declare class BaseError extends Error {
     isOperationalError(): boolean;
     /** Returns a metadata value by key. */
     getMetadata(key: string): import("./errorMetadata.type.js").ErrorMetadataValue | undefined;
-    /** Creates a new error with additional metadata. */
+    /**
+     * Creates a copy of this error with additional metadata.
+     *
+     * The copy is produced by cloning the instance (prototype, own properties,
+     * message, stack and cause) rather than re-invoking the constructor, so it
+     * works for every subclass regardless of its constructor signature.
+     */
     withMetadata(metadata: ErrorMetadata): this;
     /**
      * Converts the error into a serializable representation.
-     * Stack traces included for trusted internal logging.
+     *
+     * Intended for trusted internal logging: includes the stack trace and the
+     * cause chain (depth-limited and cycle-safe). Use `ErrorSerializer`
+     * (`serializePublicError`) for anything sent to an untrusted client.
      */
     toJSON(): SerializedBaseError;
     /** Returns the error as a plain object for internal logging. */
@@ -37,4 +54,10 @@ export declare class BaseError extends Error {
     /** Returns a concise error description. */
     toString(): string;
 }
+/**
+ * Serializes nested Error causes while avoiding recursive failures.
+ *
+ * Cause chains are cycle-safe and truncated after `MAX_CAUSE_DEPTH` levels.
+ */
+export declare function serializeErrorCause(cause: unknown, depth?: number): SerializedBaseError | unknown;
 //# sourceMappingURL=baseError.core.d.ts.map

package/dist/base/core/baseError.core.js

@@ -2,6 +2,16 @@ import { ErrorCategory } from "../types/errorCategory.type.js";
 import { ErrorCode } from "../types/errorCode.type.js";
 import { ErrorSeverity } from "../types/errorSeverity.type.js";
 import { createErrorMetadata, serializeErrorMetadata, } from "./errorMetadata.core.js";
+/**
+ * Brand used to recognise BaseError instances across duplicated copies of
+ * this package (for example when two versions of `@zudojs/errors` are
+ * installed side by side and `instanceof` fails across the boundary).
+ */
+export const BASE_ERROR_BRAND = Symbol.for("@zudojs/errors.BaseError");
+/** Maximum depth of cause chains included in serialized output. */
+const MAX_CAUSE_DEPTH = 8;
+/** Errors currently being serialized (guards against cyclic cause chains). */
+const serializing = new WeakSet();
 /**
  * Base error class shared by all Zudojs application errors.
  *
@@ -28,6 +38,12 @@ export class BaseError extends Error {
         this.isOperational = options.isOperational ?? true;
         this.metadata = createErrorMetadata(options.metadata);
         this.cause = options.cause;
+        Object.defineProperty(this, BASE_ERROR_BRAND, {
+            value: true,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
         Object.setPrototypeOf(this, new.target.prototype);
     }
     /** Returns whether this error is safe to expose to clients. */
@@ -40,28 +56,52 @@ export class BaseError extends Error {
     }
     /** Returns a metadata value by key. */
     getMetadata(key) {
+        if (!Object.prototype.hasOwnProperty.call(this.metadata, key))
+            return undefined;
         return this.metadata[key];
     }
-    /** Creates a new error with additional metadata. */
+    /**
+     * Creates a copy of this error with additional metadata.
+     *
+     * The copy is produced by cloning the instance (prototype, own properties,
+     * message, stack and cause) rather than re-invoking the constructor, so it
+     * works for every subclass regardless of its constructor signature.
+     */
     withMetadata(metadata) {
-        const ErrorConstructor = this.constructor;
-        return new ErrorConstructor(this.message, {
-            code: this.code,
-            category: this.category,
-            severity: this.severity,
-            statusCode: this.statusCode,
-            expose: this.expose,
-            isOperational: this.isOperational,
-            metadata: { ...this.metadata, ...metadata },
-            cause: this.cause,
+        const clone = Object.create(Object.getPrototypeOf(this));
+        for (const key of Reflect.ownKeys(this)) {
+            if (key === "stack")
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(this, key);
+            if (descriptor === undefined)
+                continue;
+            Object.defineProperty(clone, key, descriptor);
+        }
+        // V8 exposes `stack` as an accessor bound to the original object; copy
+        // its current value as a plain data property instead.
+        Object.defineProperty(clone, "stack", {
+            value: this.stack,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+        Object.defineProperty(clone, "metadata", {
+            value: createErrorMetadata({ ...this.metadata, ...metadata }),
+            enumerable: true,
+            writable: false,
+            configurable: true,
         });
+        return clone;
     }
     /**
      * Converts the error into a serializable representation.
-     * Stack traces included for trusted internal logging.
+     *
+     * Intended for trusted internal logging: includes the stack trace and the
+     * cause chain (depth-limited and cycle-safe). Use `ErrorSerializer`
+     * (`serializePublicError`) for anything sent to an untrusted client.
      */
     toJSON() {
-        return {
+        const base = {
             name: this.name,
             message: this.message,
             code: this.code,
@@ -72,10 +112,19 @@ export class BaseError extends Error {
             isOperational: this.isOperational,
             metadata: serializeErrorMetadata(this.metadata),
             ...(this.stack ? { stack: this.stack } : {}),
-            ...(this.cause !== undefined
-                ? { cause: serializeErrorCause(this.cause) }
-                : {}),
         };
+        if (this.cause === undefined)
+            return base;
+        if (serializing.has(this)) {
+            return { ...base, cause: "[Circular]" };
+        }
+        serializing.add(this);
+        try {
+            return { ...base, cause: serializeErrorCause(this.cause, 1) };
+        }
+        finally {
+            serializing.delete(this);
+        }
     }
     /** Returns the error as a plain object for internal logging. */
     toLogObject() {
@@ -99,16 +148,39 @@ function normalizeStatusCode(statusCode) {
 }
 /**
  * Serializes nested Error causes while avoiding recursive failures.
+ *
+ * Cause chains are cycle-safe and truncated after `MAX_CAUSE_DEPTH` levels.
  */
-function serializeErrorCause(cause) {
-    if (cause instanceof BaseError)
+export function serializeErrorCause(cause, depth = 1) {
+    if (depth > MAX_CAUSE_DEPTH)
+        return "[MaxDepth]";
+    if (cause instanceof BaseError) {
+        if (serializing.has(cause))
+            return "[Circular]";
         return cause.toJSON();
+    }
     if (cause instanceof Error) {
-        return {
-            name: cause.name,
-            message: cause.message,
-            ...(cause.stack ? { stack: cause.stack } : {}),
-        };
+        if (serializing.has(cause))
+            return "[Circular]";
+        serializing.add(cause);
+        try {
+            return {
+                name: cause.name,
+                message: cause.message,
+                ...(cause.stack ? { stack: cause.stack } : {}),
+                ...(cause.cause !== undefined
+                    ? { cause: serializeErrorCause(cause.cause, depth + 1) }
+                    : {}),
+            };
+        }
+        finally {
+            serializing.delete(cause);
+        }
+    }
+    if (cause !== null && typeof cause === "object") {
+        if (serializing.has(cause))
+            return "[Circular]";
+        return cause;
     }
     return cause;
 }

package/dist/base/core/errorMetadata.core.d.ts

@@ -1,9 +1,29 @@
 import type { ErrorMetadata, ErrorMetadataValue } from "./errorMetadata.type.js";
-/** Creates an immutable metadata object. */
+/** Maximum nesting depth accepted for metadata values. */
+export declare const MAX_METADATA_DEPTH = 32;
+/**
+ * Default pattern used to recognise metadata keys that carry secrets.
+ *
+ * Matching is case-insensitive and applies to the whole key, so
+ * `Authorization`, `x-api-key`, `headers.cookie` and `refreshToken` all match.
+ */
+export declare const SENSITIVE_METADATA_KEY_PATTERN: RegExp;
+/** Placeholder written in place of redacted values. */
+export declare const REDACTED_METADATA_VALUE = "[REDACTED]";
+/** Returns whether a metadata key should never be accepted. */
+export declare function isForbiddenMetadataKey(key: string): boolean;
+/** Returns whether a metadata key looks like it carries a secret. */
+export declare function isSensitiveMetadataKey(key: string, pattern?: RegExp): boolean;
+/**
+ * Creates an immutable metadata object.
+ *
+ * The result is a deep-frozen copy: later mutation of the caller's object
+ * does not affect the metadata, and nested values cannot be mutated.
+ */
 export declare function createErrorMetadata(metadata: ErrorMetadata | undefined | null): Readonly<ErrorMetadata>;
 /** Merges multiple metadata objects. Later metadata objects override earlier values. */
 export declare function mergeErrorMetadata(...metadata: readonly (ErrorMetadata | undefined | null)[]): Readonly<ErrorMetadata>;
-/** Reads a metadata property. */
+/** Reads a metadata property (own properties only). */
 export declare function getErrorMetadataValue(metadata: ErrorMetadata | undefined | null, key: string): ErrorMetadataValue | undefined;
 /** Determines whether metadata contains a property. */
 export declare function hasErrorMetadata(metadata: ErrorMetadata | undefined | null, key: string): boolean;
@@ -13,12 +33,49 @@ export declare function omitErrorMetadata(metadata: ErrorMetadata | undefined |
 export declare function pickErrorMetadata(metadata: ErrorMetadata | undefined | null, keys: readonly string[]): Readonly<ErrorMetadata>;
 /** Converts metadata into a plain JSON-safe object. */
 export declare function serializeErrorMetadata(metadata: ErrorMetadata | undefined | null): Record<string, ErrorMetadataValue>;
-/** Determines whether an arbitrary value is valid error metadata. */
+/**
+ * Determines whether an arbitrary value is valid error metadata.
+ *
+ * Only JSON-compatible primitives, arrays and plain objects qualify;
+ * class instances, Maps, Sets, Dates, cyclic and excessively deep values
+ * are rejected.
+ */
 export declare function isErrorMetadataValue(value: unknown): value is ErrorMetadataValue;
+/** Options for `sanitizeErrorMetadata`. */
+export interface SanitizeErrorMetadataOptions {
+    /**
+     * Also redact values whose key looks sensitive (see `redactErrorMetadata`).
+     * Defaults to `false`.
+     */
+    readonly redact?: boolean;
+    /** Pattern used to detect sensitive keys when `redact` is enabled. */
+    readonly sensitiveKeyPattern?: RegExp;
+}
 /**
  * Sanitizes arbitrary metadata by removing unsupported values.
  *
- * This is useful before serializing unknown data into logs or API responses.
+ * Drops functions, symbols, class instances and cyclic references, skips
+ * prototype-pollution keys and truncates excessive nesting. It does NOT
+ * remove secrets unless `redact: true` is passed; use `redactErrorMetadata`
+ * for that.
+ */
+export declare function sanitizeErrorMetadata(metadata: Record<string, unknown> | undefined | null, options?: SanitizeErrorMetadataOptions): Readonly<ErrorMetadata>;
+/** Options for `redactErrorMetadata`. */
+export interface RedactErrorMetadataOptions {
+    /** Pattern matched (case-insensitively) against every key at every depth. */
+    readonly sensitiveKeyPattern?: RegExp;
+    /** Additional exact keys to redact. */
+    readonly keys?: readonly string[];
+    /** Replacement value. Defaults to `"[REDACTED]"`. */
+    readonly replacement?: string;
+}
+/**
+ * Redacts sensitive values from metadata.
+ *
+ * Walks the metadata recursively and replaces the value of every key that
+ * matches the sensitive-key pattern (case-insensitive) or one of the extra
+ * `keys` with `"[REDACTED]"`. Unsupported values are dropped as in
+ * `sanitizeErrorMetadata`.
  */
-export declare function sanitizeErrorMetadata(metadata: Record<string, unknown> | undefined | null): Readonly<ErrorMetadata>;
+export declare function redactErrorMetadata(metadata: Record<string, unknown> | undefined | null, options?: RedactErrorMetadataOptions): Readonly<ErrorMetadata>;
 //# sourceMappingURL=errorMetadata.core.d.ts.map