@zudojs/errors 0.1.1 → 1.0.0

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

package/dist/utils/errorSerializer.core.js

@@ -2,6 +2,7 @@
  * Converts errors into safe, predictable serialized structures.
  */
 import { BaseError } from "../base/core/baseError.core.js";
+import { pickErrorMetadata, redactErrorMetadata, } from "../base/core/errorMetadata.core.js";
 import { normalizeUnknownError } from "./errorSerializer.factory.js";
 export { createErrorSerializer, serializeError, serializePublicError, normalizeUnknownError, } from "./errorSerializer.factory.js";
 /** Converts errors into safe, predictable serialized structures. */
@@ -11,41 +12,41 @@ export class ErrorSerializer {
     includeMetadata;
     safeMessage;
     redactSensitiveData;
+    sensitiveKeyPattern;
+    publicMetadataKeys;
     constructor(options = {}) {
         this.includeStack = options.includeStack ?? false;
         this.includeCause = options.includeCause ?? false;
         this.includeMetadata = options.includeMetadata ?? true;
         this.safeMessage = options.safeMessage ?? "An unexpected error occurred.";
         this.redactSensitiveData = options.redactSensitiveData ?? true;
+        this.sensitiveKeyPattern = options.sensitiveKeyPattern;
+        this.publicMetadataKeys = options.publicMetadataKeys;
     }
-    /** 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) {
-        const serialized = error.toJSON();
-        const result = {
-            ...serialized,
-            ...(this.includeStack ? {} : { stack: undefined }),
-            ...(this.includeCause ? {} : { cause: undefined }),
-            ...(this.includeMetadata ? {} : { metadata: {} }),
-        };
-        if (this.redactSensitiveData && result.metadata) {
-            return {
-                ...result,
-                metadata: this.redactMetadata(result.metadata),
-            };
-        }
-        return result;
+        return this.serializeLevel(error.toJSON());
     }
-    /** 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) {
-        const metadata = this.includeMetadata
-            ? this.redactMetadata(error.metadata)
-            : undefined;
+        const metadata = this.publicMetadata(error);
         return {
             code: error.code,
             message: error.expose ? error.message : this.safeMessage,
             category: error.category,
             statusCode: error.statusCode,
-            ...(metadata && Object.keys(metadata).length > 0 ? { metadata } : {}),
+            ...(metadata !== undefined ? { metadata } : {}),
         };
     }
     /** Serializes an unknown thrown value. */
@@ -56,27 +57,74 @@ export class ErrorSerializer {
     serializeUnknownPublic(value) {
         return this.serializePublic(normalizeUnknownError(value));
     }
-    /** Removes commonly sensitive metadata fields. */
-    redactMetadata(metadata) {
-        const sensitiveKeys = new Set([
-            "password",
-            "passcode",
-            "token",
-            "accessToken",
-            "refreshToken",
-            "authorization",
-            "cookie",
-            "secret",
-            "privateKey",
-            "apiKey",
-            "credential",
-            "clientSecret",
-        ]);
-        const result = {};
-        for (const [key, value] of Object.entries(metadata)) {
-            result[key] = sensitiveKeys.has(key) ? "[REDACTED]" : value;
-        }
+    /** Applies the serializer options to one level of a serialized error. */
+    serializeLevel(serialized) {
+        const { stack, cause, metadata, ...rest } = serialized;
+        const result = {
+            ...rest,
+            metadata: this.includeMetadata
+                ? this.redactSensitiveData
+                    ? this.redactMetadata(metadata)
+                    : metadata
+                : {},
+            ...(this.includeStack && stack !== undefined ? { stack } : {}),
+            ...(this.includeCause && cause !== undefined
+                ? { cause: this.serializeCause(cause) }
+                : {}),
+        };
         return result;
     }
+    /** Applies the serializer options recursively to a serialized cause. */
+    serializeCause(cause) {
+        if (cause === null || typeof cause !== "object")
+            return cause;
+        if (Array.isArray(cause))
+            return cause;
+        const record = cause;
+        if (isSerializedBaseError(record)) {
+            return this.serializeLevel(record);
+        }
+        // Native error shape: { name, message, stack?, cause? }
+        const { stack, cause: nested, ...rest } = record;
+        return {
+            ...rest,
+            ...(this.includeStack && stack !== undefined ? { stack } : {}),
+            ...(nested !== undefined ? { cause: this.serializeCause(nested) } : {}),
+        };
+    }
+    /** Computes the metadata allowed in a public response. */
+    publicMetadata(error) {
+        if (!this.includeMetadata)
+            return undefined;
+        let metadata;
+        if (this.publicMetadataKeys !== undefined) {
+            metadata = pickErrorMetadata(error.metadata, this.publicMetadataKeys);
+        }
+        else if (error.expose) {
+            metadata = error.metadata;
+        }
+        else {
+            return undefined;
+        }
+        const redacted = this.redactSensitiveData
+            ? this.redactMetadata(metadata)
+            : metadata;
+        return Object.keys(redacted).length > 0 ? redacted : undefined;
+    }
+    /** Removes commonly sensitive metadata fields (recursively). */
+    redactMetadata(metadata) {
+        return redactErrorMetadata(metadata, {
+            sensitiveKeyPattern: this.sensitiveKeyPattern,
+        });
+    }
+}
+/** Structural check for a serialized BaseError (used on nested causes). */
+function isSerializedBaseError(value) {
+    return (typeof value.code === "string" &&
+        typeof value.category === "string" &&
+        typeof value.severity === "string" &&
+        typeof value.statusCode === "number" &&
+        typeof value.metadata === "object" &&
+        value.metadata !== null);
 }
 //# sourceMappingURL=errorSerializer.core.js.map

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

@@ -1,7 +1,7 @@
 /**
  * Error serializer factory and utility functions.
  */
-import { BaseError } from "../base/core/baseError.core.js";
+import type { BaseError } from "../base/core/baseError.core.js";
 import { ErrorSerializer } from "./errorSerializer.core.js";
 import type { ErrorSerializerOptions, PublicErrorResponse, InternalErrorResponse } from "./errorSerializer.types.js";
 export type { ErrorSerializerOptions, PublicErrorResponse, InternalErrorResponse, } from "./errorSerializer.types.js";

package/dist/utils/errorSerializer.factory.js

@@ -1,9 +1,7 @@
 /**
  * Error serializer factory and utility functions.
  */
-import { BaseError } from "../base/core/baseError.core.js";
-import { ErrorCategory } from "../base/types/errorCategory.type.js";
-import { ErrorSeverity } from "../base/types/errorSeverity.type.js";
+import { normalizeUnknownToBaseError } from "../base/utils/baseError.utils.js";
 import { ErrorSerializer } from "./errorSerializer.core.js";
 /** Creates an ErrorSerializer instance. */
 export function createErrorSerializer(options = {}) {
@@ -19,28 +17,6 @@ export function serializePublicError(error, options = {}) {
 }
 /** Converts an unknown thrown value into a BaseError. */
 export function normalizeUnknownError(value) {
-    if (value instanceof BaseError) {
-        return value;
-    }
-    if (value instanceof Error) {
-        return new BaseError(value.message || "An unexpected error occurred.", {
-            code: "INTERNAL_ERROR",
-            category: ErrorCategory.SYSTEM,
-            severity: ErrorSeverity.ERROR,
-            statusCode: 500,
-            expose: false,
-            isOperational: false,
-            cause: value,
-        });
-    }
-    return new BaseError("An unexpected error occurred.", {
-        code: "INTERNAL_ERROR",
-        category: ErrorCategory.SYSTEM,
-        severity: ErrorSeverity.ERROR,
-        statusCode: 500,
-        expose: false,
-        isOperational: false,
-        metadata: { originalType: typeof value },
-    });
+    return normalizeUnknownToBaseError(value);
 }
 //# sourceMappingURL=errorSerializer.factory.js.map

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

@@ -5,16 +5,26 @@ import type { SerializedBaseError } from "../base/types/baseError.type.js";
 import { ErrorCategory } from "../base/types/errorCategory.type.js";
 /** Options controlling error serialization. */
 export interface ErrorSerializerOptions {
-    /** Include the stack trace in the serialized result. Defaults to false. */
+    /** Include the stack trace (at every level of the cause chain). Defaults to false. */
     readonly includeStack?: boolean;
-    /** Include the error cause. Defaults to false. */
+    /** Include the error cause chain. Defaults to false. */
     readonly includeCause?: boolean;
-    /** Include internal metadata. Defaults to true for internal serialization. */
+    /** Include metadata in internal serialization. Defaults to true. */
     readonly includeMetadata?: boolean;
     /** Replace non-exposable error messages with a safe message. */
     readonly safeMessage?: string;
-    /** Remove sensitive metadata values. */
+    /** Redact sensitive metadata values (recursively, at every level). Defaults to true. */
     readonly redactSensitiveData?: boolean;
+    /** Pattern used to detect sensitive metadata keys. Defaults to the package pattern. */
+    readonly sensitiveKeyPattern?: RegExp;
+    /**
+     * Metadata keys allowed in public output.
+     *
+     * When provided, only these keys are copied into `PublicErrorResponse.metadata`
+     * (for exposed and non-exposed errors alike). When omitted, metadata is only
+     * included for errors with `expose: true`, and never for non-exposed errors.
+     */
+    readonly publicMetadataKeys?: readonly string[];
 }
 /** Public error representation suitable for an API response. */
 export interface PublicErrorResponse {

package/dist/utils/errorUtils.extraction.js

@@ -1,6 +1,7 @@
 /**
  * Error extraction utilities — message, name, stack, root cause.
  */
+import { isBaseError } from "../base/utils/baseError.utils.js";
 import { BaseError } from "../base/core/baseError.core.js";
 import { isErrorLike } from "./errorUtils.typeCheck.js";
 /** Returns the message from an unknown thrown value. */
@@ -56,7 +57,7 @@ export function getRootBaseError(value) {
     const visited = new Set();
     while (current !== undefined && current !== null && !visited.has(current)) {
         visited.add(current);
-        if (current instanceof BaseError) {
+        if (isBaseError(current)) {
             result = current;
         }
         if (current instanceof Error && "cause" in current) {
@@ -77,7 +78,7 @@ export function getErrorDiagnostics(value) {
     if (stack !== undefined) {
         diagnostics.stack = stack;
     }
-    if (value instanceof BaseError) {
+    if (isBaseError(value)) {
         diagnostics.code = value.code;
         diagnostics.category = value.category;
         diagnostics.severity = value.severity;

package/dist/utils/errorUtils.transform.d.ts

@@ -1,7 +1,7 @@
 /**
  * Error transformation utilities — toError, withErrorContext, tryCatch, normalize.
  */
-import { BaseError } from "../base/core/baseError.core.js";
+import type { BaseError } from "../base/core/baseError.core.js";
 /** Safely converts an unknown thrown value into an Error instance. */
 export declare function toError(value: unknown, fallback?: string): Error;
 /** Adds context to an Error while preserving the original error as its cause. */

package/dist/utils/errorUtils.transform.js

@@ -1,9 +1,7 @@
 /**
  * Error transformation utilities — toError, withErrorContext, tryCatch, normalize.
  */
-import { BaseError } from "../base/core/baseError.core.js";
-import { ErrorCategory } from "../base/types/errorCategory.type.js";
-import { ErrorSeverity } from "../base/types/errorSeverity.type.js";
+import { normalizeUnknownToBaseError } from "../base/utils/baseError.utils.js";
 import { getErrorMessage } from "./errorUtils.extraction.js";
 /** Safely converts an unknown thrown value into an Error instance. */
 export function toError(value, fallback = "An unexpected error occurred.") {
@@ -37,28 +35,6 @@ export async function tryCatchAsync(operation) {
 }
 /** Converts an unknown thrown value into a BaseError. */
 export function normalizeToBaseError(value) {
-    if (value instanceof BaseError) {
-        return value;
-    }
-    if (value instanceof Error) {
-        return new BaseError(value.message || "An unexpected error occurred.", {
-            code: "INTERNAL_ERROR",
-            category: ErrorCategory.SYSTEM,
-            severity: ErrorSeverity.ERROR,
-            statusCode: 500,
-            expose: false,
-            isOperational: false,
-            cause: value,
-        });
-    }
-    return new BaseError(getErrorMessage(value), {
-        code: "INTERNAL_ERROR",
-        category: ErrorCategory.SYSTEM,
-        severity: ErrorSeverity.ERROR,
-        statusCode: 500,
-        expose: false,
-        isOperational: false,
-        metadata: { originalType: typeof value },
-    });
+    return normalizeUnknownToBaseError(value);
 }
 //# sourceMappingURL=errorUtils.transform.js.map

package/dist/utils/errorUtils.typeCheck.js

@@ -1,7 +1,7 @@
 /**
  * Error type-checking utilities.
  */
-import { BaseError } from "../base/core/baseError.core.js";
+import { isBaseError } from "../base/utils/baseError.utils.js";
 import { ErrorCategory } from "../base/types/errorCategory.type.js";
 import { ErrorSeverity } from "../base/types/errorSeverity.type.js";
 /** Type guard for unknown error-like values. */
@@ -13,31 +13,31 @@ export function isErrorLike(value) {
 }
 /** Returns whether an error is operational. */
 export function isOperationalError(value) {
-    return value instanceof BaseError && value.isOperational;
+    return isBaseError(value) && value.isOperational;
 }
 /** Returns whether an error is safe to expose to clients. */
 export function isExposableError(value) {
-    return value instanceof BaseError && value.expose;
+    return isBaseError(value) && value.expose;
 }
 /** Returns whether an error represents a server-side failure. */
 export function isServerError(value) {
-    if (value instanceof BaseError) {
+    if (isBaseError(value)) {
         return value.statusCode >= 500;
     }
     return true;
 }
 /** Returns whether an error represents a client-side failure. */
 export function isClientError(value) {
-    return (value instanceof BaseError &&
+    return (isBaseError(value) &&
         value.statusCode >= 400 &&
         value.statusCode < 500);
 }
 /** Returns whether an error belongs to a category. */
 export function hasErrorCategory(value, category) {
-    return value instanceof BaseError && value.category === category;
+    return isBaseError(value) && value.category === category;
 }
 /** Returns whether an error has a specific severity. */
 export function hasErrorSeverity(value, severity) {
-    return value instanceof BaseError && value.severity === severity;
+    return isBaseError(value) && value.severity === severity;
 }
 //# sourceMappingURL=errorUtils.typeCheck.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/errors",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Shared error base class, error codes, and error handling utilities for the Zudojs framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,16 +13,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "!dist/.tsbuildinfo"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
+  "sideEffects": false,
   "dependencies": {},
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -37,8 +37,19 @@
     "error-handling"
   ],
   "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "bugs": {
+    "url": "https://github.com/oyinlola-tech/zudo/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/oyinlola-tech/zudo"
+    "url": "https://github.com/oyinlola-tech/zudo",
+    "directory": "packages/errors"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
-}
+}