@catbee/utils 0.0.1

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

@@ -0,0 +1,131 @@
+/**
+ * Enum representing valid application environments.
+ */
+export declare enum Environment {
+    PRODUCTION = "production",
+    DEVELOPMENT = "development",
+    STAGING = "staging",
+    TESTING = "testing"
+}
+/**
+ * Utility class for accessing and managing environment variables.
+ * Provides typed getters with fallback defaults and validation.
+ */
+export declare class Env {
+    /**
+     * Checks if the current NODE_ENV is 'development'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
+     */
+    static isDev(): boolean;
+    /**
+     * Sets an environment variable (only affects runtime memory).
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} value - The value to set.
+     */
+    static set(key: string, value: string): void;
+    /**
+     * Returns all environment variables as an object.
+     *
+     * @returns {object} The current `process.env` object.
+     */
+    static getAll(): object;
+    /**
+     * 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.
+     */
+    static get(key: string, defaultValue?: string): string | undefined;
+    /**
+     * 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.
+     */
+    static getRequired(key: string): string;
+    /**
+     * 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.
+     */
+    static getNumber(key: string, defaultValue: number): number;
+    /**
+     * 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.
+     */
+    static getNumberRequired(key: string): number;
+    /**
+     * 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.
+     */
+    static getBoolean(key: string, defaultValue?: boolean): 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.
+     */
+    static getBooleanRequired(key: string): boolean;
+    /**
+     * 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.
+     */
+    static getJSON<T extends object = object>(key: string, defaultValue: T): T;
+    /**
+     * 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.
+     */
+    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string): string[] | T[];
+    /**
+     * 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.
+     */
+    static getEnum<T extends string>(key: string, allowedValues: T[], defaultValue?: T): T;
+    /**
+     * Checks whether the specified environment variable exists.
+     *
+     * @param {string} key - The environment variable key.
+     * @returns {boolean} `true` if the variable is defined, otherwise `false`.
+     */
+    static has(key: string): boolean;
+    /**
+     * Deletes the given environment variable (useful in tests).
+     *
+     * @param {string} key - The environment variable key to delete.
+     * @returns {void}
+     */
+    static delete(key: string): void;
+}
+//# sourceMappingURL=env.utils.d.ts.map

package/build/esnext/utils/env.utils.js

