@nextrush/errors 3.0.7 → 4.0.0-beta.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Context, Middleware, Next } from '@nextrush/types';
+import { Context, Middleware } from '@nextrush/types';
 
 /**
  * @nextrush/errors - Base Error Classes
@@ -7,6 +7,15 @@ import { Context, Middleware, Next } from '@nextrush/types';
  *
  * @packageDocumentation
  */
+/** Options accepted by {@link NextRushError.hydrate} when reconstructing errors. */
+interface HydrateOptions {
+    status?: number;
+    code?: string;
+    details?: Record<string, unknown>;
+    requestId?: string;
+    traceId?: string;
+    timestamp?: string;
+}
 /**
  * Base error class for all NextRush errors
  */
@@ -21,17 +30,45 @@ declare class NextRushError extends Error {
     readonly details?: Record<string, unknown>;
     /** Original error that caused this error */
     readonly cause?: unknown;
+    /** Correlation/request identifier for tracing across boundaries (audit E-5). */
+    readonly requestId?: string;
+    /** Distributed-trace identifier (audit E-5). */
+    readonly traceId?: string;
+    /** ISO-8601 timestamp of when the error was created, when supplied. */
+    readonly timestamp?: string;
     constructor(message: string, options?: {
         status?: number;
         code?: string;
         expose?: boolean;
         details?: Record<string, unknown>;
         cause?: unknown;
+        requestId?: string;
+        traceId?: string;
+        timestamp?: string;
     });
     /**
      * Convert error to JSON representation
      */
     toJSON(): Record<string, unknown>;
+    /**
+     * Reconstruct a {@link NextRushError} from a serialized {@link toJSON} payload
+     * (audit E-7).
+     *
+     * @remarks
+     * Enables cross-service transport: a downstream service can rebuild a typed
+     * error (with a working `instanceof NextRushError`) from the JSON it received,
+     * rather than being left with an opaque plain object. `message` falls back to
+     * a generic string when the source error was not exposed.
+     *
+     * @param json - A payload previously produced by {@link toJSON}.
+     * @returns A reconstructed {@link NextRushError}.
+     */
+    static fromJSON(json: Record<string, unknown>): NextRushError;
+    /**
+     * Shared hydration logic for {@link fromJSON} across the hierarchy.
+     * @internal
+     */
+    protected static hydrate<T extends NextRushError>(json: Record<string, unknown>, build: (message: string, options: HydrateOptions) => T): T;
     /**
      * Create a response-safe version of the error
      */
@@ -53,9 +90,52 @@ declare class HttpError extends NextRushError {
         expose?: boolean;
         details?: Record<string, unknown>;
         cause?: unknown;
+        requestId?: string;
+        traceId?: string;
+        timestamp?: string;
     });
+    /**
+     * Reconstruct an {@link HttpError} from a serialized {@link NextRushError.toJSON}
+     * payload (audit E-7).
+     *
+     * @param json - A payload previously produced by `toJSON()`.
+     * @returns A reconstructed {@link HttpError}.
+     */
+    static fromJSON(json: Record<string, unknown>): HttpError;
 }
 
+/**
+ * @nextrush/errors - Central Error Code Registry
+ *
+ * Single source of truth mapping HTTP status codes to their canonical,
+ * machine-readable error codes (audit E-4). Both the typed error classes and
+ * the {@link createError} factory resolve codes through this registry, so a
+ * given status maps to exactly one code regardless of construction path.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Canonical error code for each supported HTTP status.
+ *
+ * @remarks
+ * Keep this in sync with the typed classes in `http-errors.ts`. The
+ * `audit-fixes` test suite asserts `createError(status).code === ERROR_CODES[status]`
+ * for every entry, so drift between a class and this registry fails CI.
+ */
+declare const ERROR_CODES: Readonly<Record<number, string>>;
+/**
+ * Resolve the canonical error code for an HTTP status.
+ *
+ * @param status - HTTP status code.
+ * @returns The registered canonical code, or `HTTP_<status>` for statuses with
+ *   no dedicated class.
+ */
+declare function codeForStatus(status: number): string;
+/** Generic internal-error code used when no status-specific code applies. */
+declare const GENERIC_ERROR_CODE = "INTERNAL_ERROR";
+/** Canonical code for validation failures. */
+declare const VALIDATION_ERROR_CODE = "VALIDATION_ERROR";
+
 /**
  * @nextrush/errors - HTTP Error Classes
  *
@@ -72,6 +152,12 @@ interface HttpErrorOptions {
     expose?: boolean;
     details?: Record<string, unknown>;
     cause?: unknown;
+    /** Correlation/request identifier (audit E-5). */
+    requestId?: string;
+    /** Distributed-trace identifier (audit E-5). */
+    traceId?: string;
+    /** ISO-8601 creation timestamp (audit E-5). */
+    timestamp?: string;
 }
 /**
  * 400 Bad Request - Invalid syntax or malformed request
@@ -505,25 +591,6 @@ declare function getSafeErrorMessage(error: unknown): string;
  * @packageDocumentation
  */
 
-/**
- * Minimal context interface for error handling.
- *
- * @deprecated Use `Context` from `@nextrush/types` instead.
- * Kept for backward compatibility — will be removed in v4.
- */
-interface ErrorContext {
-    method: string;
-    path: string;
-    status: number;
-    json: (data: unknown) => void;
-}
-/**
- * Error handler middleware function type.
- *
- * @deprecated Use `Middleware` from `@nextrush/types` instead.
- * Kept for backward compatibility — will be removed in v4.
- */
-type ErrorMiddleware = Middleware;
 /**
  * Error handler options
  */
@@ -562,22 +629,5 @@ declare function errorHandler(options?: ErrorHandlerOptions): Middleware;
  * ```
  */
 declare function notFoundHandler(message?: string): Middleware;
-/**
- * Catch async errors wrapper for route handlers
- *
- * @example
- * ```typescript
- * router.get('/users/:id', catchAsync(async (ctx) => {
- *   const user = await db.users.findById(ctx.params.id);
- *   if (!user) throw new NotFoundError('User not found');
- *   ctx.json(user);
- * }));
- * ```
- *
- * @deprecated This wrapper is redundant — async errors propagate naturally
- * through the middleware chain and are caught by `errorHandler()`. Use the
- * handler directly instead.
- */
-declare function catchAsync(handler: (ctx: Context, next: Next) => Promise<void>): Middleware;
 
-export { BadGatewayError, BadRequestError, ConflictError, type ErrorContext, type ErrorHandlerOptions, type ErrorMiddleware, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorOptions, HttpVersionNotSupportedError, ImATeapotError, InsufficientStorageError, InternalServerError, InvalidEmailError, InvalidUrlError, LengthError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, NetworkAuthRequiredError, NextRushError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PatternError, PayloadTooLargeError, PaymentRequiredError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RangeNotSatisfiableError, RangeValidationError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequiredFieldError, ServiceUnavailableError, TooEarlyError, TooManyRequestsError, TypeMismatchError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, ValidationError, type ValidationIssue, VariantAlsoNegotiatesError, badGateway, badRequest, catchAsync, conflict, createError, errorHandler, forbidden, gatewayTimeout, getErrorStatus, getHttpStatusMessage, getSafeErrorMessage, internalError, isHttpError, methodNotAllowed, notFound, notFoundHandler, serviceUnavailable, tooManyRequests, unauthorized, unprocessableEntity };
+export { BadGatewayError, BadRequestError, ConflictError, ERROR_CODES, type ErrorHandlerOptions, ExpectationFailedError, FailedDependencyError, ForbiddenError, GENERIC_ERROR_CODE, GatewayTimeoutError, GoneError, HttpError, type HttpErrorOptions, HttpVersionNotSupportedError, ImATeapotError, InsufficientStorageError, InternalServerError, InvalidEmailError, InvalidUrlError, LengthError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, NetworkAuthRequiredError, NextRushError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PatternError, PayloadTooLargeError, PaymentRequiredError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RangeNotSatisfiableError, RangeValidationError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequiredFieldError, ServiceUnavailableError, TooEarlyError, TooManyRequestsError, TypeMismatchError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, VALIDATION_ERROR_CODE, ValidationError, type ValidationIssue, VariantAlsoNegotiatesError, badGateway, badRequest, codeForStatus, conflict, createError, errorHandler, forbidden, gatewayTimeout, getErrorStatus, getHttpStatusMessage, getSafeErrorMessage, internalError, isHttpError, methodNotAllowed, notFound, notFoundHandler, serviceUnavailable, tooManyRequests, unauthorized, unprocessableEntity };

package/dist/index.js

@@ -1,9 +1,76 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
+// src/codes.ts
+var ERROR_CODES = Object.freeze({
+  400: "BAD_REQUEST",
+  401: "UNAUTHORIZED",
+  402: "PAYMENT_REQUIRED",
+  403: "FORBIDDEN",
+  404: "NOT_FOUND",
+  405: "METHOD_NOT_ALLOWED",
+  406: "NOT_ACCEPTABLE",
+  407: "PROXY_AUTH_REQUIRED",
+  408: "REQUEST_TIMEOUT",
+  409: "CONFLICT",
+  410: "GONE",
+  411: "LENGTH_REQUIRED",
+  412: "PRECONDITION_FAILED",
+  413: "PAYLOAD_TOO_LARGE",
+  414: "URI_TOO_LONG",
+  415: "UNSUPPORTED_MEDIA_TYPE",
+  416: "RANGE_NOT_SATISFIABLE",
+  417: "EXPECTATION_FAILED",
+  418: "IM_A_TEAPOT",
+  422: "UNPROCESSABLE_ENTITY",
+  423: "LOCKED",
+  424: "FAILED_DEPENDENCY",
+  425: "TOO_EARLY",
+  426: "UPGRADE_REQUIRED",
+  428: "PRECONDITION_REQUIRED",
+  429: "TOO_MANY_REQUESTS",
+  431: "REQUEST_HEADER_FIELDS_TOO_LARGE",
+  451: "UNAVAILABLE_FOR_LEGAL_REASONS",
+  500: "INTERNAL_SERVER_ERROR",
+  501: "NOT_IMPLEMENTED",
+  502: "BAD_GATEWAY",
+  503: "SERVICE_UNAVAILABLE",
+  504: "GATEWAY_TIMEOUT",
+  505: "HTTP_VERSION_NOT_SUPPORTED",
+  506: "VARIANT_ALSO_NEGOTIATES",
+  507: "INSUFFICIENT_STORAGE",
+  508: "LOOP_DETECTED",
+  510: "NOT_EXTENDED",
+  511: "NETWORK_AUTH_REQUIRED"
+});
+function codeForStatus(status) {
+  return ERROR_CODES[status] ?? `HTTP_${status}`;
+}
+__name(codeForStatus, "codeForStatus");
+var GENERIC_ERROR_CODE = "INTERNAL_ERROR";
+var VALIDATION_ERROR_CODE = "VALIDATION_ERROR";
+
 // src/base.ts
 var V8Error = Error;
-var NextRushError = class extends Error {
+var MAX_CAUSE_DEPTH = 5;
+function serializeCause(cause, seen, depth) {
+  if (cause === void 0 || cause === null || depth >= MAX_CAUSE_DEPTH) return void 0;
+  if (typeof cause !== "object") return {
+    message: String(cause)
+  };
+  if (seen.has(cause)) return void 0;
+  seen.add(cause);
+  const err = cause;
+  const out = {};
+  if (typeof err.name === "string") out.name = err.name;
+  if (typeof err.message === "string") out.message = err.message;
+  if (typeof err.code === "string") out.code = err.code;
+  const nested = serializeCause(err.cause, seen, depth + 1);
+  if (nested !== void 0) out.cause = nested;
+  return out;
+}
+__name(serializeCause, "serializeCause");
+var NextRushError = class _NextRushError extends Error {
   static {
     __name(this, "NextRushError");
   }
@@ -17,14 +84,27 @@ var NextRushError = class extends Error {
   details;
   /** Original error that caused this error */
   cause;
+  /** Correlation/request identifier for tracing across boundaries (audit E-5). */
+  requestId;
+  /** Distributed-trace identifier (audit E-5). */
+  traceId;
+  /** ISO-8601 timestamp of when the error was created, when supplied. */
+  timestamp;
   constructor(message, options = {}) {
-    super(message);
+    super(message, options.cause !== void 0 ? {
+      cause: options.cause
+    } : void 0);
     this.name = this.constructor.name;
     this.status = options.status ?? 500;
     this.code = options.code ?? "INTERNAL_ERROR";
     this.expose = options.expose ?? this.status < 500;
-    this.details = options.details;
+    this.details = options.details ? Object.freeze({
+      ...options.details
+    }) : void 0;
     this.cause = options.cause;
+    this.requestId = options.requestId;
+    this.traceId = options.traceId;
+    this.timestamp = options.timestamp;
     if (V8Error.captureStackTrace && !(this.expose && this.status < 500)) {
       V8Error.captureStackTrace(this, this.constructor);
     }
@@ -42,9 +122,50 @@ var NextRushError = class extends Error {
     if (this.expose && this.details) {
       json.details = this.details;
     }
+    if (this.expose && this.cause !== void 0) {
+      const serialized = serializeCause(this.cause, /* @__PURE__ */ new Set(), 0);
+      if (serialized !== void 0) {
+        json.cause = serialized;
+      }
+    }
+    if (this.requestId !== void 0) json.requestId = this.requestId;
+    if (this.traceId !== void 0) json.traceId = this.traceId;
+    if (this.timestamp !== void 0) json.timestamp = this.timestamp;
     return json;
   }
   /**
+  * Reconstruct a {@link NextRushError} from a serialized {@link toJSON} payload
+  * (audit E-7).
+  *
+  * @remarks
+  * Enables cross-service transport: a downstream service can rebuild a typed
+  * error (with a working `instanceof NextRushError`) from the JSON it received,
+  * rather than being left with an opaque plain object. `message` falls back to
+  * a generic string when the source error was not exposed.
+  *
+  * @param json - A payload previously produced by {@link toJSON}.
+  * @returns A reconstructed {@link NextRushError}.
+  */
+  static fromJSON(json) {
+    return _NextRushError.hydrate(json, (message, options) => new _NextRushError(message, options));
+  }
+  /**
+  * Shared hydration logic for {@link fromJSON} across the hierarchy.
+  * @internal
+  */
+  static hydrate(json, build) {
+    const status = typeof json.status === "number" ? json.status : 500;
+    const message = typeof json.message === "string" ? json.message : getHttpStatusMessage(status);
+    return build(message, {
+      status,
+      code: typeof json.code === "string" ? json.code : void 0,
+      details: json.details !== null && typeof json.details === "object" ? json.details : void 0,
+      requestId: typeof json.requestId === "string" ? json.requestId : void 0,
+      traceId: typeof json.traceId === "string" ? json.traceId : void 0,
+      timestamp: typeof json.timestamp === "string" ? json.timestamp : void 0
+    });
+  }
+  /**
   * Create a response-safe version of the error
   */
   toResponse() {
@@ -99,19 +220,38 @@ function getHttpStatusMessage(status) {
   return HTTP_STATUS_MESSAGES[status] ?? `HTTP Error ${status}`;
 }
 __name(getHttpStatusMessage, "getHttpStatusMessage");
-var HttpError = class extends NextRushError {
+var HttpError = class _HttpError extends NextRushError {
   static {
     __name(this, "HttpError");
   }
   constructor(status, message, options = {}) {
     super(message ?? getHttpStatusMessage(status), {
       status,
-      code: options.code ?? `HTTP_${status}`,
+      code: options.code ?? codeForStatus(status),
       expose: options.expose ?? status < 500,
       details: options.details,
-      cause: options.cause
+      cause: options.cause,
+      requestId: options.requestId,
+      traceId: options.traceId,
+      timestamp: options.timestamp
     });
   }
+  /**
+  * Reconstruct an {@link HttpError} from a serialized {@link NextRushError.toJSON}
+  * payload (audit E-7).
+  *
+  * @param json - A payload previously produced by `toJSON()`.
+  * @returns A reconstructed {@link HttpError}.
+  */
+  static fromJSON(json) {
+    return NextRushError.hydrate(json, (message, options) => new _HttpError(options.status ?? 500, message, {
+      code: options.code,
+      details: options.details,
+      requestId: options.requestId,
+      traceId: options.traceId,
+      timestamp: options.timestamp
+    }));
+  }
 };
 
 // src/http-errors.ts
@@ -581,7 +721,9 @@ var ValidationError = class _ValidationError extends NextRushError {
       code: "VALIDATION_ERROR",
       expose: true
     });
-    this.issues = issues;
+    this.issues = Object.freeze([
+      ...issues
+    ]);
   }
   /**
   * Create from a single field error
@@ -777,16 +919,42 @@ var InvalidUrlError = class extends ValidationError {
 var ERROR_MAP = {
   400: BadRequestError,
   401: UnauthorizedError,
+  402: PaymentRequiredError,
   403: ForbiddenError,
   404: NotFoundError,
+  406: NotAcceptableError,
+  407: ProxyAuthRequiredError,
+  408: RequestTimeoutError,
   409: ConflictError,
+  410: GoneError,
+  411: LengthRequiredError,
+  412: PreconditionFailedError,
+  413: PayloadTooLargeError,
+  414: UriTooLongError,
+  415: UnsupportedMediaTypeError,
+  416: RangeNotSatisfiableError,
+  417: ExpectationFailedError,
+  418: ImATeapotError,
   422: UnprocessableEntityError,
+  423: LockedError,
+  424: FailedDependencyError,
+  425: TooEarlyError,
+  426: UpgradeRequiredError,
+  428: PreconditionRequiredError,
   429: TooManyRequestsError,
+  431: RequestHeaderFieldsTooLargeError,
+  451: UnavailableForLegalReasonsError,
   500: InternalServerError,
   501: NotImplementedError,
   502: BadGatewayError,
   503: ServiceUnavailableError,
-  504: GatewayTimeoutError
+  504: GatewayTimeoutError,
+  505: HttpVersionNotSupportedError,
+  506: VariantAlsoNegotiatesError,
+  507: InsufficientStorageError,
+  508: LoopDetectedError,
+  510: NotExtendedError,
+  511: NetworkAuthRequiredError
 };
 function createError(status, message, options) {
   if (status === 405) {
@@ -910,6 +1078,8 @@ function errorHandler(options = {}) {
       let body;
       if (transform) {
         body = transform(err, ctx);
+      } else if (err instanceof NextRushError) {
+        body = err.toJSON();
       } else {
         body = {
           error: expose ? err.name : getHttpStatusMessage(status),
@@ -920,9 +1090,9 @@ function errorHandler(options = {}) {
         if (expose && details) {
           body.details = details;
         }
-        if (includeStack && err.stack) {
-          body.stack = err.stack.split("\n").map((line) => line.trim());
-        }
+      }
+      if (includeStack && err.stack) {
+        body.stack = err.stack.split("\n").map((line) => line.trim());
       }
       ctx.json(body);
     }
@@ -943,17 +1113,15 @@ function notFoundHandler(message = "Not Found") {
   };
 }
 __name(notFoundHandler, "notFoundHandler");
-function catchAsync(handler) {
-  return handler;
-}
-__name(catchAsync, "catchAsync");
 export {
   BadGatewayError,
   BadRequestError,
   ConflictError,
+  ERROR_CODES,
   ExpectationFailedError,
   FailedDependencyError,
   ForbiddenError,
+  GENERIC_ERROR_CODE,
   GatewayTimeoutError,
   GoneError,
   HttpError,
@@ -995,11 +1163,12 @@ export {
   UnsupportedMediaTypeError,
   UpgradeRequiredError,
   UriTooLongError,
+  VALIDATION_ERROR_CODE,
   ValidationError,
   VariantAlsoNegotiatesError,
   badGateway,
   badRequest,
-  catchAsync,
+  codeForStatus,
   conflict,
   createError,
   errorHandler,