@catbee/utils 1.0.5 → 2.0.0-next.0

package/exception/index.mjs

@@ -0,0 +1,338 @@
+/*
+ * 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 { HttpStatusCodes } from '@catbee/utils/http-status-codes';
+import { getLogger } from '@catbee/utils/logger';
+import { ErrorResponse } from '@catbee/utils/response';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var HttpError = class extends ErrorResponse {
+  static {
+    __name(this, "HttpError");
+  }
+  /**
+  * 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;
+  }
+};
+var InternalServerErrorException = class extends ErrorResponse {
+  static {
+    __name(this, "InternalServerErrorException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Internal server error".
+  */
+  constructor(message = "Internal server error") {
+    super(message);
+    this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
+  }
+};
+var UnauthorizedException = class extends ErrorResponse {
+  static {
+    __name(this, "UnauthorizedException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Unauthorized".
+  */
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.status = HttpStatusCodes.UNAUTHORIZED;
+  }
+};
+var BadRequestException = class extends ErrorResponse {
+  static {
+    __name(this, "BadRequestException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Bad request".
+  */
+  constructor(message = "Bad request") {
+    super(message);
+    this.status = HttpStatusCodes.BAD_REQUEST;
+  }
+};
+var NotFoundException = class extends ErrorResponse {
+  static {
+    __name(this, "NotFoundException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Resource not found".
+  */
+  constructor(message = "Resource not found") {
+    super(message);
+    this.status = HttpStatusCodes.NOT_FOUND;
+  }
+};
+var ForbiddenException = class extends ErrorResponse {
+  static {
+    __name(this, "ForbiddenException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Forbidden".
+  */
+  constructor(message = "Forbidden") {
+    super(message);
+    this.status = HttpStatusCodes.FORBIDDEN;
+  }
+};
+var ConflictException = class extends ErrorResponse {
+  static {
+    __name(this, "ConflictException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Conflict".
+  */
+  constructor(message = "Conflict") {
+    super(message);
+    this.status = HttpStatusCodes.CONFLICT;
+  }
+};
+var BadGatewayException = class extends ErrorResponse {
+  static {
+    __name(this, "BadGatewayException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Bad Gateway".
+  */
+  constructor(message = "Bad Gateway") {
+    super(message);
+    this.status = HttpStatusCodes.BAD_GATEWAY;
+  }
+};
+var TooManyRequestsException = class extends ErrorResponse {
+  static {
+    __name(this, "TooManyRequestsException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Too many requests".
+  */
+  constructor(message = "Too many requests") {
+    super(message);
+    this.status = HttpStatusCodes.TOO_MANY_REQUESTS;
+  }
+};
+var ServiceUnavailableException = class extends ErrorResponse {
+  static {
+    __name(this, "ServiceUnavailableException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Service Unavailable".
+  */
+  constructor(message = "Service Unavailable") {
+    super(message);
+    this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;
+  }
+};
+var GatewayTimeoutException = class extends ErrorResponse {
+  static {
+    __name(this, "GatewayTimeoutException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Gateway Timeout".
+  */
+  constructor(message = "Gateway Timeout") {
+    super(message);
+    this.status = HttpStatusCodes.GATEWAY_TIMEOUT;
+  }
+};
+var UnprocessableEntityException = class extends ErrorResponse {
+  static {
+    __name(this, "UnprocessableEntityException");
+  }
+  details;
+  /**
+  * @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;
+  }
+};
+var MethodNotAllowedException = class extends ErrorResponse {
+  static {
+    __name(this, "MethodNotAllowedException");
+  }
+  allowedMethods;
+  /**
+  * @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;
+  }
+};
+var NotAcceptableException = class extends ErrorResponse {
+  static {
+    __name(this, "NotAcceptableException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Not Acceptable".
+  */
+  constructor(message = "Not Acceptable") {
+    super(message);
+    this.status = HttpStatusCodes.NOT_ACCEPTABLE;
+  }
+};
+var RequestTimeoutException = class extends ErrorResponse {
+  static {
+    __name(this, "RequestTimeoutException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Request Timeout".
+  */
+  constructor(message = "Request Timeout") {
+    super(message);
+    this.status = HttpStatusCodes.REQUEST_TIMEOUT;
+  }
+};
+var UnsupportedMediaTypeException = class extends ErrorResponse {
+  static {
+    __name(this, "UnsupportedMediaTypeException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Unsupported Media Type".
+  */
+  constructor(message = "Unsupported Media Type") {
+    super(message);
+    this.status = HttpStatusCodes.UNSUPPORTED_MEDIA_TYPE;
+  }
+};
+var PayloadTooLargeException = class extends ErrorResponse {
+  static {
+    __name(this, "PayloadTooLargeException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Payload Too Large".
+  */
+  constructor(message = "Payload Too Large") {
+    super(message);
+    this.status = HttpStatusCodes.PAYLOAD_TOO_LARGE;
+  }
+};
+var InsufficientStorageException = class extends ErrorResponse {
+  static {
+    __name(this, "InsufficientStorageException");
+  }
+  /**
+  * @param message - Optional custom message. Defaults to "Insufficient Storage".
+  */
+  constructor(message = "Insufficient Storage") {
+    super(message);
+    this.status = HttpStatusCodes.INSUFFICIENT_STORAGE;
+  }
+};
+function isHttpError(error) {
+  return error instanceof ErrorResponse;
+}
+__name(isHttpError, "isHttpError");
+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}`);
+  }
+}
+__name(createHttpError, "createHttpError");
+function hasErrorShape(error) {
+  return typeof error === "object" && error !== null && "message" in error && typeof error.message === "string";
+}
+__name(hasErrorShape, "hasErrorShape");
+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";
+}
+__name(getErrorMessage, "getErrorMessage");
+function withErrorHandling(handler) {
+  return async (...args) => {
+    try {
+      return await handler(...args);
+    } catch (err) {
+      if (isHttpError(err)) {
+        throw err;
+      }
+      getLogger().error({
+        err
+      }, "Caught error in handler");
+      let status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
+      if (hasErrorShape(err) && typeof err.status === "number") {
+        status = err.status;
+      }
+      throw createHttpError(status, getErrorMessage(err));
+    }
+  };
+}
+__name(withErrorHandling, "withErrorHandling");
+
+export { BadGatewayException, BadRequestException, ConflictException, ForbiddenException, GatewayTimeoutException, HttpError, InsufficientStorageException, InternalServerErrorException, MethodNotAllowedException, NotAcceptableException, NotFoundException, PayloadTooLargeException, RequestTimeoutException, ServiceUnavailableException, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, createHttpError, getErrorMessage, hasErrorShape, isHttpError, withErrorHandling };

package/fs/fs.utils.d.ts

@@ -0,0 +1,196 @@
+/*
+ * 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>;