@erangamadhushan/express-error-handle-middleware 1.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eranga Madhushan (EM956)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,345 @@
+# @erangamadhushan/express-error-handle-middleware
+
+Advanced TypeScript-based error handling middleware for Express.js.
+
+![npm version](https://img.shields.io/npm/v/@erangamadhushan/express-error-handle-middleware)
+![npm downloads](https://img.shields.io/npm/dm/@erangamadhushan/express-error-handle-middleware)
+![CI](https://img.shields.io/npm/ci/@erangamadhushan/express-error-handle-middleware)
+![License](https://img.shields.io/npm/l/@erangamadhushan/express-error-handle-middleware)
+
+---
+
+## ✨ Features
+
+- Async handler wrapper
+- Custom `ApiError` class
+- Predefined error classes (NotFound, BadRequest, etc.)
+- `createError` helper for clean DX
+- Global error middleware
+- 404 Not Found middleware
+- Logger integration (Pino, Winston, custom)
+- Request ID and correlation metadata
+- Structured logger context
+- Custom error adapters
+- Reusable adapter registry
+- MongoDB duplicate key smart parsing
+- Zod validation error formatting
+- Standardized error response structure
+- RFC 9457-style problem details
+- Custom response serializers
+- Configurable message exposure
+- Production-safe stack handling
+- ESM + CommonJS support
+- Full TypeScript support
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @erangamadhushan/express-error-handle-middleware
+```
+
+## Compatibility
+
+- Node.js 18.18 or newer
+- Express 4.18 or newer, including Express 5
+- Zod 4 is optional and only required when using Zod validation errors
+
+Express is a peer dependency because the middleware uses the host application's Express runtime. The package does not bundle Express, Zod, or other runtime dependencies.
+
+## 🚀 Quick Start
+
+```ts
+import express from "express";
+import {
+  asyncHandler,
+  createError,
+  notFoundMiddleware,
+  errorMiddleware,
+  requestIdMiddleware,
+} from "@erangamadhushan/express-error-handle-middleware";
+
+const app = express();
+app.use(express.json());
+app.use(requestIdMiddleware());
+
+app.get(
+  "/users/:id",
+  asyncHandler(async (req, res) => {
+    if (req.params.id !== "1") {
+      throw createError.notFound("User not found");
+    }
+
+    res.json({ id: 1, name: "John" });
+  }),
+);
+
+app.use(notFoundMiddleware);
+app.use(errorMiddleware());
+
+app.listen(5000);
+```
+
+## 🧠 Recommended Workflow
+
+- Wrap all controllers using asyncHandler.
+- Throw errors using createError.* (recommended) or ApiError.
+- Add requestIdMiddleware near the start of the application.
+- Use global errorMiddleware.
+- Integrate a logger in production.
+- Use problem details or a custom serializer when an API-specific response contract is required.
+
+## 🧩 Error Creation Options
+
+### Using createError (Recommended)
+
+```ts
+throw createError.badRequest("Invalid input");
+throw createError.notFound("User not found");
+throw createError.unauthorized();
+```
+
+### Using ApiError
+
+```ts
+throw new ApiError("User not found", 404, "USER_NOT_FOUND");
+```
+
+### Using Predefined Classes
+
+```ts
+import { NotFoundError } from "...";
+
+throw new NotFoundError("User not found");
+```
+
+## 📤 Response Format
+
+All errors follow a consistent structure:
+
+```json
+{
+  "success": false,
+  "statusCode": 404,
+  "message": "User not found",
+  "error": "NotFoundError",
+  "code": "NOT_FOUND"
+}
+```
+
+The legacy response format is the default for compatibility. Enable RFC 9457-style responses with `responseFormat: "problem"`:
+
+```json
+{
+  "type": "urn:express-error-kit:NOT_FOUND",
+  "title": "NotFoundError",
+  "status": 404,
+  "detail": "User not found",
+  "instance": "/users/42",
+  "code": "NOT_FOUND",
+  "requestId": "request-123"
+}
+```
+
+## 🧠 Smart MongoDB Error Handling
+
+### Duplicate key errors are automatically formatted
+
+```ts
+// Mongo duplicate key error
+{
+  code: 11000,
+  keyValue: { email: "test@example.com" }
+}
+```
+
+Response:
+
+```json
+{
+  "success": false,
+  "message": "email already exists",
+  "code": "DUPLICATE_FIELD"
+}
+```
+
+## 🧾 Zod Validation Formatting
+
+If using Zod:
+
+```ts
+throw new ZodError([...]);
+```
+
+Response:
+
+```json
+{
+  "success": false,
+  "message": "email: Expected string",
+  "code": "VALIDATION_ERROR"
+}
+```
+
+## 🪵 Logger Integration
+
+Use any logger:
+
+```ts
+import pino from "pino";
+
+const logger = pino();
+
+app.use(
+  errorMiddleware({
+    logger: (error, context) => logger.error({ error, ...context }),
+    showStack: false,
+  }),
+);
+```
+
+The logger receives the normalized error and structured request context containing `requestId`, `method`, `url`, `path`, `statusCode`, `code`, and `errorName`.
+
+## 📚 Middleware Order (Important)
+
+```js
+app.use(routes);
+
+app.use(notFoundMiddleware);
+app.use(errorMiddleware());
+```
+
+## 🧩 Creating Custom Errors
+
+### Using createError (Recommended)
+
+```ts
+import { createError } from "@erangamadhushan/express-error-handle-middleware";
+
+throw createError.notFound("User not found");
+throw createError.badRequest("Invalid input");
+throw createError.unauthorized();
+```
+
+### Using ApiError
+
+```ts
+import { ApiError } from "@erangamadhushan/express-error-handle-middleware";
+
+throw new ApiError("User not found", 404, "USER_NOT_FOUND");
+```
+
+You can extend it like this:
+
+```ts
+import { ApiError } from "@erangamadhushan/express-error-handle-middleware";
+
+class ValidationError extends ApiError {
+  constructor(message: string) {
+    super(message, 400, "VALIDATION_ERROR");
+  }
+}
+```
+
+## ⚙️ Configuration Options
+
+```ts
+errorMiddleware(options?: {
+  logger?: (error: unknown, context: ErrorLogContext) => void;
+  showStack?: boolean;
+  expose?: boolean | ((error: ApiError, context: ErrorRequestContext) => boolean);
+  responseFormat?: "legacy" | "problem";
+  serializer?: (error: ApiError, context: ErrorSerializationContext) => unknown;
+  requestId?: {
+    headerName?: string;
+    generator?: () => string;
+  };
+  adapters?: readonly ErrorAdapter[] | ErrorAdapterRegistry;
+});
+```
+
+Request IDs are read from `x-request-id` by default, generated when absent, returned in the response header, and exposed through the logger and serializer context. Use `requestIdMiddleware()` near the start of the application to correlate successful requests as well as failures. Set `responseFormat: "problem"` for an RFC 9457-style response with `application/problem+json` content type.
+
+Use `expose` to control whether an error message is returned. In production, 500-level messages are hidden by default.
+
+Custom adapters can map application or library errors to `ApiError` instances. They run before the built-in MongoDB and Zod adapters.
+
+```ts
+import {
+  ApiError,
+  errorMiddleware,
+} from "@erangamadhushan/express-error-handle-middleware";
+
+const domainErrorAdapter = (error: unknown) => {
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "type" in error &&
+    error.type === "domain_error"
+  ) {
+    return new ApiError("The resource is in an invalid state", 409, "INVALID_STATE");
+  }
+
+  return undefined;
+};
+
+app.use(errorMiddleware({ adapters: [domainErrorAdapter] }));
+```
+
+For shared application configuration, register adapters once and reuse the registry:
+
+```ts
+const adapters = new ErrorAdapterRegistry()
+  .register(domainErrorAdapter);
+
+app.use(errorMiddleware({ adapters }));
+```
+
+## 🛡 Production Behavior
+
+- Stack traces hidden automatically in production
+- 500-level messages hidden automatically in production
+- Request IDs returned through the response header
+- Structured context available to loggers and serializers
+- Clean legacy JSON or problem-details response formats
+- Centralized error normalization and exposure control
+
+## 🧪 Testing
+
+```bash
+npm ci
+npm test -- --runInBand
+npx tsc --noEmit
+npm run build
+npm run smoke:package
+```
+
+## Docker Validation
+
+The repository Dockerfile is a reproducible validation image for contributors and CI. It runs the typecheck, test suite, package build, and packed-package smoke test; it is not a production runtime image because this project publishes an npm library rather than an Express application.
+
+```bash
+docker build --tag express-error-handle-kit-validation .
+docker run --rm express-error-handle-kit-validation
+```
+
+## 🔄 Automated Releases
+
+- Conventional commits
+- semantic-release
+- GitHub Actions CI
+- Automatic versioning and changelog generation
+
+## Contributing
+
+Contributions are welcome!
+
+Please read CONTRIBUTING.md before opening a pull request.
+
+## Engineering Documents
+
+- [Architecture](ARCHITECTURE.md)
+- [Error contract ADR](ADRs/001-error-contract.md)
+- [Adapter system ADR](ADRs/002-adapter-system.md)
+- [Compatibility matrix](COMPATIBILITY.md)

package/dist/index.cjs

@@ -0,0 +1,309 @@
+"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, {
+  ApiError: () => ApiError,
+  BadRequestError: () => BadRequestError,
+  ConflictError: () => ConflictError,
+  ErrorAdapterRegistry: () => ErrorAdapterRegistry,
+  ForbiddenError: () => ForbiddenError,
+  InternalServerError: () => InternalServerError,
+  NotFoundError: () => NotFoundError,
+  UnauthorizedError: () => UnauthorizedError,
+  ValidationError: () => ValidationError,
+  asyncHandler: () => asyncHandler,
+  createError: () => createError,
+  createRequestContext: () => createRequestContext,
+  errorMiddleware: () => errorMiddleware,
+  getOrCreateRequestContext: () => getOrCreateRequestContext,
+  mongoDuplicateKeyAdapter: () => mongoDuplicateKeyAdapter,
+  normalizeError: () => normalizeError,
+  notFoundMiddleware: () => notFoundMiddleware,
+  requestIdMiddleware: () => requestIdMiddleware,
+  serializeError: () => serializeError,
+  zodErrorAdapter: () => zodErrorAdapter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/asyncHandler.ts
+var asyncHandler = (fn) => {
+  return (req, res, next) => {
+    Promise.resolve().then(() => fn(req, res, next)).catch(next);
+  };
+};
+
+// src/ApiError.ts
+var ApiError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true;
+    Object.setPrototypeOf(this, new.target.prototype);
+    Error.captureStackTrace(this);
+  }
+};
+
+// src/adapters/mongoDuplicateKey.ts
+var isRecord = (value) => typeof value === "object" && value !== null;
+var mongoDuplicateKeyAdapter = (error) => {
+  if (!isRecord(error) || error.code !== 11e3) {
+    return void 0;
+  }
+  const keyValue = isRecord(error.keyValue) ? error.keyValue : void 0;
+  const field = keyValue ? Object.keys(keyValue)[0] : void 0;
+  const message = field ? `${field} already exists` : "Duplicate value";
+  return new ApiError(message, 400, "DUPLICATE_FIELD");
+};
+
+// src/adapters/zod.ts
+var isRecord2 = (value) => typeof value === "object" && value !== null;
+var zodErrorAdapter = (error) => {
+  if (!isRecord2(error) || error.name !== "ZodError" || !Array.isArray(error.issues)) {
+    return void 0;
+  }
+  const message = error.issues.map((issue) => {
+    if (!isRecord2(issue)) {
+      return String(issue);
+    }
+    const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+    return path ? `${path}: ${String(issue.message)}` : String(issue.message);
+  }).join(", ");
+  return new ApiError(message || "Validation error", 400, "VALIDATION_ERROR");
+};
+
+// src/types.ts
+var ErrorAdapterRegistry = class {
+  constructor(adapters = []) {
+    this.registeredAdapters = [...adapters];
+  }
+  register(adapter) {
+    this.registeredAdapters.push(adapter);
+    return this;
+  }
+  registerMany(adapters) {
+    this.registeredAdapters.push(...adapters);
+    return this;
+  }
+  getAdapters() {
+    return this.registeredAdapters;
+  }
+};
+
+// src/normalizeError.ts
+var defaultAdapters = [
+  mongoDuplicateKeyAdapter,
+  zodErrorAdapter
+];
+var normalizeError = (error, adapters = []) => {
+  if (error instanceof ApiError) {
+    return error;
+  }
+  const registeredAdapters = adapters instanceof ErrorAdapterRegistry ? adapters.getAdapters() : adapters;
+  for (const adapter of [...registeredAdapters, ...defaultAdapters]) {
+    const normalizedError = adapter(error);
+    if (normalizedError) {
+      return normalizedError;
+    }
+  }
+  return new ApiError("Internal Server Error", 500, "INTERNAL_ERROR");
+};
+
+// src/requestContext.ts
+var import_node_crypto = require("crypto");
+var defaultHeaderName = "x-request-id";
+var createRequestContext = (req, res, options = {}) => {
+  var _a, _b, _c;
+  const headerName = (_a = options.headerName) != null ? _a : defaultHeaderName;
+  const incomingRequestId = (_b = req.get(headerName)) == null ? void 0 : _b.trim();
+  const requestId = incomingRequestId || ((_c = options.generator) != null ? _c : import_node_crypto.randomUUID)();
+  res.setHeader(headerName, requestId);
+  res.locals.requestId = requestId;
+  return {
+    requestId,
+    method: req.method,
+    url: req.originalUrl || req.url,
+    path: req.path
+  };
+};
+var requestIdMiddleware = (options = {}) => (req, res, next) => {
+  createRequestContext(req, res, options);
+  next();
+};
+var getOrCreateRequestContext = (req, res, options = {}) => {
+  const existingRequestId = res.locals.requestId;
+  if (typeof existingRequestId === "string" && existingRequestId.length > 0) {
+    return {
+      requestId: existingRequestId,
+      method: req.method,
+      url: req.originalUrl || req.url,
+      path: req.path
+    };
+  }
+  return createRequestContext(req, res, options);
+};
+
+// src/serializeError.ts
+var serializeError = (error, options = {}) => {
+  var _a, _b, _c, _d;
+  const isProduction = (_a = options.isProduction) != null ? _a : process.env.NODE_ENV === "production";
+  const exposeMessage = (_b = options.exposeMessage) != null ? _b : !(isProduction && error.statusCode >= 500);
+  const message = exposeMessage ? error.message : "Internal Server Error";
+  const includeStack = options.showStack === true && !isProduction;
+  if (options.format === "problem") {
+    const problem = {
+      type: error.code ? `urn:express-error-kit:${error.code}` : "about:blank",
+      title: error.constructor.name,
+      status: error.statusCode,
+      ...message && { detail: message },
+      ...((_c = options.context) == null ? void 0 : _c.url) && { instance: options.context.url },
+      ...error.code && { code: error.code },
+      ...((_d = options.context) == null ? void 0 : _d.requestId) && { requestId: options.context.requestId }
+    };
+    return problem;
+  }
+  return {
+    success: false,
+    statusCode: error.statusCode,
+    message,
+    error: error.constructor.name,
+    ...error.code && { code: error.code },
+    ...includeStack && error.stack ? { stack: error.stack } : {}
+  };
+};
+
+// src/errorMiddleware.ts
+var errorMiddleware = (options = {}) => (err, req, res, next) => {
+  var _a, _b;
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+  const requestContext = getOrCreateRequestContext(req, res, options.requestId);
+  const processedError = normalizeError(err, (_a = options.adapters) != null ? _a : []);
+  const isProduction = process.env.NODE_ENV === "production";
+  const exposeMessage = typeof options.expose === "function" ? options.expose(processedError, requestContext) : (_b = options.expose) != null ? _b : !(isProduction && processedError.statusCode >= 500);
+  const serializationContext = {
+    ...requestContext,
+    isProduction,
+    exposeMessage,
+    includeStack: options.showStack === true && !isProduction
+  };
+  const logContext = {
+    ...requestContext,
+    statusCode: processedError.statusCode,
+    code: processedError.code,
+    errorName: processedError.constructor.name
+  };
+  if (options.logger) {
+    options.logger(processedError, logContext);
+  } else {
+    console.error({ error: processedError, context: logContext });
+  }
+  const response = options.serializer ? options.serializer(processedError, serializationContext) : serializeError(processedError, {
+    exposeMessage,
+    format: options.responseFormat,
+    showStack: options.showStack,
+    context: serializationContext
+  });
+  if (options.responseFormat === "problem") {
+    res.type("application/problem+json");
+  }
+  res.status(processedError.statusCode).json(response);
+};
+
+// src/notFoundMiddleware.ts
+var notFoundMiddleware = (req, res, next) => {
+  next(new ApiError("Route not found", 404, "NOT_FOUND"));
+};
+
+// src/errors.ts
+var NotFoundError = class extends ApiError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+  }
+};
+var BadRequestError = class extends ApiError {
+  constructor(message = "Bad request") {
+    super(message, 400, "BAD_REQUEST");
+  }
+};
+var UnauthorizedError = class extends ApiError {
+  constructor(message = "Unauthorized") {
+    super(message, 401, "UNAUTHORIZED");
+  }
+};
+var ForbiddenError = class extends ApiError {
+  constructor(message = "Forbidden") {
+    super(message, 403, "FORBIDDEN");
+  }
+};
+var ConflictError = class extends ApiError {
+  constructor(message = "Conflict") {
+    super(message, 409, "CONFLICT");
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message = "Validation error") {
+    super(message, 400, "VALIDATION_ERROR");
+  }
+};
+var InternalServerError = class extends ApiError {
+  constructor(message = "Internal Server Error") {
+    super(message, 500, "INTERNAL_ERROR");
+  }
+};
+
+// src/createError.ts
+var createError = {
+  badRequest: (message = "Bad request") => new BadRequestError(message),
+  unauthorized: (message = "Unauthorized") => new UnauthorizedError(message),
+  forbidden: (message = "Forbidden") => new ForbiddenError(message),
+  notFound: (message = "Resource not found") => new NotFoundError(message),
+  conflict: (message = "Conflict") => new ConflictError(message),
+  validation: (message = "Validation error") => new ValidationError(message),
+  internal: (message = "Internal Server Error") => new InternalServerError(message),
+  // Custom flexible error
+  custom: (message, statusCode, code) => new ApiError(message, statusCode, code)
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  BadRequestError,
+  ConflictError,
+  ErrorAdapterRegistry,
+  ForbiddenError,
+  InternalServerError,
+  NotFoundError,
+  UnauthorizedError,
+  ValidationError,
+  asyncHandler,
+  createError,
+  createRequestContext,
+  errorMiddleware,
+  getOrCreateRequestContext,
+  mongoDuplicateKeyAdapter,
+  normalizeError,
+  notFoundMiddleware,
+  requestIdMiddleware,
+  serializeError,
+  zodErrorAdapter
+});

package/dist/index.d.cts

@@ -0,0 +1,126 @@
+import { Request, Response, NextFunction } from 'express';
+
+declare const asyncHandler: (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown> | unknown) => (req: Request, res: Response, next: NextFunction) => void;
+
+declare class ApiError extends Error {
+    statusCode: number;
+    code?: string;
+    isOperational: boolean;
+    constructor(message: string, statusCode: number, code?: string);
+}
+
+type ErrorAdapter = (error: unknown) => ApiError | undefined;
+interface ErrorRequestContext {
+    requestId: string;
+    method: string;
+    url: string;
+    path: string;
+}
+interface ErrorLogContext extends ErrorRequestContext {
+    statusCode: number;
+    code?: string;
+    errorName: string;
+}
+interface ErrorSerializationContext extends ErrorRequestContext {
+    isProduction: boolean;
+    exposeMessage: boolean;
+    includeStack: boolean;
+}
+type ErrorExposurePolicy = boolean | ((error: ApiError, context: ErrorRequestContext) => boolean);
+type ErrorResponseSerializer = (error: ApiError, context: ErrorSerializationContext) => unknown;
+type ErrorResponseFormat = "legacy" | "problem";
+interface RequestIdOptions {
+    headerName?: string;
+    generator?: () => string;
+}
+interface ErrorMiddlewareOptions {
+    logger?: (error: unknown, context: ErrorLogContext) => void;
+    showStack?: boolean;
+    expose?: ErrorExposurePolicy;
+    responseFormat?: ErrorResponseFormat;
+    serializer?: ErrorResponseSerializer;
+    requestId?: RequestIdOptions;
+    adapters?: readonly ErrorAdapter[] | ErrorAdapterRegistry;
+}
+declare class ErrorAdapterRegistry {
+    private readonly registeredAdapters;
+    constructor(adapters?: readonly ErrorAdapter[]);
+    register(adapter: ErrorAdapter): this;
+    registerMany(adapters: readonly ErrorAdapter[]): this;
+    getAdapters(): readonly ErrorAdapter[];
+}
+
+declare const errorMiddleware: (options?: ErrorMiddlewareOptions) => (err: unknown, req: Request, res: Response, next: NextFunction) => void;
+
+declare const notFoundMiddleware: (req: Request, res: Response, next: NextFunction) => void;
+
+declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends ApiError {
+    constructor(message?: string);
+}
+declare class UnauthorizedError extends ApiError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string);
+}
+declare class ConflictError extends ApiError {
+    constructor(message?: string);
+}
+declare class ValidationError extends ApiError {
+    constructor(message?: string);
+}
+declare class InternalServerError extends ApiError {
+    constructor(message?: string);
+}
+
+declare const createError: {
+    badRequest: (message?: string) => BadRequestError;
+    unauthorized: (message?: string) => UnauthorizedError;
+    forbidden: (message?: string) => ForbiddenError;
+    notFound: (message?: string) => NotFoundError;
+    conflict: (message?: string) => ConflictError;
+    validation: (message?: string) => ValidationError;
+    internal: (message?: string) => InternalServerError;
+    custom: (message: string, statusCode: number, code?: string) => ApiError;
+};
+
+declare const normalizeError: (error: unknown, adapters?: readonly ErrorAdapter[] | ErrorAdapterRegistry) => ApiError;
+
+interface SerializedError {
+    success: false;
+    statusCode: number;
+    message: string;
+    error: string;
+    code?: string;
+    stack?: string;
+}
+interface SerializeErrorOptions {
+    isProduction?: boolean;
+    showStack?: boolean;
+    exposeMessage?: boolean;
+    format?: ErrorResponseFormat;
+    context?: ErrorSerializationContext;
+}
+interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code?: string;
+    requestId?: string;
+}
+declare const serializeError: (error: ApiError, options?: SerializeErrorOptions) => SerializedError | ProblemDetails;
+
+declare const mongoDuplicateKeyAdapter: ErrorAdapter;
+
+declare const zodErrorAdapter: ErrorAdapter;
+
+declare const createRequestContext: (req: Request, res: Response, options?: RequestIdOptions) => ErrorRequestContext;
+declare const requestIdMiddleware: (options?: RequestIdOptions) => (req: Request, res: Response, next: NextFunction) => void;
+declare const getOrCreateRequestContext: (req: Request, res: Response, options?: RequestIdOptions) => ErrorRequestContext;
+
+export { ApiError, BadRequestError, ConflictError, type ErrorAdapter, ErrorAdapterRegistry, type ErrorExposurePolicy, type ErrorLogContext, type ErrorMiddlewareOptions, type ErrorRequestContext, type ErrorResponseFormat, type ErrorResponseSerializer, type ErrorSerializationContext, ForbiddenError, InternalServerError, NotFoundError, type ProblemDetails, type RequestIdOptions, type SerializeErrorOptions, type SerializedError, UnauthorizedError, ValidationError, asyncHandler, createError, createRequestContext, errorMiddleware, getOrCreateRequestContext, mongoDuplicateKeyAdapter, normalizeError, notFoundMiddleware, requestIdMiddleware, serializeError, zodErrorAdapter };

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+import { Request, Response, NextFunction } from 'express';
+
+declare const asyncHandler: (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown> | unknown) => (req: Request, res: Response, next: NextFunction) => void;
+
+declare class ApiError extends Error {
+    statusCode: number;
+    code?: string;
+    isOperational: boolean;
+    constructor(message: string, statusCode: number, code?: string);
+}
+
+type ErrorAdapter = (error: unknown) => ApiError | undefined;
+interface ErrorRequestContext {
+    requestId: string;
+    method: string;
+    url: string;
+    path: string;
+}
+interface ErrorLogContext extends ErrorRequestContext {
+    statusCode: number;
+    code?: string;
+    errorName: string;
+}
+interface ErrorSerializationContext extends ErrorRequestContext {
+    isProduction: boolean;
+    exposeMessage: boolean;
+    includeStack: boolean;
+}
+type ErrorExposurePolicy = boolean | ((error: ApiError, context: ErrorRequestContext) => boolean);
+type ErrorResponseSerializer = (error: ApiError, context: ErrorSerializationContext) => unknown;
+type ErrorResponseFormat = "legacy" | "problem";
+interface RequestIdOptions {
+    headerName?: string;
+    generator?: () => string;
+}
+interface ErrorMiddlewareOptions {
+    logger?: (error: unknown, context: ErrorLogContext) => void;
+    showStack?: boolean;
+    expose?: ErrorExposurePolicy;
+    responseFormat?: ErrorResponseFormat;
+    serializer?: ErrorResponseSerializer;
+    requestId?: RequestIdOptions;
+    adapters?: readonly ErrorAdapter[] | ErrorAdapterRegistry;
+}
+declare class ErrorAdapterRegistry {
+    private readonly registeredAdapters;
+    constructor(adapters?: readonly ErrorAdapter[]);
+    register(adapter: ErrorAdapter): this;
+    registerMany(adapters: readonly ErrorAdapter[]): this;
+    getAdapters(): readonly ErrorAdapter[];
+}
+
+declare const errorMiddleware: (options?: ErrorMiddlewareOptions) => (err: unknown, req: Request, res: Response, next: NextFunction) => void;
+
+declare const notFoundMiddleware: (req: Request, res: Response, next: NextFunction) => void;
+
+declare class NotFoundError extends ApiError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends ApiError {
+    constructor(message?: string);
+}
+declare class UnauthorizedError extends ApiError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string);
+}
+declare class ConflictError extends ApiError {
+    constructor(message?: string);
+}
+declare class ValidationError extends ApiError {
+    constructor(message?: string);
+}
+declare class InternalServerError extends ApiError {
+    constructor(message?: string);
+}
+
+declare const createError: {
+    badRequest: (message?: string) => BadRequestError;
+    unauthorized: (message?: string) => UnauthorizedError;
+    forbidden: (message?: string) => ForbiddenError;
+    notFound: (message?: string) => NotFoundError;
+    conflict: (message?: string) => ConflictError;
+    validation: (message?: string) => ValidationError;
+    internal: (message?: string) => InternalServerError;
+    custom: (message: string, statusCode: number, code?: string) => ApiError;
+};
+
+declare const normalizeError: (error: unknown, adapters?: readonly ErrorAdapter[] | ErrorAdapterRegistry) => ApiError;
+
+interface SerializedError {
+    success: false;
+    statusCode: number;
+    message: string;
+    error: string;
+    code?: string;
+    stack?: string;
+}
+interface SerializeErrorOptions {
+    isProduction?: boolean;
+    showStack?: boolean;
+    exposeMessage?: boolean;
+    format?: ErrorResponseFormat;
+    context?: ErrorSerializationContext;
+}
+interface ProblemDetails {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    code?: string;
+    requestId?: string;
+}
+declare const serializeError: (error: ApiError, options?: SerializeErrorOptions) => SerializedError | ProblemDetails;
+
+declare const mongoDuplicateKeyAdapter: ErrorAdapter;
+
+declare const zodErrorAdapter: ErrorAdapter;
+
+declare const createRequestContext: (req: Request, res: Response, options?: RequestIdOptions) => ErrorRequestContext;
+declare const requestIdMiddleware: (options?: RequestIdOptions) => (req: Request, res: Response, next: NextFunction) => void;
+declare const getOrCreateRequestContext: (req: Request, res: Response, options?: RequestIdOptions) => ErrorRequestContext;
+
+export { ApiError, BadRequestError, ConflictError, type ErrorAdapter, ErrorAdapterRegistry, type ErrorExposurePolicy, type ErrorLogContext, type ErrorMiddlewareOptions, type ErrorRequestContext, type ErrorResponseFormat, type ErrorResponseSerializer, type ErrorSerializationContext, ForbiddenError, InternalServerError, NotFoundError, type ProblemDetails, type RequestIdOptions, type SerializeErrorOptions, type SerializedError, UnauthorizedError, ValidationError, asyncHandler, createError, createRequestContext, errorMiddleware, getOrCreateRequestContext, mongoDuplicateKeyAdapter, normalizeError, notFoundMiddleware, requestIdMiddleware, serializeError, zodErrorAdapter };

package/dist/index.js

@@ -0,0 +1,263 @@
+// src/asyncHandler.ts
+var asyncHandler = (fn) => {
+  return (req, res, next) => {
+    Promise.resolve().then(() => fn(req, res, next)).catch(next);
+  };
+};
+
+// src/ApiError.ts
+var ApiError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.isOperational = true;
+    Object.setPrototypeOf(this, new.target.prototype);
+    Error.captureStackTrace(this);
+  }
+};
+
+// src/adapters/mongoDuplicateKey.ts
+var isRecord = (value) => typeof value === "object" && value !== null;
+var mongoDuplicateKeyAdapter = (error) => {
+  if (!isRecord(error) || error.code !== 11e3) {
+    return void 0;
+  }
+  const keyValue = isRecord(error.keyValue) ? error.keyValue : void 0;
+  const field = keyValue ? Object.keys(keyValue)[0] : void 0;
+  const message = field ? `${field} already exists` : "Duplicate value";
+  return new ApiError(message, 400, "DUPLICATE_FIELD");
+};
+
+// src/adapters/zod.ts
+var isRecord2 = (value) => typeof value === "object" && value !== null;
+var zodErrorAdapter = (error) => {
+  if (!isRecord2(error) || error.name !== "ZodError" || !Array.isArray(error.issues)) {
+    return void 0;
+  }
+  const message = error.issues.map((issue) => {
+    if (!isRecord2(issue)) {
+      return String(issue);
+    }
+    const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+    return path ? `${path}: ${String(issue.message)}` : String(issue.message);
+  }).join(", ");
+  return new ApiError(message || "Validation error", 400, "VALIDATION_ERROR");
+};
+
+// src/types.ts
+var ErrorAdapterRegistry = class {
+  constructor(adapters = []) {
+    this.registeredAdapters = [...adapters];
+  }
+  register(adapter) {
+    this.registeredAdapters.push(adapter);
+    return this;
+  }
+  registerMany(adapters) {
+    this.registeredAdapters.push(...adapters);
+    return this;
+  }
+  getAdapters() {
+    return this.registeredAdapters;
+  }
+};
+
+// src/normalizeError.ts
+var defaultAdapters = [
+  mongoDuplicateKeyAdapter,
+  zodErrorAdapter
+];
+var normalizeError = (error, adapters = []) => {
+  if (error instanceof ApiError) {
+    return error;
+  }
+  const registeredAdapters = adapters instanceof ErrorAdapterRegistry ? adapters.getAdapters() : adapters;
+  for (const adapter of [...registeredAdapters, ...defaultAdapters]) {
+    const normalizedError = adapter(error);
+    if (normalizedError) {
+      return normalizedError;
+    }
+  }
+  return new ApiError("Internal Server Error", 500, "INTERNAL_ERROR");
+};
+
+// src/requestContext.ts
+import { randomUUID } from "crypto";
+var defaultHeaderName = "x-request-id";
+var createRequestContext = (req, res, options = {}) => {
+  var _a, _b, _c;
+  const headerName = (_a = options.headerName) != null ? _a : defaultHeaderName;
+  const incomingRequestId = (_b = req.get(headerName)) == null ? void 0 : _b.trim();
+  const requestId = incomingRequestId || ((_c = options.generator) != null ? _c : randomUUID)();
+  res.setHeader(headerName, requestId);
+  res.locals.requestId = requestId;
+  return {
+    requestId,
+    method: req.method,
+    url: req.originalUrl || req.url,
+    path: req.path
+  };
+};
+var requestIdMiddleware = (options = {}) => (req, res, next) => {
+  createRequestContext(req, res, options);
+  next();
+};
+var getOrCreateRequestContext = (req, res, options = {}) => {
+  const existingRequestId = res.locals.requestId;
+  if (typeof existingRequestId === "string" && existingRequestId.length > 0) {
+    return {
+      requestId: existingRequestId,
+      method: req.method,
+      url: req.originalUrl || req.url,
+      path: req.path
+    };
+  }
+  return createRequestContext(req, res, options);
+};
+
+// src/serializeError.ts
+var serializeError = (error, options = {}) => {
+  var _a, _b, _c, _d;
+  const isProduction = (_a = options.isProduction) != null ? _a : process.env.NODE_ENV === "production";
+  const exposeMessage = (_b = options.exposeMessage) != null ? _b : !(isProduction && error.statusCode >= 500);
+  const message = exposeMessage ? error.message : "Internal Server Error";
+  const includeStack = options.showStack === true && !isProduction;
+  if (options.format === "problem") {
+    const problem = {
+      type: error.code ? `urn:express-error-kit:${error.code}` : "about:blank",
+      title: error.constructor.name,
+      status: error.statusCode,
+      ...message && { detail: message },
+      ...((_c = options.context) == null ? void 0 : _c.url) && { instance: options.context.url },
+      ...error.code && { code: error.code },
+      ...((_d = options.context) == null ? void 0 : _d.requestId) && { requestId: options.context.requestId }
+    };
+    return problem;
+  }
+  return {
+    success: false,
+    statusCode: error.statusCode,
+    message,
+    error: error.constructor.name,
+    ...error.code && { code: error.code },
+    ...includeStack && error.stack ? { stack: error.stack } : {}
+  };
+};
+
+// src/errorMiddleware.ts
+var errorMiddleware = (options = {}) => (err, req, res, next) => {
+  var _a, _b;
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+  const requestContext = getOrCreateRequestContext(req, res, options.requestId);
+  const processedError = normalizeError(err, (_a = options.adapters) != null ? _a : []);
+  const isProduction = process.env.NODE_ENV === "production";
+  const exposeMessage = typeof options.expose === "function" ? options.expose(processedError, requestContext) : (_b = options.expose) != null ? _b : !(isProduction && processedError.statusCode >= 500);
+  const serializationContext = {
+    ...requestContext,
+    isProduction,
+    exposeMessage,
+    includeStack: options.showStack === true && !isProduction
+  };
+  const logContext = {
+    ...requestContext,
+    statusCode: processedError.statusCode,
+    code: processedError.code,
+    errorName: processedError.constructor.name
+  };
+  if (options.logger) {
+    options.logger(processedError, logContext);
+  } else {
+    console.error({ error: processedError, context: logContext });
+  }
+  const response = options.serializer ? options.serializer(processedError, serializationContext) : serializeError(processedError, {
+    exposeMessage,
+    format: options.responseFormat,
+    showStack: options.showStack,
+    context: serializationContext
+  });
+  if (options.responseFormat === "problem") {
+    res.type("application/problem+json");
+  }
+  res.status(processedError.statusCode).json(response);
+};
+
+// src/notFoundMiddleware.ts
+var notFoundMiddleware = (req, res, next) => {
+  next(new ApiError("Route not found", 404, "NOT_FOUND"));
+};
+
+// src/errors.ts
+var NotFoundError = class extends ApiError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+  }
+};
+var BadRequestError = class extends ApiError {
+  constructor(message = "Bad request") {
+    super(message, 400, "BAD_REQUEST");
+  }
+};
+var UnauthorizedError = class extends ApiError {
+  constructor(message = "Unauthorized") {
+    super(message, 401, "UNAUTHORIZED");
+  }
+};
+var ForbiddenError = class extends ApiError {
+  constructor(message = "Forbidden") {
+    super(message, 403, "FORBIDDEN");
+  }
+};
+var ConflictError = class extends ApiError {
+  constructor(message = "Conflict") {
+    super(message, 409, "CONFLICT");
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message = "Validation error") {
+    super(message, 400, "VALIDATION_ERROR");
+  }
+};
+var InternalServerError = class extends ApiError {
+  constructor(message = "Internal Server Error") {
+    super(message, 500, "INTERNAL_ERROR");
+  }
+};
+
+// src/createError.ts
+var createError = {
+  badRequest: (message = "Bad request") => new BadRequestError(message),
+  unauthorized: (message = "Unauthorized") => new UnauthorizedError(message),
+  forbidden: (message = "Forbidden") => new ForbiddenError(message),
+  notFound: (message = "Resource not found") => new NotFoundError(message),
+  conflict: (message = "Conflict") => new ConflictError(message),
+  validation: (message = "Validation error") => new ValidationError(message),
+  internal: (message = "Internal Server Error") => new InternalServerError(message),
+  // Custom flexible error
+  custom: (message, statusCode, code) => new ApiError(message, statusCode, code)
+};
+export {
+  ApiError,
+  BadRequestError,
+  ConflictError,
+  ErrorAdapterRegistry,
+  ForbiddenError,
+  InternalServerError,
+  NotFoundError,
+  UnauthorizedError,
+  ValidationError,
+  asyncHandler,
+  createError,
+  createRequestContext,
+  errorMiddleware,
+  getOrCreateRequestContext,
+  mongoDuplicateKeyAdapter,
+  normalizeError,
+  notFoundMiddleware,
+  requestIdMiddleware,
+  serializeError,
+  zodErrorAdapter
+};

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@erangamadhushan/express-error-handle-middleware",
+  "version": "1.6.0",
+  "description": "Advanced TypeScript error handling middleware for Express applications.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "smoke:package": "npm run build && node scripts/verify-package.mjs",
+    "prepublishOnly": "npm run build",
+    "test": "jest --coverage"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Erangamadhushan/express-error-handle-middleware.git"
+  },
+  "keywords": [
+    "express",
+    "middleware",
+    "error-handler",
+    "typescript"
+  ],
+  "author": "Eranga Madhushan",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/Erangamadhushan/express-error-handle-middleware/issues"
+  },
+  "homepage": "https://github.com/Erangamadhushan/express-error-handle-middleware#readme",
+  "engines": {
+    "node": ">=18.18"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@types/express": "^5.0.6",
+    "@types/jest": "^30.0.0",
+    "@types/supertest": "^6.0.3",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "express": "^5.2.1",
+    "jest": "^30.2.0",
+    "semantic-release": "^25.0.3",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.6",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
+  }
+}