@catbee/utils 2.0.0-next.0 → 2.0.0

package/exception/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -22,4 +22,235 @@
  * SOFTWARE.
  */
 
-export * from './exception.utils';
+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 };

package/exception/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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

package/fs/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/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
@@ -24,8 +24,8 @@
 
 'use strict';
 
-var fs$1 = require('fs');
-var fs = require('fs/promises');
+var fs = require('fs');
+var fsp = require('fs/promises');
 var os = require('os');
 var path = require('path');
 var promises = require('stream/promises');
@@ -34,13 +34,14 @@ var crypto = require('crypto');
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var fs__default = /*#__PURE__*/_interopDefault(fs);
+var fsp__default = /*#__PURE__*/_interopDefault(fsp);
 var path__default = /*#__PURE__*/_interopDefault(path);
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 async function fileExists(path2) {
   try {
-    await fs__default.default.access(path2);
+    await fsp__default.default.access(path2);
     return true;
   } catch {
     return false;
@@ -49,7 +50,7 @@ async function fileExists(path2) {
 __name(fileExists, "fileExists");
 async function readJsonFile(path2) {
   try {
-    const data = await fs__default.default.readFile(path2, "utf-8");
+    const data = await fsp__default.default.readFile(path2, "utf-8");
     return JSON.parse(data);
   } catch {
     return null;
@@ -63,12 +64,12 @@ async function readJsonOrDefault(path2, defaultValue) {
 __name(readJsonOrDefault, "readJsonOrDefault");
 async function writeJsonFile(path2, data, space = 2) {
   const json = JSON.stringify(data, null, space);
-  await fs__default.default.writeFile(path2, json, "utf-8");
+  await fsp__default.default.writeFile(path2, json, "utf-8");
 }
 __name(writeJsonFile, "writeJsonFile");
 async function deleteFileIfExists(path2) {
   try {
-    await fs__default.default.unlink(path2);
+    await fsp__default.default.unlink(path2);
     return true;
   } catch (err) {
     if (err.code === "ENOENT") return true;
@@ -76,36 +77,66 @@ async function deleteFileIfExists(path2) {
   }
 }
 __name(deleteFileIfExists, "deleteFileIfExists");
-async function readTextFile(path2, encoding = "utf-8") {
+async function readFile(path2, encoding = "utf-8") {
+  return await fsp__default.default.readFile(path2, encoding);
+}
+__name(readFile, "readFile");
+function readFileSync(path2, encoding = "utf-8") {
+  return fs__default.default.readFileSync(path2, encoding);
+}
+__name(readFileSync, "readFileSync");
+async function safeReadFile(path2, encoding = "utf-8") {
   try {
-    return await fs__default.default.readFile(path2, encoding);
-  } catch {
-    return null;
+    const data = await fsp__default.default.readFile(path2, encoding);
+    return {
+      data,
+      error: null
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: new Error(`Failed to read file ${path2}: ${error.message}`)
+    };
+  }
+}
+__name(safeReadFile, "safeReadFile");
+function safeReadFileSync(path2, encoding = "utf-8") {
+  try {
+    const data = fs__default.default.readFileSync(path2, encoding);
+    return {
+      data,
+      error: null
+    };
+  } catch (error) {
+    return {
+      data: null,
+      error: new Error(`Failed to read file ${path2}: ${error.message}`)
+    };
   }
 }
-__name(readTextFile, "readTextFile");
-async function writeTextFile(path2, content, encoding = "utf-8") {
+__name(safeReadFileSync, "safeReadFileSync");
+async function writeFile(path2, content, encoding = "utf-8") {
   try {
-    await fs__default.default.writeFile(path2, content, encoding);
+    await fsp__default.default.writeFile(path2, content, encoding);
     return true;
   } catch {
     return false;
   }
 }
-__name(writeTextFile, "writeTextFile");
-async function appendTextFile(path2, content, encoding = "utf-8") {
+__name(writeFile, "writeFile");
+async function appendFile(path2, content, encoding = "utf-8") {
   try {
-    await fs__default.default.appendFile(path2, content, encoding);
+    await fsp__default.default.appendFile(path2, content, encoding);
     return true;
   } catch {
     return false;
   }
 }
-__name(appendTextFile, "appendTextFile");
+__name(appendFile, "appendFile");
 async function copyFile(source, destination, overwrite = false) {
   try {
-    const flags = overwrite ? 0 : fs__default.default.constants.COPYFILE_EXCL;
-    await fs__default.default.copyFile(source, destination, flags);
+    const flags = overwrite ? 0 : fsp__default.default.constants.COPYFILE_EXCL;
+    await fsp__default.default.copyFile(source, destination, flags);
     return true;
   } catch {
     return false;
@@ -114,12 +145,12 @@ async function copyFile(source, destination, overwrite = false) {
 __name(copyFile, "copyFile");
 async function moveFile(oldPath, newPath) {
   try {
-    await fs__default.default.rename(oldPath, newPath);
+    await fsp__default.default.rename(oldPath, newPath);
     return true;
   } catch {
     try {
-      await fs__default.default.copyFile(oldPath, newPath);
-      await fs__default.default.unlink(oldPath);
+      await fsp__default.default.copyFile(oldPath, newPath);
+      await fsp__default.default.unlink(oldPath);
       return true;
     } catch {
       return false;
@@ -129,7 +160,7 @@ async function moveFile(oldPath, newPath) {
 __name(moveFile, "moveFile");
 async function getFileStats(path2) {
   try {
-    return await fs__default.default.stat(path2);
+    return await fsp__default.default.stat(path2);
   } catch {
     return null;
   }
@@ -140,16 +171,16 @@ async function createTempFile({ prefix = "tmp-", extension = "", dir = os.tmpdir
   const filename = `${prefix}${crypto.randomUUID()}${ext}`;
   const filepath = path__default.default.join(dir, filename);
   if (content) {
-    await fs__default.default.writeFile(filepath, content);
+    await fsp__default.default.writeFile(filepath, content);
   } else {
-    await fs__default.default.writeFile(filepath, "");
+    await fsp__default.default.writeFile(filepath, "");
   }
   return filepath;
 }
 __name(createTempFile, "createTempFile");
 async function streamFile(source, destination) {
-  const readStream = fs$1.createReadStream(source);
-  const writeStream = fs$1.createWriteStream(destination);
+  const readStream = fs__default.default.createReadStream(source);
+  const writeStream = fs__default.default.createWriteStream(destination);
   try {
     await promises.pipeline(readStream, writeStream);
   } catch (error) {
@@ -160,7 +191,7 @@ async function streamFile(source, destination) {
 }
 __name(streamFile, "streamFile");
 async function readDirectory(dirPath, options = {}) {
-  const files = await fs__default.default.readdir(dirPath);
+  const files = await fsp__default.default.readdir(dirPath);
   let result = files;
   if (options.filter) {
     result = result.filter((file) => options.filter.test(file));
@@ -173,7 +204,7 @@ async function readDirectory(dirPath, options = {}) {
 __name(readDirectory, "readDirectory");
 async function createDirectory(dirPath, recursive = true) {
   try {
-    await fs__default.default.mkdir(dirPath, {
+    await fsp__default.default.mkdir(dirPath, {
       recursive
     });
     return true;
@@ -184,7 +215,7 @@ async function createDirectory(dirPath, recursive = true) {
 __name(createDirectory, "createDirectory");
 async function safeReadJsonFile(path2) {
   try {
-    const content = await fs__default.default.readFile(path2, "utf-8");
+    const content = await fsp__default.default.readFile(path2, "utf-8");
     try {
       const data = JSON.parse(content);
       return {
@@ -207,7 +238,7 @@ async function safeReadJsonFile(path2) {
 __name(safeReadJsonFile, "safeReadJsonFile");
 async function isFile(path2) {
   try {
-    const stat = await fs__default.default.stat(path2);
+    const stat = await fsp__default.default.stat(path2);
     return stat.isFile();
   } catch {
     return false;
@@ -216,7 +247,7 @@ async function isFile(path2) {
 __name(isFile, "isFile");
 async function getFileSize(path2) {
   try {
-    const stat = await fs__default.default.stat(path2);
+    const stat = await fsp__default.default.stat(path2);
     return stat.size;
   } catch {
     return -1;
@@ -225,14 +256,14 @@ async function getFileSize(path2) {
 __name(getFileSize, "getFileSize");
 async function readFileBuffer(path2) {
   try {
-    return await fs__default.default.readFile(path2);
+    return await fsp__default.default.readFile(path2);
   } catch {
     return null;
   }
 }
 __name(readFileBuffer, "readFileBuffer");
 
-exports.appendTextFile = appendTextFile;
+exports.appendFile = appendFile;
 exports.copyFile = copyFile;
 exports.createDirectory = createDirectory;
 exports.createTempFile = createTempFile;
@@ -243,11 +274,14 @@ exports.getFileStats = getFileStats;
 exports.isFile = isFile;
 exports.moveFile = moveFile;
 exports.readDirectory = readDirectory;
+exports.readFile = readFile;
 exports.readFileBuffer = readFileBuffer;
+exports.readFileSync = readFileSync;
 exports.readJsonFile = readJsonFile;
 exports.readJsonOrDefault = readJsonOrDefault;
-exports.readTextFile = readTextFile;
+exports.safeReadFile = safeReadFile;
+exports.safeReadFileSync = safeReadFileSync;
 exports.safeReadJsonFile = safeReadJsonFile;
 exports.streamFile = streamFile;
+exports.writeFile = writeFile;
 exports.writeJsonFile = writeJsonFile;
-exports.writeTextFile = writeTextFile;