adorn-api 1.0.1 → 1.0.2

package/README.md

@@ -9,15 +9,18 @@ Adorn API turns TypeScript classes into HTTP controllers with Stage-3 decorators
 
 ## Features
 - Controller decorators (`@Controller`, `@Get`, `@Post`, etc.) backed by a registry/router that mounts on Express.
+- `createAdornExpressRouter` and `buildRegistry` for mounting Adorn into existing Express stacks.
+- Problem Details error handling with an `onError` hook for custom shapes/logging.
 - Built-in OpenAPI generator with optional Swagger UI serving through the Express adapter.
 - MetalORM helpers (`entityDto`, `filtersFromEntity`, `tableDefOf`) to reuse entity metadata for payload validation and database filtering.
 - End-to-end coverage for both direct API handlers and MetalORM REST routes using Vitest + Supertest.
 
-For detailed writeups of each feature, see the companion guides under `docs/`.
+For detailed writeups of each feature, see the companion guides under `docs/` (including the Stage-3 decorator setup).
 
 ## Requirements
 - Node.js v18+
 - SQLite (only for in-memory tests; runtime persistence is pluggable via MetalORM executors)
+- TypeScript 5.x with Stage-3 decorators (do not enable `experimentalDecorators`)
 
 ## Getting started
 1. `npm install` to pull runtime and dev dependencies (Express, MetalORM, Vitest).

package/dist/adapters/express/createApp.d.ts

@@ -1,20 +1,158 @@
-import { type Express } from 'express';
-import type { ControllerCtor } from '../../core/registry/types.js';
+import { type Express, type Router } from 'express';
+import type { ControllerCtor, Registry } from '../../core/registry/types.js';
 import type { Validator } from '../../contracts/validator.js';
 import { type ApplyRoutesOptions } from './router.js';
+import { type AdornErrorHandlerOptions } from './middleware/errorHandler.js';
 import type { OpenApiBuildOptions } from '../../core/openapi/buildOpenApi.js';
