@zudojs/errors 0.1.0 → 1.0.0

package/dist/domain/plugin/pluginError.runtime.js

@@ -2,33 +2,38 @@
  * Plugin runtime error classes — timeout, state transitions.
  */
 import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { assertFiniteNonNegative } from "../shared/domainError.helpers.js";
 import { PluginError } from "./pluginError.base.js";
 /** Error thrown when a plugin operation times out. */
 export class PluginTimeoutError extends PluginError {
     constructor(pluginName, timeout, options = {}) {
+        assertFiniteNonNegative("timeout", timeout);
         super(`Plugin "${pluginName}" timed out after ${timeout}ms.`, {
             ...options,
             code: ErrorCode.PLUGIN_TIMEOUT,
             pluginName,
             statusCode: 504,
             expose: false,
-            metadata: { timeout },
+            metadata: { ...options.metadata, timeout },
         });
-        this.name = "PluginTimeoutError";
     }
 }
-/** Error thrown when an invalid plugin state transition is attempted. */
+/**
+ * Error thrown when an invalid plugin state transition is attempted.
+ *
+ * Plugin state is server-side; reported as internal (500, not exposed).
+ */
 export class PluginStateError extends PluginError {
     constructor(pluginName, fromState, toState, options = {}) {
         super(`Cannot transition plugin "${pluginName}" from "${fromState}" to "${toState}".`, {
             ...options,
             code: ErrorCode.PLUGIN_STATE,
             pluginName,
-            statusCode: 400,
-            expose: true,
-            metadata: { fromState, toState },
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
+            metadata: { ...options.metadata, fromState, toState },
         });
-        this.name = "PluginStateError";
     }
 }
 //# sourceMappingURL=pluginError.runtime.js.map

package/dist/domain/queue/queueError.base.d.ts

@@ -4,17 +4,36 @@
 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 creating a queue error. */
 export interface QueueErrorOptions extends Omit<BaseErrorOptions, "category"> {
     readonly category?: ErrorCategory;
     readonly queueName?: string;
     readonly jobId?: string;
+    readonly workerId?: string;
 }
 /** Base error for all queue subsystem failures. */
 export declare class QueueError extends BaseError {
     readonly queueName?: string;
     readonly jobId?: string;
+    readonly workerId?: string;
     constructor(message: string, options?: QueueErrorOptions);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        statusCode: number;
+        expose: boolean;
+        isOperational: boolean;
+        metadata: Readonly<import("../../index.js").ErrorMetadata>;
+        stack?: string;
+        cause?: import("../../base/types/baseError.type.js").SerializedBaseError | unknown;
+        queueName?: string | undefined;
+        jobId?: string | undefined;
+        workerId?: string | undefined;
+    };
 }
 /** Check if an error is a QueueError. */
 export declare function isQueueError(error: unknown): error is QueueError;

package/dist/domain/queue/queueError.base.js

@@ -5,22 +5,43 @@ 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 { safeErrorMessage } from "../shared/domainError.helpers.js";
 /** Base error for all queue subsystem failures. */
 export class QueueError extends BaseError {
     queueName;
     jobId;
+    workerId;
     constructor(message, options = {}) {
         super(message, {
+            ...options,
             code: options.code ?? ErrorCode.QUEUE_ERROR,
             category: options.category ?? ErrorCategory.QUEUE,
             severity: options.severity ?? ErrorSeverity.WARNING,
-            cause: options.cause,
-            metadata: options.metadata,
+            statusCode: options.statusCode ?? 500,
             expose: options.expose ?? false,
             isOperational: options.isOperational ?? true,
+            metadata: {
+                ...options.metadata,
+                ...(options.queueName !== undefined
+                    ? { queueName: options.queueName }
+                    : {}),
+                ...(options.jobId !== undefined ? { jobId: options.jobId } : {}),
+                ...(options.workerId !== undefined
+                    ? { workerId: options.workerId }
+                    : {}),
+            },
         });
         this.queueName = options.queueName;
         this.jobId = options.jobId;
+        this.workerId = options.workerId;
+    }
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            ...(this.queueName !== undefined ? { queueName: this.queueName } : {}),
+            ...(this.jobId !== undefined ? { jobId: this.jobId } : {}),
+            ...(this.workerId !== undefined ? { workerId: this.workerId } : {}),
+        };
     }
 }
 /** Check if an error is a QueueError. */
