apienvelope 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,842 @@
+import { Request, Response, NextFunction, RequestHandler, ErrorRequestHandler } from 'express';
+
+/**
+ * Base response interface with common fields
+ */
+interface BaseResponse {
+    timestamp: string;
+    meta?: ResponseMeta;
+}
+/**
+ * Metadata that can be attached to any response
+ */
+interface ResponseMeta {
+    requestId?: string;
+    correlationId?: string;
+    userId?: string;
+    [key: string]: unknown;
+}
+/**
+ * Successful response structure
+ * @template T - The type of the data payload
+ */
+interface SuccessResponse<T = unknown> extends BaseResponse {
+    success: true;
+    data: T;
+}
+/**
+ * Error details structure
+ */
+interface ErrorDetails {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+    stack?: string;
+    fields?: FieldErrors;
+}
+/**
+ * Field-level validation errors
+ */
+interface FieldErrors {
+    [field: string]: string | string[];
+}
+/**
+ * Error response structure
+ */
+interface ErrorResponse extends BaseResponse {
+    success: false;
+    error: ErrorDetails;
+}
+/**
+ * Pagination metadata
+ */
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    links?: PaginationLinks;
+}
+/**
+ * HATEOAS-style pagination links
+ */
+interface PaginationLinks {
+    self?: string;
+    first?: string;
+    last?: string;
+    next?: string;
+    previous?: string;
+}
+/**
+ * Cursor-based pagination metadata
+ */
+interface CursorPaginationMeta {
+    limit: number;
+    cursor?: string;
+    nextCursor?: string;
+    previousCursor?: string;
+    hasMore: boolean;
+    links?: PaginationLinks;
+}
+/**
+ * Paginated response structure (offset-based)
+ * @template T - The type of items in the data array
+ */
+interface PaginatedResponse<T = unknown> extends BaseResponse {
+    success: true;
+    data: T[];
+    pagination: PaginationMeta;
+}
+/**
+ * Cursor-paginated response structure
+ * @template T - The type of items in the data array
+ */
+interface CursorPaginatedResponse<T = unknown> extends BaseResponse {
+    success: true;
+    data: T[];
+    pagination: CursorPaginationMeta;
+}
+/**
+ * Discriminated union for type-safe response handling
+ * @template T - The type of the data payload for success responses
+ */
+type ApiResponse<T = unknown> = SuccessResponse<T> | ErrorResponse;
+/**
+ * Discriminated union for paginated responses
+ * @template T - The type of items in the data array
+ */
+type PaginatedApiResponse<T = unknown> = PaginatedResponse<T> | ErrorResponse;
+/**
+ * Type guard for success responses
+ */
+declare function isSuccessResponse<T>(response: ApiResponse<T>): response is SuccessResponse<T>;
+/**
+ * Type guard for error responses
+ */
+declare function isErrorResponse(response: ApiResponse<unknown>): response is ErrorResponse;
+/**
+ * Type guard for paginated responses
+ */
+declare function isPaginatedResponse<T>(response: PaginatedApiResponse<T>): response is PaginatedResponse<T>;
+
+/**
+ * Error constructor type for mapping
+ */
+type ErrorConstructor = new (...args: any[]) => Error;
+/**
+ * Error serializer function type
+ */
+type ErrorSerializer = (error: Error) => Record<string, unknown>;
+/**
+ * Error context for traceability
+ */
+interface ErrorContext {
+    requestId?: string;
+    correlationId?: string;
+    userId?: string;
+    path?: string;
+    method?: string;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/**
+ * API Error options
+ */
+interface ApiErrorOptions {
+    code?: string;
+    statusCode?: number;
+    details?: Record<string, unknown>;
+    fields?: FieldErrors;
+    cause?: Error;
+    context?: ErrorContext;
+    isOperational?: boolean;
+}
+/**
+ * Serialized error structure
+ */
+interface SerializedError {
+    code: string;
+    message: string;
+    statusCode: number;
+    details?: Record<string, unknown>;
+    fields?: FieldErrors;
+    stack?: string;
+    context?: ErrorContext;
+}
+/**
+ * Error chain item for nested errors
+ */
+interface ErrorChainItem {
+    name: string;
+    message: string;
+    code?: string;
+    stack?: string;
+}
+/**
+ * Default error codes
+ */
+declare const ErrorCodes: {
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly CONFLICT: "CONFLICT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly BAD_REQUEST: "BAD_REQUEST";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly UNPROCESSABLE_ENTITY: "UNPROCESSABLE_ENTITY";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+
+/**
+ * Environment types
+ */
+type Environment = 'development' | 'staging' | 'production' | 'test';
+/**
+ * Response hook function types
+ */
+type PreResponseHook = (data: unknown, meta?: ResponseMeta) => {
+    data: unknown;
+    meta?: ResponseMeta;
+};
+type PostResponseHook = (response: SuccessResponse<unknown> | ErrorResponse) => SuccessResponse<unknown> | ErrorResponse;
+/**
+ * Custom formatter function type
+ */
+type CustomFormatter = (response: SuccessResponse<unknown> | ErrorResponse) => Record<string, unknown>;
+/**
+ * Pagination configuration
+ */
+interface PaginationConfig {
+    defaultLimit: number;
+    maxLimit: number;
+    includeLinks: boolean;
+    baseUrl?: string;
+}
+/**
+ * Main formatter configuration
+ */
+interface FormatterConfig {
+    /** Include stack traces in error responses */
+    includeStackTraces: boolean;
+    /** Current environment */
+    environment: Environment;
+    /** Custom error to status code mappings */
+    customErrorMappers?: Map<ErrorConstructor, number>;
+    /** Custom error serializers */
+    customSerializers?: Map<ErrorConstructor, ErrorSerializer>;
+    /** Include timestamp in responses */
+    includeTimestamp: boolean;
+    /** Mask sensitive data in errors */
+    maskSensitiveData: boolean;
+    /** Header name for request ID */
+    requestIdHeader: string;
+    /** Header name for correlation ID */
+    correlationIdHeader: string;
+    /** Pagination configuration */
+    pagination: PaginationConfig;
+    /** Pre-response processing hooks */
+    preResponseHooks: PreResponseHook[];
+    /** Post-response processing hooks */
+    postResponseHooks: PostResponseHook[];
+    /** Custom response formatter (passthrough mode) */
+    customFormatter?: CustomFormatter;
+    /** Enable passthrough mode for backward compatibility */
+    passthroughMode: boolean;
+    /** Sensitive fields to mask in error details */
+    sensitiveFields: string[];
+    /** Generate request ID if not present */
+    generateRequestId: boolean;
+}
+/**
+ * Partial configuration for user input
+ */
+type FormatterConfigInput = Partial<FormatterConfig>;
+/**
+ * Default configuration values
+ */
+declare const defaultConfig: FormatterConfig;
+
+/**
+ * Pagination input for offset-based pagination
+ */
+interface PaginationInput {
+    page: number;
+    limit: number;
+    total: number;
+}
+/**
+ * Cursor pagination input
+ */
+interface CursorPaginationInput {
+    limit: number;
+    cursor?: string;
+    nextCursor?: string;
+    previousCursor?: string;
+    hasMore: boolean;
+}
+/**
+ * Validate and normalize pagination input
+ */
+declare function validatePaginationInput(input: Partial<PaginationInput>, config: PaginationConfig): PaginationInput;
+/**
+ * Calculate pagination metadata
+ */
+declare function calculatePaginationMeta(input: PaginationInput, baseUrl?: string): PaginationMeta;
+/**
+ * Generate HATEOAS-style pagination links
+ */
+declare function generatePaginationLinks(page: number, totalPages: number, limit: number, baseUrl: string): PaginationMeta['links'];
+/**
+ * Calculate cursor pagination metadata
+ */
+declare function calculateCursorPaginationMeta(input: CursorPaginationInput, baseUrl?: string): CursorPaginationMeta;
+/**
+ * Generate cursor pagination links
+ */
+declare function generateCursorPaginationLinks(input: CursorPaginationInput, baseUrl: string): CursorPaginationMeta['links'];
+/**
+ * Validate configuration input
+ */
+declare function validateConfig(input: FormatterConfigInput): string[];
+/**
+ * Check if value is a plain object
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Generate a unique request ID
+ */
+declare function generateRequestId(): string;
+
+/**
+ * Core response formatter class
+ * Handles formatting of success, error, and paginated responses
+ */
+declare class ResponseFormatter {
+    private config;
+    private statusCodeMapper;
+    constructor(config?: FormatterConfigInput);
+    /**
+     * Merge user config with defaults
+     */
+    private mergeConfig;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<FormatterConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: FormatterConfigInput): void;
+    /**
+     * Generate timestamp
+     */
+    private getTimestamp;
+    /**
+     * Apply pre-response hooks
+     */
+    private applyPreHooks;
+    /**
+     * Apply post-response hooks
+     */
+    private applyPostHooks;
+    /**
+     * Format a success response
+     */
+    formatSuccess<T>(data: T, meta?: ResponseMeta): SuccessResponse<T>;
+    /**
+     * Format an error response
+     */
+    formatError(error: Error, meta?: ResponseMeta): ErrorResponse;
+    /**
+     * Format a paginated response (offset-based)
+     */
+    formatPaginated<T>(data: T[], paginationInput: Partial<PaginationInput>, meta?: ResponseMeta, baseUrl?: string): PaginatedResponse<T>;
+    /**
+     * Format a cursor-paginated response
+     */
+    formatCursorPaginated<T>(data: T[], cursorInput: CursorPaginationInput, meta?: ResponseMeta, baseUrl?: string): CursorPaginatedResponse<T>;
+    /**
+     * Get status code for an error
+     */
+    getErrorStatusCode(error: Error): number;
+    /**
+     * Get success status code based on HTTP method
+     */
+    getSuccessStatusCode(method: string, hasData: boolean): number;
+    /**
+     * Generate or extract request ID
+     */
+    getRequestId(existingId?: string): string;
+}
+/**
+ * Create a response formatter instance
+ */
+declare function createResponseFormatter(config?: FormatterConfigInput): ResponseFormatter;
+
+/**
+ * Error handler options
+ */
+interface ErrorHandlerOptions {
+    /** Log errors to console */
+    logErrors: boolean;
+    /** Custom error logger */
+    errorLogger?: (error: Error, req: Request) => void;
+    /** Transform error before formatting */
+    transformError?: (error: Error) => Error;
+    /** Handle non-operational errors differently */
+    handleNonOperational?: (error: Error, req: Request, res: Response) => void;
+}
+/**
+ * Error handler class for Express applications
+ */
+declare class ErrorHandler {
+    private formatter;
+    private options;
+    private config;
+    constructor(formatter: ResponseFormatter, options?: Partial<ErrorHandlerOptions>);
+    /**
+     * Extract request metadata for error context
+     */
+    private extractMeta;
+    /**
+     * Log error if enabled
+     */
+    private logError;
+    /**
+     * Check if error is operational (expected)
+     */
+    private isOperationalError;
+    /**
+     * Handle the error and send response
+     */
+    handle(error: Error, req: Request, res: Response, _next: NextFunction): void;
+    /**
+     * Create Express error handling middleware
+     */
+    middleware(): (error: Error, req: Request, res: Response, next: NextFunction) => void;
+}
+/**
+ * Create an error handler instance
+ */
+declare function createErrorHandler(formatter: ResponseFormatter, options?: Partial<ErrorHandlerOptions>): ErrorHandler;
+/**
+ * Create error handling middleware directly
+ */
+declare function errorHandlerMiddleware(formatter: ResponseFormatter, options?: Partial<ErrorHandlerOptions>): (error: Error, req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Pagination helper class for handling pagination logic
+ */
+declare class PaginationHelper {
+    private config;
+    constructor(config?: Partial<PaginationConfig>);
+    /**
+     * Extract pagination parameters from request
+     */
+    extractFromRequest(req: Request): {
+        page: number;
+        limit: number;
+    };
+    /**
+     * Extract cursor pagination parameters from request
+     */
+    extractCursorFromRequest(req: Request): {
+        cursor?: string;
+        limit: number;
+    };
+    /**
+     * Calculate offset for database queries
+     */
+    calculateOffset(page: number, limit: number): number;
+    /**
+     * Build pagination metadata
+     */
+    buildMeta(input: PaginationInput, baseUrl?: string): PaginationMeta;
+    /**
+     * Build cursor pagination metadata
+     */
+    buildCursorMeta(input: CursorPaginationInput, baseUrl?: string): CursorPaginationMeta;
+    /**
+     * Create pagination info from data array and total count
+     */
+    fromArray<T>(data: T[], page: number, limit: number, total: number): {
+        data: T[];
+        pagination: PaginationMeta;
+    };
+    /**
+     * Paginate an in-memory array
+     */
+    paginateArray<T>(items: T[], page: number, limit: number): {
+        data: T[];
+        pagination: PaginationMeta;
+    };
+    /**
+     * Check if there are more pages
+     */
+    hasNextPage(page: number, limit: number, total: number): boolean;
+    /**
+     * Check if there are previous pages
+     */
+    hasPreviousPage(page: number): boolean;
+    /**
+     * Get total pages count
+     */
+    getTotalPages(total: number, limit: number): number;
+    /**
+     * Validate page number is within bounds
+     */
+    isValidPage(page: number, total: number, limit: number): boolean;
+    /**
+     * Get configuration
+     */
+    getConfig(): Readonly<PaginationConfig>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<PaginationConfig>): void;
+}
+/**
+ * Create a pagination helper instance
+ */
+declare function createPaginationHelper(config?: Partial<PaginationConfig>): PaginationHelper;
+
+/**
+ * Base API Error class for all application errors
+ * Provides structured error information for consistent API responses
+ */
+declare class ApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown>;
+    readonly fields?: FieldErrors;
+    readonly context?: ErrorContext;
+    readonly isOperational: boolean;
+    readonly timestamp: string;
+    constructor(message: string, options?: ApiErrorOptions);
+    /**
+     * Serialize error for response
+     */
+    serialize(includeStack?: boolean): SerializedError;
+    /**
+     * Get error chain for nested errors
+     */
+    getErrorChain(): Array<{
+        name: string;
+        message: string;
+        code?: string;
+    }>;
+    /**
+     * Create a new error with additional context
+     */
+    withContext(context: ErrorContext): ApiError;
+    /**
+     * Convert to JSON for logging
+     */
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Validation Error - 400 Bad Request
+ * Used for input validation failures
+ */
+declare class ValidationError extends ApiError {
+    constructor(message?: string, fields?: FieldErrors, options?: Omit<ApiErrorOptions, 'code' | 'statusCode' | 'fields'>);
+}
+/**
+ * Not Found Error - 404
+ * Used when a requested resource doesn't exist
+ */
+declare class NotFoundError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Unauthorized Error - 401
+ * Used when authentication is required but not provided or invalid
+ */
+declare class UnauthorizedError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Forbidden Error - 403
+ * Used when user is authenticated but lacks permission
+ */
+declare class ForbiddenError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Conflict Error - 409
+ * Used for resource conflicts (e.g., duplicate entries)
+ */
+declare class ConflictError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Internal Server Error - 500
+ * Used for unexpected server errors
+ */
+declare class InternalServerError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Bad Request Error - 400
+ * Used for malformed requests
+ */
+declare class BadRequestError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Rate Limit Error - 429
+ * Used when rate limiting is triggered
+ */
+declare class RateLimitError extends ApiError {
+    readonly retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Service Unavailable Error - 503
+ * Used when service is temporarily unavailable
+ */
+declare class ServiceUnavailableError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Unprocessable Entity Error - 422
+ * Used when request is valid but cannot be processed
+ */
+declare class UnprocessableEntityError extends ApiError {
+    constructor(message?: string, options?: Omit<ApiErrorOptions, 'code' | 'statusCode'>);
+}
+/**
+ * Factory function to create ApiError with context
+ */
+declare function createError(ErrorClass: new (message: string, ...args: unknown[]) => ApiError, message: string, context?: ErrorContext): ApiError;
+
+/**
+ * Extended Express Response with formatter methods
+ */
+interface FormattedResponse extends Response {
+    /** Send a formatted success response */
+    respond: <T>(data: T, meta?: ResponseMeta, statusCode?: number) => void;
+    /** Send a formatted paginated response */
+    respondPaginated: <T>(data: T[], pagination: Partial<PaginationInput>, meta?: ResponseMeta) => void;
+    /** Send a formatted cursor-paginated response */
+    respondCursorPaginated: <T>(data: T[], pagination: CursorPaginationInput, meta?: ResponseMeta) => void;
+    /** Send a formatted error response */
+    respondError: (error: Error, meta?: ResponseMeta) => void;
+    /** Get the response formatter instance */
+    formatter: ResponseFormatter;
+}
+/**
+ * Extended Express Request with formatter context
+ */
+interface FormattedRequest extends Request {
+    /** Request ID for tracing */
+    requestId: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+}
+/**
+ * Middleware options
+ */
+interface ResponseWrapperOptions extends FormatterConfigInput {
+    /** Skip wrapping for specific paths */
+    skipPaths?: string[];
+    /** Skip wrapping based on custom condition */
+    skipCondition?: (req: Request) => boolean;
+}
+/**
+ * Create response wrapper middleware
+ */
+declare function responseWrapper(options?: ResponseWrapperOptions): RequestHandler;
+/**
+ * Create response wrapper with custom formatter
+ */
+declare function createResponseWrapper(formatter: ResponseFormatter, options?: Omit<ResponseWrapperOptions, keyof FormatterConfigInput>): RequestHandler;
+
+/**
+ * Error catcher options
+ */
+interface ErrorCatcherOptions extends FormatterConfigInput {
+    /** Log errors to console */
+    logErrors?: boolean;
+    /** Custom error logger */
+    errorLogger?: (error: Error, req: Request) => void;
+    /** Transform error before formatting */
+    transformError?: (error: Error) => Error;
+    /** Custom response handler */
+    customHandler?: (error: Error, req: Request, res: Response) => boolean;
+}
+/**
+ * Create error catching middleware
+ */
+declare function errorCatcher(options?: ErrorCatcherOptions): ErrorRequestHandler;
+/**
+ * Create error catcher with existing formatter
+ */
+declare function createErrorCatcher(formatter: ResponseFormatter, options?: Omit<ErrorCatcherOptions, keyof FormatterConfigInput>): ErrorRequestHandler;
+/**
+ * Async handler wrapper to catch errors in async route handlers
+ */
+declare function asyncHandler<T>(fn: (req: Request, res: Response, next: NextFunction) => Promise<T>): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Create a try-catch wrapper for route handlers
+ */
+declare function catchErrors<T>(fn: (req: Request, res: Response) => Promise<T>): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Decorator options
+ */
+interface ResponseDecoratorOptions {
+    /** Status code to use for success response */
+    statusCode?: number;
+    /** Additional metadata to include */
+    meta?: ResponseMeta;
+    /** Skip formatting and return raw response */
+    raw?: boolean;
+}
+/**
+ * Create a response decorator factory
+ */
+declare function createResponseDecorator(formatter: ResponseFormatter): (options?: ResponseDecoratorOptions) => MethodDecorator;
+/**
+ * Handle errors decorator
+ * Wraps method in try-catch and passes errors to next()
+ */
+declare function HandleErrors(): MethodDecorator;
+/**
+ * API Route decorator factory
+ * Creates a decorator that handles response formatting and error catching
+ */
+declare function ApiRoute(formatter: ResponseFormatter, options?: ResponseDecoratorOptions): MethodDecorator;
+/**
+ * Validate decorator
+ * Validates request body/params/query before executing handler
+ */
+declare function Validate(validator: (data: unknown) => {
+    valid: boolean;
+    errors?: Record<string, string[]>;
+}, source?: 'body' | 'params' | 'query'): MethodDecorator;
+
+/**
+ * Pagination decorator options
+ */
+interface PaginateDecoratorOptions {
+    /** Default page size */
+    defaultLimit?: number;
+    /** Maximum page size */
+    maxLimit?: number;
+    /** Include HATEOAS links */
+    includeLinks?: boolean;
+    /** Additional metadata */
+    meta?: ResponseMeta;
+}
+/**
+ * Result type for paginated handlers
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    total: number;
+}
+/**
+ * Cursor paginated result type
+ */
+interface CursorPaginatedResult<T> {
+    data: T[];
+    nextCursor?: string;
+    previousCursor?: string;
+    hasMore: boolean;
+}
+/**
+ * Paginate decorator factory
+ * Automatically handles pagination for route handlers
+ */
+declare function Paginate(formatter: ResponseFormatter, options?: PaginateDecoratorOptions): MethodDecorator;
+/**
+ * Cursor paginate decorator factory
+ */
+declare function CursorPaginate(formatter: ResponseFormatter, options?: PaginateDecoratorOptions): MethodDecorator;
+
+/**
+ * Status code mapper class
+ */
+declare class StatusCodeMapper {
+    private customMappings;
+    constructor(customMappings?: Map<ErrorConstructor, number>);
+    /**
+     * Get status code for an error
+     */
+    getStatusCode(error: Error): number;
+    /**
+     * Get success status code based on HTTP method
+     */
+    getSuccessStatusCode(method: string, hasData: boolean): number;
+    /**
+     * Add custom error mapping
+     */
+    addMapping(ErrorClass: ErrorConstructor, statusCode: number): void;
+    /**
+     * Remove custom error mapping
+     */
+    removeMapping(ErrorClass: ErrorConstructor): boolean;
+    /**
+     * Check if status code indicates success
+     */
+    static isSuccessCode(statusCode: number): boolean;
+    /**
+     * Check if status code indicates client error
+     */
+    static isClientError(statusCode: number): boolean;
+    /**
+     * Check if status code indicates server error
+     */
+    static isServerError(statusCode: number): boolean;
+}
+/**
+ * Create a status code mapper with custom mappings
+ */
+declare function createStatusCodeMapper(customMappings?: Map<ErrorConstructor, number>): StatusCodeMapper;
+
+/**
+ * Options for error serialization
+ */
+interface SerializationOptions {
+    includeStack: boolean;
+    maskSensitiveData: boolean;
+    sensitiveFields: string[];
+    customSerializers?: Map<ErrorConstructor, ErrorSerializer>;
+}
+/**
+ * Serialize an error to ErrorDetails format
+ */
+declare function serializeError(error: Error, options?: Partial<SerializationOptions>): ErrorDetails;
+/**
+ * Extract field errors from validation error
+ */
+declare function extractFieldErrors(error: Error): FieldErrors | undefined;
+/**
+ * Extract error context
+ */
+declare function extractErrorContext(error: Error): ErrorContext | undefined;
+/**
+ * Create error serializer with options
+ */
+declare function createErrorSerializer(options?: Partial<SerializationOptions>): (error: Error) => ErrorDetails;
+
+/**
+ * Quick setup function that returns both middleware
+ * @example
+ * const { wrapper, errorHandler } = responseFormatter({ environment: 'production' });
+ * app.use(wrapper);
+ * // ... routes
+ * app.use(errorHandler);
+ */
+declare function responseFormatter(options?: ResponseWrapperOptions & ErrorCatcherOptions): {
+    wrapper: RequestHandler;
+    errorHandler: ErrorRequestHandler;
+};
+
+export { ApiError, type ApiErrorOptions, type ApiResponse, ApiRoute, BadRequestError, ConflictError, CursorPaginate, type CursorPaginatedResponse, type CursorPaginatedResult, type CursorPaginationInput, type CursorPaginationMeta, type CustomFormatter, type Environment, type ErrorCatcherOptions, type ErrorChainItem, type ErrorCode, ErrorCodes, type ErrorConstructor, type ErrorContext, type ErrorDetails, ErrorHandler, type ErrorHandlerOptions, type ErrorResponse, type ErrorSerializer, type FieldErrors, ForbiddenError, type FormattedRequest, type FormattedResponse, type FormatterConfig, type FormatterConfigInput, HandleErrors, InternalServerError, NotFoundError, Paginate, type PaginateDecoratorOptions, type PaginatedApiResponse, type PaginatedResponse, type PaginatedResult, type PaginationConfig, PaginationHelper, type PaginationInput, type PaginationLinks, type PaginationMeta, type PostResponseHook, type PreResponseHook, RateLimitError, type ResponseDecoratorOptions, ResponseFormatter, type ResponseMeta, type ResponseWrapperOptions, type SerializationOptions, type SerializedError, ServiceUnavailableError, StatusCodeMapper, type SuccessResponse, UnauthorizedError, UnprocessableEntityError, Validate, ValidationError, asyncHandler, calculateCursorPaginationMeta, calculatePaginationMeta, catchErrors, createError, createErrorCatcher, createErrorHandler, createErrorSerializer, createPaginationHelper, createResponseDecorator, createResponseFormatter, createResponseWrapper, createStatusCodeMapper, responseFormatter as default, defaultConfig, errorCatcher, errorHandlerMiddleware, extractErrorContext, extractFieldErrors, generateCursorPaginationLinks, generatePaginationLinks, generateRequestId, isErrorResponse, isPaginatedResponse, isPlainObject, isSuccessResponse, responseFormatter, responseWrapper, serializeError, validateConfig, validatePaginationInput };