@nextrush/errors 3.0.6 → 4.0.0-beta.0

package/src/__tests__/public-surface.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @nextrush/errors - Public API surface test
+ *
+ * Locks the exported symbol set from `src/index.ts`. If this test fails, the
+ * public API has changed. Intentional changes require an explicit update to
+ * the expected list below, plus a changeset for a published package.
+ */
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import * as errorsApi from '../index';
+import type { ErrorHandlerOptions } from '../index';
+import type { HttpErrorOptions } from '../index';
+import type { ValidationIssue } from '../index';
+
+describe('Public API surface (runtime exports)', () => {
+  it('exports exactly the intended runtime symbols', () => {
+    const actualExports = Object.keys(errorsApi).sort();
+
+    // SEALED: intentional public runtime API surface.
+    const expectedRuntime = [
+      // Base classes + helper
+      'HttpError',
+      'NextRushError',
+      'getHttpStatusMessage',
+
+      // Central error-code registry
+      'ERROR_CODES',
+      'GENERIC_ERROR_CODE',
+      'VALIDATION_ERROR_CODE',
+      'codeForStatus',
+
+      // HTTP errors — 4xx
+      'BadRequestError',
+      'ConflictError',
+      'ExpectationFailedError',
+      'FailedDependencyError',
+      'ForbiddenError',
+      'GoneError',
+      'ImATeapotError',
+      'LengthRequiredError',
+      'LockedError',
+      'MethodNotAllowedError',
+      'NotAcceptableError',
+      'NotFoundError',
+      'PayloadTooLargeError',
+      'PaymentRequiredError',
+      'PreconditionFailedError',
+      'PreconditionRequiredError',
+      'ProxyAuthRequiredError',
+      'RangeNotSatisfiableError',
+      'RequestHeaderFieldsTooLargeError',
+      'RequestTimeoutError',
+      'TooEarlyError',
+      'TooManyRequestsError',
+      'UnauthorizedError',
+      'UnavailableForLegalReasonsError',
+      'UnprocessableEntityError',
+      'UnsupportedMediaTypeError',
+      'UpgradeRequiredError',
+      'UriTooLongError',
+
+      // HTTP errors — 5xx
+      'BadGatewayError',
+      'GatewayTimeoutError',
+      'HttpVersionNotSupportedError',
+      'InsufficientStorageError',
+      'InternalServerError',
+      'LoopDetectedError',
+      'NetworkAuthRequiredError',
+      'NotExtendedError',
+      'NotImplementedError',
+      'ServiceUnavailableError',
+      'VariantAlsoNegotiatesError',
+
+      // Validation errors
+      'InvalidEmailError',
+      'InvalidUrlError',
+      'LengthError',
+      'PatternError',
+      'RangeValidationError',
+      'RequiredFieldError',
+      'TypeMismatchError',
+      'ValidationError',
+
+      // Factory functions
+      'badGateway',
+      'badRequest',
+      'conflict',
+      'createError',
+      'forbidden',
+      'gatewayTimeout',
+      'getErrorStatus',
+      'getSafeErrorMessage',
+      'internalError',
+      'isHttpError',
+      'methodNotAllowed',
+      'notFound',
+      'serviceUnavailable',
+      'tooManyRequests',
+      'unauthorized',
+      'unprocessableEntity',
+
+      // Middleware
+      'errorHandler',
+      'notFoundHandler',
+    ].sort();
+
+    expect(actualExports).toEqual(expectedRuntime);
+  });
+});
+
+describe('Public API surface (type-only exports)', () => {
+  it('the type-only surface stays importable from the barrel', () => {
+    // Compile-time only: removing/renaming any of these in src/index.ts fails
+    // this file to type-check.
+    type Surface = [HttpErrorOptions, ValidationIssue, ErrorHandlerOptions];
+    expectTypeOf<Surface>().not.toBeNever();
+  });
+});

package/src/base.ts

@@ -6,10 +6,52 @@
  * @packageDocumentation
  */
 