@@ -32,8 +53,7 @@ export function toQueueError(error, options = {}) {
     if (error instanceof QueueError) {
         return error;
     }
-    const message = error instanceof Error ? error.message : String(error);
-    return new QueueError(message, {
+    return new QueueError(safeErrorMessage(error), {
         cause: error,
         ...options,
     });

package/dist/domain/queue/queueError.job.js

@@ -2,6 +2,7 @@
  * Job-specific error classes.
  */
 import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { assertFiniteNonNegative } from "../shared/domainError.helpers.js";
 import { QueueError } from "./queueError.base.js";
 /** Error thrown for general job failures. */
 export class JobError extends QueueError {
@@ -30,6 +31,7 @@ export class JobNotFoundError extends QueueError {
 export class JobTimeoutError extends QueueError {
     timeoutMs;
     constructor(jobId, timeoutMs, options = {}) {
+        assertFiniteNonNegative("timeoutMs", timeoutMs);
         super(`Job "${jobId}" exceeded the timeout of ${timeoutMs}ms.`, {
             code: ErrorCode.JOB_TIMEOUT,
             queueName: options.queueName,

package/dist/domain/queue/queueError.worker.d.ts

@@ -4,16 +4,22 @@
 import { QueueError } from "./queueError.base.js";
 /** Error thrown for worker failures. */
 export declare class WorkerError extends QueueError {
-    readonly workerId?: string;
     constructor(message: string, options?: {
         workerId?: string;
         queueName?: string;
         cause?: unknown;
     });
 }
-/** Error thrown when a worker is not found. */
+/**
+ * Error thrown when a worker is not found.
+ *
+ * Workers are server-side components, so this is reported as an internal
+ * failure and is not exposed to clients.
+ */
 export declare class WorkerNotFoundError extends QueueError {
-    constructor(workerId: string);
+    constructor(workerId: string, options?: {
+        queueName?: string;
+    });
 }
 /** Error thrown for worker lifecycle failures. */
 export declare class WorkerLifecycleError extends QueueError {

package/dist/domain/queue/queueError.worker.js

@@ -5,23 +5,30 @@ import { ErrorCode } from "../../base/types/errorCode.type.js";
 import { QueueError } from "./queueError.base.js";
 /** Error thrown for worker failures. */
 export class WorkerError extends QueueError {
-    workerId;
     constructor(message, options = {}) {
         super(message, {
             code: ErrorCode.WORKER_ERROR,
             queueName: options.queueName,
+            workerId: options.workerId,
             cause: options.cause,
         });
-        this.workerId = options.workerId;
     }
 }
-/** Error thrown when a worker is not found. */
+/**
+ * Error thrown when a worker is not found.
+ *
+ * Workers are server-side components, so this is reported as an internal
+ * failure and is not exposed to clients.
+ */
 export class WorkerNotFoundError extends QueueError {
-    constructor(workerId) {
+    constructor(workerId, options = {}) {
         super(`Worker "${workerId}" was not found.`, {
             code: ErrorCode.WORKER_NOT_FOUND,
-            statusCode: 404,
-            expose: true,
+            workerId,
+            queueName: options.queueName,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
     }
 }
@@ -31,6 +38,7 @@ export class WorkerLifecycleError extends QueueError {
         super(message, {
             code: ErrorCode.WORKER_LIFECYCLE,
             queueName: options.queueName,
+            workerId: options.workerId,
             cause: options.cause,
         });
     }

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

@@ -46,7 +46,6 @@ export class RPCProcedureNotFoundError extends RPCError {
             statusCode: 404,
             expose: true,
         });
-        this.name = "RPCProcedureNotFoundError";
     }
 }
 /** Error thrown when an RPC request is invalid. */
@@ -58,7 +57,6 @@ export class RPCInvalidRequestError extends RPCError {
             statusCode: 400,
             expose: true,
         });
-        this.name = "RPCInvalidRequestError";
     }
 }
 //# sourceMappingURL=rpcError.base.js.map

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

@@ -14,7 +14,6 @@ export class RPCValidationError extends RPCError {
             statusCode: 422,
             expose: true,
         });
-        this.name = "RPCValidationError";
         this.issues = Object.freeze([...issues]);
     }
 }
@@ -27,7 +26,6 @@ export class RPCAuthenticationError extends RPCError {
             statusCode: 401,
             expose: true,
         });
-        this.name = "RPCAuthenticationError";
     }
 }
 /** Error thrown when RPC authorization fails. */
@@ -39,7 +37,6 @@ export class RPCForbiddenError extends RPCError {
             statusCode: 403,
             expose: true,
         });
