error-shield 1.2.3 → 2.0.1

package/dist/cjs/index.cjs

@@ -0,0 +1,270 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppError: () => AppError,
+  Errors: () => Errors,
+  asyncHandler: () => asyncHandler,
+  createErrorResponse: () => createErrorResponse,
+  default: () => index_default,
+  expressErrorHandler: () => expressErrorHandler,
+  formatError: () => formatError,
+  handleError: () => handleError,
+  withRetry: () => withRetry
+});
+module.exports = __toCommonJS(index_exports);
+var AppError = class _AppError extends Error {
+  code;
+  statusCode;
+  context;
+  isOperational;
+  constructor(message, statusCode = 500, code, context, cause) {
+    super(message, cause ? { cause } : void 0);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.code = code;
+    this.context = context;
+    this.isOperational = true;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Wraps an existing error as the cause of a new `AppError`.
+   *
+   * This is a convenience factory for error chaining — it creates a new
+   * `AppError` whose `.cause` is set to the original error.
+   *
+   * @param originalError - The caught error to wrap
+   * @param message - Human-readable description of the higher-level failure
+   * @param statusCode - HTTP status code (default: 500)
+   * @param code - Machine-readable error code
+   * @param context - Additional context metadata
+   * @returns A new `AppError` with `originalError` as its cause
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await db.query('SELECT ...');
+   * } catch (err) {
+   *   throw AppError.wrap(err, 'Database query failed', 500, 'DB_ERROR');
+   * }
+   * ```
+   */
+  static wrap(originalError, message, statusCode = 500, code, context) {
+    return new _AppError(message, statusCode, code, context, originalError);
+  }
+};
+function formatError(error, options = {}) {
+  const {
+    includeStack = false,
+    includeTimestamp = true,
+    context: optionsContext = {}
+  } = options;
+  const mergedContext = error instanceof AppError ? { ...error.context, ...optionsContext } : optionsContext;
+  const errorDetails = {
+    message: error.message,
+    ...includeTimestamp && { timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+    ...includeStack && error.stack && { stack: error.stack },
+    ...error instanceof AppError && {
+      code: error.code,
+      statusCode: error.statusCode
+    },
+    ...Object.keys(mergedContext).length > 0 && { context: mergedContext }
+  };
+  if (error.cause && error.cause instanceof Error) {
+    errorDetails.cause = formatError(error.cause, {
+      includeStack,
+      includeTimestamp: false
+      // only top-level gets timestamp
+    });
+  }
+  return errorDetails;
+}
+function handleError(error, options = {}) {
+  const errorDetails = formatError(error, options);
+  if (options.logger) {
+    options.logger(errorDetails);
+  }
+  return errorDetails;
+}
+function asyncHandler(fn) {
+  return ((...args) => {
+    return Promise.resolve(fn(...args)).catch((error) => {
+      throw error;
+    });
+  });
+}
+function expressErrorHandler(options = {}) {
+  return (err, req, res, next) => {
+    const errorDetails = handleError(err, {
+      ...options,
+      context: {
+        ...options.context,
+        method: req.method,
+        path: req.path,
+        ip: req.ip
+      }
+    });
+    const statusCode = err instanceof AppError ? err.statusCode || 500 : 500;
+    if (options.format === "string") {
+      res.status(statusCode).send(errorDetails.message);
+    } else {
+      res.status(statusCode).json(errorDetails);
+    }
+  };
+}
+function createErrorResponse(message, statusCode = 500, code, context) {
+  return new AppError(message, statusCode, code, context);
+}
+function calculateDelay(attempt, options) {
+  const { backoff, initialDelay, maxDelay, jitter } = options;
+  let delay;
+  switch (backoff) {
+    case "exponential":
+      delay = initialDelay * Math.pow(2, attempt - 1);
+      break;
+    case "linear":
+      delay = initialDelay * attempt;
+      break;
+    case "fixed":
+      delay = initialDelay;
+      break;
+    default:
+      delay = initialDelay;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    const jitterAmount = delay * 0.25;
+    delay = delay - jitterAmount + Math.random() * jitterAmount * 2;
+  }
+  return Math.round(delay);
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    backoff = "exponential",
+    initialDelay = 1e3,
+    maxDelay = 3e4,
+    retryIf,
+    onRetry,
+    jitter = true
+  } = options;
+  const errors = [];
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      lastError = error;
+      errors.push(error);
+      if (attempt === maxRetries) {
+        break;
+      }
+      if (retryIf && !retryIf(error)) {
+        break;
+      }
+      if (onRetry) {
+        onRetry(error, attempt + 1);
+      }
+      const delay = calculateDelay(attempt + 1, {
+        backoff,
+        initialDelay,
+        maxDelay,
+        jitter
+      });
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  const finalError = lastError;
+  finalError.attempts = errors;
+  throw finalError;
+}
+var Errors = {
+  // 4xx Client Errors
+  badRequest: (message, context) => new AppError(message, 400, "BAD_REQUEST", context),
+  unauthorized: (message = "Unauthorized", context) => new AppError(message, 401, "UNAUTHORIZED", context),
+  paymentRequired: (message = "Payment Required", context) => new AppError(message, 402, "PAYMENT_REQUIRED", context),
+  forbidden: (message = "Forbidden", context) => new AppError(message, 403, "FORBIDDEN", context),
+  notFound: (message = "Not Found", context) => new AppError(message, 404, "NOT_FOUND", context),
+  methodNotAllowed: (message = "Method Not Allowed", context) => new AppError(message, 405, "METHOD_NOT_ALLOWED", context),
+  notAcceptable: (message = "Not Acceptable", context) => new AppError(message, 406, "NOT_ACCEPTABLE", context),
+  proxyAuthRequired: (message = "Proxy Authentication Required", context) => new AppError(message, 407, "PROXY_AUTH_REQUIRED", context),
+  requestTimeout: (message = "Request Timeout", context) => new AppError(message, 408, "REQUEST_TIMEOUT", context),
+  conflict: (message, context) => new AppError(message, 409, "CONFLICT", context),
+  gone: (message = "Gone", context) => new AppError(message, 410, "GONE", context),
+  lengthRequired: (message = "Length Required", context) => new AppError(message, 411, "LENGTH_REQUIRED", context),
+  preconditionFailed: (message = "Precondition Failed", context) => new AppError(message, 412, "PRECONDITION_FAILED", context),
+  payloadTooLarge: (message = "Payload Too Large", context) => new AppError(message, 413, "PAYLOAD_TOO_LARGE", context),
+  uriTooLong: (message = "URI Too Long", context) => new AppError(message, 414, "URI_TOO_LONG", context),
+  unsupportedMediaType: (message = "Unsupported Media Type", context) => new AppError(message, 415, "UNSUPPORTED_MEDIA_TYPE", context),
+  rangeNotSatisfiable: (message = "Range Not Satisfiable", context) => new AppError(message, 416, "RANGE_NOT_SATISFIABLE", context),
+  expectationFailed: (message = "Expectation Failed", context) => new AppError(message, 417, "EXPECTATION_FAILED", context),
+  imATeapot: (message = "I'm a Teapot", context) => new AppError(message, 418, "IM_A_TEAPOT", context),
+  misdirectedRequest: (message = "Misdirected Request", context) => new AppError(message, 421, "MISDIRECTED_REQUEST", context),
+  unprocessableEntity: (message = "Unprocessable Entity", context) => new AppError(message, 422, "UNPROCESSABLE_ENTITY", context),
+  validationError: (message, context) => new AppError(message, 422, "VALIDATION_ERROR", context),
+  locked: (message = "Locked", context) => new AppError(message, 423, "LOCKED", context),
+  failedDependency: (message = "Failed Dependency", context) => new AppError(message, 424, "FAILED_DEPENDENCY", context),
+  tooEarly: (message = "Too Early", context) => new AppError(message, 425, "TOO_EARLY", context),
+  upgradeRequired: (message = "Upgrade Required", context) => new AppError(message, 426, "UPGRADE_REQUIRED", context),
+  preconditionRequired: (message = "Precondition Required", context) => new AppError(message, 428, "PRECONDITION_REQUIRED", context),
+  tooManyRequests: (message = "Too Many Requests", context) => new AppError(message, 429, "TOO_MANY_REQUESTS", context),
+  requestHeaderFieldsTooLarge: (message = "Request Header Fields Too Large", context) => new AppError(message, 431, "REQUEST_HEADER_FIELDS_TOO_LARGE", context),
+  unavailableForLegalReasons: (message = "Unavailable For Legal Reasons", context) => new AppError(message, 451, "UNAVAILABLE_FOR_LEGAL_REASONS", context),
+  // 5xx Server Errors
+  internalServerError: (message = "Internal Server Error", context) => new AppError(message, 500, "INTERNAL_SERVER_ERROR", context),
+  notImplemented: (message = "Not Implemented", context) => new AppError(message, 501, "NOT_IMPLEMENTED", context),
+  badGateway: (message = "Bad Gateway", context) => new AppError(message, 502, "BAD_GATEWAY", context),
+  serviceUnavailable: (message = "Service Unavailable", context) => new AppError(message, 503, "SERVICE_UNAVAILABLE", context),
+  gatewayTimeout: (message = "Gateway Timeout", context) => new AppError(message, 504, "GATEWAY_TIMEOUT", context),
+  httpVersionNotSupported: (message = "HTTP Version Not Supported", context) => new AppError(message, 505, "HTTP_VERSION_NOT_SUPPORTED", context),
+  variantAlsoNegotiates: (message = "Variant Also Negotiates", context) => new AppError(message, 506, "VARIANT_ALSO_NEGOTIATES", context),
+  insufficientStorage: (message = "Insufficient Storage", context) => new AppError(message, 507, "INSUFFICIENT_STORAGE", context),
+  loopDetected: (message = "Loop Detected", context) => new AppError(message, 508, "LOOP_DETECTED", context),
+  bandwidthLimitExceeded: (message = "Bandwidth Limit Exceeded", context) => new AppError(message, 509, "BANDWIDTH_LIMIT_EXCEEDED", context),
+  notExtended: (message = "Not Extended", context) => new AppError(message, 510, "NOT_EXTENDED", context),
+  networkAuthenticationRequired: (message = "Network Authentication Required", context) => new AppError(message, 511, "NETWORK_AUTHENTICATION_REQUIRED", context),
+  networkConnectTimeout: (message = "Network Connect Timeout", context) => new AppError(message, 599, "NETWORK_CONNECT_TIMEOUT", context)
+};
+var index_default = {
+  AppError,
+  formatError,
+  handleError,
+  asyncHandler,
+  expressErrorHandler,
+  createErrorResponse,
+  withRetry,
+  Errors
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppError,
+  Errors,
+  asyncHandler,
+  createErrorResponse,
+  expressErrorHandler,
+  formatError,
+  handleError,
+  withRetry
+});
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Error Shield - A comprehensive error handling utility for Node.js & Express.js\n *\n * Provides utilities for error handling, formatting, logging, retry logic,\n * and error chaining with full TypeScript support.\n *\n * @packageDocumentation\n */\n\n// ─── Types & Interfaces ─────────────────────────────────────────────────────\n\n/**\n * Structured representation of an error with optional metadata.\n */\nexport interface ErrorDetails {\n  message: string;\n  code?: string;\n  statusCode?: number;\n  stack?: string;\n  timestamp?: string;\n  context?: Record<string, any>;\n  /** Cause chain information when error chaining is used */\n  cause?: ErrorDetails;\n}\n\n/**\n * Options for configuring error handling behavior.\n */\nexport interface ErrorHandlerOptions {\n  includeStack?: boolean;\n  includeTimestamp?: boolean;\n  format?: 'json' | 'string';\n  logger?: (error: ErrorDetails) => void;\n  context?: Record<string, any>;\n}\n\nexport type ErrorFn = (message: string, context?: Record<string, any>) => AppError;\n\nexport type ErrorMap = Record<string, ErrorFn>;\n\n/**\n * Configuration options for the retry utility.\n */\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxRetries?: number;\n  /** Backoff strategy between retries (default: 'exponential') */\n  backoff?: 'exponential' | 'linear' | 'fixed';\n  /** Initial delay in milliseconds before the first retry (default: 1000) */\n  initialDelay?: number;\n  /** Maximum delay in milliseconds between retries (default: 30000) */\n  maxDelay?: number;\n  /**\n   * Optional predicate to determine whether a retry should be attempted.\n   * If provided and returns `false`, the error is thrown immediately.\n   */\n  retryIf?: (error: Error) => boolean;\n  /** Optional callback invoked before each retry attempt */\n  onRetry?: (error: Error, attempt: number) => void;\n  /** Whether to add random jitter to the delay to prevent thundering herd (default: true) */\n  jitter?: boolean;\n}\n\n// ─── AppError Class ──────────────────────────────────────────────────────────\n\n/**\n * Custom Error class with additional properties for structured error handling.\n *\n * Supports error chaining via the native ES2022 `Error.cause` feature.\n *\n * @example\n * ```ts\n * const error = new AppError('Something broke', 500, 'INTERNAL', { userId: 123 });\n *\n * // With error chaining\n * try {\n *   await fetchData();\n * } catch (err) {\n *   throw new AppError('Failed to fetch data', 502, 'FETCH_FAILED', undefined, err);\n * }\n * ```\n */\nexport class AppError extends Error {\n  public code?: string;\n  public statusCode?: number;\n  public context?: Record<string, any>;\n  public isOperational: boolean;\n\n  constructor(\n    message: string,\n    statusCode: number = 500,\n    code?: string,\n    context?: Record<string, any>,\n    cause?: Error\n  ) {\n    super(message, cause ? { cause } : undefined);\n    this.name = this.constructor.name;\n    this.statusCode = statusCode;\n    this.code = code;\n    this.context = context;\n    this.isOperational = true;\n    if ((Error as any).captureStackTrace) {\n      (Error as any).captureStackTrace(this, this.constructor);\n    }\n  }\n\n  /**\n   * Wraps an existing error as the cause of a new `AppError`.\n   *\n   * This is a convenience factory for error chaining — it creates a new\n   * `AppError` whose `.cause` is set to the original error.\n   *\n   * @param originalError - The caught error to wrap\n   * @param message - Human-readable description of the higher-level failure\n   * @param statusCode - HTTP status code (default: 500)\n   * @param code - Machine-readable error code\n   * @param context - Additional context metadata\n   * @returns A new `AppError` with `originalError` as its cause\n   *\n   * @example\n   * ```ts\n   * try {\n   *   await db.query('SELECT ...');\n   * } catch (err) {\n   *   throw AppError.wrap(err, 'Database query failed', 500, 'DB_ERROR');\n   * }\n   * ```\n   */\n  static wrap(\n    originalError: Error,\n    message: string,\n    statusCode: number = 500,\n    code?: string,\n    context?: Record<string, any>\n  ): AppError {\n    return new AppError(message, statusCode, code, context, originalError);\n  }\n}\n\n// ─── Core Utilities ──────────────────────────────────────────────────────────\n\n/**\n * Formats an error into a structured {@link ErrorDetails} object.\n *\n * When the error has a `.cause`, the cause chain is recursively formatted\n * and included in the output.\n */\nexport function formatError(\n  error: Error | AppError,\n  options: ErrorHandlerOptions = {}\n): ErrorDetails {\n  const {\n    includeStack = false,\n    includeTimestamp = true,\n    context: optionsContext = {},\n  } = options;\n\n  const mergedContext = error instanceof AppError\n    ? { ...error.context, ...optionsContext }\n    : optionsContext;\n\n  const errorDetails: ErrorDetails = {\n    message: error.message,\n    ...(includeTimestamp && { timestamp: new Date().toISOString() }),\n    ...(includeStack && error.stack && { stack: error.stack }),\n    ...(error instanceof AppError && {\n      code: error.code,\n      statusCode: error.statusCode,\n    }),\n    ...(Object.keys(mergedContext).length > 0 && { context: mergedContext }),\n  };\n\n  // Recursively format the cause chain\n  if (error.cause && error.cause instanceof Error) {\n    errorDetails.cause = formatError(error.cause, {\n      includeStack,\n      includeTimestamp: false, // only top-level gets timestamp\n    });\n  }\n\n  return errorDetails;\n}\n\n/**\n * Handles errors with optional logging and formatting.\n */\nexport function handleError(\n  error: Error | AppError,\n  options: ErrorHandlerOptions = {}\n): ErrorDetails {\n  const errorDetails = formatError(error, options);\n\n  if (options.logger) {\n    options.logger(errorDetails);\n  }\n\n  return errorDetails;\n}\n\n/**\n * Async error wrapper — catches errors from async route handlers\n * and forwards them to Express's `next()` function.\n */\nexport function asyncHandler<T extends (...args: any[]) => Promise<any>>(\n  fn: T\n): T {\n  return ((...args: any[]) => {\n    return Promise.resolve(fn(...args)).catch((error) => {\n      throw error;\n    });\n  }) as T;\n}\n\n/**\n * Express.js error handler middleware factory.\n *\n * Returns a standard Express error-handling middleware that formats\n * the error and sends an appropriate JSON or string response.\n */\nexport function expressErrorHandler(\n  options: ErrorHandlerOptions = {}\n) {\n  return (\n    err: Error | AppError,\n    req: any,\n    res: any,\n    next: any\n  ): void => {\n    const errorDetails = handleError(err, {\n      ...options,\n      context: {\n        ...options.context,\n        method: req.method,\n        path: req.path,\n        ip: req.ip,\n      },\n    });\n\n    const statusCode =\n      err instanceof AppError ? err.statusCode || 500 : 500;\n\n    if (options.format === 'string') {\n      res.status(statusCode).send(errorDetails.message);\n    } else {\n      res.status(statusCode).json(errorDetails);\n    }\n  };\n}\n\n/**\n * Creates a standardized error response.\n */\nexport function createErrorResponse(\n  message: string,\n  statusCode: number = 500,\n  code?: string,\n  context?: Record<string, any>\n): AppError {\n  return new AppError(message, statusCode, code, context);\n}\n\n// ─── Retry Utility ───────────────────────────────────────────────────────────\n\n/**\n * Calculates the delay for a given retry attempt based on the backoff strategy.\n * @internal\n */\nfunction calculateDelay(\n  attempt: number,\n  options: Required<Pick<RetryOptions, 'backoff' | 'initialDelay' | 'maxDelay' | 'jitter'>>\n): number {\n  const { backoff, initialDelay, maxDelay, jitter } = options;\n\n  let delay: number;\n\n  switch (backoff) {\n    case 'exponential':\n      delay = initialDelay * Math.pow(2, attempt - 1);\n      break;\n    case 'linear':\n      delay = initialDelay * attempt;\n      break;\n    case 'fixed':\n      delay = initialDelay;\n      break;\n    default:\n      delay = initialDelay;\n  }\n\n  // Cap at maxDelay\n  delay = Math.min(delay, maxDelay);\n\n  // Add jitter (±25% randomness)\n  if (jitter) {\n    const jitterAmount = delay * 0.25;\n    delay = delay - jitterAmount + Math.random() * jitterAmount * 2;\n  }\n\n  return Math.round(delay);\n}\n\n/**\n * Executes an async function with automatic retries on failure.\n *\n * Supports exponential, linear, and fixed backoff strategies with\n * optional jitter, conditional retry predicates, and retry callbacks.\n *\n * If all retries are exhausted, the **last** error is thrown. The previous\n * attempt errors are accessible via the error's `.cause` chain and the\n * `attempts` property attached to the final error.\n *\n * @typeParam T - The return type of the async function\n * @param fn - The async function to execute with retries\n * @param options - Retry configuration options\n * @returns The result of the successful function execution\n *\n * @example\n * ```ts\n * const data = await withRetry(\n *   () => fetch('https://api.example.com/data').then(r => r.json()),\n *   {\n *     maxRetries: 5,\n *     backoff: 'exponential',\n *     initialDelay: 500,\n *     retryIf: (err) => err.message.includes('ECONNREFUSED'),\n *     onRetry: (err, attempt) => console.log(`Retry ${attempt}: ${err.message}`),\n *   }\n * );\n * ```\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  options: RetryOptions = {}\n): Promise<T> {\n  const {\n    maxRetries = 3,\n    backoff = 'exponential',\n    initialDelay = 1000,\n    maxDelay = 30000,\n    retryIf,\n    onRetry,\n    jitter = true,\n  } = options;\n\n  const errors: Error[] = [];\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      lastError = error;\n      errors.push(error);\n\n      // If this was the last attempt, break to throw\n      if (attempt === maxRetries) {\n        break;\n      }\n\n      // Check retryIf predicate\n      if (retryIf && !retryIf(error)) {\n        break;\n      }\n\n      // Invoke onRetry callback\n      if (onRetry) {\n        onRetry(error, attempt + 1);\n      }\n\n      // Wait before retrying\n      const delay = calculateDelay(attempt + 1, {\n        backoff,\n        initialDelay,\n        maxDelay,\n        jitter,\n      });\n\n      await new Promise((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  // Attach attempt history to the final error\n  const finalError = lastError!;\n  (finalError as any).attempts = errors;\n\n  throw finalError;\n}\n\n// ─── Common Error Creators ───────────────────────────────────────────────────\n\n/**\n * Pre-built factory functions for common HTTP error responses.\n *\n * @example\n * ```ts\n * throw Errors.notFound('User not found', { userId: 42 });\n * throw Errors.unauthorized();\n * throw Errors.tooManyRequests('Rate limit exceeded');\n * ```\n */\nexport const Errors: ErrorMap = {\n  // 4xx Client Errors\n  badRequest: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 400, 'BAD_REQUEST', context),\n\n  unauthorized: (message: string = 'Unauthorized', context?: Record<string, any>) =>\n    new AppError(message, 401, 'UNAUTHORIZED', context),\n\n  paymentRequired: (message: string = 'Payment Required', context?: Record<string, any>) =>\n    new AppError(message, 402, 'PAYMENT_REQUIRED', context),\n\n  forbidden: (message: string = 'Forbidden', context?: Record<string, any>) =>\n    new AppError(message, 403, 'FORBIDDEN', context),\n\n  notFound: (message: string = 'Not Found', context?: Record<string, any>) =>\n    new AppError(message, 404, 'NOT_FOUND', context),\n\n  methodNotAllowed: (message: string = 'Method Not Allowed', context?: Record<string, any>) =>\n    new AppError(message, 405, 'METHOD_NOT_ALLOWED', context),\n\n  notAcceptable: (message: string = 'Not Acceptable', context?: Record<string, any>) =>\n    new AppError(message, 406, 'NOT_ACCEPTABLE', context),\n\n  proxyAuthRequired: (message: string = 'Proxy Authentication Required', context?: Record<string, any>) =>\n    new AppError(message, 407, 'PROXY_AUTH_REQUIRED', context),\n\n  requestTimeout: (message: string = 'Request Timeout', context?: Record<string, any>) =>\n    new AppError(message, 408, 'REQUEST_TIMEOUT', context),\n\n  conflict: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 409, 'CONFLICT', context),\n\n  gone: (message: string = 'Gone', context?: Record<string, any>) =>\n    new AppError(message, 410, 'GONE', context),\n\n  lengthRequired: (message: string = 'Length Required', context?: Record<string, any>) =>\n    new AppError(message, 411, 'LENGTH_REQUIRED', context),\n\n  preconditionFailed: (message: string = 'Precondition Failed', context?: Record<string, any>) =>\n    new AppError(message, 412, 'PRECONDITION_FAILED', context),\n\n  payloadTooLarge: (message: string = 'Payload Too Large', context?: Record<string, any>) =>\n    new AppError(message, 413, 'PAYLOAD_TOO_LARGE', context),\n\n  uriTooLong: (message: string = 'URI Too Long', context?: Record<string, any>) =>\n    new AppError(message, 414, 'URI_TOO_LONG', context),\n\n  unsupportedMediaType: (message: string = 'Unsupported Media Type', context?: Record<string, any>) =>\n    new AppError(message, 415, 'UNSUPPORTED_MEDIA_TYPE', context),\n\n  rangeNotSatisfiable: (message: string = 'Range Not Satisfiable', context?: Record<string, any>) =>\n    new AppError(message, 416, 'RANGE_NOT_SATISFIABLE', context),\n\n  expectationFailed: (message: string = 'Expectation Failed', context?: Record<string, any>) =>\n    new AppError(message, 417, 'EXPECTATION_FAILED', context),\n\n  imATeapot: (message: string = \"I'm a Teapot\", context?: Record<string, any>) =>\n    new AppError(message, 418, 'IM_A_TEAPOT', context),\n\n  misdirectedRequest: (message: string = 'Misdirected Request', context?: Record<string, any>) =>\n    new AppError(message, 421, 'MISDIRECTED_REQUEST', context),\n\n  unprocessableEntity: (message: string = 'Unprocessable Entity', context?: Record<string, any>) =>\n    new AppError(message, 422, 'UNPROCESSABLE_ENTITY', context),\n\n  validationError: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 422, 'VALIDATION_ERROR', context),\n\n  locked: (message: string = 'Locked', context?: Record<string, any>) =>\n    new AppError(message, 423, 'LOCKED', context),\n\n  failedDependency: (message: string = 'Failed Dependency', context?: Record<string, any>) =>\n    new AppError(message, 424, 'FAILED_DEPENDENCY', context),\n\n  tooEarly: (message: string = 'Too Early', context?: Record<string, any>) =>\n    new AppError(message, 425, 'TOO_EARLY', context),\n\n  upgradeRequired: (message: string = 'Upgrade Required', context?: Record<string, any>) =>\n    new AppError(message, 426, 'UPGRADE_REQUIRED', context),\n\n  preconditionRequired: (message: string = 'Precondition Required', context?: Record<string, any>) =>\n    new AppError(message, 428, 'PRECONDITION_REQUIRED', context),\n\n  tooManyRequests: (message: string = 'Too Many Requests', context?: Record<string, any>) =>\n    new AppError(message, 429, 'TOO_MANY_REQUESTS', context),\n\n  requestHeaderFieldsTooLarge: (message: string = 'Request Header Fields Too Large', context?: Record<string, any>) =>\n    new AppError(message, 431, 'REQUEST_HEADER_FIELDS_TOO_LARGE', context),\n\n  unavailableForLegalReasons: (message: string = 'Unavailable For Legal Reasons', context?: Record<string, any>) =>\n    new AppError(message, 451, 'UNAVAILABLE_FOR_LEGAL_REASONS', context),\n\n  // 5xx Server Errors\n  internalServerError: (message: string = 'Internal Server Error', context?: Record<string, any>) =>\n    new AppError(message, 500, 'INTERNAL_SERVER_ERROR', context),\n\n  notImplemented: (message: string = 'Not Implemented', context?: Record<string, any>) =>\n    new AppError(message, 501, 'NOT_IMPLEMENTED', context),\n\n  badGateway: (message: string = 'Bad Gateway', context?: Record<string, any>) =>\n    new AppError(message, 502, 'BAD_GATEWAY', context),\n\n  serviceUnavailable: (message: string = 'Service Unavailable', context?: Record<string, any>) =>\n    new AppError(message, 503, 'SERVICE_UNAVAILABLE', context),\n\n  gatewayTimeout: (message: string = 'Gateway Timeout', context?: Record<string, any>) =>\n    new AppError(message, 504, 'GATEWAY_TIMEOUT', context),\n\n  httpVersionNotSupported: (message: string = 'HTTP Version Not Supported', context?: Record<string, any>) =>\n    new AppError(message, 505, 'HTTP_VERSION_NOT_SUPPORTED', context),\n\n  variantAlsoNegotiates: (message: string = 'Variant Also Negotiates', context?: Record<string, any>) =>\n    new AppError(message, 506, 'VARIANT_ALSO_NEGOTIATES', context),\n\n  insufficientStorage: (message: string = 'Insufficient Storage', context?: Record<string, any>) =>\n    new AppError(message, 507, 'INSUFFICIENT_STORAGE', context),\n\n  loopDetected: (message: string = 'Loop Detected', context?: Record<string, any>) =>\n    new AppError(message, 508, 'LOOP_DETECTED', context),\n\n  bandwidthLimitExceeded: (message: string = 'Bandwidth Limit Exceeded', context?: Record<string, any>) =>\n    new AppError(message, 509, 'BANDWIDTH_LIMIT_EXCEEDED', context),\n\n  notExtended: (message: string = 'Not Extended', context?: Record<string, any>) =>\n    new AppError(message, 510, 'NOT_EXTENDED', context),\n\n  networkAuthenticationRequired: (message: string = 'Network Authentication Required', context?: Record<string, any>) =>\n    new AppError(message, 511, 'NETWORK_AUTHENTICATION_REQUIRED', context),\n\n  networkConnectTimeout: (message: string = 'Network Connect Timeout', context?: Record<string, any>) =>\n    new AppError(message, 599, 'NETWORK_CONNECT_TIMEOUT', context),\n};\n\n// Default export\nexport default {\n  AppError,\n  formatError,\n  handleError,\n  asyncHandler,\n  expressErrorHandler,\n  createErrorResponse,\n  withRetry,\n  Errors,\n};\n"],"mappings":"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","names":[]}

package/dist/esm/index.js

@@ -0,0 +1,238 @@
+// src/index.ts
+var AppError = class _AppError extends Error {
+  code;
+  statusCode;
+  context;
+  isOperational;
+  constructor(message, statusCode = 500, code, context, cause) {
+    super(message, cause ? { cause } : void 0);
+    this.name = this.constructor.name;
+    this.statusCode = statusCode;
+    this.code = code;
+    this.context = context;
+    this.isOperational = true;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  /**
+   * Wraps an existing error as the cause of a new `AppError`.
+   *
+   * This is a convenience factory for error chaining — it creates a new
+   * `AppError` whose `.cause` is set to the original error.
+   *
+   * @param originalError - The caught error to wrap
+   * @param message - Human-readable description of the higher-level failure
+   * @param statusCode - HTTP status code (default: 500)
+   * @param code - Machine-readable error code
+   * @param context - Additional context metadata
+   * @returns A new `AppError` with `originalError` as its cause
+   *
+   * @example
+   * ```ts
+   * try {
+   *   await db.query('SELECT ...');
+   * } catch (err) {
+   *   throw AppError.wrap(err, 'Database query failed', 500, 'DB_ERROR');
+   * }
+   * ```
+   */
+  static wrap(originalError, message, statusCode = 500, code, context) {
+    return new _AppError(message, statusCode, code, context, originalError);
+  }
+};
+function formatError(error, options = {}) {
+  const {
+    includeStack = false,
+    includeTimestamp = true,
+    context: optionsContext = {}
+  } = options;
+  const mergedContext = error instanceof AppError ? { ...error.context, ...optionsContext } : optionsContext;
+  const errorDetails = {
+    message: error.message,
+    ...includeTimestamp && { timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+    ...includeStack && error.stack && { stack: error.stack },
+    ...error instanceof AppError && {
+      code: error.code,
+      statusCode: error.statusCode
+    },
+    ...Object.keys(mergedContext).length > 0 && { context: mergedContext }
+  };
+  if (error.cause && error.cause instanceof Error) {
+    errorDetails.cause = formatError(error.cause, {
+      includeStack,
+      includeTimestamp: false
+      // only top-level gets timestamp
+    });
+  }
+  return errorDetails;
+}
+function handleError(error, options = {}) {
+  const errorDetails = formatError(error, options);
+  if (options.logger) {
+    options.logger(errorDetails);
+  }
+  return errorDetails;
+}
+function asyncHandler(fn) {
+  return ((...args) => {
+    return Promise.resolve(fn(...args)).catch((error) => {
+      throw error;
+    });
+  });
+}
+function expressErrorHandler(options = {}) {
+  return (err, req, res, next) => {
+    const errorDetails = handleError(err, {
+      ...options,
+      context: {
+        ...options.context,
+        method: req.method,
+        path: req.path,
+        ip: req.ip
+      }
+    });
+    const statusCode = err instanceof AppError ? err.statusCode || 500 : 500;
+    if (options.format === "string") {
+      res.status(statusCode).send(errorDetails.message);
+    } else {
+      res.status(statusCode).json(errorDetails);
+    }
+  };
+}
+function createErrorResponse(message, statusCode = 500, code, context) {
+  return new AppError(message, statusCode, code, context);
+}
+function calculateDelay(attempt, options) {
+  const { backoff, initialDelay, maxDelay, jitter } = options;
+  let delay;
+  switch (backoff) {
+    case "exponential":
+      delay = initialDelay * Math.pow(2, attempt - 1);
+      break;
+    case "linear":
+      delay = initialDelay * attempt;
+      break;
+    case "fixed":
+      delay = initialDelay;
+      break;
+    default:
+      delay = initialDelay;
+  }
+  delay = Math.min(delay, maxDelay);
+  if (jitter) {
+    const jitterAmount = delay * 0.25;
+    delay = delay - jitterAmount + Math.random() * jitterAmount * 2;
+  }
+  return Math.round(delay);
+}
+async function withRetry(fn, options = {}) {
+  const {
+    maxRetries = 3,
+    backoff = "exponential",
+    initialDelay = 1e3,
+    maxDelay = 3e4,
+    retryIf,
+    onRetry,
+    jitter = true
+  } = options;
+  const errors = [];
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      lastError = error;
+      errors.push(error);
+      if (attempt === maxRetries) {
+        break;
+      }
+      if (retryIf && !retryIf(error)) {
+        break;
+      }
+      if (onRetry) {
+        onRetry(error, attempt + 1);
+      }
+      const delay = calculateDelay(attempt + 1, {
+        backoff,
+        initialDelay,
+        maxDelay,
+        jitter
+      });
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  const finalError = lastError;
+  finalError.attempts = errors;
+  throw finalError;
+}
+var Errors = {
+  // 4xx Client Errors
+  badRequest: (message, context) => new AppError(message, 400, "BAD_REQUEST", context),
+  unauthorized: (message = "Unauthorized", context) => new AppError(message, 401, "UNAUTHORIZED", context),
+  paymentRequired: (message = "Payment Required", context) => new AppError(message, 402, "PAYMENT_REQUIRED", context),
+  forbidden: (message = "Forbidden", context) => new AppError(message, 403, "FORBIDDEN", context),
+  notFound: (message = "Not Found", context) => new AppError(message, 404, "NOT_FOUND", context),
+  methodNotAllowed: (message = "Method Not Allowed", context) => new AppError(message, 405, "METHOD_NOT_ALLOWED", context),
+  notAcceptable: (message = "Not Acceptable", context) => new AppError(message, 406, "NOT_ACCEPTABLE", context),
+  proxyAuthRequired: (message = "Proxy Authentication Required", context) => new AppError(message, 407, "PROXY_AUTH_REQUIRED", context),
+  requestTimeout: (message = "Request Timeout", context) => new AppError(message, 408, "REQUEST_TIMEOUT", context),
+  conflict: (message, context) => new AppError(message, 409, "CONFLICT", context),
+  gone: (message = "Gone", context) => new AppError(message, 410, "GONE", context),
+  lengthRequired: (message = "Length Required", context) => new AppError(message, 411, "LENGTH_REQUIRED", context),
+  preconditionFailed: (message = "Precondition Failed", context) => new AppError(message, 412, "PRECONDITION_FAILED", context),
+  payloadTooLarge: (message = "Payload Too Large", context) => new AppError(message, 413, "PAYLOAD_TOO_LARGE", context),
+  uriTooLong: (message = "URI Too Long", context) => new AppError(message, 414, "URI_TOO_LONG", context),
+  unsupportedMediaType: (message = "Unsupported Media Type", context) => new AppError(message, 415, "UNSUPPORTED_MEDIA_TYPE", context),
+  rangeNotSatisfiable: (message = "Range Not Satisfiable", context) => new AppError(message, 416, "RANGE_NOT_SATISFIABLE", context),
+  expectationFailed: (message = "Expectation Failed", context) => new AppError(message, 417, "EXPECTATION_FAILED", context),
+  imATeapot: (message = "I'm a Teapot", context) => new AppError(message, 418, "IM_A_TEAPOT", context),
+  misdirectedRequest: (message = "Misdirected Request", context) => new AppError(message, 421, "MISDIRECTED_REQUEST", context),
+  unprocessableEntity: (message = "Unprocessable Entity", context) => new AppError(message, 422, "UNPROCESSABLE_ENTITY", context),
+  validationError: (message, context) => new AppError(message, 422, "VALIDATION_ERROR", context),
+  locked: (message = "Locked", context) => new AppError(message, 423, "LOCKED", context),
+  failedDependency: (message = "Failed Dependency", context) => new AppError(message, 424, "FAILED_DEPENDENCY", context),
+  tooEarly: (message = "Too Early", context) => new AppError(message, 425, "TOO_EARLY", context),
+  upgradeRequired: (message = "Upgrade Required", context) => new AppError(message, 426, "UPGRADE_REQUIRED", context),
+  preconditionRequired: (message = "Precondition Required", context) => new AppError(message, 428, "PRECONDITION_REQUIRED", context),
+  tooManyRequests: (message = "Too Many Requests", context) => new AppError(message, 429, "TOO_MANY_REQUESTS", context),
+  requestHeaderFieldsTooLarge: (message = "Request Header Fields Too Large", context) => new AppError(message, 431, "REQUEST_HEADER_FIELDS_TOO_LARGE", context),
+  unavailableForLegalReasons: (message = "Unavailable For Legal Reasons", context) => new AppError(message, 451, "UNAVAILABLE_FOR_LEGAL_REASONS", context),
+  // 5xx Server Errors
+  internalServerError: (message = "Internal Server Error", context) => new AppError(message, 500, "INTERNAL_SERVER_ERROR", context),
+  notImplemented: (message = "Not Implemented", context) => new AppError(message, 501, "NOT_IMPLEMENTED", context),
+  badGateway: (message = "Bad Gateway", context) => new AppError(message, 502, "BAD_GATEWAY", context),
+  serviceUnavailable: (message = "Service Unavailable", context) => new AppError(message, 503, "SERVICE_UNAVAILABLE", context),
+  gatewayTimeout: (message = "Gateway Timeout", context) => new AppError(message, 504, "GATEWAY_TIMEOUT", context),
+  httpVersionNotSupported: (message = "HTTP Version Not Supported", context) => new AppError(message, 505, "HTTP_VERSION_NOT_SUPPORTED", context),
+  variantAlsoNegotiates: (message = "Variant Also Negotiates", context) => new AppError(message, 506, "VARIANT_ALSO_NEGOTIATES", context),
+  insufficientStorage: (message = "Insufficient Storage", context) => new AppError(message, 507, "INSUFFICIENT_STORAGE", context),
+  loopDetected: (message = "Loop Detected", context) => new AppError(message, 508, "LOOP_DETECTED", context),
+  bandwidthLimitExceeded: (message = "Bandwidth Limit Exceeded", context) => new AppError(message, 509, "BANDWIDTH_LIMIT_EXCEEDED", context),
+  notExtended: (message = "Not Extended", context) => new AppError(message, 510, "NOT_EXTENDED", context),
+  networkAuthenticationRequired: (message = "Network Authentication Required", context) => new AppError(message, 511, "NETWORK_AUTHENTICATION_REQUIRED", context),
+  networkConnectTimeout: (message = "Network Connect Timeout", context) => new AppError(message, 599, "NETWORK_CONNECT_TIMEOUT", context)
+};
+var index_default = {
+  AppError,
+  formatError,
+  handleError,
+  asyncHandler,
+  expressErrorHandler,
+  createErrorResponse,
+  withRetry,
+  Errors
+};
+export {
+  AppError,
+  Errors,
+  asyncHandler,
+  createErrorResponse,
+  index_default as default,
+  expressErrorHandler,
+  formatError,
+  handleError,
+  withRetry
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/index.ts"],"sourcesContent":["/**\n * Error Shield - A comprehensive error handling utility for Node.js & Express.js\n *\n * Provides utilities for error handling, formatting, logging, retry logic,\n * and error chaining with full TypeScript support.\n *\n * @packageDocumentation\n */\n\n// ─── Types & Interfaces ─────────────────────────────────────────────────────\n\n/**\n * Structured representation of an error with optional metadata.\n */\nexport interface ErrorDetails {\n  message: string;\n  code?: string;\n  statusCode?: number;\n  stack?: string;\n  timestamp?: string;\n  context?: Record<string, any>;\n  /** Cause chain information when error chaining is used */\n  cause?: ErrorDetails;\n}\n\n/**\n * Options for configuring error handling behavior.\n */\nexport interface ErrorHandlerOptions {\n  includeStack?: boolean;\n  includeTimestamp?: boolean;\n  format?: 'json' | 'string';\n  logger?: (error: ErrorDetails) => void;\n  context?: Record<string, any>;\n}\n\nexport type ErrorFn = (message: string, context?: Record<string, any>) => AppError;\n\nexport type ErrorMap = Record<string, ErrorFn>;\n\n/**\n * Configuration options for the retry utility.\n */\nexport interface RetryOptions {\n  /** Maximum number of retry attempts (default: 3) */\n  maxRetries?: number;\n  /** Backoff strategy between retries (default: 'exponential') */\n  backoff?: 'exponential' | 'linear' | 'fixed';\n  /** Initial delay in milliseconds before the first retry (default: 1000) */\n  initialDelay?: number;\n  /** Maximum delay in milliseconds between retries (default: 30000) */\n  maxDelay?: number;\n  /**\n   * Optional predicate to determine whether a retry should be attempted.\n   * If provided and returns `false`, the error is thrown immediately.\n   */\n  retryIf?: (error: Error) => boolean;\n  /** Optional callback invoked before each retry attempt */\n  onRetry?: (error: Error, attempt: number) => void;\n  /** Whether to add random jitter to the delay to prevent thundering herd (default: true) */\n  jitter?: boolean;\n}\n\n// ─── AppError Class ──────────────────────────────────────────────────────────\n\n/**\n * Custom Error class with additional properties for structured error handling.\n *\n * Supports error chaining via the native ES2022 `Error.cause` feature.\n *\n * @example\n * ```ts\n * const error = new AppError('Something broke', 500, 'INTERNAL', { userId: 123 });\n *\n * // With error chaining\n * try {\n *   await fetchData();\n * } catch (err) {\n *   throw new AppError('Failed to fetch data', 502, 'FETCH_FAILED', undefined, err);\n * }\n * ```\n */\nexport class AppError extends Error {\n  public code?: string;\n  public statusCode?: number;\n  public context?: Record<string, any>;\n  public isOperational: boolean;\n\n  constructor(\n    message: string,\n    statusCode: number = 500,\n    code?: string,\n    context?: Record<string, any>,\n    cause?: Error\n  ) {\n    super(message, cause ? { cause } : undefined);\n    this.name = this.constructor.name;\n    this.statusCode = statusCode;\n    this.code = code;\n    this.context = context;\n    this.isOperational = true;\n    if ((Error as any).captureStackTrace) {\n      (Error as any).captureStackTrace(this, this.constructor);\n    }\n  }\n\n  /**\n   * Wraps an existing error as the cause of a new `AppError`.\n   *\n   * This is a convenience factory for error chaining — it creates a new\n   * `AppError` whose `.cause` is set to the original error.\n   *\n   * @param originalError - The caught error to wrap\n   * @param message - Human-readable description of the higher-level failure\n   * @param statusCode - HTTP status code (default: 500)\n   * @param code - Machine-readable error code\n   * @param context - Additional context metadata\n   * @returns A new `AppError` with `originalError` as its cause\n   *\n   * @example\n   * ```ts\n   * try {\n   *   await db.query('SELECT ...');\n   * } catch (err) {\n   *   throw AppError.wrap(err, 'Database query failed', 500, 'DB_ERROR');\n   * }\n   * ```\n   */\n  static wrap(\n    originalError: Error,\n    message: string,\n    statusCode: number = 500,\n    code?: string,\n    context?: Record<string, any>\n  ): AppError {\n    return new AppError(message, statusCode, code, context, originalError);\n  }\n}\n\n// ─── Core Utilities ──────────────────────────────────────────────────────────\n\n/**\n * Formats an error into a structured {@link ErrorDetails} object.\n *\n * When the error has a `.cause`, the cause chain is recursively formatted\n * and included in the output.\n */\nexport function formatError(\n  error: Error | AppError,\n  options: ErrorHandlerOptions = {}\n): ErrorDetails {\n  const {\n    includeStack = false,\n    includeTimestamp = true,\n    context: optionsContext = {},\n  } = options;\n\n  const mergedContext = error instanceof AppError\n    ? { ...error.context, ...optionsContext }\n    : optionsContext;\n\n  const errorDetails: ErrorDetails = {\n    message: error.message,\n    ...(includeTimestamp && { timestamp: new Date().toISOString() }),\n    ...(includeStack && error.stack && { stack: error.stack }),\n    ...(error instanceof AppError && {\n      code: error.code,\n      statusCode: error.statusCode,\n    }),\n    ...(Object.keys(mergedContext).length > 0 && { context: mergedContext }),\n  };\n\n  // Recursively format the cause chain\n  if (error.cause && error.cause instanceof Error) {\n    errorDetails.cause = formatError(error.cause, {\n      includeStack,\n      includeTimestamp: false, // only top-level gets timestamp\n    });\n  }\n\n  return errorDetails;\n}\n\n/**\n * Handles errors with optional logging and formatting.\n */\nexport function handleError(\n  error: Error | AppError,\n  options: ErrorHandlerOptions = {}\n): ErrorDetails {\n  const errorDetails = formatError(error, options);\n\n  if (options.logger) {\n    options.logger(errorDetails);\n  }\n\n  return errorDetails;\n}\n\n/**\n * Async error wrapper — catches errors from async route handlers\n * and forwards them to Express's `next()` function.\n */\nexport function asyncHandler<T extends (...args: any[]) => Promise<any>>(\n  fn: T\n): T {\n  return ((...args: any[]) => {\n    return Promise.resolve(fn(...args)).catch((error) => {\n      throw error;\n    });\n  }) as T;\n}\n\n/**\n * Express.js error handler middleware factory.\n *\n * Returns a standard Express error-handling middleware that formats\n * the error and sends an appropriate JSON or string response.\n */\nexport function expressErrorHandler(\n  options: ErrorHandlerOptions = {}\n) {\n  return (\n    err: Error | AppError,\n    req: any,\n    res: any,\n    next: any\n  ): void => {\n    const errorDetails = handleError(err, {\n      ...options,\n      context: {\n        ...options.context,\n        method: req.method,\n        path: req.path,\n        ip: req.ip,\n      },\n    });\n\n    const statusCode =\n      err instanceof AppError ? err.statusCode || 500 : 500;\n\n    if (options.format === 'string') {\n      res.status(statusCode).send(errorDetails.message);\n    } else {\n      res.status(statusCode).json(errorDetails);\n    }\n  };\n}\n\n/**\n * Creates a standardized error response.\n */\nexport function createErrorResponse(\n  message: string,\n  statusCode: number = 500,\n  code?: string,\n  context?: Record<string, any>\n): AppError {\n  return new AppError(message, statusCode, code, context);\n}\n\n// ─── Retry Utility ───────────────────────────────────────────────────────────\n\n/**\n * Calculates the delay for a given retry attempt based on the backoff strategy.\n * @internal\n */\nfunction calculateDelay(\n  attempt: number,\n  options: Required<Pick<RetryOptions, 'backoff' | 'initialDelay' | 'maxDelay' | 'jitter'>>\n): number {\n  const { backoff, initialDelay, maxDelay, jitter } = options;\n\n  let delay: number;\n\n  switch (backoff) {\n    case 'exponential':\n      delay = initialDelay * Math.pow(2, attempt - 1);\n      break;\n    case 'linear':\n      delay = initialDelay * attempt;\n      break;\n    case 'fixed':\n      delay = initialDelay;\n      break;\n    default:\n      delay = initialDelay;\n  }\n\n  // Cap at maxDelay\n  delay = Math.min(delay, maxDelay);\n\n  // Add jitter (±25% randomness)\n  if (jitter) {\n    const jitterAmount = delay * 0.25;\n    delay = delay - jitterAmount + Math.random() * jitterAmount * 2;\n  }\n\n  return Math.round(delay);\n}\n\n/**\n * Executes an async function with automatic retries on failure.\n *\n * Supports exponential, linear, and fixed backoff strategies with\n * optional jitter, conditional retry predicates, and retry callbacks.\n *\n * If all retries are exhausted, the **last** error is thrown. The previous\n * attempt errors are accessible via the error's `.cause` chain and the\n * `attempts` property attached to the final error.\n *\n * @typeParam T - The return type of the async function\n * @param fn - The async function to execute with retries\n * @param options - Retry configuration options\n * @returns The result of the successful function execution\n *\n * @example\n * ```ts\n * const data = await withRetry(\n *   () => fetch('https://api.example.com/data').then(r => r.json()),\n *   {\n *     maxRetries: 5,\n *     backoff: 'exponential',\n *     initialDelay: 500,\n *     retryIf: (err) => err.message.includes('ECONNREFUSED'),\n *     onRetry: (err, attempt) => console.log(`Retry ${attempt}: ${err.message}`),\n *   }\n * );\n * ```\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  options: RetryOptions = {}\n): Promise<T> {\n  const {\n    maxRetries = 3,\n    backoff = 'exponential',\n    initialDelay = 1000,\n    maxDelay = 30000,\n    retryIf,\n    onRetry,\n    jitter = true,\n  } = options;\n\n  const errors: Error[] = [];\n  let lastError: Error | undefined;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      lastError = error;\n      errors.push(error);\n\n      // If this was the last attempt, break to throw\n      if (attempt === maxRetries) {\n        break;\n      }\n\n      // Check retryIf predicate\n      if (retryIf && !retryIf(error)) {\n        break;\n      }\n\n      // Invoke onRetry callback\n      if (onRetry) {\n        onRetry(error, attempt + 1);\n      }\n\n      // Wait before retrying\n      const delay = calculateDelay(attempt + 1, {\n        backoff,\n        initialDelay,\n        maxDelay,\n        jitter,\n      });\n\n      await new Promise((resolve) => setTimeout(resolve, delay));\n    }\n  }\n\n  // Attach attempt history to the final error\n  const finalError = lastError!;\n  (finalError as any).attempts = errors;\n\n  throw finalError;\n}\n\n// ─── Common Error Creators ───────────────────────────────────────────────────\n\n/**\n * Pre-built factory functions for common HTTP error responses.\n *\n * @example\n * ```ts\n * throw Errors.notFound('User not found', { userId: 42 });\n * throw Errors.unauthorized();\n * throw Errors.tooManyRequests('Rate limit exceeded');\n * ```\n */\nexport const Errors: ErrorMap = {\n  // 4xx Client Errors\n  badRequest: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 400, 'BAD_REQUEST', context),\n\n  unauthorized: (message: string = 'Unauthorized', context?: Record<string, any>) =>\n    new AppError(message, 401, 'UNAUTHORIZED', context),\n\n  paymentRequired: (message: string = 'Payment Required', context?: Record<string, any>) =>\n    new AppError(message, 402, 'PAYMENT_REQUIRED', context),\n\n  forbidden: (message: string = 'Forbidden', context?: Record<string, any>) =>\n    new AppError(message, 403, 'FORBIDDEN', context),\n\n  notFound: (message: string = 'Not Found', context?: Record<string, any>) =>\n    new AppError(message, 404, 'NOT_FOUND', context),\n\n  methodNotAllowed: (message: string = 'Method Not Allowed', context?: Record<string, any>) =>\n    new AppError(message, 405, 'METHOD_NOT_ALLOWED', context),\n\n  notAcceptable: (message: string = 'Not Acceptable', context?: Record<string, any>) =>\n    new AppError(message, 406, 'NOT_ACCEPTABLE', context),\n\n  proxyAuthRequired: (message: string = 'Proxy Authentication Required', context?: Record<string, any>) =>\n    new AppError(message, 407, 'PROXY_AUTH_REQUIRED', context),\n\n  requestTimeout: (message: string = 'Request Timeout', context?: Record<string, any>) =>\n    new AppError(message, 408, 'REQUEST_TIMEOUT', context),\n\n  conflict: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 409, 'CONFLICT', context),\n\n  gone: (message: string = 'Gone', context?: Record<string, any>) =>\n    new AppError(message, 410, 'GONE', context),\n\n  lengthRequired: (message: string = 'Length Required', context?: Record<string, any>) =>\n    new AppError(message, 411, 'LENGTH_REQUIRED', context),\n\n  preconditionFailed: (message: string = 'Precondition Failed', context?: Record<string, any>) =>\n    new AppError(message, 412, 'PRECONDITION_FAILED', context),\n\n  payloadTooLarge: (message: string = 'Payload Too Large', context?: Record<string, any>) =>\n    new AppError(message, 413, 'PAYLOAD_TOO_LARGE', context),\n\n  uriTooLong: (message: string = 'URI Too Long', context?: Record<string, any>) =>\n    new AppError(message, 414, 'URI_TOO_LONG', context),\n\n  unsupportedMediaType: (message: string = 'Unsupported Media Type', context?: Record<string, any>) =>\n    new AppError(message, 415, 'UNSUPPORTED_MEDIA_TYPE', context),\n\n  rangeNotSatisfiable: (message: string = 'Range Not Satisfiable', context?: Record<string, any>) =>\n    new AppError(message, 416, 'RANGE_NOT_SATISFIABLE', context),\n\n  expectationFailed: (message: string = 'Expectation Failed', context?: Record<string, any>) =>\n    new AppError(message, 417, 'EXPECTATION_FAILED', context),\n\n  imATeapot: (message: string = \"I'm a Teapot\", context?: Record<string, any>) =>\n    new AppError(message, 418, 'IM_A_TEAPOT', context),\n\n  misdirectedRequest: (message: string = 'Misdirected Request', context?: Record<string, any>) =>\n    new AppError(message, 421, 'MISDIRECTED_REQUEST', context),\n\n  unprocessableEntity: (message: string = 'Unprocessable Entity', context?: Record<string, any>) =>\n    new AppError(message, 422, 'UNPROCESSABLE_ENTITY', context),\n\n  validationError: (message: string, context?: Record<string, any>) =>\n    new AppError(message, 422, 'VALIDATION_ERROR', context),\n\n  locked: (message: string = 'Locked', context?: Record<string, any>) =>\n    new AppError(message, 423, 'LOCKED', context),\n\n  failedDependency: (message: string = 'Failed Dependency', context?: Record<string, any>) =>\n    new AppError(message, 424, 'FAILED_DEPENDENCY', context),\n\n  tooEarly: (message: string = 'Too Early', context?: Record<string, any>) =>\n    new AppError(message, 425, 'TOO_EARLY', context),\n\n  upgradeRequired: (message: string = 'Upgrade Required', context?: Record<string, any>) =>\n    new AppError(message, 426, 'UPGRADE_REQUIRED', context),\n\n  preconditionRequired: (message: string = 'Precondition Required', context?: Record<string, any>) =>\n    new AppError(message, 428, 'PRECONDITION_REQUIRED', context),\n\n  tooManyRequests: (message: string = 'Too Many Requests', context?: Record<string, any>) =>\n    new AppError(message, 429, 'TOO_MANY_REQUESTS', context),\n\n  requestHeaderFieldsTooLarge: (message: string = 'Request Header Fields Too Large', context?: Record<string, any>) =>\n    new AppError(message, 431, 'REQUEST_HEADER_FIELDS_TOO_LARGE', context),\n\n  unavailableForLegalReasons: (message: string = 'Unavailable For Legal Reasons', context?: Record<string, any>) =>\n    new AppError(message, 451, 'UNAVAILABLE_FOR_LEGAL_REASONS', context),\n\n  // 5xx Server Errors\n  internalServerError: (message: string = 'Internal Server Error', context?: Record<string, any>) =>\n    new AppError(message, 500, 'INTERNAL_SERVER_ERROR', context),\n\n  notImplemented: (message: string = 'Not Implemented', context?: Record<string, any>) =>\n    new AppError(message, 501, 'NOT_IMPLEMENTED', context),\n\n  badGateway: (message: string = 'Bad Gateway', context?: Record<string, any>) =>\n    new AppError(message, 502, 'BAD_GATEWAY', context),\n\n  serviceUnavailable: (message: string = 'Service Unavailable', context?: Record<string, any>) =>\n    new AppError(message, 503, 'SERVICE_UNAVAILABLE', context),\n\n  gatewayTimeout: (message: string = 'Gateway Timeout', context?: Record<string, any>) =>\n    new AppError(message, 504, 'GATEWAY_TIMEOUT', context),\n\n  httpVersionNotSupported: (message: string = 'HTTP Version Not Supported', context?: Record<string, any>) =>\n    new AppError(message, 505, 'HTTP_VERSION_NOT_SUPPORTED', context),\n\n  variantAlsoNegotiates: (message: string = 'Variant Also Negotiates', context?: Record<string, any>) =>\n    new AppError(message, 506, 'VARIANT_ALSO_NEGOTIATES', context),\n\n  insufficientStorage: (message: string = 'Insufficient Storage', context?: Record<string, any>) =>\n    new AppError(message, 507, 'INSUFFICIENT_STORAGE', context),\n\n  loopDetected: (message: string = 'Loop Detected', context?: Record<string, any>) =>\n    new AppError(message, 508, 'LOOP_DETECTED', context),\n\n  bandwidthLimitExceeded: (message: string = 'Bandwidth Limit Exceeded', context?: Record<string, any>) =>\n    new AppError(message, 509, 'BANDWIDTH_LIMIT_EXCEEDED', context),\n\n  notExtended: (message: string = 'Not Extended', context?: Record<string, any>) =>\n    new AppError(message, 510, 'NOT_EXTENDED', context),\n\n  networkAuthenticationRequired: (message: string = 'Network Authentication Required', context?: Record<string, any>) =>\n    new AppError(message, 511, 'NETWORK_AUTHENTICATION_REQUIRED', context),\n\n  networkConnectTimeout: (message: string = 'Network Connect Timeout', context?: Record<string, any>) =>\n    new AppError(message, 599, 'NETWORK_CONNECT_TIMEOUT', context),\n};\n\n// Default export\nexport default {\n  AppError,\n  formatError,\n  handleError,\n  asyncHandler,\n  expressErrorHandler,\n  createErrorResponse,\n  withRetry,\n  Errors,\n};\n"],"mappings":"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","names":[]}

package/dist/types/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Error Shield - A comprehensive error handling utility for Node.js & Express.js
+ *
+ * Provides utilities for error handling, formatting, logging, retry logic,
+ * and error chaining with full TypeScript support.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Structured representation of an error with optional metadata.
+ */
+interface ErrorDetails {
+    message: string;
+    code?: string;
+    statusCode?: number;
+    stack?: string;
+    timestamp?: string;
+    context?: Record<string, any>;
+    /** Cause chain information when error chaining is used */
+    cause?: ErrorDetails;
+}
+/**
+ * Options for configuring error handling behavior.
+ */
+interface ErrorHandlerOptions {
+    includeStack?: boolean;
+    includeTimestamp?: boolean;
+    format?: 'json' | 'string';
+    logger?: (error: ErrorDetails) => void;
+    context?: Record<string, any>;
+}
+type ErrorFn = (message: string, context?: Record<string, any>) => AppError;
+type ErrorMap = Record<string, ErrorFn>;
+/**
+ * Configuration options for the retry utility.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Backoff strategy between retries (default: 'exponential') */
+    backoff?: 'exponential' | 'linear' | 'fixed';
+    /** Initial delay in milliseconds before the first retry (default: 1000) */
+    initialDelay?: number;
+    /** Maximum delay in milliseconds between retries (default: 30000) */
+    maxDelay?: number;
+    /**
+     * Optional predicate to determine whether a retry should be attempted.
+     * If provided and returns `false`, the error is thrown immediately.
+     */
+    retryIf?: (error: Error) => boolean;
+    /** Optional callback invoked before each retry attempt */
+    onRetry?: (error: Error, attempt: number) => void;
+    /** Whether to add random jitter to the delay to prevent thundering herd (default: true) */
+    jitter?: boolean;
+}
+/**
+ * Custom Error class with additional properties for structured error handling.
+ *
+ * Supports error chaining via the native ES2022 `Error.cause` feature.
+ *
+ * @example
+ * ```ts
+ * const error = new AppError('Something broke', 500, 'INTERNAL', { userId: 123 });
+ *
+ * // With error chaining
+ * try {
+ *   await fetchData();
+ * } catch (err) {
+ *   throw new AppError('Failed to fetch data', 502, 'FETCH_FAILED', undefined, err);
+ * }
+ * ```
+ */
+declare class AppError extends Error {
+    code?: string;
+    statusCode?: number;
+    context?: Record<string, any>;
+    isOperational: boolean;
+    constructor(message: string, statusCode?: number, code?: string, context?: Record<string, any>, cause?: Error);
+    /**
+     * Wraps an existing error as the cause of a new `AppError`.
+     *
+     * This is a convenience factory for error chaining — it creates a new
+     * `AppError` whose `.cause` is set to the original error.
+     *
+     * @param originalError - The caught error to wrap
+     * @param message - Human-readable description of the higher-level failure
+     * @param statusCode - HTTP status code (default: 500)
+     * @param code - Machine-readable error code
+     * @param context - Additional context metadata
+     * @returns A new `AppError` with `originalError` as its cause
+     *
+     * @example
+     * ```ts
+     * try {
+     *   await db.query('SELECT ...');
+     * } catch (err) {
+     *   throw AppError.wrap(err, 'Database query failed', 500, 'DB_ERROR');
+     * }
+     * ```
+     */
+    static wrap(originalError: Error, message: string, statusCode?: number, code?: string, context?: Record<string, any>): AppError;
+}
+/**
+ * Formats an error into a structured {@link ErrorDetails} object.
+ *
+ * When the error has a `.cause`, the cause chain is recursively formatted
+ * and included in the output.
+ */
+declare function formatError(error: Error | AppError, options?: ErrorHandlerOptions): ErrorDetails;
+/**
+ * Handles errors with optional logging and formatting.
+ */
+declare function handleError(error: Error | AppError, options?: ErrorHandlerOptions): ErrorDetails;
+/**
+ * Async error wrapper — catches errors from async route handlers
+ * and forwards them to Express's `next()` function.
+ */
+declare function asyncHandler<T extends (...args: any[]) => Promise<any>>(fn: T): T;
+/**
+ * Express.js error handler middleware factory.
+ *
+ * Returns a standard Express error-handling middleware that formats
+ * the error and sends an appropriate JSON or string response.
+ */
+declare function expressErrorHandler(options?: ErrorHandlerOptions): (err: Error | AppError, req: any, res: any, next: any) => void;
+/**
+ * Creates a standardized error response.
+ */
+declare function createErrorResponse(message: string, statusCode?: number, code?: string, context?: Record<string, any>): AppError;
+/**
+ * Executes an async function with automatic retries on failure.
+ *
+ * Supports exponential, linear, and fixed backoff strategies with
+ * optional jitter, conditional retry predicates, and retry callbacks.
+ *
+ * If all retries are exhausted, the **last** error is thrown. The previous
+ * attempt errors are accessible via the error's `.cause` chain and the
+ * `attempts` property attached to the final error.
+ *
+ * @typeParam T - The return type of the async function
+ * @param fn - The async function to execute with retries
+ * @param options - Retry configuration options
+ * @returns The result of the successful function execution
+ *
+ * @example
+ * ```ts
+ * const data = await withRetry(
+ *   () => fetch('https://api.example.com/data').then(r => r.json()),
+ *   {
+ *     maxRetries: 5,
+ *     backoff: 'exponential',
+ *     initialDelay: 500,
+ *     retryIf: (err) => err.message.includes('ECONNREFUSED'),
+ *     onRetry: (err, attempt) => console.log(`Retry ${attempt}: ${err.message}`),
+ *   }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Pre-built factory functions for common HTTP error responses.
+ *
+ * @example
+ * ```ts
+ * throw Errors.notFound('User not found', { userId: 42 });
+ * throw Errors.unauthorized();
+ * throw Errors.tooManyRequests('Rate limit exceeded');
+ * ```
+ */
+declare const Errors: ErrorMap;
+declare const _default: {
+    AppError: typeof AppError;
+    formatError: typeof formatError;
+    handleError: typeof handleError;
+    asyncHandler: typeof asyncHandler;
+    expressErrorHandler: typeof expressErrorHandler;
+    createErrorResponse: typeof createErrorResponse;
+    withRetry: typeof withRetry;
+    Errors: ErrorMap;
+};
+
+export { AppError, type ErrorDetails, type ErrorFn, type ErrorHandlerOptions, type ErrorMap, Errors, type RetryOptions, asyncHandler, createErrorResponse, _default as default, expressErrorHandler, formatError, handleError, withRetry };

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "error-shield",
-  "version": "1.2.3",
-  "description": "Comprehensive error handling utility for Node.js & Express.js — custom error classes, async handler wrapper, Express middleware, HTTP error creators, and TypeScript support.",
+  "version": "2.0.1",
+  "description": "Comprehensive error handling utility for Node.js & Express.js — custom error classes, async handler wrapper, Express middleware, HTTP error creators, retry logic, error chaining, and TypeScript support.",
+  "type": "module",
   "keywords": [
     "error-handling",
     "error-handler",
@@ -26,7 +27,11 @@
     "validation-error",
     "app-error",
     "error-utility",
-    "structured-errors"
+    "structured-errors",
+    "error-chaining",
+    "retry",
+    "retry-logic",
+    "exponential-backoff"
   ],
   "homepage": "https://github.com/Gopinathgopi13/error-shield",
   "repository": {
@@ -35,13 +40,38 @@
   },
   "author": "Gopinath Kathirvel",
   "license": "ISC",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0",
+    "@vitest/coverage-v8": "^2.0.0"
   }
 }