@nextrush/errors 3.0.0

package/src/base.ts

@@ -0,0 +1,162 @@
+/**
+ * @nextrush/errors - Base Error Classes
+ *
+ * Foundational error classes for NextRush framework.
+ *
+ * @packageDocumentation
+ */
+
+const V8Error = Error as ErrorConstructor & {
+  captureStackTrace?: (targetObject: object, constructorOpt?: Function) => void;
+};
+
+/**
+ * Base error class for all NextRush errors
+ */
+export class NextRushError extends Error {
+  /** HTTP status code */
+  readonly status: number;
+
+  /** Error code for programmatic handling */
+  readonly code: string;
+
+  /** Whether error message is safe to expose to client */
+  readonly expose: boolean;
+
+  /** Additional error details */
+  readonly details?: Record<string, unknown>;
+
+  /** Original error that caused this error */
+  readonly cause?: unknown;
+
+  constructor(
+    message: string,
+    options: {
+      status?: number;
+      code?: string;
+      expose?: boolean;
+      details?: Record<string, unknown>;
+      cause?: unknown;
+    } = {}
+  ) {
+    super(message);
+    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.cause = options.cause;
+
+    // Maintain proper stack trace for V8
+    // Skip for common client errors (4xx with expose=true) to reduce overhead.
+    // These are expected control-flow errors, not bugs — stack traces add cost
+    // without diagnostic value in production.
+    if (V8Error.captureStackTrace && !(this.expose && this.status < 500)) {
+      V8Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Convert error to JSON representation
+   */
+  toJSON(): Record<string, unknown> {
+    const json: Record<string, unknown> = {
+      error: this.name,
+      message: this.expose ? this.message : 'Internal Server Error',
+      code: this.code,
+      status: this.status,
+    };
+
+    if (this.expose && this.details) {
+      json.details = this.details;
+    }
+
+    return json;
+  }
+
+  /**
+   * Create a response-safe version of the error
+   */
+  toResponse(): { status: number; body: Record<string, unknown> } {
+    return {
+      status: this.status,
+      body: this.toJSON(),
+    };
+  }
+}
+
+/**
+ * Default HTTP status messages
+ */
+const HTTP_STATUS_MESSAGES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  407: 'Proxy Authentication 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: "I'm 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 Authentication Required',
+};
+
+/**
+ * Get default message for an HTTP status code
+ */
+export function getHttpStatusMessage(status: number): string {
+  return HTTP_STATUS_MESSAGES[status] ?? `HTTP Error ${status}`;
+}
+
+/**
+ * Base class for HTTP errors
+ */
+export class HttpError extends NextRushError {
+  constructor(
+    status: number,
+    message?: string,
+    options: {
+      code?: string;
+      expose?: boolean;
+      details?: Record<string, unknown>;
+      cause?: unknown;
+    } = {}
+  ) {
+    super(message ?? getHttpStatusMessage(status), {
+      status,
+      code: options.code ?? `HTTP_${status}`,
+      expose: options.expose ?? status < 500,
+      details: options.details,
+      cause: options.cause,
+    });
+  }
+}

package/src/factory.ts

@@ -0,0 +1,205 @@
+/**
+ * @nextrush/errors - Error Factory
+ *
+ * Factory functions for creating errors.
+ *
+ * @packageDocumentation
+ */
+
+import { HttpError, NextRushError } from './base';
+import {
+  BadGatewayError,
+  BadRequestError,
+  ConflictError,
+  ForbiddenError,
+  GatewayTimeoutError,
+  InternalServerError,
+  MethodNotAllowedError,
+  NotFoundError,
+  NotImplementedError,
+  ServiceUnavailableError,
+  TooManyRequestsError,
+  UnauthorizedError,
+  UnprocessableEntityError,
+  type HttpErrorOptions,
+} from './http-errors';
+
+/**
+ * HTTP status code to error class mapping
+ */
+const ERROR_MAP: Record<number, new (message?: string, options?: HttpErrorOptions) => HttpError> = {
+  400: BadRequestError,
+  401: UnauthorizedError,
+  403: ForbiddenError,
+  404: NotFoundError,
+  409: ConflictError,
+  422: UnprocessableEntityError,
+  429: TooManyRequestsError,
+  500: InternalServerError,
+  501: NotImplementedError,
+  502: BadGatewayError,
+  503: ServiceUnavailableError,
+  504: GatewayTimeoutError,
+};
+
+/**
+ * Create an HTTP error by status code
+ */
+export function createError(
+  status: number,
+  message?: string,
+  options?: HttpErrorOptions
+): HttpError {
+  // Special case: MethodNotAllowedError requires allowedMethods array
+  if (status === 405) {
+    return new MethodNotAllowedError([], message, options);
+  }
+
+  const ErrorClass = ERROR_MAP[status];
+
+  if (ErrorClass) {
+    return new ErrorClass(message, options);
+  }
+
+  // Fallback: let HttpError constructor resolve the message via getHttpStatusMessage()
+  return new HttpError(status, message, options);
+}
+
+/**
+ * Create a 400 Bad Request error
+ */
+export function badRequest(message?: string, options?: HttpErrorOptions): BadRequestError {
+  return new BadRequestError(message, options);
+}
+
+/**
+ * Create a 401 Unauthorized error
+ */
+export function unauthorized(message?: string, options?: HttpErrorOptions): UnauthorizedError {
+  return new UnauthorizedError(message, options);
+}
+
+/**
+ * Create a 403 Forbidden error
+ */
+export function forbidden(message?: string, options?: HttpErrorOptions): ForbiddenError {
+  return new ForbiddenError(message, options);
+}
+
+/**
+ * Create a 404 Not Found error
+ */
+export function notFound(message?: string, options?: HttpErrorOptions): NotFoundError {
+  return new NotFoundError(message, options);
+}
+
+/**
+ * Create a 405 Method Not Allowed error
+ */
+export function methodNotAllowed(
+  allowedMethods?: string[],
+  message?: string,
+  options?: HttpErrorOptions
+): MethodNotAllowedError {
+  return new MethodNotAllowedError(allowedMethods, message, options);
+}
+
+/**
+ * Create a 409 Conflict error
+ */
+export function conflict(message?: string, options?: HttpErrorOptions): ConflictError {
+  return new ConflictError(message, options);
+}
+
+/**
+ * Create a 422 Unprocessable Entity error
+ */
+export function unprocessableEntity(
+  message?: string,
+  options?: HttpErrorOptions
+): UnprocessableEntityError {
+  return new UnprocessableEntityError(message, options);
+}
+
+/**
+ * Create a 429 Too Many Requests error
+ */
+export function tooManyRequests(
+  message?: string,
+  options?: HttpErrorOptions & { retryAfter?: number }
+): TooManyRequestsError {
+  return new TooManyRequestsError(message, options);
+}
+
+/**
+ * Create a 500 Internal Server Error
+ */
+export function internalError(message?: string, options?: HttpErrorOptions): InternalServerError {
+  return new InternalServerError(message, options);
+}
+
+/**
+ * Create a 502 Bad Gateway error
+ */
+export function badGateway(message?: string, options?: HttpErrorOptions): BadGatewayError {
+  return new BadGatewayError(message, options);
+}
+
+/**
+ * Create a 503 Service Unavailable error
+ */
+export function serviceUnavailable(
+  message?: string,
+  options?: HttpErrorOptions & { retryAfter?: number }
+): ServiceUnavailableError {
+  return new ServiceUnavailableError(message, options);
+}
+
+/**
+ * Create a 504 Gateway Timeout error
+ */
+export function gatewayTimeout(message?: string, options?: HttpErrorOptions): GatewayTimeoutError {
+  return new GatewayTimeoutError(message, options);
+}
+
+/**
+ * Check if an error is a NextRush HttpError
+ */
+export function isHttpError(error: unknown): error is HttpError {
+  return error instanceof HttpError;
+}
+
+/**
+ * Get HTTP status from any error
+ *
+ * Checks NextRushError first (covers HttpError, ValidationError, and all subclasses),
+ * then falls back to duck-typed status property.
+ */
+export function getErrorStatus(error: unknown): number {
+  if (error instanceof NextRushError) {
+    return error.status;
+  }
+  if (
+    error != null &&
+    typeof error === 'object' &&
+    'status' in error &&
+    typeof (error as { status: unknown }).status === 'number'
+  ) {
+    const status = (error as { status: number }).status;
+    return status >= 400 && status < 600 ? status : 500;
+  }
+  return 500;
+}
+
+/**
+ * Get error message safe for client response
+ *
+ * Exposes message for any NextRushError (including ValidationError)
+ * when the error's expose flag is true.
+ */
+export function getSafeErrorMessage(error: unknown): string {
+  if (error instanceof NextRushError && error.expose) {
+    return error.message;
+  }
+  return 'Internal Server Error';
+}