-        this.name = "RPCForbiddenError";
     }
 }
 /** Error thrown when an unexpected internal RPC error occurs. */
@@ -52,7 +49,6 @@ export class RPCInternalError extends RPCError {
             expose: false,
             isOperational: false,
         });
-        this.name = "RPCInternalError";
     }
 }
 /** Error thrown when RPC serialization fails. */
@@ -64,7 +60,6 @@ export class RPCSerializationError extends RPCError {
             statusCode: 500,
             expose: false,
         });
-        this.name = "RPCSerializationError";
     }
 }
 /** Error thrown when RPC deserialization fails. */
@@ -76,7 +71,6 @@ export class RPCDeserializationError extends RPCError {
             statusCode: 400,
             expose: true,
         });
-        this.name = "RPCDeserializationError";
     }
 }
 /** Error thrown when a duplicate RPC procedure is registered. */
@@ -88,7 +82,6 @@ export class RPCDuplicateProcedureError extends RPCError {
             statusCode: 409,
             expose: true,
         });
-        this.name = "RPCDuplicateProcedureError";
     }
 }
 //# sourceMappingURL=rpcError.protocol.js.map

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

@@ -19,8 +19,17 @@ export declare class RPCTransportError extends RPCError {
 export declare class RPCUnavailableError extends RPCError {
     constructor(message?: string, procedureName?: string);
 }
-/** Error thrown when an RPC rate limit is exceeded. */
+/**
+ * Error thrown when an RPC rate limit is exceeded.
+ *
+ * `retryAfter` is expressed in seconds (as the HTTP `Retry-After` header);
+ * fractional values are rounded up and the value is only recorded in
+ * metadata (as `retryAfterSeconds`) when provided.
+ */
 export declare class RPCRateLimitedError extends RPCError {
+    /** Seconds to wait before retrying, if known. */
+    readonly retryAfterSeconds?: number;
+    /** @deprecated Use `retryAfterSeconds`. */
     readonly retryAfter?: number;
     constructor(message?: string, retryAfter?: number, procedureName?: string);
 }

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

@@ -2,11 +2,13 @@
  * RPC transport error classes — timeout, cancelled, availability.
  */
 import { ErrorCode } from "../../base/types/errorCode.type.js";
+import { assertFiniteNonNegative, normalizeRetryAfterSeconds, } from "../shared/domainError.helpers.js";
 import { RPCError } from "./rpcError.base.js";
 /** Error thrown when an RPC operation times out. */
 export class RPCTimeoutError extends RPCError {
     timeout;
     constructor(timeout, procedureName) {
+        assertFiniteNonNegative("timeout", timeout);
         super(`RPC operation timed out after ${timeout}ms.`, {
             code: ErrorCode.RPC_TIMEOUT,
             procedureName,
@@ -14,7 +16,6 @@ export class RPCTimeoutError extends RPCError {
             statusCode: 504,
             expose: false,
         });
-        this.name = "RPCTimeoutError";
         this.timeout = timeout;
     }
 }
@@ -27,7 +28,6 @@ export class RPCCancelledError extends RPCError {
             statusCode: 499,
             expose: false,
         });
-        this.name = "RPCCancelledError";
     }
 }
 /** Error thrown when an RPC transport error occurs. */
