http-response-kit 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,564 @@
+/**
+ * HTTP Response Kit - Type Definitions
+ * @module types
+ */
+/**
+ * Information structure for HTTP errors
+ */
+interface HttpErrorInfo {
+    /** Lowercase identifier for the error type */
+    type: string;
+    /** Human-readable title */
+    title: string;
+    /** HTTP status code */
+    code: number;
+    /** Default error description */
+    details: string;
+    /** Optional retry-after time in seconds */
+    retryAfter?: number;
+    /** Optional resolution suggestion */
+    resolution?: string;
+}
+/**
+ * Configuration options for HttpError
+ */
+interface HttpErrorOptions {
+    /** Custom error message */
+    message?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Original error cause */
+    cause?: Error;
+    /** Retry-after time in seconds */
+    retryAfter?: number;
+}
+/**
+ * Information structure for HTTP success responses
+ */
+interface HttpSuccessInfo {
+    /** HTTP status code */
+    code: number;
+    /** Description of the status */
+    description: string;
+}
+/**
+ * Configuration for success responses
+ */
+interface SuccessResponseConfig {
+    /** Response data payload */
+    data?: unknown;
+    /** Custom success message */
+    message?: string;
+    /** HTTP status code (default: 200) */
+    statusCode?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configuration for error responses
+ */
+interface ErrorResponseConfig {
+    /** Include stack trace in response */
+    includeStack?: boolean;
+    /** Additional fields to include */
+    additionalFields?: Record<string, unknown>;
+}
+/**
+ * Global library configuration
+ */
+interface LibraryConfig {
+    /** Enable development mode (includes stack traces) */
+    isDevelopment?: boolean;
+    /** Include timestamp in responses */
+    includeTimestamp?: boolean;
+    /** Custom default messages per error code */
+    customMessages?: Partial<Record<number, string>>;
+    /** Custom response transformer */
+    responseTransformer?: (response: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Standard success response structure
+ */
+interface SuccessResponse {
+    success: true;
+    status_code: number;
+    timestamp?: string;
+    data?: unknown;
+    message?: string;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Standard error response structure
+ */
+interface ErrorResponse {
+    success: false;
+    status_code: number;
+    timestamp?: string;
+    error: {
+        type: string;
+        title: string;
+        message: string;
+        details?: string;
+    };
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+/**
+ * HTTP Response Kit - Status Code Enums
+ * @module constants/status-codes
+ */
+/**
+ * HTTP 4xx Client Error codes
+ */
+declare enum HttpClientErrorCode {
+    BAD_REQUEST = 400,
+    UNAUTHORIZED = 401,
+    PAYMENT_REQUIRED = 402,
+    FORBIDDEN = 403,
+    NOT_FOUND = 404,
+    METHOD_NOT_ALLOWED = 405,
+    NOT_ACCEPTABLE = 406,
+    PROXY_AUTHENTICATION_REQUIRED = 407,
+    REQUEST_TIMEOUT = 408,
+    CONFLICT = 409,
+    GONE = 410,
+    LENGTH_REQUIRED = 411,
+    PRECONDITION_FAILED = 412,
+    PAYLOAD_TOO_LARGE = 413,
+    URI_TOO_LONG = 414,
+    UNSUPPORTED_MEDIA_TYPE = 415,
+    RANGE_NOT_SATISFIABLE = 416,
+    EXPECTATION_FAILED = 417,
+    IM_A_TEAPOT = 418,
+    MISDIRECTED_REQUEST = 421,
+    UNPROCESSABLE_ENTITY = 422,
+    LOCKED = 423,
+    FAILED_DEPENDENCY = 424,
+    TOO_EARLY = 425,
+    UPGRADE_REQUIRED = 426,
+    PRECONDITION_REQUIRED = 428,
+    TOO_MANY_REQUESTS = 429,
+    REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
+    UNAVAILABLE_FOR_LEGAL_REASONS = 451
+}
+/**
+ * HTTP 5xx Server Error codes
+ */
+declare enum HttpServerErrorCode {
+    INTERNAL_SERVER_ERROR = 500,
+    NOT_IMPLEMENTED = 501,
+    BAD_GATEWAY = 502,
+    SERVICE_UNAVAILABLE = 503,
+    GATEWAY_TIMEOUT = 504,
+    HTTP_VERSION_NOT_SUPPORTED = 505,
+    VARIANT_ALSO_NEGOTIATES = 506,
+    INSUFFICIENT_STORAGE = 507,
+    LOOP_DETECTED = 508,
+    BANDWIDTH_LIMIT_EXCEEDED = 509,
+    NOT_EXTENDED = 510,
+    NETWORK_AUTHENTICATION_REQUIRED = 511
+}
+/**
+ * All HTTP Error codes (4xx + 5xx)
+ */
+declare const HttpErrorCode: {
+    readonly [x: number]: string;
+    readonly INTERNAL_SERVER_ERROR: HttpServerErrorCode.INTERNAL_SERVER_ERROR;
+    readonly NOT_IMPLEMENTED: HttpServerErrorCode.NOT_IMPLEMENTED;
+    readonly BAD_GATEWAY: HttpServerErrorCode.BAD_GATEWAY;
+    readonly SERVICE_UNAVAILABLE: HttpServerErrorCode.SERVICE_UNAVAILABLE;
+    readonly GATEWAY_TIMEOUT: HttpServerErrorCode.GATEWAY_TIMEOUT;
+    readonly HTTP_VERSION_NOT_SUPPORTED: HttpServerErrorCode.HTTP_VERSION_NOT_SUPPORTED;
+    readonly VARIANT_ALSO_NEGOTIATES: HttpServerErrorCode.VARIANT_ALSO_NEGOTIATES;
+    readonly INSUFFICIENT_STORAGE: HttpServerErrorCode.INSUFFICIENT_STORAGE;
+    readonly LOOP_DETECTED: HttpServerErrorCode.LOOP_DETECTED;
+    readonly BANDWIDTH_LIMIT_EXCEEDED: HttpServerErrorCode.BANDWIDTH_LIMIT_EXCEEDED;
+    readonly NOT_EXTENDED: HttpServerErrorCode.NOT_EXTENDED;
+    readonly NETWORK_AUTHENTICATION_REQUIRED: HttpServerErrorCode.NETWORK_AUTHENTICATION_REQUIRED;
+    readonly BAD_REQUEST: HttpClientErrorCode.BAD_REQUEST;
+    readonly UNAUTHORIZED: HttpClientErrorCode.UNAUTHORIZED;
+    readonly PAYMENT_REQUIRED: HttpClientErrorCode.PAYMENT_REQUIRED;
+    readonly FORBIDDEN: HttpClientErrorCode.FORBIDDEN;
+    readonly NOT_FOUND: HttpClientErrorCode.NOT_FOUND;
+    readonly METHOD_NOT_ALLOWED: HttpClientErrorCode.METHOD_NOT_ALLOWED;
+    readonly NOT_ACCEPTABLE: HttpClientErrorCode.NOT_ACCEPTABLE;
+    readonly PROXY_AUTHENTICATION_REQUIRED: HttpClientErrorCode.PROXY_AUTHENTICATION_REQUIRED;
+    readonly REQUEST_TIMEOUT: HttpClientErrorCode.REQUEST_TIMEOUT;
+    readonly CONFLICT: HttpClientErrorCode.CONFLICT;
+    readonly GONE: HttpClientErrorCode.GONE;
+    readonly LENGTH_REQUIRED: HttpClientErrorCode.LENGTH_REQUIRED;
+    readonly PRECONDITION_FAILED: HttpClientErrorCode.PRECONDITION_FAILED;
+    readonly PAYLOAD_TOO_LARGE: HttpClientErrorCode.PAYLOAD_TOO_LARGE;
+    readonly URI_TOO_LONG: HttpClientErrorCode.URI_TOO_LONG;
+    readonly UNSUPPORTED_MEDIA_TYPE: HttpClientErrorCode.UNSUPPORTED_MEDIA_TYPE;
+    readonly RANGE_NOT_SATISFIABLE: HttpClientErrorCode.RANGE_NOT_SATISFIABLE;
+    readonly EXPECTATION_FAILED: HttpClientErrorCode.EXPECTATION_FAILED;
+    readonly IM_A_TEAPOT: HttpClientErrorCode.IM_A_TEAPOT;
+    readonly MISDIRECTED_REQUEST: HttpClientErrorCode.MISDIRECTED_REQUEST;
+    readonly UNPROCESSABLE_ENTITY: HttpClientErrorCode.UNPROCESSABLE_ENTITY;
+    readonly LOCKED: HttpClientErrorCode.LOCKED;
+    readonly FAILED_DEPENDENCY: HttpClientErrorCode.FAILED_DEPENDENCY;
+    readonly TOO_EARLY: HttpClientErrorCode.TOO_EARLY;
+    readonly UPGRADE_REQUIRED: HttpClientErrorCode.UPGRADE_REQUIRED;
+    readonly PRECONDITION_REQUIRED: HttpClientErrorCode.PRECONDITION_REQUIRED;
+    readonly TOO_MANY_REQUESTS: HttpClientErrorCode.TOO_MANY_REQUESTS;
+    readonly REQUEST_HEADER_FIELDS_TOO_LARGE: HttpClientErrorCode.REQUEST_HEADER_FIELDS_TOO_LARGE;
+    readonly UNAVAILABLE_FOR_LEGAL_REASONS: HttpClientErrorCode.UNAVAILABLE_FOR_LEGAL_REASONS;
+};
+type HttpErrorCode = HttpClientErrorCode | HttpServerErrorCode;
+/**
+ * HTTP 2xx Success codes
+ */
+declare enum HttpSuccessCode {
+    OK = 200,
+    CREATED = 201,
+    ACCEPTED = 202,
+    NON_AUTHORITATIVE_INFORMATION = 203,
+    NO_CONTENT = 204,
+    RESET_CONTENT = 205,
+    PARTIAL_CONTENT = 206,
+    MULTI_STATUS = 207,
+    ALREADY_REPORTED = 208,
+    IM_USED = 226
+}
+/**
+ * HTTP 3xx Redirect codes
+ */
+declare enum HttpRedirectCode {
+    MULTIPLE_CHOICES = 300,
+    MOVED_PERMANENTLY = 301,
+    FOUND = 302,
+    SEE_OTHER = 303,
+    NOT_MODIFIED = 304,
+    USE_PROXY = 305,
+    TEMPORARY_REDIRECT = 307,
+    PERMANENT_REDIRECT = 308
+}
+/**
+ * HTTP 1xx Informational codes
+ */
+declare enum HttpInfoCode {
+    CONTINUE = 100,
+    SWITCHING_PROTOCOLS = 101,
+    PROCESSING = 102,
+    EARLY_HINTS = 103
+}
+
+/**
+ * HTTP Response Kit - Error Definitions
+ * @module constants/error-definitions
+ */
+
+/**
+ * Complete definitions for all HTTP error types (4xx and 5xx)
+ */
+declare const HttpErrorDefinitions: Record<number, HttpErrorInfo>;
+/**
+ * Get error definition by status code
+ */
+declare function getErrorDefinition(code: number): HttpErrorInfo;
+
+/**
+ * HTTP Response Kit - Success Definitions
+ * @module constants/success-definitions
+ */
+
+/**
+ * Complete definitions for HTTP 2xx Success codes
+ */
+declare const HttpSuccessDefinitions: Record<number, HttpSuccessInfo>;
+/**
+ * Complete definitions for HTTP 3xx Redirect codes
+ */
+declare const HttpRedirectDefinitions: Record<number, HttpSuccessInfo>;
+/**
+ * Complete definitions for HTTP 1xx Informational codes
+ */
+declare const HttpInfoDefinitions: Record<number, HttpSuccessInfo>;
+/**
+ * Get success definition by status code
+ */
+declare function getSuccessDefinition(code: number): HttpSuccessInfo;
+
+/**
+ * HTTP Response Kit - HttpError Class
+ * @module errors/HttpError
+ */
+
+/**
+ * Custom HTTP Error class that extends the native Error class.
+ * Provides structured error information for HTTP responses.
+ *
+ * @example
+ * ```ts
+ * // Basic usage with status code
+ * throw new HttpError(404);
+ * throw new HttpError(HttpErrorCode.NOT_FOUND);
+ *
+ * // With custom message
+ * throw new HttpError(404, { message: 'User not found' });
+ *
+ * // With metadata
+ * throw new HttpError(400, {
+ *   message: 'Validation failed',
+ *   metadata: { fields: ['email', 'password'] }
+ * });
+ *
+ * // Using factory methods
+ * throw HttpError.notFound('Resource not found');
+ * throw HttpError.badRequest('Invalid input');
+ * ```
+ */
+declare class HttpError extends Error {
+    /** HTTP status code */
+    readonly code: number;
+    /** Lowercase error type identifier */
+    readonly type: string;
+    /** Human-readable error title */
+    readonly title: string;
+    /** Additional error metadata */
+    readonly metadata?: Record<string, unknown>;
+    /** Original error cause */
+    readonly cause?: Error;
+    /** Retry-after time in seconds (if applicable) */
+    readonly retryAfter?: number;
+    /**
+     * Creates a new HttpError instance
+     *
+     * @param code - HTTP status code (e.g., 404, 500)
+     * @param options - Optional configuration
+     */
+    constructor(code: number, options?: HttpErrorOptions);
+    /**
+     * Convert error to plain object for JSON serialization
+     */
+    toJSON(): Record<string, unknown>;
+    /** 400 Bad Request */
+    static badRequest(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 401 Unauthorized */
+    static unauthorized(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 402 Payment Required */
+    static paymentRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 403 Forbidden */
+    static forbidden(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 404 Not Found */
+    static notFound(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 405 Method Not Allowed */
+    static methodNotAllowed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 406 Not Acceptable */
+    static notAcceptable(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 407 Proxy Authentication Required */
+    static proxyAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 408 Request Timeout */
+    static requestTimeout(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 409 Conflict */
+    static conflict(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 410 Gone */
+    static gone(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 411 Length Required */
+    static lengthRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 412 Precondition Failed */
+    static preconditionFailed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 413 Payload Too Large */
+    static payloadTooLarge(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 414 URI Too Long */
+    static uriTooLong(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 415 Unsupported Media Type */
+    static unsupportedMediaType(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 416 Range Not Satisfiable */
+    static rangeNotSatisfiable(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 417 Expectation Failed */
+    static expectationFailed(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 418 I'm a Teapot */
+    static imATeapot(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 421 Misdirected Request */
+    static misdirectedRequest(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 422 Unprocessable Entity */
+    static unprocessableEntity(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 423 Locked */
+    static locked(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 424 Failed Dependency */
+    static failedDependency(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 425 Too Early */
+    static tooEarly(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 426 Upgrade Required */
+    static upgradeRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 428 Precondition Required */
+    static preconditionRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 429 Too Many Requests */
+    static tooManyRequests(message?: string, retryAfter?: number, metadata?: Record<string, unknown>): HttpError;
+    /** 431 Request Header Fields Too Large */
+    static requestHeaderFieldsTooLarge(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 451 Unavailable For Legal Reasons */
+    static unavailableForLegalReasons(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 500 Internal Server Error */
+    static internalServerError(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 501 Not Implemented */
+    static notImplemented(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 502 Bad Gateway */
+    static badGateway(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 503 Service Unavailable */
+    static serviceUnavailable(message?: string, retryAfter?: number, metadata?: Record<string, unknown>): HttpError;
+    /** 504 Gateway Timeout */
+    static gatewayTimeout(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 505 HTTP Version Not Supported */
+    static httpVersionNotSupported(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 506 Variant Also Negotiates */
+    static variantAlsoNegotiates(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 507 Insufficient Storage */
+    static insufficientStorage(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 508 Loop Detected */
+    static loopDetected(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 509 Bandwidth Limit Exceeded */
+    static bandwidthLimitExceeded(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 510 Not Extended */
+    static notExtended(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /** 511 Network Authentication Required */
+    static networkAuthenticationRequired(message?: string, metadata?: Record<string, unknown>): HttpError;
+    /**
+     * Create an HttpError from an unknown error
+     */
+    static fromError(error: unknown, fallbackCode?: number): HttpError;
+    /**
+     * Check if an error is an HttpError
+     */
+    static isHttpError(error: unknown): error is HttpError;
+    /**
+     * Check if error is a client error (4xx)
+     */
+    isClientError(): boolean;
+    /**
+     * Check if error is a server error (5xx)
+     */
+    isServerError(): boolean;
+}
+
+/**
+ * HTTP Response Kit - HttpResponse Class
+ * @module responses/HttpResponse
+ */
+
+/**
+ * Utility class for formatting HTTP responses.
+ * Provides consistent structure for both success and error responses.
+ *
+ * @example
+ * ```ts
+ * // Success response
+ * const response = HttpResponse.success({
+ *   data: { id: 1, name: 'John' },
+ *   message: 'User created successfully',
+ *   statusCode: 201
+ * });
+ *
+ * // Error response
+ * const error = new HttpError(404, { message: 'User not found' });
+ * const errorResponse = HttpResponse.error(error);
+ *
+ * // Express integration
+ * app.get('/user/:id', (req, res) => {
+ *   try {
+ *     const user = findUser(req.params.id);
+ *     const response = HttpResponse.success({ data: user });
+ *     res.status(response.status_code).json(response);
+ *   } catch (err) {
+ *     const response = HttpResponse.error(HttpError.fromError(err));
+ *     res.status(response.status_code).json(response);
+ *   }
+ * });
+ * ```
+ */
+declare class HttpResponse {
+    /**
+     * Format a success response
+     *
+     * @param config - Success response configuration
+     * @returns Formatted success response object
+     */
+    static success(config?: SuccessResponseConfig): SuccessResponse;
+    /**
+     * Format an error response
+     *
+     * @param error - HttpError instance
+     * @param config - Optional error response configuration
+     * @returns Formatted error response object
+     */
+    static error(error: HttpError, config?: ErrorResponseConfig): ErrorResponse;
+    /**
+     * Format a response from any error (converts to HttpError first)
+     *
+     * @param error - Any error type
+     * @param config - Optional error response configuration
+     * @returns Formatted error response object
+     */
+    static fromError(error: unknown, config?: ErrorResponseConfig): ErrorResponse;
+    /** 200 OK */
+    static ok(data?: unknown, message?: string): SuccessResponse;
+    /** 201 Created */
+    static created(data?: unknown, message?: string): SuccessResponse;
+    /** 202 Accepted */
+    static accepted(data?: unknown, message?: string): SuccessResponse;
+    /** 204 No Content */
+    static noContent(): SuccessResponse;
+    /** 206 Partial Content */
+    static partialContent(data?: unknown, message?: string): SuccessResponse;
+    /** 304 Not Modified */
+    static notModified(): SuccessResponse;
+    /**
+     * Check if a response is a success response
+     */
+    static isSuccess(response: SuccessResponse | ErrorResponse): response is SuccessResponse;
+    /**
+     * Check if a response is an error response
+     */
+    static isError(response: SuccessResponse | ErrorResponse): response is ErrorResponse;
+    /**
+     * Create a paginated success response
+     */
+    static paginated(data: unknown[], pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages?: number;
+    }, message?: string): SuccessResponse;
+}
+
+/**
+ * HTTP Response Kit - Library Configuration
+ * @module config
+ */
+
+/**
+ * Configure the library globally
+ *
+ * @param config - Partial configuration to merge with current settings
+ *
+ * @example
+ * ```ts
+ * configure({
+ *   isDevelopment: true,
+ *   includeTimestamp: false,
+ *   customMessages: {
+ *     404: 'Oops! This page went on vacation 🏝️',
+ *     500: 'Well, this is embarrassing... 🤖'
+ *   },
+ * });
+ * ```
+ */
+declare function configure(config: Partial<LibraryConfig>): void;
+/**
+ * Get the current library configuration
+ */
+declare function getConfig(): LibraryConfig;
+/**
+ * Reset configuration to defaults
+ */
+declare function resetConfig(): void;
+/**
+ * Check if running in development mode
+ */
+declare function isDevelopment(): boolean;
+
+export { type ErrorResponse, type ErrorResponseConfig, HttpClientErrorCode, HttpError, HttpErrorCode, HttpErrorDefinitions, type HttpErrorInfo, type HttpErrorOptions, HttpInfoCode, HttpInfoDefinitions, HttpRedirectCode, HttpRedirectDefinitions, HttpResponse, HttpServerErrorCode, HttpSuccessCode, HttpSuccessDefinitions, type HttpSuccessInfo, type LibraryConfig, type SuccessResponse, type SuccessResponseConfig, configure, getConfig, getErrorDefinition, getSuccessDefinition, isDevelopment, resetConfig };