@catbee/utils 0.0.1

package/build/esm/utils/env.utils.js

@@ -0,0 +1,218 @@
+/* eslint-disable n/no-process-env */
+/**
+ * Enum representing valid application environments.
+ */
+export var Environment;
+(function (Environment) {
+    Environment["PRODUCTION"] = "production";
+    Environment["DEVELOPMENT"] = "development";
+    Environment["STAGING"] = "staging";
+    Environment["TESTING"] = "testing";
+})(Environment || (Environment = {}));
+/**
+ * Utility class for accessing and managing environment variables.
+ * Provides typed getters with fallback defaults and validation.
+ */
+var Env = /** @class */ (function () {
+    function Env() {
+    }
+    /**
+     * Checks if the current NODE_ENV is 'development'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
+     */
+    Env.isDev = function () {
+        return (Env.get("NODE_ENV", Environment.DEVELOPMENT) === Environment.DEVELOPMENT);
+    };
+    /**
+     * Sets an environment variable (only affects runtime memory).
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} value - The value to set.
+     */
+    Env.set = function (key, value) {
+        process.env[key] = value;
+    };
+    /**
+     * Returns all environment variables as an object.
+     *
+     * @returns {object} The current `process.env` object.
+     */
+    Env.getAll = function () {
+        return process.env;
+    };
+    /**
+     * Retrieves a string environment variable with a fallback default.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Value to return if the key is missing.
+     * @returns {string | undefined} The env value or the fallback.
+     */
+    Env.get = function (key, defaultValue) {
+        var _a;
+        return (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+    };
+    /**
+     * Retrieves a string environment variable and throws if it's missing.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {string} The environment variable's value.
+     * @throws {Error} If the variable is not defined.
+     */
+    Env.getRequired = function (key) {
+        var value = process.env[key];
+        if (value === undefined) {
+            throw new Error("Required env ".concat(key, " is missing"));
+        }
+        return value;
+    };
+    /**
+     * Retrieves an environment variable as a number, or returns a default.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} defaultValue - Fallback number if key is not present.
+     * @returns {number} Parsed numeric value or default.
+     * @throws {Error} If the value is not a valid number.
+     */
+    Env.getNumber = function (key, defaultValue) {
+        var _a;
+        var value = (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        var numberValue = Number(value);
+        if (isNaN(numberValue)) {
+            throw new Error("Env ".concat(key, " is not a number"));
+        }
+        return numberValue;
+    };
+    /**
+     * Retrieves a required environment variable as a number.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {number} Parsed number.
+     * @throws {Error} If the value is missing or not a number.
+     */
+    Env.getNumberRequired = function (key) {
+        var value = process.env[key];
+        if (value === undefined) {
+            throw new Error("Required env ".concat(key, " is missing"));
+        }
+        var numberValue = Number(value);
+        if (isNaN(numberValue)) {
+            throw new Error("Required env ".concat(key, " is not a number"));
+        }
+        return numberValue;
+    };
+    /**
+     * Retrieves an environment variable as a boolean.
+     * Accepts `true`, `1`, `yes`, `on` as true; `false`, `0`, `no`, `off` as false.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {boolean} [defaultValue=false] - Optional fallback value if key is missing.
+     * @returns {boolean} Parsed boolean.
+     * @throws {Error} If the value is not a recognized boolean string.
+     */
+    Env.getBoolean = function (key, defaultValue) {
+        var _a;
+        if (defaultValue === void 0) { defaultValue = false; }
+        var value = ((_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue).toString().toLowerCase();
+        if (["true", "1", "yes", "on"].includes(value))
+            return true;
+        if (["false", "0", "no", "off"].includes(value))
+            return false;
+        throw new Error("Env variable ".concat(key, " is not a boolean"));
+    };
+    /**
+     * Retrieves a required environment variable as a boolean.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {boolean} Parsed boolean value.
+     * @throws {Error} If missing or invalid.
+     */
+    Env.getBooleanRequired = function (key) {
+        var value = process.env[key];
+        if (value === undefined) {
+            throw new Error("Required env ".concat(key, " is missing"));
+        }
+        return this.getBoolean(key); // reuse logic
+    };
+    /**
+     * Parses a stringified JSON object from an environment variable.
+     *
+     * @typeParam T - The type to parse as (defaults to `object`).
+     * @param {string} key - The environment variable key.
+     * @param {T} defaultValue - Value to return if key is missing.
+     * @returns {T} Parsed object or default.
+     * @throws {Error} If the value is not valid JSON.
+     */
+    Env.getJSON = function (key, defaultValue) {
+        var v = process.env[key];
+        if (v !== undefined) {
+            try {
+                return JSON.parse(v);
+            }
+            catch (_a) {
+                throw new Error("Env variable ".concat(key, " is not a valid JSON string"));
+            }
+        }
+        return defaultValue;
+    };
+    /**
+     * Parses a comma-separated string as an array.
+     *
+     * @typeParam T - The item type (optional, defaults to string).
+     * @param {string} key - The environment variable key.
+     * @param {T[]} [defaultValue=[]] - Array to return if value is empty or missing.
+     * @param {string} [splitter=','] - Delimiter to split on.
+     * @returns {string[] | T[]} An array of strings.
+     */
+    Env.getArray = function (key, defaultValue, splitter) {
+        if (defaultValue === void 0) { defaultValue = []; }
+        if (splitter === void 0) { splitter = ","; }
+        var value = process.env[key];
+        if (!value || value.trim() === "") {
+            return defaultValue;
+        }
+        return value
+            .split(splitter)
+            .map(function (item) { return item.trim(); })
+            .filter(function (item) { return item.length > 0; });
+    };
+    /**
+     * Retrieves an enum-like environment variable value, validating against allowed values.
+     *
+     * @typeParam T - The allowed value type (string literal types).
+     * @param {string} key - The environment variable key.
+     * @param {T[]} allowedValues - Array of accepted string values.
+     * @param {T} [defaultValue] - Optional fallback value.
+     * @returns {T} The validated environment value.
+     * @throws {Error} If missing or invalid.
+     */
+    Env.getEnum = function (key, allowedValues, defaultValue) {
+        var _a;
+        var value = (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        if (!value || !allowedValues.includes(value)) {
+            throw new Error("Env ".concat(key, " must be one of ").concat(allowedValues.join(", "), ". Received: ").concat(value));
+        }
+        return value;
+    };
+    /**
+     * Checks whether the specified environment variable exists.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {boolean} `true` if the variable is defined, otherwise `false`.
+     */
+    Env.has = function (key) {
+        return process.env[key] !== undefined;
+    };
+    /**
+     * Deletes the given environment variable (useful in tests).
+     *
+     * @param {string} key - The environment variable key to delete.
+     * @returns {void}
+     */
+    Env.delete = function (key) {
+        delete process.env[key];
+    };
+    return Env;
+}());
+export { Env };
+//# sourceMappingURL=env.utils.js.map

package/build/esm/utils/env.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.utils.js","sourceRoot":"","sources":["../../../src/utils/env.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/* eslint-disable n/no-process-env */\n\n/**\n * Enum representing valid application environments.\n */\nexport enum Environment {\n  PRODUCTION = \"production\",\n  DEVELOPMENT = \"development\",\n  STAGING = \"staging\",\n  TESTING = \"testing\",\n}\n\n/**\n * Utility class for accessing and managing environment variables.\n * Provides typed getters with fallback defaults and validation.\n */\nexport class Env {\n  /**\n   * Checks if the current NODE_ENV is 'development'.\n   *\n   * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.\n   */\n  static isDev(): boolean {\n    return (\n      Env.get(\"NODE_ENV\", Environment.DEVELOPMENT) === Environment.DEVELOPMENT\n    );\n  }\n\n  /**\n   * Sets an environment variable (only affects runtime memory).\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string} value - The value to set.\n   */\n  static set(key: string, value: string): void {\n    process.env[key] = value;\n  }\n\n  /**\n   * Returns all environment variables as an object.\n   *\n   * @returns {object} The current `process.env` object.\n   */\n  static getAll(): object {\n    return process.env;\n  }\n\n  /**\n   * Retrieves a string environment variable with a fallback default.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string} [defaultValue] - Value to return if the key is missing.\n   * @returns {string | undefined} The env value or the fallback.\n   */\n  static get(key: string, defaultValue?: string): string | undefined {\n    return process.env[key] ?? defaultValue;\n  }\n\n  /**\n   * Retrieves a string environment variable and throws if it's missing.\n   *\n   * @param {string} key - The environment variable key.\n   * @returns {string} The environment variable's value.\n   * @throws {Error} If the variable is not defined.\n   */\n  static getRequired(key: string): string {\n    const value = process.env[key];\n    if (value === undefined) {\n      throw new Error(`Required env ${key} is missing`);\n    }\n    return value;\n  }\n\n  /**\n   * Retrieves an environment variable as a number, or returns a default.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {number} defaultValue - Fallback number if key is not present.\n   * @returns {number} Parsed numeric value or default.\n   * @throws {Error} If the value is not a valid number.\n   */\n  static getNumber(key: string, defaultValue: number): number {\n    const value = process.env[key] ?? defaultValue;\n    const numberValue = Number(value);\n    if (isNaN(numberValue)) {\n      throw new Error(`Env ${key} is not a number`);\n    }\n    return numberValue;\n  }\n\n  /**\n   * Retrieves a required environment variable as a number.\n   *\n   * @param {string} key - The environment variable key.\n   * @returns {number} Parsed number.\n   * @throws {Error} If the value is missing or not a number.\n   */\n  static getNumberRequired(key: string): number {\n    const value = process.env[key];\n    if (value === undefined) {\n      throw new Error(`Required env ${key} is missing`);\n    }\n    const numberValue = Number(value);\n    if (isNaN(numberValue)) {\n      throw new Error(`Required env ${key} is not a number`);\n    }\n    return numberValue;\n  }\n\n  /**\n   * Retrieves an environment variable as a boolean.\n   * Accepts `true`, `1`, `yes`, `on` as true; `false`, `0`, `no`, `off` as false.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {boolean} [defaultValue=false] - Optional fallback value if key is missing.\n   * @returns {boolean} Parsed boolean.\n   * @throws {Error} If the value is not a recognized boolean string.\n   */\n  static getBoolean(key: string, defaultValue = false): boolean {\n    const value = (process.env[key] ?? defaultValue).toString().toLowerCase();\n    if ([\"true\", \"1\", \"yes\", \"on\"].includes(value)) return true;\n    if ([\"false\", \"0\", \"no\", \"off\"].includes(value)) return false;\n    throw new Error(`Env variable ${key} is not a boolean`);\n  }\n\n  /**\n   * Retrieves a required environment variable as a boolean.\n   *\n   * @param {string} key - The environment variable key.\n   * @returns {boolean} Parsed boolean value.\n   * @throws {Error} If missing or invalid.\n   */\n  static getBooleanRequired(key: string): boolean {\n    const value = process.env[key];\n    if (value === undefined) {\n      throw new Error(`Required env ${key} is missing`);\n    }\n    return this.getBoolean(key); // reuse logic\n  }\n\n  /**\n   * Parses a stringified JSON object from an environment variable.\n   *\n   * @typeParam T - The type to parse as (defaults to `object`).\n   * @param {string} key - The environment variable key.\n   * @param {T} defaultValue - Value to return if key is missing.\n   * @returns {T} Parsed object or default.\n   * @throws {Error} If the value is not valid JSON.\n   */\n  static getJSON<T extends object = object>(key: string, defaultValue: T): T {\n    const v = process.env[key];\n    if (v !== undefined) {\n      try {\n        return JSON.parse(v);\n      } catch {\n        throw new Error(`Env variable ${key} is not a valid JSON string`);\n      }\n    }\n    return defaultValue;\n  }\n\n  /**\n   * Parses a comma-separated string as an array.\n   *\n   * @typeParam T - The item type (optional, defaults to string).\n   * @param {string} key - The environment variable key.\n   * @param {T[]} [defaultValue=[]] - Array to return if value is empty or missing.\n   * @param {string} [splitter=','] - Delimiter to split on.\n   * @returns {string[] | T[]} An array of strings.\n   */\n  static getArray<T = string>(\n    key: string,\n    defaultValue: T[] = [],\n    splitter = \",\",\n  ): string[] | T[] {\n    const value = process.env[key];\n    if (!value || value.trim() === \"\") {\n      return defaultValue;\n    }\n    return value\n      .split(splitter)\n      .map((item) => item.trim())\n      .filter((item) => item.length > 0);\n  }\n\n  /**\n   * Retrieves an enum-like environment variable value, validating against allowed values.\n   *\n   * @typeParam T - The allowed value type (string literal types).\n   * @param {string} key - The environment variable key.\n   * @param {T[]} allowedValues - Array of accepted string values.\n   * @param {T} [defaultValue] - Optional fallback value.\n   * @returns {T} The validated environment value.\n   * @throws {Error} If missing or invalid.\n   */\n  static getEnum<T extends string>(\n    key: string,\n    allowedValues: T[],\n    defaultValue?: T,\n  ): T {\n    const value = process.env[key] ?? defaultValue;\n    if (!value || !allowedValues.includes(value as T)) {\n      throw new Error(\n        `Env ${key} must be one of ${allowedValues.join(\", \")}. Received: ${value}`,\n      );\n    }\n    return value as T;\n  }\n\n  /**\n   * Checks whether the specified environment variable exists.\n   *\n   * @param {string} key - The environment variable key.\n   * @returns {boolean} `true` if the variable is defined, otherwise `false`.\n   */\n  static has(key: string): boolean {\n    return process.env[key] !== undefined;\n  }\n\n  /**\n   * Deletes the given environment variable (useful in tests).\n   *\n   * @param {string} key - The environment variable key to delete.\n   * @returns {void}\n   */\n  static delete(key: string): void {\n    delete process.env[key];\n  }\n}\n"]}

package/build/esm/utils/exception.utils.d.ts

@@ -0,0 +1,114 @@
+import { ErrorResponse } from "./response.utils";
+/**
+ * Generic HTTP error class used for custom exceptions with any status code.
+ * Inherit this when you need to throw errors dynamically at runtime.
+ */
+export declare class HttpError extends ErrorResponse {
+    /**
+     * Creates a new HTTP error instance.
+     * @param status - A valid HTTP status code (e.g., 400, 500).
+     * @param message - The error message to return to the client.
+     */
+    constructor(status: number, message: string);
+}
+/**
+ * Represents a 500 Internal Server Error.
+ * Use this for unexpected backend errors that are not caused by the client.
+ */
+export declare class InternalServerErrorException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Internal server error".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 401 Unauthorized Error.
+ * Indicates that authentication is required and has failed or not been provided.
+ */
+export declare class UnauthorizedException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Unauthorized".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 400 Bad Request Error.
+ * Indicates that the client has sent invalid data (e.g., malformed request body).
+ */
+export declare class BadRequestException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad request".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 404 Not Found Error.
+ * Used when a requested resource (e.g., user, file) could not be located.
+ */
+export declare class NotFoundException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Resource not found".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 403 Forbidden Error.
+ * Indicates that the client is authenticated but not allowed to access the resource.
+ */
+export declare class ForbiddenException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Forbidden".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 409 Conflict Error.
+ * Commonly used when a resource already exists or a versioning conflict occurs.
+ */
+export declare class ConflictException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Conflict".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 502 Bad Gateway Error.
+ * Used when the server receives an invalid response from an upstream server.
+ */
+export declare class BadGatewayException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad Gateway".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 429 Too Many Requests Error.
+ * Returned when the client has hit a rate limit.
+ */
+export declare class TooManyRequestsException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Too many requests".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 503 Service Unavailable Error.
+ * Indicates that the server is temporarily unavailable (e.g., for maintenance).
+ */
+export declare class ServiceUnavailableException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Service Unavailable".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 504 Gateway Timeout Error.
+ * Returned when the server acting as a gateway times out waiting for a response.
+ */
+export declare class GatewayTimeoutException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Gateway Timeout".
+     */
+    constructor(message?: string);
+}
+//# sourceMappingURL=exception.utils.d.ts.map

package/build/esm/utils/exception.utils.js

@@ -0,0 +1,217 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+import { HttpStatusCodes } from "./http-status-codes";
+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.
+ */
+var HttpError = /** @class */ (function (_super) {
+    __extends(HttpError, _super);
+    /**
+     * 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.
+     */
+    function HttpError(status, message) {
+        var _this = _super.call(this, message) || this;
+        _this.status = status;
+        return _this;
+    }
+    return HttpError;
+}(ErrorResponse));
+export { HttpError };
+/**
+ * Represents a 500 Internal Server Error.
+ * Use this for unexpected backend errors that are not caused by the client.
+ */
+var InternalServerErrorException = /** @class */ (function (_super) {
+    __extends(InternalServerErrorException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Internal server error".
+     */
+    function InternalServerErrorException(message) {
+        if (message === void 0) { message = "Internal server error"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
+        return _this;
+    }
+    return InternalServerErrorException;
+}(ErrorResponse));
+export { InternalServerErrorException };
+/**
+ * Represents a 401 Unauthorized Error.
+ * Indicates that authentication is required and has failed or not been provided.
+ */
+var UnauthorizedException = /** @class */ (function (_super) {
+    __extends(UnauthorizedException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Unauthorized".
+     */
+    function UnauthorizedException(message) {
+        if (message === void 0) { message = "Unauthorized"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.UNAUTHORIZED;
+        return _this;
+    }
+    return UnauthorizedException;
+}(ErrorResponse));
+export { UnauthorizedException };
+/**
+ * Represents a 400 Bad Request Error.
+ * Indicates that the client has sent invalid data (e.g., malformed request body).
+ */
+var BadRequestException = /** @class */ (function (_super) {
+    __extends(BadRequestException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Bad request".
+     */
+    function BadRequestException(message) {
+        if (message === void 0) { message = "Bad request"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.BAD_REQUEST;
+        return _this;
+    }
+    return BadRequestException;
+}(ErrorResponse));
+export { BadRequestException };
+/**
+ * Represents a 404 Not Found Error.
+ * Used when a requested resource (e.g., user, file) could not be located.
+ */
+var NotFoundException = /** @class */ (function (_super) {
+    __extends(NotFoundException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Resource not found".
+     */
+    function NotFoundException(message) {
+        if (message === void 0) { message = "Resource not found"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.NOT_FOUND;
+        return _this;
+    }
+    return NotFoundException;
+}(ErrorResponse));
+export { NotFoundException };
+/**
+ * Represents a 403 Forbidden Error.
+ * Indicates that the client is authenticated but not allowed to access the resource.
+ */
+var ForbiddenException = /** @class */ (function (_super) {
+    __extends(ForbiddenException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Forbidden".
+     */
+    function ForbiddenException(message) {
+        if (message === void 0) { message = "Forbidden"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.FORBIDDEN;
+        return _this;
+    }
+    return ForbiddenException;
+}(ErrorResponse));
+export { ForbiddenException };
+/**
+ * Represents a 409 Conflict Error.
+ * Commonly used when a resource already exists or a versioning conflict occurs.
+ */
+var ConflictException = /** @class */ (function (_super) {
+    __extends(ConflictException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Conflict".
+     */
+    function ConflictException(message) {
+        if (message === void 0) { message = "Conflict"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.CONFLICT;
+        return _this;
+    }
+    return ConflictException;
+}(ErrorResponse));
+export { ConflictException };
+/**
+ * Represents a 502 Bad Gateway Error.
+ * Used when the server receives an invalid response from an upstream server.
+ */
+var BadGatewayException = /** @class */ (function (_super) {
+    __extends(BadGatewayException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Bad Gateway".
+     */
+    function BadGatewayException(message) {
+        if (message === void 0) { message = "Bad Gateway"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.BAD_GATEWAY;
+        return _this;
+    }
+    return BadGatewayException;
+}(ErrorResponse));
+export { BadGatewayException };
+/**
+ * Represents a 429 Too Many Requests Error.
+ * Returned when the client has hit a rate limit.
+ */
+var TooManyRequestsException = /** @class */ (function (_super) {
+    __extends(TooManyRequestsException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Too many requests".
+     */
+    function TooManyRequestsException(message) {
+        if (message === void 0) { message = "Too many requests"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.TOO_MANY_REQUESTS;
+        return _this;
+    }
+    return TooManyRequestsException;
+}(ErrorResponse));
+export { TooManyRequestsException };
+/**
+ * Represents a 503 Service Unavailable Error.
+ * Indicates that the server is temporarily unavailable (e.g., for maintenance).
+ */
+var ServiceUnavailableException = /** @class */ (function (_super) {
+    __extends(ServiceUnavailableException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Service Unavailable".
+     */
+    function ServiceUnavailableException(message) {
+        if (message === void 0) { message = "Service Unavailable"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;
+        return _this;
+    }
+    return ServiceUnavailableException;
+}(ErrorResponse));
+export { ServiceUnavailableException };
+/**
+ * Represents a 504 Gateway Timeout Error.
+ * Returned when the server acting as a gateway times out waiting for a response.
+ */
+var GatewayTimeoutException = /** @class */ (function (_super) {
+    __extends(GatewayTimeoutException, _super);
+    /**
+     * @param message - Optional custom message. Defaults to "Gateway Timeout".
+     */
+    function GatewayTimeoutException(message) {
+        if (message === void 0) { message = "Gateway Timeout"; }
+        var _this = _super.call(this, message) || this;
+        _this.status = HttpStatusCodes.GATEWAY_TIMEOUT;
+        return _this;
+    }
+    return GatewayTimeoutException;
+}(ErrorResponse));
+export { GatewayTimeoutException };
+//# sourceMappingURL=exception.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exception.utils.js","sourceRoot":"","sources":["../../../src/utils/exception.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { HttpStatusCodes } from \"./http-status-codes\";\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"]}

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

@@ -0,0 +1,32 @@
+/**
+ * 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>;
+//# sourceMappingURL=fs.utils.d.ts.map