-export type CreateAdornExpressAppOptions = ApplyRoutesOptions & {
+/**
+ * Options for OpenAPI documentation generation and serving.
+ * Extends OpenApiBuildOptions with serving configuration.
+ */
+export type AdornOpenApiOptions = OpenApiBuildOptions & {
+    /** Whether to enable OpenAPI documentation (default: true) */
+    enabled?: boolean;
+    /** Path to serve the OpenAPI JSON specification (default: '/openapi.json') */
+    jsonPath?: string;
+    /** Path to serve the OpenAPI documentation UI (default: '/docs') */
+    docsPath?: string;
+    /** Whether to serve Swagger UI (default: true) */
+    swaggerUi?: boolean;
+    /** Configuration options for Swagger UI */
+    swaggerUiConfig?: Record<string, unknown>;
+};
+/**
+ * Options for creating an Adorn Express router with controllers.
+ *
+ * @see ApplyRoutesOptions for additional routing options
+ */
+export type CreateAdornExpressRouterOptions = ApplyRoutesOptions & {
+    /** Array of controller constructors to register */
     controllers: ControllerCtor[];
-    mountPath?: string;
+    /** Whether to automatically add JSON body parser middleware (default: true) */
     jsonBodyParser?: boolean;
+    /** Validator instance for request validation */
     validator?: Validator;
-    openapi?: (OpenApiBuildOptions & {
-        enabled?: boolean;
-        jsonPath?: string;
-        docsPath?: string;
-        swaggerUi?: boolean;
-        swaggerUiConfig?: Record<string, unknown>;
-    });
+    /** Error handler configuration or false to disable (default: built-in handler) */
+    errorHandler?: AdornErrorHandlerOptions | false;
+    /** OpenAPI documentation configuration */
+    openapi?: AdornOpenApiOptions;
+};
+/**
+ * Result of creating an Adorn Express router.
+ */
+export type CreateAdornExpressRouterResult = {
+    /** Configured Express router with all routes */
+    router: Router;
+    /** Route registry containing metadata about all registered routes */
+    registry: Registry;
+};
+/**
+ * Options for creating an Adorn Express application.
+ * Extends router options with mount path configuration.
+ *
+ * @see CreateAdornExpressRouterOptions for base options
+ */
+export type CreateAdornExpressAppOptions = CreateAdornExpressRouterOptions & {
+    /** Path to mount the router (default: '/') */
+    mountPath?: string;
 };
+/**
+ * Creates a complete Express application with Adorn API functionality.
+ *
+ * This function sets up an Express app with all Adorn features including:
+ * - Controller-based routing
+ * - Automatic OpenAPI documentation
+ * - Built-in error handling
+ * - Request validation
+ *
+ * @param options - Configuration options for the application
+ * @returns Configured Express application instance
+ *
+ * @example
+ * ```typescript
+ * import { createAdornExpressApp } from '@adorn/api';
+ * import { UserController } from './controllers/user.controller';
+ *
+ * const app = createAdornExpressApp({
+ *   controllers: [UserController],
+ *   openapi: {
+ *     title: 'My API',
+ *     version: '1.0.0'
+ *   }
+ * });
+ *
+ * app.listen(3000, () => {
+ *   console.log('Server running on port 3000');
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom mount path
+ * const app = createAdornExpressApp({
+ *   controllers: [UserController, ProductController],
+ *   mountPath: '/api/v1',
+ *   jsonBodyParser: true,
+ *   errorHandler: {
+ *     logErrors: true,
+ *     exposeStack: process.env.NODE_ENV === 'development'
+ *   }
+ * });
+ * ```
+ *
+ * @see createAdornExpressRouter for router-specific functionality
+ * @see AdornOpenApiOptions for OpenAPI configuration
+ */
 export declare function createAdornExpressApp(options: CreateAdornExpressAppOptions): Express;
+/**
+ * Creates an Express router with Adorn API functionality.
+ *
+ * This function sets up an Express router with all Adorn features including:
+ * - Controller-based routing
+ * - Automatic OpenAPI documentation
+ * - Built-in error handling
+ * - Request validation
+ *
+ * @param options - Configuration options for the router
+ * @returns Object containing the configured router and route registry
+ *
+ * @example
+ * ```typescript
+ * import { createAdornExpressRouter } from '@adorn/api';
+ * import { UserController } from './controllers/user.controller';
+ * import express from 'express';
+ *
+ * const app = express();
+ * const { router, registry } = createAdornExpressRouter({
+ *   controllers: [UserController],
+ *   openapi: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     docsPath: '/api-docs'
+ *   }
+ * });
+ *
+ * app.use('/api', router);
+ *
+ * // Access the registry for runtime inspection
+ * console.log('Registered routes:', registry.routes.length);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom validator and error handling
+ * const { router } = createAdornExpressRouter({
+ *   controllers: [UserController],
+ *   validator: new CustomValidator(),
+ *   errorHandler: {
+ *     logErrors: true,
+ *     customErrorFormatter: (err) => ({ ...err, timestamp: new Date() })
+ *   }
+ * });
+ * ```
+ *
+ * @see createAdornExpressApp for full application setup
+ * @see AdornOpenApiOptions for OpenAPI configuration
+ */
+export declare function createAdornExpressRouter(options: CreateAdornExpressRouterOptions): CreateAdornExpressRouterResult;
 //# sourceMappingURL=createApp.d.ts.map

package/dist/adapters/express/createApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createApp.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAG9E,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,GAAG;IAC9D,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,OAAO,CAAC,EAAE,CAAC,mBAAmB,GAAG;QAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,CAAC,CAAC;CACJ,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAyCpF"}
+{"version":3,"file":"createApp.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAG9E;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACtD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,+BAA+B,GAAG,kBAAkB,GAAG;IACjE,mDAAmD;IACnD,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gDAAgD;IAChD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kFAAkF;IAClF,YAAY,CAAC,EAAE,wBAAwB,GAAG,KAAK,CAAC;IAChD,0CAA0C;IAC1C,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,8BAA8B,GAAG;IAC3C,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,QAAQ,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GAAG,+BAA+B,GAAG;IAC3E,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAKpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,8BAA8B,CAqChC"}

package/dist/adapters/express/createApp.js

@@ -1,15 +1,117 @@
 import express, {} from 'express';
 import { buildRegistry } from '../../core/registry/buildRegistry.js';
 import { applyRegistryToExpressRouter } from './router.js';
-import { adornErrorHandler } from './middleware/errorHandler.js';
+import { adornErrorHandler, createAdornExpressErrorHandler, } from './middleware/errorHandler.js';
 import { serveOpenApi } from './swagger/serve.js';
+/**
+ * Creates a complete Express application with Adorn API functionality.
+ *
+ * This function sets up an Express app with all Adorn features including:
+ * - Controller-based routing
+ * - Automatic OpenAPI documentation
+ * - Built-in error handling
+ * - Request validation
+ *
+ * @param options - Configuration options for the application
+ * @returns Configured Express application instance
+ *
+ * @example
+ * ```typescript
+ * import { createAdornExpressApp } from '@adorn/api';
+ * import { UserController } from './controllers/user.controller';
+ *
+ * const app = createAdornExpressApp({
+ *   controllers: [UserController],
+ *   openapi: {
+ *     title: 'My API',
+ *     version: '1.0.0'
+ *   }
+ * });
+ *
+ * app.listen(3000, () => {
+ *   console.log('Server running on port 3000');
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom mount path
+ * const app = createAdornExpressApp({
+ *   controllers: [UserController, ProductController],
+ *   mountPath: '/api/v1',
+ *   jsonBodyParser: true,
+ *   errorHandler: {
+ *     logErrors: true,
+ *     exposeStack: process.env.NODE_ENV === 'development'
+ *   }
+ * });
+ * ```
+ *
+ * @see createAdornExpressRouter for router-specific functionality
+ * @see AdornOpenApiOptions for OpenAPI configuration
+ */
 export function createAdornExpressApp(options) {
     const app = express();
+    const { router } = createAdornExpressRouter(options);
+    app.use(options.mountPath ?? '/', router);
+    return app;
+}
+/**
+ * Creates an Express router with Adorn API functionality.
+ *
+ * This function sets up an Express router with all Adorn features including:
+ * - Controller-based routing
+ * - Automatic OpenAPI documentation
+ * - Built-in error handling
+ * - Request validation
+ *
+ * @param options - Configuration options for the router
+ * @returns Object containing the configured router and route registry
+ *
+ * @example
+ * ```typescript
+ * import { createAdornExpressRouter } from '@adorn/api';
+ * import { UserController } from './controllers/user.controller';
+ * import express from 'express';
+ *
+ * const app = express();
+ * const { router, registry } = createAdornExpressRouter({
+ *   controllers: [UserController],
+ *   openapi: {
+ *     title: 'My API',
+ *     version: '1.0.0',
+ *     docsPath: '/api-docs'
+ *   }
+ * });
+ *
+ * app.use('/api', router);
+ *
+ * // Access the registry for runtime inspection
+ * console.log('Registered routes:', registry.routes.length);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom validator and error handling
+ * const { router } = createAdornExpressRouter({
+ *   controllers: [UserController],
+ *   validator: new CustomValidator(),
+ *   errorHandler: {
+ *     logErrors: true,
+ *     customErrorFormatter: (err) => ({ ...err, timestamp: new Date() })
+ *   }
+ * });
+ * ```
+ *
+ * @see createAdornExpressApp for full application setup
+ * @see AdornOpenApiOptions for OpenAPI configuration
+ */
+export function createAdornExpressRouter(options) {
+    const router = express.Router();
     if (options.jsonBodyParser ?? true) {
-        app.use(express.json());
+        router.use(express.json());
     }
     const registry = buildRegistry(options.controllers);
-    const router = express.Router();
     applyRegistryToExpressRouter(router, registry, options);
     const oa = options.openapi;
     if (oa?.enabled ?? true) {
@@ -28,8 +130,12 @@ export function createAdornExpressApp(options) {
             router.use(serveOpenApi(registry, openApiOptions, serveOptions));
         }
     }
-    app.use(options.mountPath ?? '/', router);
-    app.use(adornErrorHandler);
-    return app;
+    if (options.errorHandler !== false) {
+        const handler = options.errorHandler
+            ? createAdornExpressErrorHandler(options.errorHandler)
+            : adornErrorHandler;
+        router.use(handler);
+    }
+    return { router, registry };
 }
 //# sourceMappingURL=createApp.js.map

package/dist/adapters/express/createApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"createApp.js","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAA2B,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiBlD,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IACzE,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IAEtB,IAAI,OAAO,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,4BAA4B,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAExD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,IAAI,EAAE,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC;YAC7B,MAAM,cAAc,GAAwB;gBAC1C,KAAK,EAAE,EAAE,CAAC,KAAK;gBACf,OAAO,EAAE,EAAE,CAAC,OAAO;gBACnB,GAAG,CAAC,EAAE,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7D,CAAC;YACF,MAAM,YAAY,GAAG;gBACnB,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,GAAG,CAAC,EAAE,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrF,CAAC;YAEF,MAAM,CAAC,GAAG,CACR,YAAY,CACV,QAAQ,EACR,cAAc,EACd,YAAY,CACb,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,EAAE,MAAM,CAAC,CAAC;IAC1C,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAE3B,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"createApp.js","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"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"}

package/dist/adapters/express/middleware/errorHandler.d.ts

@@ -1,3 +1,194 @@
-import type { NextFunction, Request, Response } from 'express';
-export declare function adornErrorHandler(err: unknown, req: Request, res: Response, _next: NextFunction): void;
+import type { ErrorRequestHandler, Request, Response } from 'express';
+import type { ProblemDetails } from '../../../contracts/errors.js';
+/**
+ * Context object provided to custom error handlers.
+ *
+ * Contains the Express request and response objects, the request path,
+ * and the default problem details that would be returned.
+ */
+export type AdornErrorHandlerContext = {
+    /** Express request object */
+    req: Request;
+    /** Express response object */
+    res: Response;
+    /** Request path/URL */
+    instance: string;
+    /** Default problem details that would be returned */
+    defaultProblem: ProblemDetails;
+};
+/**
+ * Result types that can be returned from a custom error handler.
+ *
+ * Supports returning ProblemDetails, custom responses, or void (to use default).
+ */
+export type AdornErrorHandlerResult = ProblemDetails | {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+} | void;
+/**
+ * Options for configuring the Adorn error handler.
+ *
+ * Allows customization of error handling behavior through the onError callback.
+ */
+export type AdornErrorHandlerOptions = {
+    /**
+     * Custom error handler function.
+     *
+     * @param err - The error that occurred
+     * @param ctx - Error handler context with request/response info
+     * @returns Custom error response, problem details, or void to use default
+     *
+     * @example
+     * ```typescript
+     * // Custom error formatting
+     * onError: (err, ctx) => {
+     *   if (err instanceof ValidationError) {
+     *     return {
+     *       status: 400,
+     *       body: {
+     *         success: false,
+     *         errors: err.issues,
+     *         timestamp: new Date().toISOString()
+     *       }
+     *     };
+     *   }
+     *   return ctx.defaultProblem; // Use default for other errors
+     * }
+     * ```
+     */
+    onError?: (err: unknown, ctx: AdornErrorHandlerContext) => AdornErrorHandlerResult;
+};
+/**
+ * Default Adorn error handler for Express applications.
+ *
+ * This is the built-in error handler that converts errors to appropriate
+ * HTTP responses. It handles HttpError, ValidationError, and other errors
+ * by converting them to Problem Details format.
+ *
+ * @param err - The error that occurred
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ *
+ * @example
+ * ```typescript
+ * // Basic usage in Express app
+ * import { adornErrorHandler } from '@adorn/api';
+ *
+ * const app = express();
+ * // ... routes and middleware
+ * app.use(adornErrorHandler); // Use as last middleware
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom error handling
+ * app.use((err, req, res, next) => {
+ *   // Custom logging
+ *   console.error('Error occurred:', err);
+ *
+ *   // Use adorn error handler
+ *   adornErrorHandler(err, req, res, next);
+ * });
+ * ```
+ *
+ * @see createAdornExpressErrorHandler for customizable error handler
+ * @see HttpError for HTTP error class
+ */
+export declare function adornErrorHandler(err: unknown, req: Request, res: Response, next: Parameters<ErrorRequestHandler>[3]): unknown;
+/**
+ * Creates a customizable Adorn error handler for Express applications.
+ *
+ * This function allows customization of error handling behavior while
+ * maintaining the core functionality of converting errors to appropriate
+ * HTTP responses.
+ *
+ * @param options - Error handler configuration options
+ * @returns Express error request handler function
+ *
+ * @example
+ * ```typescript
+ * // Basic custom error handler
+ * const errorHandler = createAdornExpressErrorHandler({
+ *   onError: (err, ctx) => {
+ *     // Add custom logging
+ *     console.error('Error:', err.message, 'Path:', ctx.instance);
+ *
+ *     // Return default problem details
+ *     return ctx.defaultProblem;
+ *   }
+ * });
+ *
+ * app.use(errorHandler);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced error handling with custom responses
+ * const errorHandler = createAdornExpressErrorHandler({
+ *   onError: (err, ctx) => {
+ *     if (err instanceof ValidationError) {
+ *       return {
+ *         status: 400,
+ *         body: {
+ *           success: false,
+ *           type: 'validation_error',
+ *           issues: err.issues,
+ *           timestamp: new Date().toISOString(),
+ *           requestId: ctx.req.id
+ *         },
+ *         headers: {
+ *           'X-Error-Type': 'validation'
+ *         }
+ *       };
+ *     }
+ *
+ *     if (err instanceof HttpError && err.status === 404) {
+ *       return {
+ *         status: 404,
+ *         body: {
+ *           success: false,
+ *           type: 'not_found',
+ *           message: 'Resource not found',
+ *           details: err.details
+ *         }
+ *       };
+ *     }
+ *
+ *     // Use default for other errors
+ *     return ctx.defaultProblem;
+ *   }
+ * });
+ *
+ * app.use(errorHandler);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handler with request ID correlation
+ * const errorHandler = createAdornExpressErrorHandler({
+ *   onError: (err, ctx) => {
+ *     const requestId = ctx.req.headers['x-request-id'] || ctx.req.id;
+ *
+ *     // Add request ID to all error responses
+ *     const problem = ctx.defaultProblem;
+ *     return {
+ *       ...problem,
+ *       body: {
+ *         ...problem,
+ *         requestId,
+ *         timestamp: new Date().toISOString()
+ *       }
+ *     };
+ *   }
+ * });
+ *
+ * app.use(errorHandler);
+ * ```
+ *
+ * @see adornErrorHandler for the default error handler
+ * @see AdornErrorHandlerOptions for configuration options
+ */
+export declare function createAdornExpressErrorHandler(options?: AdornErrorHandlerOptions): ErrorRequestHandler;
 //# sourceMappingURL=errorHandler.d.ts.map

package/dist/adapters/express/middleware/errorHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG/D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,QAI/F"}
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGnE;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,6BAA6B;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,8BAA8B;IAC9B,GAAG,EAAE,QAAQ,CAAC;IACd,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,cAAc,EAAE,cAAc,CAAC;CAChC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd;IACE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,GACD,IAAI,CAAC;AAET;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,wBAAwB,KAAK,uBAAuB,CAAC;CACpF,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,WAGzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4FG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,wBAA6B,GACrC,mBAAmB,CA+BrB"}