@catbee/utils 2.0.0-next.0 → 2.0.0-next.1

package/exception/exception.utils.d.ts

@@ -1,253 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 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.
- */
-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>>>;

package/fs/fs.utils.d.ts

@@ -1,196 +0,0 @@
-/*
- * The MIT License
- * 
- * Copyright (c) 2025 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 type { BufferEncoding } from '@catbee/utils/crypto';
-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>;
-/**
- * Read and parse JSON file or return a provided default value on error.
- *
- * @typeParam T
- * @param {string} path - Path to JSON file
- * @param {T} defaultValue - Default value to return when read/parse fails
- * @returns {Promise<T>} Parsed JSON or defaultValue
- */
-export declare function readJsonOrDefault<T = any>(path: string, defaultValue: T): Promise<T>;
-/**
- * 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>;