@@ -0,0 +1,211 @@
+/* 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.
+ */
+export class Env {
+    /**
+     * Checks if the current NODE_ENV is 'development'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
+     */
+    static isDev() {
+        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.
+     */
+    static set(key, value) {
+        process.env[key] = value;
+    }
+    /**
+     * Returns all environment variables as an object.
+     *
+     * @returns {object} The current `process.env` object.
+     */
+    static getAll() {
+        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.
+     */
+    static get(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.
+     */
+    static getRequired(key) {
+        const value = process.env[key];
+        if (value === undefined) {
+            throw new Error(`Required env ${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.
+     */
+    static getNumber(key, defaultValue) {
+        var _a;
+        const value = (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        const numberValue = Number(value);
+        if (isNaN(numberValue)) {
+            throw new Error(`Env ${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.
+     */
+    static getNumberRequired(key) {
+        const value = process.env[key];
+        if (value === undefined) {
+            throw new Error(`Required env ${key} is missing`);
+        }
+        const numberValue = Number(value);
+        if (isNaN(numberValue)) {
+            throw new Error(`Required env ${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.
+     */
+    static getBoolean(key, defaultValue = false) {
+        var _a;
+        const 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 ${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.
+     */
+    static getBooleanRequired(key) {
+        const value = process.env[key];
+        if (value === undefined) {
+            throw new Error(`Required env ${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.
+     */
+    static getJSON(key, defaultValue) {
+        const v = process.env[key];
+        if (v !== undefined) {
+            try {
+                return JSON.parse(v);
+            }
+            catch (_a) {
+                throw new Error(`Env variable ${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.
+     */
+    static getArray(key, defaultValue = [], splitter = ",") {
+        const value = process.env[key];
+        if (!value || value.trim() === "") {
+            return defaultValue;
+        }
+        return value
+            .split(splitter)
+            .map((item) => item.trim())
+            .filter((item) => 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.
+     */
+    static getEnum(key, allowedValues, defaultValue) {
+        var _a;
+        const value = (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        if (!value || !allowedValues.includes(value)) {
+            throw new Error(`Env ${key} must be one of ${allowedValues.join(", ")}. Received: ${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`.
+     */
+    static has(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}
+     */
+    static delete(key) {
+        delete process.env[key];
+    }
+}
+//# sourceMappingURL=env.utils.js.map

package/build/esnext/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/esnext/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/esnext/utils/exception.utils.js

@@ -0,0 +1,148 @@
+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.
+ */
+export class HttpError extends ErrorResponse {
+    /**
+     * Creates a new HTTP error instance.
+     * @param status - A valid HTTP status code (e.g., 400, 500).
+     * @param message - The error message to return to the client.
+     */
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Represents a 500 Internal Server Error.
+ * Use this for unexpected backend errors that are not caused by the client.
+ */
+export class InternalServerErrorException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Internal server error".
+     */
+    constructor(message = "Internal server error") {
+        super(message);
+        this.status = HttpStatusCodes.INTERNAL_SERVER_ERROR;
+    }
+}
+/**
+ * Represents a 401 Unauthorized Error.
+ * Indicates that authentication is required and has failed or not been provided.
+ */
+export class UnauthorizedException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Unauthorized".
+     */
+    constructor(message = "Unauthorized") {
+        super(message);
+        this.status = HttpStatusCodes.UNAUTHORIZED;
+    }
+}
+/**
+ * Represents a 400 Bad Request Error.
+ * Indicates that the client has sent invalid data (e.g., malformed request body).
+ */
+export class BadRequestException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad request".
+     */
+    constructor(message = "Bad request") {
+        super(message);
+        this.status = HttpStatusCodes.BAD_REQUEST;
+    }
+}
+/**
+ * Represents a 404 Not Found Error.
+ * Used when a requested resource (e.g., user, file) could not be located.
+ */
+export class NotFoundException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Resource not found".
+     */
+    constructor(message = "Resource not found") {
+        super(message);
+        this.status = HttpStatusCodes.NOT_FOUND;
+    }
+}
+/**
+ * Represents a 403 Forbidden Error.
+ * Indicates that the client is authenticated but not allowed to access the resource.
+ */
+export class ForbiddenException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Forbidden".
+     */
+    constructor(message = "Forbidden") {
+        super(message);
+        this.status = HttpStatusCodes.FORBIDDEN;
+    }
+}
+/**
+ * Represents a 409 Conflict Error.
+ * Commonly used when a resource already exists or a versioning conflict occurs.
+ */
+export class ConflictException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Conflict".
+     */
+    constructor(message = "Conflict") {
+        super(message);
+        this.status = HttpStatusCodes.CONFLICT;
+    }
+}
+/**
+ * Represents a 502 Bad Gateway Error.
+ * Used when the server receives an invalid response from an upstream server.
+ */
+export class BadGatewayException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Bad Gateway".
+     */
+    constructor(message = "Bad Gateway") {
+        super(message);
+        this.status = HttpStatusCodes.BAD_GATEWAY;
+    }
+}
+/**
+ * Represents a 429 Too Many Requests Error.
+ * Returned when the client has hit a rate limit.
+ */
+export class TooManyRequestsException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Too many requests".
+     */
+    constructor(message = "Too many requests") {
+        super(message);
+        this.status = HttpStatusCodes.TOO_MANY_REQUESTS;
+    }
+}
+/**
+ * Represents a 503 Service Unavailable Error.
+ * Indicates that the server is temporarily unavailable (e.g., for maintenance).
+ */
+export class ServiceUnavailableException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Service Unavailable".
+     */
+    constructor(message = "Service Unavailable") {
+        super(message);
+        this.status = HttpStatusCodes.SERVICE_UNAVAILABLE;
+    }
+}
+/**
+ * Represents a 504 Gateway Timeout Error.
+ * Returned when the server acting as a gateway times out waiting for a response.
+ */
+export class GatewayTimeoutException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Gateway Timeout".
+     */
+    constructor(message = "Gateway Timeout") {
+        super(message);
+        this.status = HttpStatusCodes.GATEWAY_TIMEOUT;
+    }
+}
+//# sourceMappingURL=exception.utils.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exception.utils.js","sourceRoot":"","sources":["../../../src/utils/exception.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;GAGG;AACH,MAAM,OAAO,SAAU,SAAQ,aAAa;IAC1C;;;;OAIG;IACH,YAAY,MAAc,EAAE,OAAe;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,4BAA6B,SAAQ,aAAa;IAC7D;;OAEG;IACH,YAAY,UAAkB,uBAAuB;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,qBAAqB,CAAC;IACtD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,qBAAsB,SAAQ,aAAa;IACtD;;OAEG;IACH,YAAY,UAAkB,cAAc;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,YAAY,CAAC;IAC7C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD;;OAEG;IACH,YAAY,UAAkB,aAAa;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD;;OAEG;IACH,YAAY,UAAkB,oBAAoB;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC;IAC1C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,aAAa;IACnD;;OAEG;IACH,YAAY,UAAkB,WAAW;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,SAAS,CAAC;IAC1C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,aAAa;IAClD;;OAEG;IACH,YAAY,UAAkB,UAAU;QACtC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC;IACzC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,aAAa;IACpD;;OAEG;IACH,YAAY,UAAkB,aAAa;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,WAAW,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,aAAa;IACzD;;OAEG;IACH,YAAY,UAAkB,mBAAmB;QAC/C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,iBAAiB,CAAC;IAClD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,aAAa;IAC5D;;OAEG;IACH,YAAY,UAAkB,qBAAqB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,mBAAmB,CAAC;IACpD,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,uBAAwB,SAAQ,aAAa;IACxD;;OAEG;IACH,YAAY,UAAkB,iBAAiB;QAC7C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,eAAe,CAAC,eAAe,CAAC;IAChD,CAAC;CACF","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/esnext/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