+import { codeForStatus } from './codes';
+
+/** 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;
+}
+
 const V8Error = Error as ErrorConstructor & {
   captureStackTrace?: (targetObject: object, constructorOpt?: Function) => void;
 };
 
+/** Maximum depth walked when serializing a `cause` chain (audit E-2). */
+const MAX_CAUSE_DEPTH = 5;
+
+/**
+ * Serialize an error `cause` chain into a plain, JSON-safe object.
+ *
+ * @remarks
+ * Walks nested `cause` links up to {@link MAX_CAUSE_DEPTH}, guards against
+ * cyclic chains via a visited set, and only surfaces `name`/`message`/`code`
+ * so no unexpected enumerable properties (or secrets on ad-hoc error objects)
+ * leak. Returns `undefined` when there is nothing meaningful to serialize.
+ */
+function serializeCause(cause: unknown, seen: Set<unknown>, depth: number): unknown {
+  if (cause === undefined || cause === null || depth >= MAX_CAUSE_DEPTH) return undefined;
+  if (typeof cause !== 'object') return { message: String(cause) };
+  if (seen.has(cause)) return undefined; // cycle guard
+  seen.add(cause);
+
+  const err = cause as { name?: unknown; message?: unknown; code?: unknown; cause?: unknown };
+  const out: Record<string, unknown> = {};
+  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 !== undefined) out.cause = nested;
+
+  return out;
+}
+
 /**
  * Base error class for all NextRush errors
  */
@@ -29,6 +71,15 @@ export class NextRushError extends Error {
   /** 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: {
@@ -37,15 +88,25 @@ export class NextRushError extends Error {
       expose?: boolean;
       details?: Record<string, unknown>;
       cause?: unknown;
+      requestId?: string;
+      traceId?: string;
+      timestamp?: string;
     } = {}
   ) {
-    super(message);
+    // Pass cause to the native Error constructor so `util.inspect` / logging
+    // tooling walks the chain natively, in addition to our own `cause` field.
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
     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;
+    // Freeze a shallow snapshot so the error owns immutable details and the
+    // caller's object cannot be mutated through the error (audit E-6).
+    this.details = options.details ? Object.freeze({ ...options.details }) : undefined;
     this.cause = options.cause;
+    this.requestId = options.requestId;
+    this.traceId = options.traceId;
+    this.timestamp = options.timestamp;
 
     // Maintain proper stack trace for V8
     // Skip for common client errors (4xx with expose=true) to reduce overhead.
@@ -71,9 +132,66 @@ export class NextRushError extends Error {
       json.details = this.details;
     }
 
+    // Surface the cause chain for diagnosability, but only on exposed errors —
+    // a non-exposed 5xx cause may contain internal detail (audit E-2). Server
+    // -side logging should read `error.cause` directly, which is never gated.
+    if (this.expose && this.cause !== undefined) {
+      const serialized = serializeCause(this.cause, new Set(), 0);
+      if (serialized !== undefined) {
+        json.cause = serialized;
+      }
+    }
+
+    // Correlation identifiers are safe to surface and are the primary handle
+    // for cross-service debugging (audit E-5). Only emitted when set, so the
+    // default serialized shape is unchanged.
+    if (this.requestId !== undefined) json.requestId = this.requestId;
+    if (this.traceId !== undefined) json.traceId = this.traceId;
+    if (this.timestamp !== undefined) 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: Record<string, unknown>): NextRushError {
+    return NextRushError.hydrate(json, (message, options) => new NextRushError(message, options));
+  }
+
+  /**
+   * 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 {
+    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 : undefined,
+      details:
+        json.details !== null && typeof json.details === 'object'
+          ? (json.details as Record<string, unknown>)
+          : undefined,
+      requestId: typeof json.requestId === 'string' ? json.requestId : undefined,
+      traceId: typeof json.traceId === 'string' ? json.traceId : undefined,
+      timestamp: typeof json.timestamp === 'string' ? json.timestamp : undefined,
+    });
+  }
+
   /**
    * Create a response-safe version of the error
    */
@@ -149,14 +267,41 @@ export class HttpError extends NextRushError {
       expose?: boolean;
       details?: Record<string, unknown>;
       cause?: unknown;
+      requestId?: string;
+      traceId?: string;
+      timestamp?: string;
     } = {}
   ) {
     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,
+      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 override fromJSON(json: Record<string, unknown>): HttpError {
+    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,
+        })
+    );
+  }
 }

package/src/codes.ts

@@ -0,0 +1,77 @@
+/**
+ * @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.
+ */
+export const ERROR_CODES: Readonly<Record<number, string>> = 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',
+});
+
+/**
+ * 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.
+ */
+export function codeForStatus(status: number): string {
+  return ERROR_CODES[status] ?? `HTTP_${status}`;
+}
+
+/** Generic internal-error code used when no status-specific code applies. */
+export const GENERIC_ERROR_CODE = 'INTERNAL_ERROR';
+
+/** Canonical code for validation failures. */
+export const VALIDATION_ERROR_CODE = 'VALIDATION_ERROR';

package/src/factory.ts