@@ -39,7 +39,6 @@ export class RPCTransportError extends RPCError {
             statusCode: 502,
             expose: false,
         });
-        this.name = "RPCTransportError";
     }
 }
 /** Error thrown when an RPC service is unavailable. */
@@ -51,27 +50,39 @@ export class RPCUnavailableError extends RPCError {
             statusCode: 503,
             expose: true,
         });
-        this.name = "RPCUnavailableError";
     }
 }
-/** Error thrown when an RPC rate limit is exceeded. */
+/**
+ * Error thrown when an RPC rate limit is exceeded.
+ *
+ * `retryAfter` is expressed in seconds (as the HTTP `Retry-After` header);
+ * fractional values are rounded up and the value is only recorded in
+ * metadata (as `retryAfterSeconds`) when provided.
+ */
 export class RPCRateLimitedError extends RPCError {
+    /** Seconds to wait before retrying, if known. */
+    retryAfterSeconds;
+    /** @deprecated Use `retryAfterSeconds`. */
     retryAfter;
     constructor(message = "RPC rate limit exceeded.", retryAfter, procedureName) {
+        const retryAfterSeconds = retryAfter !== undefined
+            ? normalizeRetryAfterSeconds(retryAfter, "retryAfter")
+            : undefined;
         super(message, {
             code: ErrorCode.RPC_RATE_LIMITED,
             procedureName,
-            metadata: { retryAfter },
+            metadata: retryAfterSeconds !== undefined ? { retryAfterSeconds } : {},
             statusCode: 429,
             expose: true,
         });
-        this.name = "RPCRateLimitedError";
-        this.retryAfter = retryAfter;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.retryAfter = retryAfterSeconds;
     }
 }
 /** Error thrown when an RPC deadline is exceeded. */
 export class RPCDeadlineExceededError extends RPCError {
     constructor(deadline, procedureName) {
+        assertFiniteNonNegative("deadline", deadline);
         super(`RPC deadline exceeded at ${deadline}.`, {
             code: ErrorCode.RPC_DEADLINE_EXCEEDED,
             procedureName,
@@ -79,7 +90,6 @@ export class RPCDeadlineExceededError extends RPCError {
             statusCode: 504,
             expose: false,
         });
-        this.name = "RPCDeadlineExceededError";
     }
 }
 //# sourceMappingURL=rpcError.transport.js.map

package/dist/domain/scheduler/schedulerError.base.d.ts

@@ -36,15 +36,29 @@ export declare class SchedulerError extends BaseError {
 export declare function createSchedulerError(message: string, options?: SchedulerErrorOptions): SchedulerError;
 /** Determines whether an unknown value is a SchedulerError. */
 export declare function isSchedulerError(value: unknown): value is SchedulerError;
-/** Error thrown when the scheduler has not been started. */
+/**
+ * Error thrown when the scheduler has not been started.
+ *
+ * Scheduler state is a server-side concern: reported as 503 (temporarily
+ * unavailable), not exposed, non-operational.
+ */
 export declare class SchedulerNotStartedError extends SchedulerError {
     constructor();
 }
-/** Error thrown when the scheduler is already started. */
+/**
+ * Error thrown when the scheduler is already started.
+ *
+ * Scheduler state is a server-side concern: reported as internal.
+ */
 export declare class SchedulerAlreadyStartedError extends SchedulerError {
     constructor();
 }
-/** Error thrown when the scheduler is stopped. */
+/**
+ * Error thrown when the scheduler is stopped.
+ *
+ * Scheduler state is a server-side concern: reported as 503 (temporarily
+ * unavailable), not exposed, non-operational.
+ */
 export declare class SchedulerStoppedError extends SchedulerError {
     constructor();
 }

package/dist/domain/scheduler/schedulerError.base.js

@@ -38,37 +38,51 @@ export function createSchedulerError(message, options = {}) {
 export function isSchedulerError(value) {
     return value instanceof SchedulerError;
 }
-/** Error thrown when the scheduler has not been started. */
+/**
+ * Error thrown when the scheduler has not been started.
+ *
+ * Scheduler state is a server-side concern: reported as 503 (temporarily
+ * unavailable), not exposed, non-operational.
+ */
 export class SchedulerNotStartedError extends SchedulerError {
     constructor() {
         super("Scheduler has not been started.", {
             code: ErrorCode.SCHEDULER_NOT_STARTED,
-            statusCode: 400,
-            expose: true,
+            statusCode: 503,
+            expose: false,
+            isOperational: false,
         });
-        this.name = "SchedulerNotStartedError";
     }
 }
-/** Error thrown when the scheduler is already started. */
+/**
+ * Error thrown when the scheduler is already started.
+ *
+ * Scheduler state is a server-side concern: reported as internal.
+ */
 export class SchedulerAlreadyStartedError extends SchedulerError {
     constructor() {
         super("Scheduler is already started.", {
             code: ErrorCode.SCHEDULER_ALREADY_STARTED,
-            statusCode: 400,
-            expose: true,
+            statusCode: 500,
+            expose: false,
+            isOperational: false,
         });
-        this.name = "SchedulerAlreadyStartedError";
     }
 }
-/** Error thrown when the scheduler is stopped. */
+/**
+ * Error thrown when the scheduler is stopped.
+ *
+ * Scheduler state is a server-side concern: reported as 503 (temporarily
+ * unavailable), not exposed, non-operational.
+ */
 export class SchedulerStoppedError extends SchedulerError {
     constructor() {
         super("Scheduler is stopped.", {
             code: ErrorCode.SCHEDULER_STOPPED,
-            statusCode: 400,
-            expose: true,
+            statusCode: 503,
+            expose: false,
+            isOperational: false,
         });
-        this.name = "SchedulerStoppedError";
     }
 }
 /** Error thrown when a job is not found. */
@@ -80,7 +94,6 @@ export class SchedulerJobNotFoundError extends SchedulerError {
             statusCode: 404,
             expose: true,
         });
-        this.name = "SchedulerJobNotFoundError";
     }
 }
 /** Error thrown when a job already exists. */
