@catbee/utils/exception/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

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

import { ErrorResponse } from '@catbee/utils/response';

/**
 * Generic HTTP error class used for custom exceptions with any status code.
 * Inherit this when you need to throw errors dynamically at runtime.
 */
declare class HttpError extends ErrorResponse {
    /**
     * Creates a new HTTP error instance.
     * @param status - A valid HTTP status code (e.g., 400, 500).
     * @param message - The error message to return to the client.
     */
    constructor(status: number, message: string);
}
/**
 * Represents a 500 Internal Server Error.
 * Use this for unexpected backend errors that are not caused by the client.
 */
declare class InternalServerErrorException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Internal server error".
     */
    constructor(message?: string);
}
/**
 * Represents a 401 Unauthorized Error.
 * Indicates that authentication is required and has failed or not been provided.
 */
declare class UnauthorizedException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Unauthorized".
     */
    constructor(message?: string);
}
/**
 * Represents a 400 Bad Request Error.
 * Indicates that the client has sent invalid data (e.g., malformed request body).
 */
declare class BadRequestException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Bad request".
     */
    constructor(message?: string);
}
/**
 * Represents a 404 Not Found Error.
 * Used when a requested resource (e.g., user, file) could not be located.
 */
declare class NotFoundException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Resource not found".
     */
    constructor(message?: string);
}
/**
 * Represents a 403 Forbidden Error.
 * Indicates that the client is authenticated but not allowed to access the resource.
 */
declare class ForbiddenException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Forbidden".
     */
    constructor(message?: string);
}
/**
 * Represents a 409 Conflict Error.
 * Commonly used when a resource already exists or a versioning conflict occurs.
 */
declare class ConflictException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Conflict".
     */
    constructor(message?: string);
}
/**
 * Represents a 502 Bad Gateway Error.
 * Used when the server receives an invalid response from an upstream server.
 */
declare class BadGatewayException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Bad Gateway".
     */
    constructor(message?: string);
}
/**
 * Represents a 429 Too Many Requests Error.
 * Returned when the client has hit a rate limit.
 */
declare class TooManyRequestsException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Too many requests".
     */
    constructor(message?: string);
}
/**
 * Represents a 503 Service Unavailable Error.
 * Indicates that the server is temporarily unavailable (e.g., for maintenance).
 */
declare class ServiceUnavailableException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Service Unavailable".
     */
    constructor(message?: string);
}
/**
 * Represents a 504 Gateway Timeout Error.
 * Returned when the server acting as a gateway times out waiting for a response.
 */
declare class GatewayTimeoutException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Gateway Timeout".
     */
    constructor(message?: string);
}
/**
 * Represents a 422 Unprocessable Entity Error.
 * Used when the server understands the content type but cannot process the contained instructions.
 */
declare class UnprocessableEntityException extends ErrorResponse {
    details?: Record<string, any> | undefined;
    /**
     * @param message - Optional custom message. Defaults to "Unprocessable Entity".
     * @param details - Optional validation details or additional error context.
     */
    constructor(message?: string, details?: Record<string, any> | undefined);
}
/**
 * Represents a 405 Method Not Allowed Error.
 * Used when the request method is not supported for the requested resource.
 */
declare class MethodNotAllowedException extends ErrorResponse {
    allowedMethods?: string[] | undefined;
    /**
     * @param message - Optional custom message. Defaults to "Method Not Allowed".
     * @param allowedMethods - Optional array of allowed HTTP methods.
     */
    constructor(message?: string, allowedMethods?: string[] | undefined);
}
/**
 * Represents a 406 Not Acceptable Error.
 * Used when the server cannot produce a response matching the client's accepted content types.
 */
declare class NotAcceptableException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Not Acceptable".
     */
    constructor(message?: string);
}
/**
 * Represents a 408 Request Timeout Error.
 * Used when the server times out waiting for the client to send a request.
 */
declare class RequestTimeoutException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Request Timeout".
     */
    constructor(message?: string);
}
/**
 * Represents a 415 Unsupported Media Type Error.
 * Used when the request's Content-Type is not supported.
 */
declare class UnsupportedMediaTypeException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Unsupported Media Type".
     */
    constructor(message?: string);
}
/**
 * Represents a 413 Payload Too Large Error.
 * Used when the request body exceeds server limits.
 */
declare class PayloadTooLargeException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Payload Too Large".
     */
    constructor(message?: string);
}
/**
 * Represents a 507 Insufficient Storage Error.
 * Used when the server has insufficient storage to complete the request.
 */
declare class InsufficientStorageException extends ErrorResponse {
    /**
     * @param message - Optional custom message. Defaults to "Insufficient Storage".
     */
    constructor(message?: string);
}
/**
 * Checks if an error is an instance of HttpError or its subclasses.
 *
 * @param error - The error to check.
 * @returns True if the error is an HttpError, false otherwise.
 */
declare function isHttpError(error: unknown): error is ErrorResponse;
/**
 * Creates an HTTP error with the specified status code and message.
 * Factory function for creating appropriate HTTP error instances.
 *
 * @param status - HTTP status code.
 * @param message - Optional custom error message.
 * @returns An instance of the appropriate HTTP error class.
 */
declare function createHttpError(status: number, message?: string): ErrorResponse;
/**
 * Type guard to check if an object has specific error properties.
 *
 * @param error - The object to check.
 * @returns True if object has error-like structure.
 */
declare function hasErrorShape(error: unknown): error is {
    message: string;
    status?: number;
    code?: string;
};
/**
 * Safely extracts message from any error type.
 *
 * @param error - Any error object or value.
 * @returns A string error message.
 */
declare function getErrorMessage(error: unknown): string;
/**
 * Wraps a function and transforms any errors into HTTP errors.
 * Useful for API handlers to ensure consistent error responses.
 *
 * @param handler - The async function to wrap.
 * @returns A function that always returns or throws an HTTP error.
 */
declare function withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;

export { BadGatewayException, BadRequestException, ConflictException, ForbiddenException, GatewayTimeoutException, HttpError, InsufficientStorageException, InternalServerErrorException, MethodNotAllowedException, NotAcceptableException, NotFoundException, PayloadTooLargeException, RequestTimeoutException, ServiceUnavailableException, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, createHttpError, getErrorMessage, hasErrorShape, isHttpError, withErrorHandling };