@@ -11,35 +11,92 @@ import {
   BadGatewayError,
   BadRequestError,
   ConflictError,
+  ExpectationFailedError,
+  FailedDependencyError,
   ForbiddenError,
   GatewayTimeoutError,
+  GoneError,
+  HttpVersionNotSupportedError,
+  ImATeapotError,
+  InsufficientStorageError,
   InternalServerError,
+  LengthRequiredError,
+  LockedError,
+  LoopDetectedError,
   MethodNotAllowedError,
+  NetworkAuthRequiredError,
+  NotAcceptableError,
+  NotExtendedError,
   NotFoundError,
   NotImplementedError,
+  PayloadTooLargeError,
+  PaymentRequiredError,
+  PreconditionFailedError,
+  PreconditionRequiredError,
+  ProxyAuthRequiredError,
+  RangeNotSatisfiableError,
+  RequestHeaderFieldsTooLargeError,
+  RequestTimeoutError,
   ServiceUnavailableError,
+  TooEarlyError,
   TooManyRequestsError,
   UnauthorizedError,
+  UnavailableForLegalReasonsError,
   UnprocessableEntityError,
+  UnsupportedMediaTypeError,
+  UpgradeRequiredError,
+  UriTooLongError,
+  VariantAlsoNegotiatesError,
   type HttpErrorOptions,
 } from './http-errors';
 
 /**
- * HTTP status code to error class mapping
+ * HTTP status code to error class mapping.
+ *
+ * @remarks
+ * Covers every status that has a dedicated typed class so {@link createError}
+ * returns the correctly-coded instance (audit E-3). `405` is handled separately
+ * because {@link MethodNotAllowedError} has a divergent constructor signature.
  */
 const ERROR_MAP: Record<number, new (message?: string, options?: HttpErrorOptions) => HttpError> = {
   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,
+  505: HttpVersionNotSupportedError,
+  506: VariantAlsoNegotiatesError,
+  507: InsufficientStorageError,
+  508: LoopDetectedError,
+  510: NotExtendedError,
+  511: NetworkAuthRequiredError,
 };
 
 /**

package/src/http-errors.ts

@@ -16,6 +16,12 @@ export 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;
 }
 
 // =============================================================================

package/src/index.ts

@@ -9,6 +9,9 @@
 // Base classes
 export { HttpError, NextRushError, getHttpStatusMessage } from './base';
 
+// Central error-code registry
+export { ERROR_CODES, GENERIC_ERROR_CODE, VALIDATION_ERROR_CODE, codeForStatus } from './codes';
+
 // HTTP errors - 4xx
 export {
   BadRequestError,
@@ -91,11 +94,4 @@ export {
 } from './factory';
 
 // Middleware
-export {
-  catchAsync,
-  errorHandler,
-  notFoundHandler,
-  type ErrorContext,
-  type ErrorHandlerOptions,
-  type ErrorMiddleware,
-} from './middleware';
+export { errorHandler, notFoundHandler, type ErrorHandlerOptions } from './middleware';

package/src/middleware.ts

@@ -9,27 +9,6 @@
 import type { Context, Middleware, Next } from '@nextrush/types';
 import { HttpError, NextRushError, getHttpStatusMessage } from './base';
 
-/**
- * Minimal context interface for error handling.
- *
- * @deprecated Use `Context` from `@nextrush/types` instead.
- * Kept for backward compatibility — will be removed in v4.
- */
-export 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.
- */
-export type ErrorMiddleware = Middleware;
-
 /**
  * Error handler options
  */
@@ -116,6 +95,12 @@ export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
 
       if (transform) {
         body = transform(err, ctx);
+      } else if (err instanceof NextRushError) {
+        // Delegate to the error's own toJSON() — this is the single source of
+        // truth for what a given error type serializes to (e.g. ValidationError
+        // adds `issues` while stripping `received`). Duplicating that shape here
+        // would silently drift out of sync with subclass overrides.
+        body = err.toJSON();
       } else {
         body = {
           error: expose ? err.name : getHttpStatusMessage(status),
@@ -127,10 +112,10 @@ export function errorHandler(options: ErrorHandlerOptions = {}): Middleware {
         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);
@@ -162,22 +147,3 @@ export function notFoundHandler(message = 'Not Found'): 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.
- */
-export function catchAsync(handler: (ctx: Context, next: Next) => Promise<void>): Middleware {
-  return handler;
-}

package/src/validation.ts

@@ -37,7 +37,8 @@ export class ValidationError extends NextRushError {
       code: 'VALIDATION_ERROR',
       expose: true,
     });
-    this.issues = issues;
+    // Freeze a snapshot so issues are immutable after construction (audit E-6).
+    this.issues = Object.freeze([...issues]) as ValidationIssue[];
   }
 
   /**