@@ -92,7 +105,6 @@ export class SchedulerJobAlreadyExistsError extends SchedulerError {
             statusCode: 409,
             expose: true,
         });
-        this.name = "SchedulerJobAlreadyExistsError";
     }
 }
 /** Error thrown when a job definition is invalid. */
@@ -104,7 +116,6 @@ export class InvalidJobError extends SchedulerError {
             statusCode: 400,
             expose: true,
         });
-        this.name = "InvalidJobError";
     }
 }
 //# sourceMappingURL=schedulerError.base.js.map

package/dist/domain/scheduler/schedulerError.execution.d.ts

@@ -1,25 +1,26 @@
 /**
  * Scheduler execution error classes — job execution, timeout, cancellation, store, lock.
  */
-import { SchedulerError } from "./schedulerError.base.js";
+import { SchedulerError, type SchedulerErrorOptions } from "./schedulerError.base.js";
 /** Error thrown when a job execution fails. */
 export declare class SchedulerJobExecutionError extends SchedulerError {
-    constructor(message: string, jobId?: string, scheduleId?: string);
+    constructor(message: string, jobId?: string, scheduleId?: string, options?: SchedulerErrorOptions);
 }
 /** Error thrown when a job times out. */
 export declare class SchedulerJobTimeoutError extends SchedulerError {
-    constructor(timeout: number, jobId?: string);
+    readonly timeout: number;
+    constructor(timeout: number, jobId?: string, options?: SchedulerErrorOptions);
 }
 /** Error thrown when a job is cancelled. */
 export declare class SchedulerJobCancelledError extends SchedulerError {
-    constructor(message?: string, jobId?: string);
+    constructor(message?: string, jobId?: string, options?: SchedulerErrorOptions);
 }
 /** Error thrown when the scheduler store encounters an error. */
 export declare class SchedulerStoreError extends SchedulerError {
-    constructor(message: string, scheduleId?: string);
+    constructor(message: string, scheduleId?: string, options?: SchedulerErrorOptions);
 }
 /** Error thrown when the scheduler lock encounters an error. */
 export declare class SchedulerLockError extends SchedulerError {
-    constructor(message: string, scheduleId?: string);
+    constructor(message: string, scheduleId?: string, options?: SchedulerErrorOptions);
 }
 //# sourceMappingURL=schedulerError.execution.d.ts.map

package/dist/domain/scheduler/schedulerError.execution.js

@@ -2,67 +2,71 @@
  * Scheduler execution error classes — job execution, timeout, cancellation, store, lock.
  */
 import { ErrorCode } from "../../base/types/errorCode.type.js";
-import { SchedulerError } from "./schedulerError.base.js";
+import { assertFiniteNonNegative } from "../shared/domainError.helpers.js";
+import { SchedulerError, } from "./schedulerError.base.js";
 /** Error thrown when a job execution fails. */
 export class SchedulerJobExecutionError extends SchedulerError {
-    constructor(message, jobId, scheduleId) {
+    constructor(message, jobId, scheduleId, options = {}) {
         super(message, {
+            ...options,
             code: ErrorCode.SCHEDULER_JOB_EXECUTION_ERROR,
-            jobId,
-            scheduleId,
+            jobId: jobId ?? options.jobId,
+            scheduleId: scheduleId ?? options.scheduleId,
             statusCode: 500,
             expose: false,
         });
-        this.name = "SchedulerJobExecutionError";
     }
 }
 /** Error thrown when a job times out. */
 export class SchedulerJobTimeoutError extends SchedulerError {
-    constructor(timeout, jobId) {
+    timeout;
+    constructor(timeout, jobId, options = {}) {
+        assertFiniteNonNegative("timeout", timeout);
         super(`Job timed out after ${timeout}ms.`, {
+            ...options,
             code: ErrorCode.SCHEDULER_JOB_TIMEOUT,
-            jobId,
-            metadata: { timeout },
+            jobId: jobId ?? options.jobId,
+            metadata: { ...options.metadata, timeout },
             statusCode: 504,
             expose: false,
         });
-        this.name = "SchedulerJobTimeoutError";
+        this.timeout = timeout;
     }
 }
 /** Error thrown when a job is cancelled. */
 export class SchedulerJobCancelledError extends SchedulerError {
-    constructor(message = "Job was cancelled.", jobId) {
+    constructor(message = "Job was cancelled.", jobId, options = {}) {
         super(message, {
+            ...options,
             code: ErrorCode.SCHEDULER_JOB_CANCELLED,
-            jobId,
+            jobId: jobId ?? options.jobId,
             statusCode: 499,
             expose: false,
         });
-        this.name = "SchedulerJobCancelledError";
     }
 }
 /** Error thrown when the scheduler store encounters an error. */
 export class SchedulerStoreError extends SchedulerError {
-    constructor(message, scheduleId) {
+    constructor(message, scheduleId, options = {}) {
         super(message, {
+            ...options,
             code: ErrorCode.SCHEDULER_STORE_ERROR,
-            scheduleId,
+            scheduleId: scheduleId ?? options.scheduleId,
             statusCode: 500,
             expose: false,
         });
-        this.name = "SchedulerStoreError";
     }
 }
 /** Error thrown when the scheduler lock encounters an error. */
 export class SchedulerLockError extends SchedulerError {
-    constructor(message, scheduleId) {
+    constructor(message, scheduleId, options = {}) {
         super(message, {
+            ...options,
             code: ErrorCode.SCHEDULER_LOCK_ERROR,
-            scheduleId,
+            scheduleId: scheduleId ?? options.scheduleId,
             statusCode: 409,
             expose: false,
         });
-        this.name = "SchedulerLockError";
     }
 }
 //# sourceMappingURL=schedulerError.execution.js.map