@zudojs/errors 0.1.1 → 1.0.1

package/dist/base/core/errorMetadata.core.js

@@ -1,8 +1,133 @@
-/** Creates an immutable metadata object. */
+/** Maximum nesting depth accepted for metadata values. */
+export const MAX_METADATA_DEPTH = 32;
+/** Keys that are never copied into metadata (prototype pollution vectors). */
+const FORBIDDEN_METADATA_KEYS = new Set([
+    "__proto__",
+    "constructor",
+    "prototype",
+]);
+/**
+ * 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 const SENSITIVE_METADATA_KEY_PATTERN = /pass(word|code|phrase|wd)?|secret|token|jwt|bearer|private[_-]?key|api[_-]?key|x-api-key|auth(orization|entication)?|cookie|session|credential|client[_-]?secret|ssn|social[_-]?security|card[_-]?number|cvv|cvc|pin\b/i;
+/** Placeholder written in place of redacted values. */
+export const REDACTED_METADATA_VALUE = "[REDACTED]";
+/** Returns whether a metadata key should never be accepted. */
+export function isForbiddenMetadataKey(key) {
+    return FORBIDDEN_METADATA_KEYS.has(key);
+}
+/**
+ * Returns a copy of `pattern` without the `g` and `y` flags.
+ *
+ * Those flags make `RegExp.prototype.test` advance `lastIndex`, so a shared
+ * sensitive-key pattern would redact a key on one call and let the same key
+ * through on the next. Every key check in this module goes through here.
+ */
+function statelessPattern(pattern) {
+    if (!pattern.global && !pattern.sticky)
+        return pattern;
+    return new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+}
+/** Returns whether a metadata key looks like it carries a secret. */
+export function isSensitiveMetadataKey(key, pattern = SENSITIVE_METADATA_KEY_PATTERN) {
+    return statelessPattern(pattern).test(key);
+}
+/** Returns whether a value is a plain object (Object.prototype or null prototype). */
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * Deep-clones and deep-freezes a metadata value.
+ *
+ * - Skips forbidden keys (`__proto__`, `constructor`, `prototype`).
+ * - Replaces cyclic references with `"[Circular]"`.
+ * - Truncates values deeper than `MAX_METADATA_DEPTH` with `"[MaxDepth]"`.
+ * - Drops `undefined` entries.
+ */
+function cloneValue(value, seen, depth) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value !== "object")
+        return String(value);
+    if (depth > MAX_METADATA_DEPTH)
+        return "[MaxDepth]";
+    if (seen.has(value))
+        return "[Circular]";
+    if (value instanceof Date)
+        return value.toISOString();
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const result = [];
+            for (const entry of value) {
+                const cloned = cloneValue(entry, seen, depth + 1);
+                result.push(cloned === undefined ? null : cloned);
+            }
+            return Object.freeze(result);
+        }
+        if (value instanceof Map) {
+            const result = {};
+            for (const [key, entry] of value) {
+                const stringKey = String(key);
+                if (isForbiddenMetadataKey(stringKey))
+                    continue;
+                const cloned = cloneValue(entry, seen, depth + 1);
+                if (cloned !== undefined)
+                    result[stringKey] = cloned;
+            }
+            return Object.freeze(result);
+        }
+        if (value instanceof Set) {
+            return cloneValue([...value], seen, depth);
+        }
+        if (value instanceof Error) {
+            return Object.freeze({ name: value.name, message: value.message });
+        }
+        const result = {};
+        for (const key of Object.keys(value)) {
+            if (isForbiddenMetadataKey(key))
+                continue;
+            const cloned = cloneValue(value[key], seen, depth + 1);
+            if (cloned !== undefined)
+                result[key] = cloned;
+        }
+        return Object.freeze(result);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Clones an entire metadata object. */
+function cloneMetadata(metadata) {
+    const cloned = cloneValue(metadata, new WeakSet(), 0);
+    if (cloned === undefined || cloned === null || typeof cloned !== "object")
+        return {};
+    return { ...cloned };
+}
+/**
+ * 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 function createErrorMetadata(metadata) {
     if (metadata === undefined || metadata === null)
         return Object.freeze({});
-    return Object.freeze({ ...metadata });
+    return Object.freeze(cloneMetadata(metadata));
 }
 /** Merges multiple metadata objects. Later metadata objects override earlier values. */
 export function mergeErrorMetadata(...metadata) {
@@ -10,16 +135,15 @@ export function mergeErrorMetadata(...metadata) {
     for (const current of metadata) {
         if (current === undefined || current === null)
             continue;
-        for (const [key, value] of Object.entries(current)) {
-            if (value !== undefined)
-                merged[key] = value;
+        for (const [key, value] of Object.entries(cloneMetadata(current))) {
+            merged[key] = value;
         }
     }
     return Object.freeze(merged);
 }
-/** Reads a metadata property. */
+/** Reads a metadata property (own properties only). */
 export function getErrorMetadataValue(metadata, key) {
-    if (metadata === undefined || metadata === null)
+    if (!hasErrorMetadata(metadata, key))
         return undefined;
     return metadata[key];
 }
@@ -33,7 +157,7 @@ export function hasErrorMetadata(metadata, key) {
 export function omitErrorMetadata(metadata, ...keys) {
     if (metadata === undefined || metadata === null)
         return Object.freeze({});
-    const omitted = { ...metadata };
+    const omitted = cloneMetadata(metadata);
     for (const key of keys)
         delete omitted[key];
     return Object.freeze(omitted);
@@ -42,9 +166,12 @@ export function omitErrorMetadata(metadata, ...keys) {
 export function pickErrorMetadata(metadata, keys) {
     if (metadata === undefined || metadata === null)
         return Object.freeze({});
+    const cloned = cloneMetadata(metadata);
     const selected = {};
     for (const key of keys) {
-        const value = metadata[key];
+        if (!Object.prototype.hasOwnProperty.call(cloned, key))
+            continue;
+        const value = cloned[key];
         if (value !== undefined)
             selected[key] = value;
     }
@@ -54,34 +181,176 @@ export function pickErrorMetadata(metadata, keys) {
 export function serializeErrorMetadata(metadata) {
     if (metadata === undefined || metadata === null)
         return {};
-    return { ...metadata };
+    return cloneMetadata(metadata);
 }
-/** 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 function isErrorMetadataValue(value) {
+    return isMetadataValue(value, new WeakSet(), 0);
+}
+function isMetadataValue(value, seen, depth) {
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return true;
     if (typeof value === "number")
         return Number.isFinite(value);
-    if (Array.isArray(value))
-        return value.every(isErrorMetadataValue);
-    if (typeof value === "object") {
-        return Object.values(value).every((entry) => entry === undefined || isErrorMetadataValue(entry));
+    if (typeof value !== "object")
+        return false;
+    if (depth > MAX_METADATA_DEPTH)
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.every((entry) => isMetadataValue(entry, seen, depth + 1));
+        }
+        if (!isPlainObject(value))
+            return false;
+        for (const key of Object.keys(value)) {
+            if (isForbiddenMetadataKey(key))
+                return false;
+            const entry = value[key];
+            if (entry !== undefined && !isMetadataValue(entry, seen, depth + 1))
+                return false;
+        }
+        return true;
+    }
+    finally {
+        seen.delete(value);
     }
-    return false;
 }
 /**
  * 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 function sanitizeErrorMetadata(metadata, options = {}) {
+    if (metadata === undefined || metadata === null)
+        return Object.freeze({});
+    const sanitized = sanitizeValue(metadata, new WeakSet(), 0);
+    const result = sanitized !== undefined &&
+        sanitized !== null &&
+        typeof sanitized === "object" &&
+        !Array.isArray(sanitized)
+        ? { ...sanitized }
+        : {};
+    if (options.redact) {
+        return redactErrorMetadata(result, {
+            sensitiveKeyPattern: options.sensitiveKeyPattern,
+        });
+    }
+    return Object.freeze(result);
+}
+function sanitizeValue(value, seen, depth) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "object")
+        return undefined;
+    if (depth > MAX_METADATA_DEPTH)
+        return undefined;
+    if (seen.has(value))
+        return undefined;
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const result = [];
+            for (const entry of value) {
+                const cleaned = sanitizeValue(entry, seen, depth + 1);
+                if (cleaned !== undefined)
+                    result.push(cleaned);
+            }
+            return Object.freeze(result);
+        }
+        if (!isPlainObject(value))
+            return undefined;
+        const result = {};
+        for (const key of Object.keys(value)) {
+            if (isForbiddenMetadataKey(key))
+                continue;
+            const cleaned = sanitizeValue(value[key], seen, depth + 1);
+            if (cleaned !== undefined)
+                result[key] = cleaned;
+        }
+        return Object.freeze(result);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/**
+ * 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 function sanitizeErrorMetadata(metadata) {
+export function redactErrorMetadata(metadata, options = {}) {
     if (metadata === undefined || metadata === null)
         return Object.freeze({});
-    const sanitized = {};
-    for (const [key, value] of Object.entries(metadata)) {
-        if (value !== undefined && isErrorMetadataValue(value))
-            sanitized[key] = value;
+    const pattern = statelessPattern(options.sensitiveKeyPattern ?? SENSITIVE_METADATA_KEY_PATTERN);
+    const extraKeys = new Set((options.keys ?? []).map((key) => key.toLowerCase()));
+    const replacement = options.replacement ?? REDACTED_METADATA_VALUE;
+    const isSensitive = (key) => pattern.test(key) || extraKeys.has(key.toLowerCase());
+    const redacted = redactValue(metadata, isSensitive, replacement, new WeakSet(), 0);
+    if (redacted === undefined ||
+        redacted === null ||
+        typeof redacted !== "object" ||
+        Array.isArray(redacted))
+        return Object.freeze({});
+    return Object.freeze({ ...redacted });
+}
+function redactValue(value, isSensitive, replacement, seen, depth) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "object")
+        return undefined;
+    if (depth > MAX_METADATA_DEPTH)
+        return undefined;
+    if (seen.has(value))
+        return undefined;
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const result = [];
+            for (const entry of value) {
+                const cleaned = redactValue(entry, isSensitive, replacement, seen, depth + 1);
+                if (cleaned !== undefined)
+                    result.push(cleaned);
+            }
+            return Object.freeze(result);
+        }
+        if (!isPlainObject(value))
+            return undefined;
+        const result = {};
+        for (const key of Object.keys(value)) {
+            if (isForbiddenMetadataKey(key))
+                continue;
+            if (isSensitive(key)) {
+                if (value[key] !== undefined)
+                    result[key] = replacement;
+                continue;
+            }
+            const cleaned = redactValue(value[key], isSensitive, replacement, seen, depth + 1);
+            if (cleaned !== undefined)
+                result[key] = cleaned;
+        }
+        return Object.freeze(result);
+    }
+    finally {
+        seen.delete(value);
     }
-    return Object.freeze(sanitized);
 }
 //# sourceMappingURL=errorMetadata.core.js.map

package/dist/base/types/errorCategory.helpers.js

@@ -2,10 +2,11 @@
  * Error category helper functions.
  */
 import { ErrorCategory } from "./errorCategory.enum.js";
+/** Precomputed set of every error category value. */
+const ERROR_CATEGORY_VALUES = new Set(Object.values(ErrorCategory));
 /** Determines whether a value is a valid error category. */
 export function isErrorCategory(value) {
-    return (typeof value === "string" &&
-        Object.values(ErrorCategory).includes(value));
+    return typeof value === "string" && ERROR_CATEGORY_VALUES.has(value);
 }
 /** Converts an unknown value into a valid error category. */
 export function normalizeErrorCategory(value, fallback = ErrorCategory.UNKNOWN) {

package/dist/base/types/errorCode.type.d.ts

@@ -102,6 +102,21 @@ export declare enum ErrorCode {
     RUNTIME_MANAGER = "ERR_RUNTIME_MANAGER",
     EVENT_HANDLING_FAILED = "ERR_EVENT_HANDLING_FAILED",
     EVENT_PUBLISH_FAILED = "ERR_EVENT_PUBLISH_FAILED",
+    EVENT_HANDLER_NOT_FOUND = "ERR_EVENT_HANDLER_NOT_FOUND",
+    EVENT_DUPLICATE_HANDLER = "ERR_EVENT_DUPLICATE_HANDLER",
+    EVENT_MIDDLEWARE_FAILED = "ERR_EVENT_MIDDLEWARE_FAILED",
+    EVENT_INVALID = "ERR_EVENT_INVALID",
+    EVENT_TYPE_NOT_FOUND = "ERR_EVENT_TYPE_NOT_FOUND",
+    EVENT_DUPLICATE_DEFINITION = "ERR_EVENT_DUPLICATE_DEFINITION",
+    EVENT_DEFINITION_NOT_FOUND = "ERR_EVENT_DEFINITION_NOT_FOUND",
+    EVENT_DISPATCH_ABORTED = "ERR_EVENT_DISPATCH_ABORTED",
+    EVENT_EMITTER_DISPOSED = "ERR_EVENT_EMITTER_DISPOSED",
+    EVENT_REGISTRY_DISPOSED = "ERR_EVENT_REGISTRY_DISPOSED",
+    EVENT_BUS_DISPOSED = "ERR_EVENT_BUS_DISPOSED",
+    EVENT_SUBSCRIPTION_CLOSED = "ERR_EVENT_SUBSCRIPTION_CLOSED",
+    EVENT_TIMEOUT = "ERR_EVENT_TIMEOUT",
+    EVENT_SERIALIZATION_FAILED = "ERR_EVENT_SERIALIZATION_FAILED",
+    EVENT_DESERIALIZATION_FAILED = "ERR_EVENT_DESERIALIZATION_FAILED",
     MESSAGE_HANDLER_NOT_FOUND = "ERR_MESSAGE_HANDLER_NOT_FOUND",
     MESSAGE_DISPATCH_FAILED = "ERR_MESSAGE_DISPATCH_FAILED",
     MESSAGE_VALIDATION_FAILED = "ERR_MESSAGE_VALIDATION_FAILED",
@@ -109,9 +124,14 @@ export declare enum ErrorCode {
     MESSAGE_TIMEOUT = "ERR_MESSAGE_TIMEOUT",
     MESSAGE_ABORTED = "ERR_MESSAGE_ABORTED",
     MESSAGE_INVALID = "ERR_MESSAGE_INVALID",
+    MESSAGE_BUS_DISPOSED = "ERR_MESSAGE_BUS_DISPOSED",
+    /** @deprecated Use `MESSAGE_BUS_DISPOSED`. Same value; kept for compatibility. */
     MESSAGE_BUSDisposed = "ERR_MESSAGE_BUS_DISPOSED",
     MESSAGE_SERIALIZATION_FAILED = "ERR_MESSAGE_SERIALIZATION_FAILED",
     MESSAGE_DESERIALIZATION_FAILED = "ERR_MESSAGE_DESERIALIZATION_FAILED",
+    MESSAGE_HANDLER_FAILED = "ERR_MESSAGE_HANDLER_FAILED",
+    MESSAGE_MIDDLEWARE_FAILED = "ERR_MESSAGE_MIDDLEWARE_FAILED",
+    MESSAGE_TYPE_NOT_FOUND = "ERR_MESSAGE_TYPE_NOT_FOUND",
     LOGGING_FAILED = "ERR_LOGGING_FAILED",
     MIDDLEWARE_EXECUTION = "ERR_MIDDLEWARE_EXECUTION",
     MIDDLEWARE_TIMEOUT = "ERR_MIDDLEWARE_TIMEOUT",
@@ -301,7 +321,56 @@ export declare enum ErrorCode {
     DOCUMENT_NAVIGATION_INVALID = "ERR_DOCUMENT_NAVIGATION_INVALID",
     DOCUMENT_EXAMPLE_INVALID = "ERR_DOCUMENT_EXAMPLE_INVALID",
     DOCUMENT_GENERATION = "ERR_DOCUMENT_GENERATION",
-    DOCUMENT_VERSION = "ERR_DOCUMENT_VERSION"
+    DOCUMENT_VERSION = "ERR_DOCUMENT_VERSION",
+    CACHE = "ERR_CACHE",
+    DATABASE_MIGRATION = "ERR_DATABASE_MIGRATION",
+    RUNTIME = "ERR_RUNTIME",
+    HTTP_BAD_REQUEST = "ERR_HTTP_BAD_REQUEST",
+    HTTP_UNAUTHORIZED = "ERR_HTTP_UNAUTHORIZED",
+    HTTP_PAYMENT_REQUIRED = "ERR_HTTP_PAYMENT_REQUIRED",
+    HTTP_FORBIDDEN = "ERR_HTTP_FORBIDDEN",
+    HTTP_NOT_FOUND = "ERR_HTTP_NOT_FOUND",
+    HTTP_METHOD_NOT_ALLOWED = "ERR_HTTP_METHOD_NOT_ALLOWED",
+    HTTP_NOT_ACCEPTABLE = "ERR_HTTP_NOT_ACCEPTABLE",
+    HTTP_PROXY_AUTHENTICATION_REQUIRED = "ERR_HTTP_PROXY_AUTHENTICATION_REQUIRED",
+    HTTP_REQUEST_TIMEOUT = "ERR_HTTP_REQUEST_TIMEOUT",
+    HTTP_CONFLICT = "ERR_HTTP_CONFLICT",
+    HTTP_GONE = "ERR_HTTP_GONE",
+    HTTP_LENGTH_REQUIRED = "ERR_HTTP_LENGTH_REQUIRED",
+    HTTP_PRECONDITION_FAILED = "ERR_HTTP_PRECONDITION_FAILED",
+    HTTP_PAYLOAD_TOO_LARGE = "ERR_HTTP_PAYLOAD_TOO_LARGE",
+    HTTP_URI_TOO_LONG = "ERR_HTTP_URI_TOO_LONG",
+    HTTP_UNSUPPORTED_MEDIA_TYPE = "ERR_HTTP_UNSUPPORTED_MEDIA_TYPE",
+    HTTP_RANGE_NOT_SATISFIABLE = "ERR_HTTP_RANGE_NOT_SATISFIABLE",
+    HTTP_EXPECTATION_FAILED = "ERR_HTTP_EXPECTATION_FAILED",
+    HTTP_MISDIRECTED_REQUEST = "ERR_HTTP_MISDIRECTED_REQUEST",
+    HTTP_UNPROCESSABLE_ENTITY = "ERR_HTTP_UNPROCESSABLE_ENTITY",
+    HTTP_LOCKED = "ERR_HTTP_LOCKED",
+    HTTP_FAILED_DEPENDENCY = "ERR_HTTP_FAILED_DEPENDENCY",
+    HTTP_TOO_EARLY = "ERR_HTTP_TOO_EARLY",
+    HTTP_UPGRADE_REQUIRED = "ERR_HTTP_UPGRADE_REQUIRED",
+    HTTP_PRECONDITION_REQUIRED = "ERR_HTTP_PRECONDITION_REQUIRED",
+    HTTP_TOO_MANY_REQUESTS = "ERR_HTTP_TOO_MANY_REQUESTS",
+    HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE = "ERR_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE",
+    HTTP_UNAVAILABLE_FOR_LEGAL_REASONS = "ERR_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS",
+    HTTP_REQUEST_ABORTED = "ERR_HTTP_REQUEST_ABORTED",
+    HTTP_INTERNAL_SERVER_ERROR = "ERR_HTTP_INTERNAL_SERVER_ERROR",
+    HTTP_NOT_IMPLEMENTED = "ERR_HTTP_NOT_IMPLEMENTED",
+    HTTP_BAD_GATEWAY = "ERR_HTTP_BAD_GATEWAY",
+    HTTP_SERVICE_UNAVAILABLE = "ERR_HTTP_SERVICE_UNAVAILABLE",
+    HTTP_GATEWAY_TIMEOUT = "ERR_HTTP_GATEWAY_TIMEOUT",
+    HTTP_VERSION_NOT_SUPPORTED = "ERR_HTTP_VERSION_NOT_SUPPORTED",
+    HTTP_INSUFFICIENT_STORAGE = "ERR_HTTP_INSUFFICIENT_STORAGE",
+    HTTP_LOOP_DETECTED = "ERR_HTTP_LOOP_DETECTED",
+    HTTP_NETWORK_AUTHENTICATION_REQUIRED = "ERR_HTTP_NETWORK_AUTHENTICATION_REQUIRED",
+    HTTP_CLIENT = "ERR_HTTP_CLIENT",
+    HTTP_CLIENT_TIMEOUT = "ERR_HTTP_CLIENT_TIMEOUT",
+    HTTP_CLIENT_ABORTED = "ERR_HTTP_CLIENT_ABORTED",
+    HTTP_CLIENT_NETWORK = "ERR_HTTP_CLIENT_NETWORK",
+    HTTP_CLIENT_REQUEST_BODY_TIMEOUT = "ERR_HTTP_CLIENT_REQUEST_BODY_TIMEOUT",
+    HTTP_CLIENT_UNSUPPORTED_PROTOCOL = "ERR_HTTP_CLIENT_UNSUPPORTED_PROTOCOL",
+    HTTP_CLIENT_INVALID_HEADER = "ERR_HTTP_CLIENT_INVALID_HEADER",
+    HTTP_CLIENT_INVALID_CONTENT_TYPE = "ERR_HTTP_CLIENT_INVALID_CONTENT_TYPE"
 }
 /**
  * Determines whether a value is a valid Zudojs error code.

package/dist/base/types/errorCode.type.js

@@ -108,6 +108,21 @@ export var ErrorCode;
     // Event
     ErrorCode["EVENT_HANDLING_FAILED"] = "ERR_EVENT_HANDLING_FAILED";
     ErrorCode["EVENT_PUBLISH_FAILED"] = "ERR_EVENT_PUBLISH_FAILED";
+    ErrorCode["EVENT_HANDLER_NOT_FOUND"] = "ERR_EVENT_HANDLER_NOT_FOUND";
+    ErrorCode["EVENT_DUPLICATE_HANDLER"] = "ERR_EVENT_DUPLICATE_HANDLER";
+    ErrorCode["EVENT_MIDDLEWARE_FAILED"] = "ERR_EVENT_MIDDLEWARE_FAILED";
+    ErrorCode["EVENT_INVALID"] = "ERR_EVENT_INVALID";
+    ErrorCode["EVENT_TYPE_NOT_FOUND"] = "ERR_EVENT_TYPE_NOT_FOUND";
+    ErrorCode["EVENT_DUPLICATE_DEFINITION"] = "ERR_EVENT_DUPLICATE_DEFINITION";
+    ErrorCode["EVENT_DEFINITION_NOT_FOUND"] = "ERR_EVENT_DEFINITION_NOT_FOUND";
+    ErrorCode["EVENT_DISPATCH_ABORTED"] = "ERR_EVENT_DISPATCH_ABORTED";
+    ErrorCode["EVENT_EMITTER_DISPOSED"] = "ERR_EVENT_EMITTER_DISPOSED";
+    ErrorCode["EVENT_REGISTRY_DISPOSED"] = "ERR_EVENT_REGISTRY_DISPOSED";
+    ErrorCode["EVENT_BUS_DISPOSED"] = "ERR_EVENT_BUS_DISPOSED";
+    ErrorCode["EVENT_SUBSCRIPTION_CLOSED"] = "ERR_EVENT_SUBSCRIPTION_CLOSED";
+    ErrorCode["EVENT_TIMEOUT"] = "ERR_EVENT_TIMEOUT";
+    ErrorCode["EVENT_SERIALIZATION_FAILED"] = "ERR_EVENT_SERIALIZATION_FAILED";
+    ErrorCode["EVENT_DESERIALIZATION_FAILED"] = "ERR_EVENT_DESERIALIZATION_FAILED";
     // Message
     ErrorCode["MESSAGE_HANDLER_NOT_FOUND"] = "ERR_MESSAGE_HANDLER_NOT_FOUND";
     ErrorCode["MESSAGE_DISPATCH_FAILED"] = "ERR_MESSAGE_DISPATCH_FAILED";
@@ -116,9 +131,14 @@ export var ErrorCode;
     ErrorCode["MESSAGE_TIMEOUT"] = "ERR_MESSAGE_TIMEOUT";
     ErrorCode["MESSAGE_ABORTED"] = "ERR_MESSAGE_ABORTED";
     ErrorCode["MESSAGE_INVALID"] = "ERR_MESSAGE_INVALID";
+    ErrorCode["MESSAGE_BUS_DISPOSED"] = "ERR_MESSAGE_BUS_DISPOSED";
+    /** @deprecated Use `MESSAGE_BUS_DISPOSED`. Same value; kept for compatibility. */
     ErrorCode["MESSAGE_BUSDisposed"] = "ERR_MESSAGE_BUS_DISPOSED";
     ErrorCode["MESSAGE_SERIALIZATION_FAILED"] = "ERR_MESSAGE_SERIALIZATION_FAILED";
     ErrorCode["MESSAGE_DESERIALIZATION_FAILED"] = "ERR_MESSAGE_DESERIALIZATION_FAILED";
+    ErrorCode["MESSAGE_HANDLER_FAILED"] = "ERR_MESSAGE_HANDLER_FAILED";
+    ErrorCode["MESSAGE_MIDDLEWARE_FAILED"] = "ERR_MESSAGE_MIDDLEWARE_FAILED";
+    ErrorCode["MESSAGE_TYPE_NOT_FOUND"] = "ERR_MESSAGE_TYPE_NOT_FOUND";
     // Logger
     ErrorCode["LOGGING_FAILED"] = "ERR_LOGGING_FAILED";
     // Middleware
@@ -335,13 +355,69 @@ export var ErrorCode;
     ErrorCode["DOCUMENT_EXAMPLE_INVALID"] = "ERR_DOCUMENT_EXAMPLE_INVALID";
     ErrorCode["DOCUMENT_GENERATION"] = "ERR_DOCUMENT_GENERATION";
     ErrorCode["DOCUMENT_VERSION"] = "ERR_DOCUMENT_VERSION";
+    // Cache
+    ErrorCode["CACHE"] = "ERR_CACHE";
+    // Database (additional)
+    ErrorCode["DATABASE_MIGRATION"] = "ERR_DATABASE_MIGRATION";
+    // Runtime (generic)
+    ErrorCode["RUNTIME"] = "ERR_RUNTIME";
+    // HTTP status errors (client 4xx)
+    ErrorCode["HTTP_BAD_REQUEST"] = "ERR_HTTP_BAD_REQUEST";
+    ErrorCode["HTTP_UNAUTHORIZED"] = "ERR_HTTP_UNAUTHORIZED";
+    ErrorCode["HTTP_PAYMENT_REQUIRED"] = "ERR_HTTP_PAYMENT_REQUIRED";
+    ErrorCode["HTTP_FORBIDDEN"] = "ERR_HTTP_FORBIDDEN";
+    ErrorCode["HTTP_NOT_FOUND"] = "ERR_HTTP_NOT_FOUND";
+    ErrorCode["HTTP_METHOD_NOT_ALLOWED"] = "ERR_HTTP_METHOD_NOT_ALLOWED";
+    ErrorCode["HTTP_NOT_ACCEPTABLE"] = "ERR_HTTP_NOT_ACCEPTABLE";
+    ErrorCode["HTTP_PROXY_AUTHENTICATION_REQUIRED"] = "ERR_HTTP_PROXY_AUTHENTICATION_REQUIRED";
+    ErrorCode["HTTP_REQUEST_TIMEOUT"] = "ERR_HTTP_REQUEST_TIMEOUT";
+    ErrorCode["HTTP_CONFLICT"] = "ERR_HTTP_CONFLICT";
+    ErrorCode["HTTP_GONE"] = "ERR_HTTP_GONE";
+    ErrorCode["HTTP_LENGTH_REQUIRED"] = "ERR_HTTP_LENGTH_REQUIRED";
+    ErrorCode["HTTP_PRECONDITION_FAILED"] = "ERR_HTTP_PRECONDITION_FAILED";
+    ErrorCode["HTTP_PAYLOAD_TOO_LARGE"] = "ERR_HTTP_PAYLOAD_TOO_LARGE";
+    ErrorCode["HTTP_URI_TOO_LONG"] = "ERR_HTTP_URI_TOO_LONG";
+    ErrorCode["HTTP_UNSUPPORTED_MEDIA_TYPE"] = "ERR_HTTP_UNSUPPORTED_MEDIA_TYPE";
+    ErrorCode["HTTP_RANGE_NOT_SATISFIABLE"] = "ERR_HTTP_RANGE_NOT_SATISFIABLE";
+    ErrorCode["HTTP_EXPECTATION_FAILED"] = "ERR_HTTP_EXPECTATION_FAILED";
+    ErrorCode["HTTP_MISDIRECTED_REQUEST"] = "ERR_HTTP_MISDIRECTED_REQUEST";
+    ErrorCode["HTTP_UNPROCESSABLE_ENTITY"] = "ERR_HTTP_UNPROCESSABLE_ENTITY";
+    ErrorCode["HTTP_LOCKED"] = "ERR_HTTP_LOCKED";
+    ErrorCode["HTTP_FAILED_DEPENDENCY"] = "ERR_HTTP_FAILED_DEPENDENCY";
+    ErrorCode["HTTP_TOO_EARLY"] = "ERR_HTTP_TOO_EARLY";
+    ErrorCode["HTTP_UPGRADE_REQUIRED"] = "ERR_HTTP_UPGRADE_REQUIRED";
+    ErrorCode["HTTP_PRECONDITION_REQUIRED"] = "ERR_HTTP_PRECONDITION_REQUIRED";
+    ErrorCode["HTTP_TOO_MANY_REQUESTS"] = "ERR_HTTP_TOO_MANY_REQUESTS";
+    ErrorCode["HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE"] = "ERR_HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE";
+    ErrorCode["HTTP_UNAVAILABLE_FOR_LEGAL_REASONS"] = "ERR_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS";
+    ErrorCode["HTTP_REQUEST_ABORTED"] = "ERR_HTTP_REQUEST_ABORTED";
+    // HTTP status errors (server 5xx)
+    ErrorCode["HTTP_INTERNAL_SERVER_ERROR"] = "ERR_HTTP_INTERNAL_SERVER_ERROR";
+    ErrorCode["HTTP_NOT_IMPLEMENTED"] = "ERR_HTTP_NOT_IMPLEMENTED";
+    ErrorCode["HTTP_BAD_GATEWAY"] = "ERR_HTTP_BAD_GATEWAY";
+    ErrorCode["HTTP_SERVICE_UNAVAILABLE"] = "ERR_HTTP_SERVICE_UNAVAILABLE";
+    ErrorCode["HTTP_GATEWAY_TIMEOUT"] = "ERR_HTTP_GATEWAY_TIMEOUT";
+    ErrorCode["HTTP_VERSION_NOT_SUPPORTED"] = "ERR_HTTP_VERSION_NOT_SUPPORTED";
+    ErrorCode["HTTP_INSUFFICIENT_STORAGE"] = "ERR_HTTP_INSUFFICIENT_STORAGE";
+    ErrorCode["HTTP_LOOP_DETECTED"] = "ERR_HTTP_LOOP_DETECTED";
+    ErrorCode["HTTP_NETWORK_AUTHENTICATION_REQUIRED"] = "ERR_HTTP_NETWORK_AUTHENTICATION_REQUIRED";
+    // HTTP client (outbound requests)
+    ErrorCode["HTTP_CLIENT"] = "ERR_HTTP_CLIENT";
+    ErrorCode["HTTP_CLIENT_TIMEOUT"] = "ERR_HTTP_CLIENT_TIMEOUT";
+    ErrorCode["HTTP_CLIENT_ABORTED"] = "ERR_HTTP_CLIENT_ABORTED";
+    ErrorCode["HTTP_CLIENT_NETWORK"] = "ERR_HTTP_CLIENT_NETWORK";
+    ErrorCode["HTTP_CLIENT_REQUEST_BODY_TIMEOUT"] = "ERR_HTTP_CLIENT_REQUEST_BODY_TIMEOUT";
+    ErrorCode["HTTP_CLIENT_UNSUPPORTED_PROTOCOL"] = "ERR_HTTP_CLIENT_UNSUPPORTED_PROTOCOL";
+    ErrorCode["HTTP_CLIENT_INVALID_HEADER"] = "ERR_HTTP_CLIENT_INVALID_HEADER";
+    ErrorCode["HTTP_CLIENT_INVALID_CONTENT_TYPE"] = "ERR_HTTP_CLIENT_INVALID_CONTENT_TYPE";
 })(ErrorCode || (ErrorCode = {}));
+/** Precomputed set of every error code value. */
+const ERROR_CODE_VALUES = new Set(Object.values(ErrorCode));
 /**
  * Determines whether a value is a valid Zudojs error code.
  */
 export function isErrorCode(value) {
-    return (typeof value === "string" &&
-        Object.values(ErrorCode).includes(value));
+    return typeof value === "string" && ERROR_CODE_VALUES.has(value);
 }
 /**
  * Converts an unknown value into a valid error code.

package/dist/base/types/errorSeverity.type.js

@@ -31,9 +31,10 @@ export var ErrorSeverity;
  * Determines whether a value is a valid error severity.
  */
 export function isErrorSeverity(value) {
-    return (typeof value === "string" &&
-        Object.values(ErrorSeverity).includes(value));
+    return typeof value === "string" && ERROR_SEVERITY_VALUES.has(value);
 }
+/** Precomputed set of every error severity value. */
+const ERROR_SEVERITY_VALUES = new Set(Object.values(ErrorSeverity));
 /**
  * Normalizes an unknown severity into a valid ErrorSeverity.
  */

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

@@ -1,12 +1,28 @@
-import type { ErrorCategory } from "../types/errorCategory.type.js";
+import { ErrorCategory } from "../types/errorCategory.type.js";
 import { ErrorCode } from "../types/errorCode.type.js";
-import type { ErrorSeverity } from "../types/errorSeverity.type.js";
+import { ErrorSeverity } from "../types/errorSeverity.type.js";
 import { BaseError } from "../core/baseError.core.js";
 import type { BaseErrorOptions } from "../types/baseError.type.js";
 /**
  * Determines whether an unknown value is a BaseError.
+ *
+ * Uses `instanceof` as the fast path and falls back to the package brand plus
+ * a structural check, so errors produced by another installed copy of
+ * `@zudojs/errors` are still recognised.
  */
 export declare function isBaseError(value: unknown): value is BaseError;
+/** Default message used when an unknown value is converted into a BaseError. */
+export declare const UNKNOWN_ERROR_MESSAGE = "An unexpected error occurred.";
+/**
+ * Converts an unknown thrown value into a BaseError.
+ *
+ * This is the single normalization routine shared by `toBaseError`,
+ * `normalizeToBaseError`, `normalizeUnknownError` and `ErrorHandler.normalize`.
+ * Unknown values are classified as non-operational internal errors
+ * (`ERR_INTERNAL_ERROR`, 500, not exposed) and the original value is kept as
+ * `cause`; a plain string is used as the message.
+ */
+export declare function normalizeUnknownToBaseError(value: unknown, options?: BaseErrorOptions): BaseError;
 /**
  * Converts an unknown thrown value into a BaseError.
  */