@catbee/utils 0.0.8-rc.1 → 0.0.8-rc.2

package/build/esnext/utils/exception.utils.js

@@ -1,381 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/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 { HttpStatusCodes } from './http-status-codes';
-import { getLogger } from './logger.utils';
-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 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, message) {
-        super(message);
-        this.status = status;
-    }
-}
-/**
- * Represents a 500 Internal Server Error.
- * Use this for unexpected backend errors that are not caused by the client.
- */
-export class InternalServerErrorException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Internal server error".
-     */
-    constructor(message = 'Internal server error') {
-        super(message);
-        this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
-    }
-}
-/**
- * Represents a 401 Unauthorized Error.
- * Indicates that authentication is required and has failed or not been provided.
- */
-export class UnauthorizedException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Unauthorized".
-     */
-    constructor(message = 'Unauthorized') {
-        super(message);
-        this.status = HttpStatusCodes.UNAUTHORIZED;
-    }
-}
-/**
- * Represents a 400 Bad Request Error.
- * Indicates that the client has sent invalid data (e.g., malformed request body).
- */
-export class BadRequestException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Bad request".
-     */
-    constructor(message = 'Bad request') {
-        super(message);
-        this.status = HttpStatusCodes.BAD_REQUEST;
-    }
-}
-/**
- * Represents a 404 Not Found Error.
- * Used when a requested resource (e.g., user, file) could not be located.
- */
-export class NotFoundException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Resource not found".
-     */
-    constructor(message = 'Resource not found') {
-        super(message);
-        this.status = HttpStatusCodes.NOT_FOUND;
-    }
-}
-/**
- * Represents a 403 Forbidden Error.
- * Indicates that the client is authenticated but not allowed to access the resource.
- */
-export class ForbiddenException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Forbidden".
-     */
-    constructor(message = 'Forbidden') {
-        super(message);
-        this.status = HttpStatusCodes.FORBIDDEN;
-    }
-}
-/**
- * Represents a 409 Conflict Error.
- * Commonly used when a resource already exists or a versioning conflict occurs.
- */
-export class ConflictException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Conflict".
-     */
-    constructor(message = 'Conflict') {
-        super(message);
-        this.status = HttpStatusCodes.CONFLICT;
-    }
-}
-/**
- * Represents a 502 Bad Gateway Error.
- * Used when the server receives an invalid response from an upstream server.
- */
-export class BadGatewayException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Bad Gateway".
-     */
-    constructor(message = 'Bad Gateway') {
-        super(message);
-        this.status = HttpStatusCodes.BAD_GATEWAY;
-    }
-}
-/**
- * Represents a 429 Too Many Requests Error.
- * Returned when the client has hit a rate limit.
- */
-export class TooManyRequestsException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Too many requests".
-     */
-    constructor(message = 'Too many requests') {
-        super(message);
-        this.status = HttpStatusCodes.TOO_MANY_REQUESTS;
-    }
-}
-/**
- * Represents a 503 Service Unavailable Error.
- * Indicates that the server is temporarily unavailable (e.g., for maintenance).
- */
-export class ServiceUnavailableException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Service Unavailable".
-     */
-    constructor(message = 'Service Unavailable') {
-        super(message);
-        this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;
-    }
-}
-/**
- * Represents a 504 Gateway Timeout Error.
- * Returned when the server acting as a gateway times out waiting for a response.
- */
-export class GatewayTimeoutException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Gateway Timeout".
-     */
-    constructor(message = 'Gateway Timeout') {
-        super(message);
-        this.status = HttpStatusCodes.GATEWAY_TIMEOUT;
-    }
-}
-/**
- * Represents a 422 Unprocessable Entity Error.
- * Used when the server understands the content type but cannot process the contained instructions.
- */
-export class UnprocessableEntityException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Unprocessable Entity".
-     * @param details - Optional validation details or additional error context.
-     */
-    constructor(message = 'Unprocessable Entity', details) {
-        super(message);
-        this.details = details;
-        this.status = HttpStatusCodes.UNPROCESSABLE_ENTITY;
-    }
-}
-/**
- * Represents a 405 Method Not Allowed Error.
- * Used when the request method is not supported for the requested resource.
- */
-export class MethodNotAllowedException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Method Not Allowed".
-     * @param allowedMethods - Optional array of allowed HTTP methods.
-     */
-    constructor(message = 'Method Not Allowed', allowedMethods) {
-        super(message);
-        this.allowedMethods = allowedMethods;
-        this.status = HttpStatusCodes.METHOD_NOT_ALLOWED;
-    }
-}
-/**
- * Represents a 406 Not Acceptable Error.
- * Used when the server cannot produce a response matching the client's accepted content types.
- */
-export class NotAcceptableException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Not Acceptable".
-     */
-    constructor(message = 'Not Acceptable') {
-        super(message);
-        this.status = HttpStatusCodes.NOT_ACCEPTABLE;
-    }
-}
-/**
- * Represents a 408 Request Timeout Error.
- * Used when the server times out waiting for the client to send a request.
- */
-export class RequestTimeoutException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Request Timeout".
-     */
-    constructor(message = 'Request Timeout') {
-        super(message);
-        this.status = HttpStatusCodes.REQUEST_TIMEOUT;
-    }
-}
-/**
- * Represents a 415 Unsupported Media Type Error.
- * Used when the request's Content-Type is not supported.
- */
-export class UnsupportedMediaTypeException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Unsupported Media Type".
-     */
-    constructor(message = 'Unsupported Media Type') {
-        super(message);
-        this.status = HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE;
-    }
-}
-/**
- * Represents a 413 Payload Too Large Error.
- * Used when the request body exceeds server limits.
- */
-export class PayloadTooLargeException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Payload Too Large".
-     */
-    constructor(message = 'Payload Too Large') {
-        super(message);
-        this.status = HttpStatusCodes.PAYLOAD_TOO_LARGE;
-    }
-}
-/**
- * Represents a 507 Insufficient Storage Error.
- * Used when the server has insufficient storage to complete the request.
- */
-export class InsufficientStorageException extends ErrorResponse {
-    /**
-     * @param message - Optional custom message. Defaults to "Insufficient Storage".
-     */
-    constructor(message = 'Insufficient Storage') {
-        super(message);
-        this.status = HttpStatusCodes.INSUFFICIENT_STORAGE;
-    }
-}
-/**
- * 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 function isHttpError(error) {
-    return error instanceof 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 function createHttpError(status, message) {
-    switch (status) {
-        case HttpStatusCodes.BAD_REQUEST:
-            return new BadRequestException(message);
-        case HttpStatusCodes.UNAUTHORIZED:
-            return new UnauthorizedException(message);
-        case HttpStatusCodes.FORBIDDEN:
-            return new ForbiddenException(message);
-        case HttpStatusCodes.NOT_FOUND:
-            return new NotFoundException(message);
-        case HttpStatusCodes.METHOD_NOT_ALLOWED:
-            return new MethodNotAllowedException(message);
-        case HttpStatusCodes.NOT_ACCEPTABLE:
-            return new NotAcceptableException(message);
-        case HttpStatusCodes.REQUEST_TIMEOUT:
-            return new RequestTimeoutException(message);
-        case HttpStatusCodes.CONFLICT:
-            return new ConflictException(message);
-        case HttpStatusCodes.GONE:
-            return new HttpError(HttpStatusCodes.GONE, message || 'Gone');
-        case HttpStatusCodes.PAYLOAD_TOO_LARGE:
-            return new PayloadTooLargeException(message);
-        case HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE:
-            return new UnsupportedMediaTypeException(message);
-        case HttpStatusCodes.UNPROCESSABLE_ENTITY:
-            return new UnprocessableEntityException(message);
-        case HttpStatusCodes.TOO_MANY_REQUESTS:
-            return new TooManyRequestsException(message);
-        case HttpStatusCodes.INTERNAL_SERVER_ERROR:
-            return new InternalServerErrorException(message);
-        case HttpStatusCodes.BAD_GATEWAY:
-            return new BadGatewayException(message);
-        case HttpStatusCodes.SERVICE_UNAVAILABLE:
-            return new ServiceUnavailableException(message);
-        case HttpStatusCodes.GATEWAY_TIMEOUT:
-            return new GatewayTimeoutException(message);
-        case HttpStatusCodes.INSUFFICIENT_STORAGE:
-            return new InsufficientStorageException(message);
-        default:
-            return new HttpError(status, message || `HTTP Error ${status}`);
-    }
-}
-/**
- * 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 function hasErrorShape(error) {
-    return (typeof error === 'object' && error !== null && 'message' in error && typeof error.message === 'string');
-}
-/**
- * Safely extracts message from any error type.
- *
- * @param error - Any error object or value.
- * @returns A string error message.
- */
-export function getErrorMessage(error) {
-    if (typeof error === 'string') {
-        return error;
-    }
-    if (error instanceof Error) {
-        return error.message;
-    }
-    if (hasErrorShape(error)) {
-        return error.message;
-    }
-    return 'Unknown error occurred';
-}
-/**
- * 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 function withErrorHandling(handler) {
-    return async (...args) => {
-        try {
-            return await handler(...args);
-        }
-        catch (err) {
-            if (isHttpError(err)) {
-                throw err;
-            }
-            // Log the original error (consider using a proper logger)
-            getLogger().error({ err }, 'Caught error in handler');
-            // Extract status code if it exists, otherwise use 500
-            let status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
-            if (hasErrorShape(err) && typeof err.status === 'number') {
-                status = err.status;
-            }
-            // Create appropriate HTTP error
-            throw createHttpError(status, getErrorMessage(err));
-        }
-    };
-}
-//# sourceMappingURL=exception.utils.js.map

package/build/esnext/utils/exception.utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"exception.utils.js","sourceRoot":"","sources":["../../../src/utils/exception.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * The MIT License\n *\n * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { HttpStatusCodes } from './http-status-codes';\nimport { getLogger } from './logger.utils';\nimport { ErrorResponse } from './response.utils';\n\n/**\n * Generic HTTP error class used for custom exceptions with any status code.\n * Inherit this when you need to throw errors dynamically at runtime.\n */\nexport class HttpError extends ErrorResponse {\n  /**\n   * Creates a new HTTP error instance.\n   * @param status - A valid HTTP status code (e.g., 400, 500).\n   * @param message - The error message to return to the client.\n   */\n  constructor(status: number, message: string) {\n    super(message);\n    this.status = status;\n  }\n}\n\n/**\n * Represents a 500 Internal Server Error.\n * Use this for unexpected backend errors that are not caused by the client.\n */\nexport class InternalServerErrorException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Internal server error\".\n   */\n  constructor(message: string = 'Internal server error') {\n    super(message);\n    this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;\n  }\n}\n\n/**\n * Represents a 401 Unauthorized Error.\n * Indicates that authentication is required and has failed or not been provided.\n */\nexport class UnauthorizedException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unauthorized\".\n   */\n  constructor(message: string = 'Unauthorized') {\n    super(message);\n    this.status = HttpStatusCodes.UNAUTHORIZED;\n  }\n}\n\n/**\n * Represents a 400 Bad Request Error.\n * Indicates that the client has sent invalid data (e.g., malformed request body).\n */\nexport class BadRequestException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad request\".\n   */\n  constructor(message: string = 'Bad request') {\n    super(message);\n    this.status = HttpStatusCodes.BAD_REQUEST;\n  }\n}\n\n/**\n * Represents a 404 Not Found Error.\n * Used when a requested resource (e.g., user, file) could not be located.\n */\nexport class NotFoundException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Resource not found\".\n   */\n  constructor(message: string = 'Resource not found') {\n    super(message);\n    this.status = HttpStatusCodes.NOT_FOUND;\n  }\n}\n\n/**\n * Represents a 403 Forbidden Error.\n * Indicates that the client is authenticated but not allowed to access the resource.\n */\nexport class ForbiddenException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Forbidden\".\n   */\n  constructor(message: string = 'Forbidden') {\n    super(message);\n    this.status = HttpStatusCodes.FORBIDDEN;\n  }\n}\n\n/**\n * Represents a 409 Conflict Error.\n * Commonly used when a resource already exists or a versioning conflict occurs.\n */\nexport class ConflictException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Conflict\".\n   */\n  constructor(message: string = 'Conflict') {\n    super(message);\n    this.status = HttpStatusCodes.CONFLICT;\n  }\n}\n\n/**\n * Represents a 502 Bad Gateway Error.\n * Used when the server receives an invalid response from an upstream server.\n */\nexport class BadGatewayException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Bad Gateway\".\n   */\n  constructor(message: string = 'Bad Gateway') {\n    super(message);\n    this.status = HttpStatusCodes.BAD_GATEWAY;\n  }\n}\n\n/**\n * Represents a 429 Too Many Requests Error.\n * Returned when the client has hit a rate limit.\n */\nexport class TooManyRequestsException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Too many requests\".\n   */\n  constructor(message: string = 'Too many requests') {\n    super(message);\n    this.status = HttpStatusCodes.TOO_MANY_REQUESTS;\n  }\n}\n\n/**\n * Represents a 503 Service Unavailable Error.\n * Indicates that the server is temporarily unavailable (e.g., for maintenance).\n */\nexport class ServiceUnavailableException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Service Unavailable\".\n   */\n  constructor(message: string = 'Service Unavailable') {\n    super(message);\n    this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;\n  }\n}\n\n/**\n * Represents a 504 Gateway Timeout Error.\n * Returned when the server acting as a gateway times out waiting for a response.\n */\nexport class GatewayTimeoutException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Gateway Timeout\".\n   */\n  constructor(message: string = 'Gateway Timeout') {\n    super(message);\n    this.status = HttpStatusCodes.GATEWAY_TIMEOUT;\n  }\n}\n\n/**\n * Represents a 422 Unprocessable Entity Error.\n * Used when the server understands the content type but cannot process the contained instructions.\n */\nexport class UnprocessableEntityException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unprocessable Entity\".\n   * @param details - Optional validation details or additional error context.\n   */\n  constructor(\n    message: string = 'Unprocessable Entity',\n    public details?: Record<string, any>\n  ) {\n    super(message);\n    this.status = HttpStatusCodes.UNPROCESSABLE_ENTITY;\n  }\n}\n\n/**\n * Represents a 405 Method Not Allowed Error.\n * Used when the request method is not supported for the requested resource.\n */\nexport class MethodNotAllowedException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Method Not Allowed\".\n   * @param allowedMethods - Optional array of allowed HTTP methods.\n   */\n  constructor(\n    message: string = 'Method Not Allowed',\n    public allowedMethods?: string[]\n  ) {\n    super(message);\n    this.status = HttpStatusCodes.METHOD_NOT_ALLOWED;\n  }\n}\n\n/**\n * Represents a 406 Not Acceptable Error.\n * Used when the server cannot produce a response matching the client's accepted content types.\n */\nexport class NotAcceptableException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Not Acceptable\".\n   */\n  constructor(message: string = 'Not Acceptable') {\n    super(message);\n    this.status = HttpStatusCodes.NOT_ACCEPTABLE;\n  }\n}\n\n/**\n * Represents a 408 Request Timeout Error.\n * Used when the server times out waiting for the client to send a request.\n */\nexport class RequestTimeoutException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Request Timeout\".\n   */\n  constructor(message: string = 'Request Timeout') {\n    super(message);\n    this.status = HttpStatusCodes.REQUEST_TIMEOUT;\n  }\n}\n\n/**\n * Represents a 415 Unsupported Media Type Error.\n * Used when the request's Content-Type is not supported.\n */\nexport class UnsupportedMediaTypeException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Unsupported Media Type\".\n   */\n  constructor(message: string = 'Unsupported Media Type') {\n    super(message);\n    this.status = HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE;\n  }\n}\n\n/**\n * Represents a 413 Payload Too Large Error.\n * Used when the request body exceeds server limits.\n */\nexport class PayloadTooLargeException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Payload Too Large\".\n   */\n  constructor(message: string = 'Payload Too Large') {\n    super(message);\n    this.status = HttpStatusCodes.PAYLOAD_TOO_LARGE;\n  }\n}\n\n/**\n * Represents a 507 Insufficient Storage Error.\n * Used when the server has insufficient storage to complete the request.\n */\nexport class InsufficientStorageException extends ErrorResponse {\n  /**\n   * @param message - Optional custom message. Defaults to \"Insufficient Storage\".\n   */\n  constructor(message: string = 'Insufficient Storage') {\n    super(message);\n    this.status = HttpStatusCodes.INSUFFICIENT_STORAGE;\n  }\n}\n\n/**\n * Checks if an error is an instance of HttpError or its subclasses.\n *\n * @param error - The error to check.\n * @returns True if the error is an HttpError, false otherwise.\n */\nexport function isHttpError(error: unknown): error is ErrorResponse {\n  return error instanceof ErrorResponse;\n}\n\n/**\n * Creates an HTTP error with the specified status code and message.\n * Factory function for creating appropriate HTTP error instances.\n *\n * @param status - HTTP status code.\n * @param message - Optional custom error message.\n * @returns An instance of the appropriate HTTP error class.\n */\nexport function createHttpError(status: number, message?: string): ErrorResponse {\n  switch (status) {\n    case HttpStatusCodes.BAD_REQUEST:\n      return new BadRequestException(message);\n    case HttpStatusCodes.UNAUTHORIZED:\n      return new UnauthorizedException(message);\n    case HttpStatusCodes.FORBIDDEN:\n      return new ForbiddenException(message);\n    case HttpStatusCodes.NOT_FOUND:\n      return new NotFoundException(message);\n    case HttpStatusCodes.METHOD_NOT_ALLOWED:\n      return new MethodNotAllowedException(message);\n    case HttpStatusCodes.NOT_ACCEPTABLE:\n      return new NotAcceptableException(message);\n    case HttpStatusCodes.REQUEST_TIMEOUT:\n      return new RequestTimeoutException(message);\n    case HttpStatusCodes.CONFLICT:\n      return new ConflictException(message);\n    case HttpStatusCodes.GONE:\n      return new HttpError(HttpStatusCodes.GONE, message || 'Gone');\n    case HttpStatusCodes.PAYLOAD_TOO_LARGE:\n      return new PayloadTooLargeException(message);\n    case HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE:\n      return new UnsupportedMediaTypeException(message);\n    case HttpStatusCodes.UNPROCESSABLE_ENTITY:\n      return new UnprocessableEntityException(message);\n    case HttpStatusCodes.TOO_MANY_REQUESTS:\n      return new TooManyRequestsException(message);\n    case HttpStatusCodes.INTERNAL_SERVER_ERROR:\n      return new InternalServerErrorException(message);\n    case HttpStatusCodes.BAD_GATEWAY:\n      return new BadGatewayException(message);\n    case HttpStatusCodes.SERVICE_UNAVAILABLE:\n      return new ServiceUnavailableException(message);\n    case HttpStatusCodes.GATEWAY_TIMEOUT:\n      return new GatewayTimeoutException(message);\n    case HttpStatusCodes.INSUFFICIENT_STORAGE:\n      return new InsufficientStorageException(message);\n    default:\n      return new HttpError(status, message || `HTTP Error ${status}`);\n  }\n}\n\n/**\n * Type guard to check if an object has specific error properties.\n *\n * @param error - The object to check.\n * @returns True if object has error-like structure.\n */\nexport function hasErrorShape(error: unknown): error is { message: string; status?: number; code?: string } {\n  return (\n    typeof error === 'object' && error !== null && 'message' in error && typeof (error as any).message === 'string'\n  );\n}\n\n/**\n * Safely extracts message from any error type.\n *\n * @param error - Any error object or value.\n * @returns A string error message.\n */\nexport function getErrorMessage(error: unknown): string {\n  if (typeof error === 'string') {\n    return error;\n  }\n\n  if (error instanceof Error) {\n    return error.message;\n  }\n\n  if (hasErrorShape(error)) {\n    return error.message;\n  }\n\n  return 'Unknown error occurred';\n}\n\n/**\n * Wraps a function and transforms any errors into HTTP errors.\n * Useful for API handlers to ensure consistent error responses.\n *\n * @param handler - The async function to wrap.\n * @returns A function that always returns or throws an HTTP error.\n */\nexport function withErrorHandling<T extends (...args: any[]) => Promise<any>>(\n  handler: T\n): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>> {\n  return async (...args: Parameters<T>) => {\n    try {\n      return await handler(...args);\n    } catch (err) {\n      if (isHttpError(err)) {\n        throw err;\n      }\n\n      // Log the original error (consider using a proper logger)\n      getLogger().error({ err }, 'Caught error in handler');\n\n      // Extract status code if it exists, otherwise use 500\n      let status = HttpStatusCodes.INTERNAL_SERVER_ERROR;\n      if (hasErrorShape(err) && typeof err.status === 'number') {\n        status = err.status;\n      }\n\n      // Create appropriate HTTP error\n      throw createHttpError(status, getErrorMessage(err));\n    }\n  };\n}\n"]}

