apienvelope 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,32 +1,19 @@
 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;
@@ -34,22 +21,13 @@ interface ErrorDetails {
     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;
@@ -59,9 +37,6 @@ interface PaginationMeta {
     hasPreviousPage: boolean;
     links?: PaginationLinks;
 }
-/**
- * HATEOAS-style pagination links
- */
 interface PaginationLinks {
     self?: string;
     first?: string;
@@ -69,9 +44,6 @@ interface PaginationLinks {
     next?: string;
     previous?: string;
 }
-/**
- * Cursor-based pagination metadata
- */
 interface CursorPaginationMeta {
     limit: number;
     cursor?: string;
@@ -80,58 +52,24 @@ interface CursorPaginationMeta {
     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;
@@ -141,9 +79,6 @@ interface ErrorContext {
     timestamp?: string;
     [key: string]: unknown;
 }
-/**
- * API Error options
- */
 interface ApiErrorOptions {
     code?: string;
     statusCode?: number;
@@ -153,9 +88,6 @@ interface ApiErrorOptions {
     context?: ErrorContext;
     isOperational?: boolean;
 }
-/**
- * Serialized error structure
- */
 interface SerializedError {
     code: string;
     message: string;
@@ -165,18 +97,12 @@ interface SerializedError {
     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";
@@ -191,86 +117,44 @@ declare const ErrorCodes: {
 };
 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;
@@ -278,236 +162,88 @@ interface CursorPaginationInput {
     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
-     */
+    private safeParseInt;
     extractFromRequest(req: Request): {
         page: number;
         limit: number;
     };
-    /**
-     * Extract cursor pagination parameters from request
-     */
+    private validateCursor;
     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;
@@ -517,323 +253,134 @@ declare class ApiError extends Error {
     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;