@catbee/utils
Version:
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.
230 lines • 8.06 kB
TypeScript
import { ErrorResponse } from "./response.utils";
/**
* Generic HTTP error class used for custom exceptions with any status code.
* Inherit this when you need to throw errors dynamically at runtime.
*/
export 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.
*/
export 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.
*/
export 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).
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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).
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export 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.
*/
export declare function withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
//# sourceMappingURL=exception.utils.d.ts.map