package/build/esnext/utils/fs.utils.d.ts

@@ -1,164 +0,0 @@
-import { BufferEncoding } from './crypto.utils';
-import { Stats } from 'fs';
-/**
- * Checks whether a file or directory exists at the given path.
- *
- * @param {string} path - The file or directory path to check.
- * @returns {Promise<boolean>} Resolves to `true` if the path exists, `false` otherwise.
- */
-export declare function fileExists(path: string): Promise<boolean>;
-/**
- * Reads and parses a JSON file from the specified path.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<T | null>} The parsed object, or `null` if reading or parsing fails.
- */
-export declare function readJsonFile<T = any>(path: string): Promise<T | null>;
-/**
- * Writes a JavaScript object to a file as formatted JSON.
- *
- * @param {string} path - The destination file path.
- * @param {any} data - The object to serialize and write.
- * @param {number} [space=2] - Number of spaces for JSON formatting.
- * @returns {Promise<void>} Resolves when writing is complete.
- */
-export declare function writeJsonFile(path: string, data: any, space?: number): Promise<void>;
-/**
- * Deletes a file if it exists.
- *
- * @param {string} path - The file path to delete.
- * @returns {Promise<boolean>} Resolves to `true` if the file was deleted or didn't exist, `false` if deletion failed.
- */
-export declare function deleteFileIfExists(path: string): Promise<boolean>;
-/**
- * Reads a text file from the specified path.
- *
- * @param {string} path - The path to the text file.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<string | null>} The file contents, or `null` if reading fails.
- */
-export declare function readTextFile(path: string, encoding?: BufferEncoding): Promise<string | null>;
-/**
- * Writes text content to a file.
- *
- * @param {string} path - The destination file path.
- * @param {string} content - The text content to write.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function writeTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
-/**
- * Appends text content to a file.
- *
- * @param {string} path - The file path to append to.
- * @param {string} content - The text content to append.
- * @param {BufferEncoding} [encoding="utf-8"] - The encoding to use.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function appendTextFile(path: string, content: string, encoding?: BufferEncoding): Promise<boolean>;
-/**
- * Copies a file from source to destination.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @param {boolean} [overwrite=false] - Whether to overwrite if destination exists.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function copyFile(source: string, destination: string, overwrite?: boolean): Promise<boolean>;
-/**
- * Renames/moves a file.
- *
- * @param {string} oldPath - Current file path.
- * @param {string} newPath - New file path.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function moveFile(oldPath: string, newPath: string): Promise<boolean>;
-/**
- * Gets file stats if the file exists.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<fs.Stats | null>} File stats object or null if file doesn't exist.
- */
-export declare function getFileStats(path: string): Promise<Stats | null>;
-/**
- * Creates a temporary file with optional content.
- *
- * @param {object} [options] - Options for creating the temp file.
- * @param {string} [options.prefix="tmp-"] - Filename prefix.
- * @param {string} [options.extension=""] - File extension.
- * @param {string} [options.dir] - Directory to create the file in (defaults to OS temp dir).
- * @param {string | Buffer} [options.content] - Optional content to write to the file.
- * @returns {Promise<string>} Path to the created temporary file.
- */
-export declare function createTempFile({ prefix, extension, dir, content }?: {
-    prefix?: string;
-    extension?: string;
-    dir?: string;
-    content?: string | Buffer;
-}): Promise<string>;
-/**
- * Streams a file from source to destination.
- * Useful for large files to avoid loading the entire file into memory.
- *
- * @param {string} source - Source file path.
- * @param {string} destination - Destination file path.
- * @returns {Promise<void>} Resolves when streaming completes.
- * @throws {Error} If streaming fails.
- */
-export declare function streamFile(source: string, destination: string): Promise<void>;
-/**
- * Reads a directory and returns file names.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {object} [options] - Options for reading the directory.
- * @param {boolean} [options.fullPaths=false] - Whether to return full paths.
- * @param {RegExp} [options.filter] - Optional regex to filter files.
- * @returns {Promise<string[]>} Array of file names or paths.
- * @throws {Error} If directory cannot be read.
- */
-export declare function readDirectory(dirPath: string, options?: {
-    fullPaths?: boolean;
-    filter?: RegExp;
-}): Promise<string[]>;
-/**
- * Creates a directory if it doesn't exist.
- *
- * @param {string} dirPath - Path to the directory.
- * @param {boolean} [recursive=true] - Whether to create parent directories.
- * @returns {Promise<boolean>} Resolves to `true` if successful, `false` otherwise.
- */
-export declare function createDirectory(dirPath: string, recursive?: boolean): Promise<boolean>;
-/**
- * Safely reads and parses a JSON file with error details.
- *
- * @typeParam T - The expected type of the parsed JSON object.
- * @param {string} path - The path to the JSON file.
- * @returns {Promise<{ data: T | null; error: Error | null }>} Object with data and error properties.
- */
-export declare function safeReadJsonFile<T = any>(path: string): Promise<{
-    data: T | null;
-    error: Error | null;
-}>;
-/**
- * Checks if a path points to a file (not a directory).
- *
- * @param {string} path - Path to check.
- * @returns {Promise<boolean>} True if the path is a file, false otherwise.
- */
-export declare function isFile(path: string): Promise<boolean>;
-/**
- * Gets the size of a file in bytes.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<number>} Size in bytes or -1 if file doesn't exist.
- */
-export declare function getFileSize(path: string): Promise<number>;
-/**
- * Reads a file as a Buffer.
- *
- * @param {string} path - Path to the file.
- * @returns {Promise<Buffer | null>} File contents as Buffer or null if reading fails.
- */
-export declare function readFileBuffer(path: string): Promise<Buffer | null>;
-//# sourceMappingURL=fs.utils.d.ts.map