@zudojs/errors 1.1.0 → 1.3.0

package/README.md

@@ -47,7 +47,7 @@ try {
 - `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
-- Base classes for other packages' error families, so their `instanceof` checks match: `TransactionError` (+ 10 subclasses), `MiddlewareLimitExceededError` / `MiddlewareDepthExceededError` / `MiddlewareRateLimitError` / `MiddlewareAbortedError`, `TraversalLimitError`, `HttpMiddlewareError` / `HttpMiddlewarePipelineError` / `HttpRequestGuardError`, `OpenAPIError`, `AuthError`, `OAuthError` (with `ErrorCode.OAUTH_*`), `CqrsError`, `ObservabilityError`, `InvalidConstantError` / `ConstantContextError`, and the `zudojs-cli` errors `CLIValidationError` / `CLIGenerationError` / `CLINotInProjectError` / `CLITemplateError`
+- Base classes for other packages' error families, so their `instanceof` checks match: `TransactionError` (+ 10 subclasses), `MiddlewareLimitExceededError` / `MiddlewareDepthExceededError` / `MiddlewareRateLimitError` / `MiddlewareAbortedError`, `TraversalLimitError`, `HttpMiddlewareError` / `HttpMiddlewarePipelineError` / `HttpRequestGuardError`, `OpenAPIError`, `AuthError`, `OAuthError` (with `ErrorCode.OAUTH_*`), `CqrsError` (+ `CommandFailedError` / `QueryFailedError`, thrown when a failed command or query result is unwrapped), `EventBusStoppedError` / `EventBusDisposedError` (re-exported by `@zudojs/events`), `ObservabilityError`, `InvalidConstantError` / `ConstantContextError`, and the `zudojs-cli` errors `CLIValidationError` / `CLIGenerationError` / `CLINotInProjectError` / `CLITemplateError`
 - `withMetadata()` copies any error (including subclasses with custom constructors) with extra metadata
 - Serialization: `toJSON()`/`toLogObject()` for trusted logs (cycle-safe cause chains truncated with `"[MaxDepth]"` after 8 levels across the whole chain; metadata under sensitive keys, sensitive keys in object causes and submitted issue values are redacted, so `JSON.stringify(error)` is safe to log), `serializePublicError` / `ErrorSerializer` / `ErrorHandler.toPublicResult` for untrusted clients (recursive redaction, metadata allow-list)
 - Metadata utilities: `createErrorMetadata`, `mergeErrorMetadata`, `sanitizeErrorMetadata` (drops unsupported values) and `redactErrorMetadata` (removes secrets)

package/dist/base/core/errorCause.redact.d.ts

@@ -10,11 +10,16 @@
  * Redacts sensitive keys inside a record without changing its shape:
  * primitives, dates and class instances are kept, plain objects and arrays
  * are walked, cycles stop at `"[Circular]"`, prototype keys are dropped.
+ *
+ * The walk is depth-bounded exactly as metadata cloning is: a subtree past
+ * {@link MAX_METADATA_DEPTH} becomes `"[MaxDepth]"`. Without that bound a
+ * parsed request body attached as a cause could overflow the stack *inside*
+ * the serializer, turning a logged error into an uncaught `RangeError`.
  */
-export declare function redactCauseFields(fields: Record<string, unknown>, pattern: RegExp | undefined, seen?: WeakSet<object>): Record<string, unknown>;
+export declare function redactCauseFields(fields: Record<string, unknown>, pattern: RegExp | undefined, seen?: WeakSet<object>, depth?: number): Record<string, unknown>;
 /**
  * Redacts one cause value: arrays and plain objects are walked, every other
- * value is returned unchanged.
+ * value is returned unchanged. Walking stops at {@link MAX_METADATA_DEPTH}.
  */
-export declare function redactCauseValue(value: unknown, pattern: RegExp | undefined, seen?: WeakSet<object>): unknown;
+export declare function redactCauseValue(value: unknown, pattern: RegExp | undefined, seen?: WeakSet<object>, depth?: number): unknown;
 //# sourceMappingURL=errorCause.redact.d.ts.map

package/dist/base/core/errorCause.redact.js

@@ -6,7 +6,9 @@
  *
  * @module base/core/errorCause.redact
  */
-import { isForbiddenMetadataKey, isSensitiveMetadataKey, REDACTED_METADATA_VALUE, } from "./errorMetadata.core.js";
+import { isForbiddenMetadataKey, isSensitiveMetadataKey, MAX_METADATA_DEPTH, REDACTED_METADATA_VALUE, } from "./errorMetadata.core.js";
+/** Marker substituted for a cause subtree deeper than {@link MAX_METADATA_DEPTH}. */
+const MAX_DEPTH_VALUE = "[MaxDepth]";
 /** Plain objects (Object.prototype or null prototype) are walked; anything else is kept as-is. */
 function isPlainRecord(value) {
     if (value === null || typeof value !== "object")
@@ -18,8 +20,13 @@ function isPlainRecord(value) {
  * Redacts sensitive keys inside a record without changing its shape:
  * primitives, dates and class instances are kept, plain objects and arrays
  * are walked, cycles stop at `"[Circular]"`, prototype keys are dropped.
+ *
+ * The walk is depth-bounded exactly as metadata cloning is: a subtree past
+ * {@link MAX_METADATA_DEPTH} becomes `"[MaxDepth]"`. Without that bound a
+ * parsed request body attached as a cause could overflow the stack *inside*
+ * the serializer, turning a logged error into an uncaught `RangeError`.
  */
-export function redactCauseFields(fields, pattern, seen = new WeakSet()) {
+export function redactCauseFields(fields, pattern, seen = new WeakSet(), depth = 0) {
     const result = {};
     for (const key of Object.keys(fields)) {
         if (isForbiddenMetadataKey(key))
@@ -29,21 +36,23 @@ export function redactCauseFields(fields, pattern, seen = new WeakSet()) {
             : isSensitiveMetadataKey(key, pattern);
         result[key] = sensitive
             ? REDACTED_METADATA_VALUE
-            : redactCauseValue(fields[key], pattern, seen);
+            : redactCauseValue(fields[key], pattern, seen, depth + 1);
     }
     return result;
 }
 /**
  * Redacts one cause value: arrays and plain objects are walked, every other
- * value is returned unchanged.
+ * value is returned unchanged. Walking stops at {@link MAX_METADATA_DEPTH}.
  */
-export function redactCauseValue(value, pattern, seen = new WeakSet()) {
+export function redactCauseValue(value, pattern, seen = new WeakSet(), depth = 0) {
     if (Array.isArray(value)) {
+        if (depth > MAX_METADATA_DEPTH)
+            return MAX_DEPTH_VALUE;
         if (seen.has(value))
             return "[Circular]";
         seen.add(value);
         try {
-            return value.map((entry) => redactCauseValue(entry, pattern, seen));
+            return value.map((entry) => redactCauseValue(entry, pattern, seen, depth + 1));
         }
         finally {
             seen.delete(value);
@@ -51,11 +60,13 @@ export function redactCauseValue(value, pattern, seen = new WeakSet()) {
     }
     if (!isPlainRecord(value))
         return value;
+    if (depth > MAX_METADATA_DEPTH)
+        return MAX_DEPTH_VALUE;
     if (seen.has(value))
         return "[Circular]";
     seen.add(value);
     try {
-        return redactCauseFields(value, pattern, seen);
+        return redactCauseFields(value, pattern, seen, depth);
     }
     finally {
         seen.delete(value);

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

@@ -43,6 +43,12 @@ export declare enum ErrorCode {
     SESSION_EXPIRED = "ERR_SESSION_EXPIRED",
     TOKEN_INVALID = "ERR_TOKEN_INVALID",
     TOKEN_EXPIRED = "ERR_TOKEN_EXPIRED",
+    /** A token that verified but has been revoked (logout, rotation replay). */
+    TOKEN_REVOKED = "ERR_TOKEN_REVOKED",
+    /** The account is temporarily locked after repeated failed sign-ins. */
+    ACCOUNT_LOCKED = "ERR_ACCOUNT_LOCKED",
+    /** The account exists but has been deactivated. */
+    ACCOUNT_DEACTIVATED = "ERR_ACCOUNT_DEACTIVATED",
     CRYPTO = "ERR_CRYPTO",
     CRYPTO_KEY = "ERR_CRYPTO_KEY",
     CRYPTO_HASH = "ERR_CRYPTO_HASH",
@@ -84,6 +90,8 @@ export declare enum ErrorCode {
     QUERY_HANDLER_NOT_FOUND = "ERR_QUERY_HANDLER_NOT_FOUND",
     INVALID_COMMAND = "ERR_INVALID_COMMAND",
     INVALID_QUERY = "ERR_INVALID_QUERY",
+    COMMAND_FAILED = "ERR_COMMAND_FAILED",
+    QUERY_FAILED = "ERR_QUERY_FAILED",
     EVENT_HANDLER_FAILED = "ERR_EVENT_HANDLER_FAILED",
     CONFIGURATION_ERROR = "ERR_CONFIGURATION_ERROR",
     CONTAINER_DUPLICATE_REGISTRATION = "ERR_CONTAINER_DUPLICATE_REGISTRATION",
@@ -114,6 +122,7 @@ export declare enum ErrorCode {
     EVENT_REGISTRY_DISPOSED = "ERR_EVENT_REGISTRY_DISPOSED",
     EVENT_BUS_DISPOSED = "ERR_EVENT_BUS_DISPOSED",
     EVENT_SUBSCRIPTION_CLOSED = "ERR_EVENT_SUBSCRIPTION_CLOSED",
+    EVENT_LISTENER_LIMIT_EXCEEDED = "ERR_EVENT_LISTENER_LIMIT_EXCEEDED",
     EVENT_TIMEOUT = "ERR_EVENT_TIMEOUT",
     EVENT_SERIALIZATION_FAILED = "ERR_EVENT_SERIALIZATION_FAILED",
     EVENT_DESERIALIZATION_FAILED = "ERR_EVENT_DESERIALIZATION_FAILED",

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

@@ -44,6 +44,12 @@ export var ErrorCode;
     ErrorCode["SESSION_EXPIRED"] = "ERR_SESSION_EXPIRED";
     ErrorCode["TOKEN_INVALID"] = "ERR_TOKEN_INVALID";
     ErrorCode["TOKEN_EXPIRED"] = "ERR_TOKEN_EXPIRED";
+    /** A token that verified but has been revoked (logout, rotation replay). */
+    ErrorCode["TOKEN_REVOKED"] = "ERR_TOKEN_REVOKED";
+    /** The account is temporarily locked after repeated failed sign-ins. */
+    ErrorCode["ACCOUNT_LOCKED"] = "ERR_ACCOUNT_LOCKED";
+    /** The account exists but has been deactivated. */
+    ErrorCode["ACCOUNT_DEACTIVATED"] = "ERR_ACCOUNT_DEACTIVATED";
     ErrorCode["CRYPTO"] = "ERR_CRYPTO";
     ErrorCode["CRYPTO_KEY"] = "ERR_CRYPTO_KEY";
     ErrorCode["CRYPTO_HASH"] = "ERR_CRYPTO_HASH";
@@ -86,6 +92,8 @@ export var ErrorCode;
     ErrorCode["QUERY_HANDLER_NOT_FOUND"] = "ERR_QUERY_HANDLER_NOT_FOUND";
     ErrorCode["INVALID_COMMAND"] = "ERR_INVALID_COMMAND";
     ErrorCode["INVALID_QUERY"] = "ERR_INVALID_QUERY";
+    ErrorCode["COMMAND_FAILED"] = "ERR_COMMAND_FAILED";
+    ErrorCode["QUERY_FAILED"] = "ERR_QUERY_FAILED";
     ErrorCode["EVENT_HANDLER_FAILED"] = "ERR_EVENT_HANDLER_FAILED";
     ErrorCode["CONFIGURATION_ERROR"] = "ERR_CONFIGURATION_ERROR";
     // Container
@@ -120,6 +128,7 @@ export var ErrorCode;
     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_LISTENER_LIMIT_EXCEEDED"] = "ERR_EVENT_LISTENER_LIMIT_EXCEEDED";
     ErrorCode["EVENT_TIMEOUT"] = "ERR_EVENT_TIMEOUT";
     ErrorCode["EVENT_SERIALIZATION_FAILED"] = "ERR_EVENT_SERIALIZATION_FAILED";
     ErrorCode["EVENT_DESERIALIZATION_FAILED"] = "ERR_EVENT_DESERIALIZATION_FAILED";

package/dist/domain/cqrs/cqrsError.result.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Errors raised when a failed command or query result is unwrapped.
+ */
+import { CqrsError } from "./cqrsError.base.js";
+/**
+ * Thrown by `unwrapCommandResult` for a result whose status is `"failure"`.
+ *
+ * `failure` holds the failure payload the result carried, which is also the
+ * error's `cause`. Not exposed to clients: the payload is an internal value.
+ */
+export declare class CommandFailedError extends CqrsError {
+    readonly commandType: string;
+    readonly failure: unknown;
+    constructor(commandType: string, failure: unknown);
+}
+/**
+ * Thrown by `unwrapQueryResult` for a result whose status is `"failure"`.
+ *
+ * `failure` holds the failure payload the result carried, which is also the
+ * error's `cause`. Not exposed to clients: the payload is an internal value.
+ */
+export declare class QueryFailedError extends CqrsError {
+    readonly queryType: string;
+    readonly failure: unknown;
+    constructor(queryType: string, failure: unknown);
+}
+//# sourceMappingURL=cqrsError.result.d.ts.map

package/dist/domain/cqrs/cqrsError.result.js

@@ -0,0 +1,50 @@
+/**
+ * Errors raised when a failed command or query result is unwrapped.
+ */
+import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { CqrsError } from "./cqrsError.base.js";
+/**
+ * Thrown by `unwrapCommandResult` for a result whose status is `"failure"`.
+ *
+ * `failure` holds the failure payload the result carried, which is also the
+ * error's `cause`. Not exposed to clients: the payload is an internal value.
+ */
+export class CommandFailedError extends CqrsError {
+    commandType;
+    failure;
+    constructor(commandType, failure) {
+        super(`Command "${commandType}" failed.`, {
+            code: ErrorCode.COMMAND_FAILED,
+            statusCode: 500,
+            expose: false,
+            isOperational: true,
+            cause: failure,
+            metadata: { commandType },
+        });
+        this.commandType = commandType;
+        this.failure = failure;
+    }
+}
+/**
+ * Thrown by `unwrapQueryResult` for a result whose status is `"failure"`.
+ *
+ * `failure` holds the failure payload the result carried, which is also the
+ * error's `cause`. Not exposed to clients: the payload is an internal value.
+ */
+export class QueryFailedError extends CqrsError {
+    queryType;
+    failure;
+    constructor(queryType, failure) {
+        super(`Query "${queryType}" failed.`, {
+            code: ErrorCode.QUERY_FAILED,
+            statusCode: 500,
+            expose: false,
+            isOperational: true,
+            cause: failure,
+            metadata: { queryType },
+        });
+        this.queryType = queryType;
+        this.failure = failure;
+    }
+}
+//# sourceMappingURL=cqrsError.result.js.map

package/dist/domain/cqrs/index.d.ts

@@ -4,4 +4,5 @@
  * Command/query bus errors.
  */
 export * from "./cqrsError.base.js";
+export * from "./cqrsError.result.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/domain/cqrs/index.js

@@ -4,4 +4,5 @@
  * Command/query bus errors.
  */
 export * from "./cqrsError.base.js";
+export * from "./cqrsError.result.js";
 //# sourceMappingURL=index.js.map

package/dist/domain/event/event.error.d.ts

@@ -4,6 +4,6 @@
 export { EventError, createEventError, isEventError, toEventError, } from "./eventError.base.js";
 export type { EventErrorOptions } from "./eventError.base.js";
 export { EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, EventMiddlewareError, } from "./eventError.handler.js";
-export { EventPublishError, InvalidEventError, EventTypeNotFoundError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventBusDisposedError, EventTimeoutError, } from "./eventError.lifecycle.js";
+export { EventPublishError, InvalidEventError, EventTypeNotFoundError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventBusDisposedError, EventBusStoppedError, EventListenerLimitExceededError, EventTimeoutError, } from "./eventError.lifecycle.js";
 export { EventSerializationError, EventDeserializationError, } from "./eventError.serialization.js";
 //# sourceMappingURL=event.error.d.ts.map

package/dist/domain/event/event.error.js

@@ -3,6 +3,6 @@
  */
 export { EventError, createEventError, isEventError, toEventError, } from "./eventError.base.js";
 export { EventHandlerError, createEventHandlerError, EventHandlerNotFoundError, DuplicateEventHandlerError, EventMiddlewareError, } from "./eventError.handler.js";
-export { EventPublishError, InvalidEventError, EventTypeNotFoundError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventBusDisposedError, EventTimeoutError, } from "./eventError.lifecycle.js";
+export { EventPublishError, InvalidEventError, EventTypeNotFoundError, DuplicateEventDefinitionError, EventDefinitionNotFoundError, EventDispatchAbortedError, EventEmitterDisposedError, EventRegistryDisposedError, EventSubscriptionClosedError, EventBusDisposedError, EventBusStoppedError, EventListenerLimitExceededError, EventTimeoutError, } from "./eventError.lifecycle.js";
 export { EventSerializationError, EventDeserializationError, } from "./eventError.serialization.js";
 //# sourceMappingURL=event.error.js.map

package/dist/domain/event/eventError.lifecycle.d.ts

@@ -62,6 +62,30 @@ export declare class EventSubscriptionClosedError extends EventError {
 export declare class EventBusDisposedError extends EventError {
     constructor();
 }
+/**
+ * Error thrown when publishing or subscribing on a stopped event bus.
+ * Call `start()` to resume.
+ */
+export declare class EventBusStoppedError extends EventError {
+    readonly operation: string;
+    constructor(operation: string);
+}
+/**
+ * Error thrown when a pattern exceeds its configured handler limit.
+ *
+ * The limit exists to catch a subscribe-without-unsubscribe leak. Registering
+ * past it is a programming fault rather than bad input, so this is reported as
+ * internal and is never exposed to a caller.
+ *
+ * A registry only raises this when it is configured to enforce the limit;
+ * the default is a one-shot warning, which does not interrupt registration.
+ */
+export declare class EventListenerLimitExceededError extends EventError {
+    readonly pattern: string;
+    readonly count: number;
+    readonly limit: number;
+    constructor(pattern: string, count: number, limit: number);
+}
 /** Error thrown when an event operation times out. */
 export declare class EventTimeoutError extends EventError {
     readonly timeoutMs: number;

package/dist/domain/event/eventError.lifecycle.js

@@ -130,6 +130,54 @@ export class EventBusDisposedError extends EventError {
         });
     }
 }
+/**
+ * Error thrown when publishing or subscribing on a stopped event bus.
+ * Call `start()` to resume.
+ */
+export class EventBusStoppedError extends EventError {
+    operation;
+    constructor(operation) {
+        super(`Cannot ${operation} on a stopped event bus. Call start() first.`, {
+            code: ErrorCode.LIFECYCLE_STATE,
+            statusCode: 500,
+            expose: false,
+            isOperational: true,
+            metadata: { operation },
+        });
+        this.operation = operation;
+    }
+}
+/**
+ * Error thrown when a pattern exceeds its configured handler limit.
+ *
+ * The limit exists to catch a subscribe-without-unsubscribe leak. Registering
+ * past it is a programming fault rather than bad input, so this is reported as
+ * internal and is never exposed to a caller.
+ *
+ * A registry only raises this when it is configured to enforce the limit;
+ * the default is a one-shot warning, which does not interrupt registration.
+ */
+export class EventListenerLimitExceededError extends EventError {
+    pattern;
+    count;
+    limit;
+    constructor(pattern, count, limit) {
+        assertFiniteNonNegative("count", count);
+        assertFiniteNonNegative("limit", limit);
+        super(`Possible event handler leak: ${count} handlers registered for ` +
+            `"${pattern}" (limit ${limit}). Unsubscribe handlers you no longer ` +
+            "need or raise maxHandlersPerPattern / maxListeners.", {
+            code: ErrorCode.EVENT_LISTENER_LIMIT_EXCEEDED,
+            metadata: { pattern, count, limit },
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
+        });
+        this.pattern = pattern;
+        this.count = count;
+        this.limit = limit;
+    }
+}
 /** Error thrown when an event operation times out. */
 export class EventTimeoutError extends EventError {
     timeoutMs;

package/dist/domain/rpc/rpcError.base.d.ts

@@ -9,10 +9,19 @@ import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
 export interface RPCErrorOptions extends Omit<BaseErrorOptions, "category"> {
     readonly category?: ErrorCategory;
     readonly procedureName?: string;
+    /** Structured, caller-safe detail sent with the error's wire payload. */
+    readonly details?: unknown;
 }
 /** Base error for all RPC failures. */
 export declare class RPCError extends BaseError {
     readonly procedureName?: string;
+    /**
+     * Structured, caller-safe detail carried by the wire payload — validation
+     * issues, `{ retryAfter }` for a rate limit, or whatever a custom error
+     * sent. Set on errors an RPC client rebuilds from a response; `undefined`
+     * when the payload had none.
+     */
+    readonly details?: unknown;
     constructor(message: string, options?: RPCErrorOptions);
     toJSON(): {
         name: string;
@@ -27,6 +36,7 @@ export declare class RPCError extends BaseError {
         stack?: string;
         cause?: import("../../base/types/baseError.type.js").SerializedBaseError | unknown;
         procedureName?: string | undefined;
+        details?: {} | null | undefined;
     };
 }
 /** Creates an RPC error. */

package/dist/domain/rpc/rpcError.base.js

@@ -19,6 +19,13 @@ export class RPCError extends BaseError {
             isOperational: options.isOperational ?? true,
         });
         this.procedureName = options.procedureName;
+        if (options.details !== undefined) {
+            Object.defineProperty(this, "details", {
+                value: options.details,
+                enumerable: true,
+                configurable: true,
+            });
+        }
     }
     toJSON() {
         return {
@@ -26,6 +33,7 @@ export class RPCError extends BaseError {
             ...(this.procedureName !== undefined
                 ? { procedureName: this.procedureName }
                 : {}),
+            ...(this.details !== undefined ? { details: this.details } : {}),
         };
     }
 }

package/dist/domain/schema/schemaError.base.d.ts

@@ -5,10 +5,16 @@ import { BaseError } from "../../base/core/baseError.core.js";
 import type { BaseErrorOptions } from "../../base/types/baseError.type.js";
 import { ErrorCategory } from "../../base/types/errorCategory.type.js";
 import { ErrorSeverity } from "../../base/types/errorSeverity.type.js";
-/** Options for constructing a SchemaError. */
-export interface SchemaErrorOptions extends Omit<BaseErrorOptions, "category"> {
+/**
+ * Options for constructing a SchemaError.
+ *
+ * @typeParam TIssue - Shape of one issue. `@zudojs/errors` cannot know it
+ *   (the schema package sits above it), so it defaults to `unknown`;
+ *   `@zudojs/schema` throws `SchemaError<SchemaIssue>`.
+ */
+export interface SchemaErrorOptions<TIssue = unknown> extends Omit<BaseErrorOptions, "category"> {
     readonly category?: ErrorCategory;
-    readonly issues?: readonly unknown[];
+    readonly issues?: readonly TIssue[];
 }
 /**
  * Base error for all schema validation failures.
@@ -19,9 +25,9 @@ export interface SchemaErrorOptions extends Omit<BaseErrorOptions, "category"> {
  * (`value`, `received`, `input`, `actual`) with a type/size description so
  * that secrets submitted by a client are never echoed back or logged.
  */
-export declare class SchemaError extends BaseError {
-    readonly issues: readonly unknown[];
-    constructor(message: string, options?: SchemaErrorOptions);
+export declare class SchemaError<TIssue = unknown> extends BaseError {
+    readonly issues: readonly TIssue[];
+    constructor(message: string, options?: SchemaErrorOptions<TIssue>);
     /** Returns whether any issues were recorded. */
     hasIssues(): boolean;
     /** Returns a serialized representation including (redacted) issues. */
@@ -37,11 +43,11 @@ export declare class SchemaError extends BaseError {
         metadata: Readonly<import("../../index.js").ErrorMetadata>;
         stack?: string;
         cause?: import("../../base/types/baseError.type.js").SerializedBaseError | unknown;
-        issues: readonly unknown[];
+        issues: readonly TIssue[];
     };
 }
 /** Creates a schema error. */
-export declare function createSchemaError(message: string, options?: SchemaErrorOptions): SchemaError;
+export declare function createSchemaError<TIssue = unknown>(message: string, options?: SchemaErrorOptions<TIssue>): SchemaError<TIssue>;
 /** Determines whether an unknown value is a SchemaError. */
 export declare function isSchemaError(value: unknown): value is SchemaError;
 //# sourceMappingURL=schemaError.base.d.ts.map

package/dist/domain/serialization/serializationError.types.d.ts

@@ -42,14 +42,21 @@ export declare class CircularReferenceError extends SerializationError {
 /**
  * Error thrown when maximum serialization depth is exceeded.
  *
- * Over-deep data is a server-side data bug, so this is an internal (500) error.
+ * By default over-deep data is a server-side data bug, so this is an
+ * internal (500) error. Code that checks UNTRUSTED input (for example
+ * `assertDepthWithinLimit` in `@zudojs/validation`) passes
+ * `{ statusCode: 400, expose: true }`: too-deep client input is a client
+ * error. The message holds only the two numbers, so it is safe to expose.
  */
 export declare class SerializationDepthError extends SerializationError {
     readonly depth: number;
     readonly maxDepth: number;
     /** @deprecated Use `maxDepth`. */
     readonly maxDepthValue: number;
-    constructor(depth: number, maxDepth: number);
+    constructor(depth: number, maxDepth: number, options?: {
+        readonly statusCode?: number;
+        readonly expose?: boolean;
+    });
 }
 /** Error thrown when a serialized payload exceeds the size limit. */
 export declare class SerializationPayloadTooLargeError extends SerializationError {

package/dist/domain/serialization/serializationError.types.js

@@ -74,20 +74,24 @@ export class CircularReferenceError extends SerializationError {
 /**
  * Error thrown when maximum serialization depth is exceeded.
  *
- * Over-deep data is a server-side data bug, so this is an internal (500) error.
+ * By default over-deep data is a server-side data bug, so this is an
+ * internal (500) error. Code that checks UNTRUSTED input (for example
+ * `assertDepthWithinLimit` in `@zudojs/validation`) passes
+ * `{ statusCode: 400, expose: true }`: too-deep client input is a client
+ * error. The message holds only the two numbers, so it is safe to expose.
  */
 export class SerializationDepthError extends SerializationError {
     depth;
     maxDepth;
     /** @deprecated Use `maxDepth`. */
     maxDepthValue;
-    constructor(depth, maxDepth) {
+    constructor(depth, maxDepth, options = {}) {
         super(`Maximum serialization depth exceeded: ${depth} > ${maxDepth}`, {
             code: ErrorCode.MAX_DEPTH_EXCEEDED,
             depth,
             maxDepth,
-            statusCode: 500,
-            expose: false,
+            statusCode: options.statusCode ?? 500,
+            expose: options.expose ?? false,
         });
         this.depth = depth;
         this.maxDepth = maxDepth;

package/dist/domain/transaction/transactionError.types.d.ts

@@ -20,8 +20,23 @@ export declare class TransactionRollbackError extends TransactionError {
     constructor(transactionId: string, options?: {
         readonly cause?: unknown;
         readonly originalError?: unknown;
+        /** Overrides the default "rollback failed" message (for subclasses). */
+        readonly message?: string;
     });
 }
+/**
+ * A commit was refused because the transaction was marked rollback-only;
+ * the transaction was rolled back instead.
+ *
+ * Distinct from a rollback that *failed*. It extends
+ * `TransactionRollbackError`, so existing `instanceof` checks and the
+ * `ERR_DATABASE_TRANSACTION` code still match, while the message and
+ * class say what actually happened. `metadata.originalError` carries the
+ * reason passed to `markRollbackOnly`.
+ */
+export declare class TransactionRollbackOnlyError extends TransactionRollbackError {
+    constructor(transactionId: string, reason?: unknown);
+}
 /** The underlying adapter threw an error. */
 export declare class TransactionAdapterError extends TransactionError {
     constructor(message: string, cause?: unknown);

package/dist/domain/transaction/transactionError.types.js

@@ -35,7 +35,7 @@ export class TransactionCommitError extends TransactionError {
 /** Transaction rollback failed. */
 export class TransactionRollbackError extends TransactionError {
     constructor(transactionId, options) {
-        super(`Transaction "${transactionId}" rollback failed`, {
+        super(options?.message ?? `Transaction "${transactionId}" rollback failed`, {
             code: ErrorCode.DATABASE_TRANSACTION,
             cause: options?.cause,
             metadata: {
@@ -47,6 +47,24 @@ export class TransactionRollbackError extends TransactionError {
         });
     }
 }
+/**
+ * A commit was refused because the transaction was marked rollback-only;
+ * the transaction was rolled back instead.
+ *
+ * Distinct from a rollback that *failed*. It extends
+ * `TransactionRollbackError`, so existing `instanceof` checks and the
+ * `ERR_DATABASE_TRANSACTION` code still match, while the message and
+ * class say what actually happened. `metadata.originalError` carries the
+ * reason passed to `markRollbackOnly`.
+ */
+export class TransactionRollbackOnlyError extends TransactionRollbackError {
+    constructor(transactionId, reason) {
+        super(transactionId, {
+            originalError: reason ?? "marked rollback-only",
+            message: `Transaction "${transactionId}" commit refused: transaction marked rollback-only`,
+        });
+    }
+}
 /** The underlying adapter threw an error. */
 export class TransactionAdapterError extends TransactionError {
     constructor(message, cause) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/errors",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Shared error base class, error codes, and error handling utilities for the Zudojs framework.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
   "dependencies": {},
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -40,7 +40,7 @@
     "errors",
     "error-handling"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-errors",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },