@zudojs/errors 0.1.0 → 1.0.0

package/dist/domain/shared/domainError.helpers.js

@@ -0,0 +1,191 @@
+/**
+ * Shared helpers for domain error classes.
+ *
+ * These utilities keep untrusted input out of error messages, make
+ * normalizers robust against exotic thrown values, and validate the
+ * numeric arguments that domain errors record.
+ */
+/** Default maximum length for untrusted strings embedded in messages. */
+export const MAX_MESSAGE_FRAGMENT_LENGTH = 200;
+/** Control characters (C0 range, DEL, and C1 range) that must not reach logs. */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
+/** Default maximum length for untrusted strings stored in metadata. */
+export const MAX_METADATA_FRAGMENT_LENGTH = 1024;
+/**
+ * Removes control characters (including newlines and ANSI escapes) and
+ * truncates the string so it can be safely embedded in a message or log line.
+ */
+export function sanitizeFragment(value, maxLength = MAX_MESSAGE_FRAGMENT_LENGTH) {
+    const text = typeof value === "string" ? value : safeStringify(value);
+    const cleaned = text.replace(CONTROL_CHARS, " ");
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return `${cleaned.slice(0, maxLength)}… [truncated ${cleaned.length - maxLength} chars]`;
+}
+/**
+ * Serializes any value to a string without throwing.
+ *
+ * Handles BigInt, circular structures, symbols, and objects whose
+ * `toString` throws. Never returns more than `maxLength` characters.
+ */
+export function safeStringify(value, maxLength = MAX_METADATA_FRAGMENT_LENGTH) {
+    let text;
+    try {
+        if (typeof value === "string") {
+            text = value;
+        }
+        else if (typeof value === "bigint") {
+            text = `${value.toString()}n`;
+        }
+        else if (typeof value === "symbol") {
+            text = value.toString();
+        }
+        else if (typeof value === "function") {
+            text = `[function ${value.name || "anonymous"}]`;
+        }
+        else if (value === undefined) {
+            text = "undefined";
+        }
+        else {
+            const seen = new WeakSet();
+            const json = JSON.stringify(value, (_key, item) => {
+                if (typeof item === "bigint")
+                    return `${item.toString()}n`;
+                if (typeof item === "symbol")
+                    return item.toString();
+                if (typeof item === "object" && item !== null) {
+                    if (seen.has(item))
+                        return "[Circular]";
+                    seen.add(item);
+                }
+                return item;
+            });
+            text = json === undefined ? String(value) : json;
+        }
+    }
+    catch {
+        try {
+            text = Object.prototype.toString.call(value);
+        }
+        catch {
+            text = "[unserializable]";
+        }
+    }
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength)}…`;
+}
+/**
+ * Describes a value by type and size without revealing its contents.
+ *
+ * Use this instead of embedding submitted values into exposed messages.
+ */
+export function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    switch (typeof value) {
+        case "string":
+            return `string(${value.length})`;
+        case "number":
+            return Number.isFinite(value) ? "number" : `number(${String(value)})`;
+        case "bigint":
+            return "bigint";
+        case "boolean":
+            return `boolean(${String(value)})`;
+        case "symbol":
+            return "symbol";
+        case "function":
+            return "function";
+        default: {
+            if (value instanceof Date)
+                return "date";
+            const proto = Object.getPrototypeOf(value);
+            if (proto === null || proto === Object.prototype)
+                return "object";
+            const name = value.constructor
+                ?.name;
+            return name ? `object(${name})` : "object";
+        }
+    }
+}
+/**
+ * Produces a message for an unknown thrown value without throwing.
+ */
+export function safeErrorMessage(error) {
+    if (error instanceof Error) {
+        return typeof error.message === "string" ? error.message : "Unknown error";
+    }
+    if (typeof error === "string")
+        return error;
+    if (error === null || error === undefined)
+        return "Unknown error";
+    const text = safeStringify(error, MAX_MESSAGE_FRAGMENT_LENGTH);
+    return text.length > 0 ? text : "Unknown error";
+}
+/**
+ * Asserts that a numeric argument is finite and non-negative.
+ */
+export function assertFiniteNonNegative(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`${name} must be a finite non-negative number.`);
+    }
+    return value;
+}
+/**
+ * Normalizes a retry-after value in seconds to a finite, non-negative integer
+ * (rounded up), as required by the HTTP `Retry-After` header.
+ */
+export function normalizeRetryAfterSeconds(value, name = "retryAfterSeconds") {
+    return Math.ceil(assertFiniteNonNegative(name, value));
+}
+/**
+ * Merges caller-provided metadata with class-specific fields, letting the
+ * class-specific fields win.
+ */
+export function mergeMetadata(callerMetadata, own) {
+    return { ...(callerMetadata ?? {}), ...own };
+}
+/** Keys that hold submitted values inside validation/schema issues. */
+const VALUE_KEYS = new Set(["value", "received", "input", "actual"]);
+/**
+ * Removes submitted values from a list of issue objects so they can be
+ * exposed to clients. Values are replaced by a type/size description under
+ * `<key>Type`.
+ */
+export function redactIssueValues(issues) {
+    return issues.map((issue) => {
+        if (typeof issue !== "object" || issue === null || Array.isArray(issue)) {
+            return issue;
+        }
+        const out = {};
+        for (const [key, val] of Object.entries(issue)) {
+            if (VALUE_KEYS.has(key)) {
+                out[`${key}Type`] = describeValue(val);
+            }
+            else {
+                out[key] = val;
+            }
+        }
+        return out;
+    });
+}
+/**
+ * Converts issue objects into JSON-safe structures (no BigInt, no cycles)
+ * so that `JSON.stringify` on the error never throws.
+ */
+export function toJsonSafeIssues(issues) {
+    return issues.map((issue) => {
+        try {
+            return JSON.parse(safeStringify(issue, Number.POSITIVE_INFINITY));
+        }
+        catch {
+            return issue;
+        }
+    });
+}
+//# sourceMappingURL=domainError.helpers.js.map

package/dist/domain/state/conflict.error.d.ts

@@ -21,6 +21,6 @@ export declare function isConflictError(value: unknown): value is ConflictError;
 export declare function alreadyExistsError(resource: string, identifier?: string | number): ConflictError;
 /** Creates an error indicating that a duplicate value was submitted. */
 export declare function duplicateError(field: string, value?: string | number): ConflictError;
-/** Creates an error indicating that a resource is currently locked. */
+/** Creates an error indicating that a resource is currently locked (HTTP 423). */
 export declare function resourceLockedError(resource: string, identifier?: string | number): ConflictError;
 //# sourceMappingURL=conflict.error.d.ts.map

package/dist/domain/state/conflict.error.js

@@ -58,7 +58,7 @@ export function duplicateError(field, value) {
         },
     });
 }
-/** Creates an error indicating that a resource is currently locked. */
+/** Creates an error indicating that a resource is currently locked (HTTP 423). */
 export function resourceLockedError(resource, identifier) {
     const message = identifier !== undefined
         ? `${resource} with identifier "${String(identifier)}" is currently locked.`
@@ -66,7 +66,7 @@ export function resourceLockedError(resource, identifier) {
     return new ConflictError(message, {
         code: ErrorCode.RESOURCE_LOCKED,
         category: ErrorCategory.CONFLICT,
-        statusCode: 409,
+        statusCode: 423,
         expose: true,
         metadata: {
             resource,

package/dist/domain/state/validationError.base.d.ts

@@ -31,7 +31,14 @@ export declare class ValidationError extends BaseError {
     get issueCount(): number;
     /** Returns issues associated with a specific field. */
     issuesForField(field: string): readonly ValidationIssue[];
-    /** Returns a serialized representation including validation issues. */
+    /**
+     * Returns a serialized representation including validation issues.
+     *
+     * When the error is exposable (the default), submitted values inside
+     * issues (`value`) are replaced by a type/size description so that secrets
+     * such as passwords are never echoed to clients or written to logs. The
+     * output is always JSON-safe (BigInt and cyclic values are stringified).
+     */
     toJSON(): {
         name: string;
         message: string;

package/dist/domain/state/validationError.base.js

@@ -2,6 +2,7 @@ import { BaseError } from "../../base/core/baseError.core.js";
 import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
+import { redactIssueValues, toJsonSafeIssues, } from "../shared/domainError.helpers.js";
 /**
  * Error raised when input fails validation.
  */
@@ -31,11 +32,19 @@ export class ValidationError extends BaseError {
     issuesForField(field) {
         return this.issues.filter((issue) => issue.field === field || issue.path?.[0] === field);
     }
-    /** Returns a serialized representation including validation issues. */
+    /**
+     * Returns a serialized representation including validation issues.
+     *
+     * When the error is exposable (the default), submitted values inside
+     * issues (`value`) are replaced by a type/size description so that secrets
+     * such as passwords are never echoed to clients or written to logs. The
+     * output is always JSON-safe (BigInt and cyclic values are stringified).
+     */
     toJSON() {
+        const safeIssues = toJsonSafeIssues(this.issues);
         return {
             ...super.toJSON(),
-            issues: this.issues,
+            issues: this.expose ? redactIssueValues(safeIssues) : safeIssues,
         };
     }
 }

package/dist/infrastructure/adapter/adapterError.base.js

@@ -41,10 +41,10 @@ export class AdapterNotFoundError extends AdapterError {
         super(`Adapter "${adapterName}" is not registered.`, {
             code: ErrorCode.ADAPTER_NOT_FOUND,
             adapter: adapterName,
-            statusCode: 404,
-            expose: true,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
-        this.name = "AdapterNotFoundError";
     }
 }
 /** Error thrown when an adapter is already registered. */
@@ -53,10 +53,10 @@ export class AdapterAlreadyRegisteredError extends AdapterError {
         super(`Adapter "${adapterName}" is already registered.`, {
             code: ErrorCode.ADAPTER_ALREADY_REGISTERED,
             adapter: adapterName,
-            statusCode: 409,
-            expose: true,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
-        this.name = "AdapterAlreadyRegisteredError";
     }
 }
 //# sourceMappingURL=adapterError.base.js.map

package/dist/infrastructure/adapter/adapterError.lifecycle.js

@@ -14,7 +14,6 @@ export class AdapterInitializationError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterInitializationError";
     }
 }
 /** Error thrown when an adapter fails to configure. */
@@ -28,7 +27,6 @@ export class AdapterConfigurationError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterConfigurationError";
     }
 }
 /** Error thrown when an adapter fails to dispose. */
@@ -42,7 +40,6 @@ export class AdapterDisposeError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterDisposeError";
     }
 }
 //# sourceMappingURL=adapterError.lifecycle.js.map

package/dist/infrastructure/adapter/adapterError.operation.js

@@ -13,7 +13,6 @@ export class AdapterNotSupportedError extends AdapterError {
             statusCode: 501,
             expose: true,
         });
-        this.name = "AdapterNotSupportedError";
     }
 }
 /** Error thrown when an adapter capability is missing. */
@@ -26,7 +25,6 @@ export class AdapterCapabilityMissingError extends AdapterError {
             statusCode: 500,
             expose: false,
         });
-        this.name = "AdapterCapabilityMissingError";
     }
 }
 /** Error thrown when an adapter fails to connect. */
@@ -40,7 +38,6 @@ export class AdapterConnectionError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterConnectionError";
     }
 }
 /** Error thrown when an adapter operation fails. */
@@ -55,7 +52,6 @@ export class AdapterOperationError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterOperationError";
     }
 }
 /** Error thrown when an adapter operation times out. */
@@ -71,7 +67,6 @@ export class AdapterTimeoutError extends AdapterError {
             expose: false,
             isOperational: false,
         });
-        this.name = "AdapterTimeoutError";
         this.timeout = timeout;
     }
 }

package/dist/infrastructure/cache/cacheError.base.js

@@ -33,7 +33,7 @@ export class CacheError extends BaseError {
     constructor(message = "A cache operation failed.", options = {}) {
         super(message, {
             ...options,
-            code: options.code ?? ErrorCode.UNKNOWN,
+            code: options.code ?? ErrorCode.CACHE,
             category: options.category ?? ErrorCategory.CACHE,
             severity: options.severity ?? ErrorSeverity.ERROR,
             statusCode: options.statusCode ?? 500,

package/dist/infrastructure/container/containerError.registration.js

@@ -11,8 +11,9 @@ export class DuplicateRegistrationError extends ContainerError {
         super(message ?? `Token "${token}" is already registered.`, {
             code: ErrorCode.CONTAINER_DUPLICATE_REGISTRATION,
             token,
-            statusCode: 409,
-            expose: true,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
         this.token = token;
         this.existingScope = options.existingScope;
@@ -34,8 +35,9 @@ export class RegistrationNotFoundError extends ContainerError {
         super(message ?? `No registration found for token "${token}".`, {
             code: ErrorCode.CONTAINER_REGISTRATION_NOT_FOUND,
             token,
-            statusCode: 404,
-            expose: true,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
         this.requestedToken = token;
     }

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

@@ -19,7 +19,6 @@ export class HttpAdapterError extends BaseError {
             statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
         });
-        this.name = "HttpAdapterError";
         this.adapter = options.adapter;
     }
 }
@@ -38,12 +37,15 @@ export class RequestBodyTooLargeError extends HttpAdapterError {
     constructor(maxSize, actualSize) {
         super(`HTTP request body exceeds the maximum allowed size of ${maxSize} bytes (actual: ${actualSize}).`, {
             code: ErrorCode.HTTP_REQUEST_BODY_TOO_LARGE,
+            statusCode: 413,
+            expose: true,
+            isOperational: true,
+            severity: ErrorSeverity.WARNING,
             metadata: {
                 maxSize,
                 actualSize,
             },
         });
-        this.name = "RequestBodyTooLargeError";
         this.maxSize = maxSize;
         this.actualSize = actualSize;
     }

package/dist/infrastructure/network/httpClientError.advanced.js

@@ -1,6 +1,7 @@
 /**
  * Advanced HTTP client error classes (422+).
  */
+import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { HttpError } from "./http.error.js";
 /** 422 Unprocessable Entity */
 export class UnprocessableEntityError extends HttpError {
@@ -8,9 +9,8 @@ export class UnprocessableEntityError extends HttpError {
         super(message, {
             ...options,
             statusCode: 422,
-            code: options.code ?? "UNPROCESSABLE_ENTITY",
+            code: options.code ?? ErrorCode.HTTP_UNPROCESSABLE_ENTITY,
         });
-        this.name = "UnprocessableEntityError";
     }
 }
 /** 423 Locked */
@@ -19,9 +19,8 @@ export class LockedError extends HttpError {
         super(message, {
             ...options,
             statusCode: 423,
-            code: options.code ?? "LOCKED",
+            code: options.code ?? ErrorCode.HTTP_LOCKED,
         });
-        this.name = "LockedError";
     }
 }
 /** 424 Failed Dependency */
@@ -30,9 +29,8 @@ export class FailedDependencyError extends HttpError {
         super(message, {
             ...options,
             statusCode: 424,
-            code: options.code ?? "FAILED_DEPENDENCY",
+            code: options.code ?? ErrorCode.HTTP_FAILED_DEPENDENCY,
         });
-        this.name = "FailedDependencyError";
     }
 }
 /** 425 Too Early */
@@ -41,9 +39,8 @@ export class TooEarlyError extends HttpError {
         super(message, {
             ...options,
             statusCode: 425,
-            code: options.code ?? "TOO_EARLY",
+            code: options.code ?? ErrorCode.HTTP_TOO_EARLY,
         });
-        this.name = "TooEarlyError";
     }
 }
 /** 426 Upgrade Required */
@@ -52,9 +49,8 @@ export class UpgradeRequiredError extends HttpError {
         super(message, {
             ...options,
             statusCode: 426,
-            code: options.code ?? "UPGRADE_REQUIRED",
+            code: options.code ?? ErrorCode.HTTP_UPGRADE_REQUIRED,
         });
-        this.name = "UpgradeRequiredError";
     }
 }
 /** 428 Precondition Required */
@@ -63,9 +59,8 @@ export class PreconditionRequiredError extends HttpError {
         super(message, {
             ...options,
             statusCode: 428,
-            code: options.code ?? "PRECONDITION_REQUIRED",
+            code: options.code ?? ErrorCode.HTTP_PRECONDITION_REQUIRED,
         });
-        this.name = "PreconditionRequiredError";
     }
 }
 /** 429 Too Many Requests */
@@ -74,9 +69,8 @@ export class TooManyRequestsError extends HttpError {
         super(message, {
             ...options,
             statusCode: 429,
-            code: options.code ?? "TOO_MANY_REQUESTS",
+            code: options.code ?? ErrorCode.HTTP_TOO_MANY_REQUESTS,
         });
-        this.name = "TooManyRequestsError";
     }
 }
 /** 431 Request Header Fields Too Large */
@@ -85,9 +79,8 @@ export class RequestHeaderFieldsTooLargeError extends HttpError {
         super(message, {
             ...options,
             statusCode: 431,
-            code: options.code ?? "REQUEST_HEADER_FIELDS_TOO_LARGE",
+            code: options.code ?? ErrorCode.HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE,
         });
-        this.name = "RequestHeaderFieldsTooLargeError";
     }
 }
 /** 499 Request Aborted */
@@ -96,9 +89,8 @@ export class RequestAbortedError extends HttpError {
         super(message, {
             ...options,
             statusCode: 499,
-            code: options.code ?? "REQUEST_ABORTED",
+            code: options.code ?? ErrorCode.HTTP_REQUEST_ABORTED,
         });
-        this.name = "RequestAbortedError";
     }
 }
 //# sourceMappingURL=httpClientError.advanced.js.map

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

@@ -11,6 +11,8 @@ export interface HttpClientClientErrorOptions {
     readonly code?: string;
     readonly expose?: boolean;
     readonly metadata?: ErrorMetadata;
+    /** Local status code. Defaults to a mapping of the upstream `status` (502 for upstream failures). */
+    readonly statusCode?: number;
     readonly status?: number;
     readonly statusText?: string;
     readonly url?: string;
@@ -35,4 +37,13 @@ export declare class HttpClientError extends BaseError {
     get isAbortError(): boolean;
     get isHttpStatusError(): boolean;
 }
+/**
+ * Maps an upstream HTTP status to the local status reported to our caller.
+ *
+ * Upstream failures are our problem, not the caller's: everything except
+ * 429 (which is passed through) maps to 502 Bad Gateway.
+ */
+export declare function mapUpstreamStatus(status: number | undefined): number;
+/** Removes credentials and the query string from a URL before storing it. */
+export declare function stripUrlCredentials(url: string): string;
 //# sourceMappingURL=httpClientError.base.d.ts.map

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

@@ -2,6 +2,9 @@
  * HTTP client error base class.
  */
 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";
 /**
  * Base HTTP client error for outbound request failures.
  *
@@ -15,30 +18,67 @@ export class HttpClientError extends BaseError {
     response;
     request;
     constructor(message, options = {}) {
+        const url = options.url !== undefined ? stripUrlCredentials(options.url) : undefined;
         super(message, {
-            code: options.code ?? "HTTP_CLIENT_ERROR",
+            code: options.code ?? ErrorCode.HTTP_CLIENT,
+            category: ErrorCategory.NETWORK,
+            severity: ErrorSeverity.ERROR,
+            statusCode: options.statusCode ?? mapUpstreamStatus(options.status),
             expose: options.expose ?? false,
-            metadata: options.metadata,
+            isOperational: true,
+            metadata: {
+                ...options.metadata,
+                ...(options.status !== undefined ? { upstreamStatus: options.status } : {}),
+                ...(url !== undefined ? { url } : {}),
+            },
             cause: options.cause,
         });
-        this.name = "HttpClientError";
         this.status = options.status;
         this.statusText = options.statusText;
-        this.url = options.url;
+        this.url = url;
         this.response = options.response;
         this.request = options.request;
     }
     get isNetworkError() {
-        return this.code === "HTTP_CLIENT_NETWORK_ERROR";
+        return (this.code === ErrorCode.HTTP_CLIENT_NETWORK ||
+            this.code === "HTTP_CLIENT_NETWORK_ERROR");
     }
     get isTimeoutError() {
-        return this.code === "HTTP_CLIENT_TIMEOUT";
+        return (this.code === ErrorCode.HTTP_CLIENT_TIMEOUT ||
+            this.code === "HTTP_CLIENT_TIMEOUT");
     }
     get isAbortError() {
-        return this.code === "HTTP_CLIENT_ABORTED";
+        return (this.code === ErrorCode.HTTP_CLIENT_ABORTED ||
+            this.code === "HTTP_CLIENT_ABORTED");
     }
     get isHttpStatusError() {
         return this.status !== undefined;
     }
 }
+/**
+ * Maps an upstream HTTP status to the local status reported to our caller.
+ *
+ * Upstream failures are our problem, not the caller's: everything except
+ * 429 (which is passed through) maps to 502 Bad Gateway.
+ */
+export function mapUpstreamStatus(status) {
+    if (status === 429)
+        return 429;
+    return 502;
+}
+/** Removes credentials and the query string from a URL before storing it. */
+export function stripUrlCredentials(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.username = "";
+        parsed.password = "";
+        parsed.search = "";
+        parsed.hash = "";
+        return parsed.toString();
+    }
+    catch {
+        const withoutQuery = url.split(/[?#]/)[0] ?? url;
+        return withoutQuery.replace(/\/\/[^/@]*@/, "//");
+    }
+}
 //# sourceMappingURL=httpClientError.base.js.map

package/dist/infrastructure/network/httpClientError.common.d.ts

@@ -23,6 +23,20 @@ export declare class HttpNotFoundError extends HttpError {
 export declare class MethodNotAllowedError extends HttpError {
     readonly methods: readonly string[];
     constructor(methods?: readonly string[], message?: string, options?: HttpClientErrorOptions);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        category: import("../../index.js").ErrorCategory;
+        severity: import("../../index.js").ErrorSeverity;
+        statusCode: number;
+        expose: boolean;
+        isOperational: boolean;
+        metadata: Readonly<import("../../index.js").ErrorMetadata>;
+        stack?: string;
+        cause?: import("../../index.js").SerializedBaseError | unknown;
+        methods: readonly string[];
+    };
 }
 /** 406 Not Acceptable */
 export declare class NotAcceptableError extends HttpError {