@catbee/utils 0.0.1 → 0.0.3

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

@@ -1,4 +1,6 @@
 /* eslint-disable n/no-process-env */
+import { existsSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
 /**
  * Enum representing valid application environments.
  */
@@ -20,7 +22,31 @@ export class Env {
      * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
      */
     static isDev() {
-        return (Env.get("NODE_ENV", Environment.DEVELOPMENT) === Environment.DEVELOPMENT);
+        return Env.get('NODE_ENV', Environment.DEVELOPMENT) === Environment.DEVELOPMENT;
+    }
+    /**
+     * Checks if the current NODE_ENV is 'production'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'production', else `false`.
+     */
+    static isProd() {
+        return Env.get('NODE_ENV') === Environment.PRODUCTION;
+    }
+    /**
+     * Checks if the current NODE_ENV is 'testing'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'testing', else `false`.
+     */
+    static isTest() {
+        return Env.get('NODE_ENV') === Environment.TESTING;
+    }
+    /**
+     * Checks if the current NODE_ENV is 'staging'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'staging', else `false`.
+     */
+    static isStaging() {
+        return Env.get('NODE_ENV') === Environment.STAGING;
     }
     /**
      * Sets an environment variable (only affects runtime memory).
@@ -111,9 +137,9 @@ export class Env {
     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))
+        if (['true', '1', 'yes', 'on'].includes(value))
             return true;
-        if (["false", "0", "no", "off"].includes(value))
+        if (['false', '0', 'no', 'off'].includes(value))
             return false;
         throw new Error(`Env variable ${key} is not a boolean`);
     }
@@ -161,15 +187,15 @@ export class Env {
      * @param {string} [splitter=','] - Delimiter to split on.
      * @returns {string[] | T[]} An array of strings.
      */
-    static getArray(key, defaultValue = [], splitter = ",") {
+    static getArray(key, defaultValue = [], splitter = ',') {
         const value = process.env[key];
-        if (!value || value.trim() === "") {
+        if (!value || value.trim() === '') {
             return defaultValue;
         }
         return value
             .split(splitter)
-            .map((item) => item.trim())
-            .filter((item) => item.length > 0);
+            .map(item => item.trim())
+            .filter(item => item.length > 0);
     }
     /**
      * Retrieves an enum-like environment variable value, validating against allowed values.
@@ -185,10 +211,167 @@ export class Env {
         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}`);
+            throw new Error(`Env ${key} must be one of ${allowedValues.join(', ')}. Received: ${value}`);
+        }
+        return value;
+    }
+    /**
+     * Retrieves a URL environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Optional fallback value.
+     * @param {object} [options] - Validation options.
+     * @param {string[]} [options.protocols] - Allowed protocols.
+     * @param {boolean} [options.requireTld=true] - Whether TLD is required.
+     * @returns {string} The validated URL.
+     * @throws {Error} If URL is invalid.
+     */
+    static getUrl(key, defaultValue, options = {}) {
+        const value = Env.get(key, defaultValue);
+        if (!value) {
+            throw new Error(`Env ${key} is missing or empty`);
+        }
+        let url;
+        try {
+            url = new URL(value);
+        }
+        catch (_a) {
+            throw new Error(`Env ${key} is not a valid URL`);
+        }
+        if (options.protocols && options.protocols.length > 0) {
+            const protocol = url.protocol.replace(':', '');
+            if (!options.protocols.includes(protocol)) {
+                throw new Error(`Env ${key} must use one of the protocols: ${options.protocols.join(', ')}`);
+            }
+        }
+        if (options.requireTld === true) {
+            // Check if hostname has a TLD (contains at least one dot and doesn't end with a dot)
+            // localhost, 127.0.0.1, etc. don't have TLDs
+            const hostname = url.hostname;
+            if (!hostname.includes('.') ||
+                hostname === 'localhost' ||
+                /^[\d.]+$/.test(hostname) || // IP address
+                hostname.endsWith('.')) {
+                throw new Error(`Env ${key} must have a valid host with TLD`);
+            }
+        }
+        return value;
+    }
+    /**
+     * Retrieves an email environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Optional fallback value.
+     * @returns {string} The validated email address.
+     * @throws {Error} If email is invalid.
+     */
+    static getEmail(key, defaultValue) {
+        const value = Env.get(key, defaultValue);
+        if (!value) {
+            if (defaultValue === undefined) {
+                throw new Error(`Email env ${key} is missing`);
+            }
+            return defaultValue;
+        }
+        // Simple email validation regex
+        const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+        if (!emailRegex.test(value)) {
+            throw new Error(`Env ${key} is not a valid email address`);
         }
         return value;
     }
+    /**
+     * Retrieves a path environment variable and validates it exists.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Optional fallback value.
+     * @param {object} [options] - Validation options.
+     * @param {boolean} [options.mustExist=false] - Whether path must exist.
+     * @param {boolean} [options.makeAbsolute=true] - Convert relative paths to absolute.
+     * @returns {string} The validated path.
+     * @throws {Error} If path is invalid.
+     */
+    static getPath(key, defaultValue, options = {}) {
+        const value = Env.get(key, defaultValue);
+        if (!value) {
+            if (defaultValue === undefined) {
+                throw new Error(`Path env ${key} is missing`);
+            }
+            return defaultValue;
+        }
+        const path = options.makeAbsolute !== false && !isAbsolute(value) ? resolve(process.cwd(), value) : value;
+        if (options.mustExist && !existsSync(path)) {
+            throw new Error(`Path in env ${key} does not exist: ${path}`);
+        }
+        return path;
+    }
+    /**
+     * Retrieves a port environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} [defaultValue=3000] - Optional fallback value.
+     * @returns {number} The validated port number.
+     * @throws {Error} If port is invalid.
+     */
+    static getPort(key, defaultValue = 3000) {
+        const port = Env.getNumber(key, defaultValue);
+        if (port < 0 || port > 65535) {
+            throw new Error(`Env ${key} must be a valid port number (0-65535)`);
+        }
+        return port;
+    }
+    /**
+     * Retrieves a duration string and converts to milliseconds.
+     * Supports formats like "1d", "2h", "30m", "45s", "100ms" or combinations like "1h30m".
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string|number} [defaultValue='0'] - Optional fallback value.
+     * @returns {number} The duration in milliseconds.
+     * @throws {Error} If duration format is invalid.
+     */
+    static getDuration(key, defaultValue = '0') {
+        const value = Env.get(key, String(defaultValue));
+        if (!value)
+            return 0;
+        // Handle plain number input (assume milliseconds)
+        if (/^\d+$/.test(value)) {
+            return parseInt(value, 10);
+        }
+        // Parse duration string like "1d2h30m15s"
+        const durationRegex = /(\d+d)?(\d+h)?(\d+m)?(\d+s)?(\d+ms)?/;
+        const matches = value.match(durationRegex);
+        if (!matches || matches[0] === '') {
+            throw new Error(`Env ${key} has invalid duration format. Use 1d, 2h, 30m, 45s, or 100ms.`);
+        }
+        let ms = 0;
+        if (matches[1])
+            ms += parseInt(matches[1], 10) * 86400000; // days
+        if (matches[2])
+            ms += parseInt(matches[2], 10) * 3600000; // hours
+        if (matches[3])
+            ms += parseInt(matches[3], 10) * 60000; // minutes
+        if (matches[4])
+            ms += parseInt(matches[4], 10) * 1000; // seconds
+        if (matches[5])
+            ms += parseInt(matches[5], 10); // milliseconds
+        return ms;
+    }
+    /**
+     * Gets all environment variables with sensitive values masked for safe logging.
+     *
+     * @param {string[]} [sensitiveKeys=['password', 'secret', 'key', 'token', 'auth']] - Keys to mask.
+     * @returns {Record<string, string>} Environment variables with sensitive values masked.
+     */
+    static getSafeEnv(sensitiveKeys = ['password', 'secret', 'key', 'token', 'auth']) {
+        const safeEnv = {};
+        for (const [key, value] of Object.entries(process.env)) {
+            if (!value)
+                continue;
+            const isSensitive = sensitiveKeys.some(sensitiveKey => key.toLowerCase().includes(sensitiveKey.toLowerCase()));
+            safeEnv[key] = isSensitive ? '******' : value;
+        }
+        return safeEnv;
+    }
     /**
      * Checks whether the specified environment variable exists.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"env.utils.js","sourceRoot":"","sources":["../../../src/utils/env.utils.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC;;GAEG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,0CAA2B,CAAA;IAC3B,kCAAmB,CAAA;IACnB,kCAAmB,CAAA;AACrB,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;;GAGG;AACH,MAAM,OAAO,GAAG;IACd;;;;OAIG;IACH,MAAM,CAAC,KAAK;QACV,OAAO,CACL,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,WAAW,CAAC,KAAK,WAAW,CAAC,WAAW,CACzE,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QACnC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,OAAO,CAAC,GAAG,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,CAAC,GAAW,EAAE,YAAqB;;QAC3C,OAAO,MAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,YAAY,CAAC;IAC1C,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CAAC,GAAW;QAC5B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,aAAa,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,GAAW,EAAE,YAAoB;;QAChD,MAAM,KAAK,GAAG,MAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,YAAY,CAAC;QAC/C,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,OAAO,GAAG,kBAAkB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,iBAAiB,CAAC,GAAW;QAClC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,aAAa,CAAC,CAAC;QACpD,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,kBAAkB,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,UAAU,CAAC,GAAW,EAAE,YAAY,GAAG,KAAK;;QACjD,MAAM,KAAK,GAAG,CAAC,MAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC;QAC1E,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAC5D,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,mBAAmB,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CAAC,GAAW;QACnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,aAAa,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,cAAc;IAC7C,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,CAA4B,GAAW,EAAE,YAAe;QACpE,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC;YAAC,WAAM,CAAC;gBACP,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,6BAA6B,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QACD,OAAO,YAAY,CAAC;IACtB,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CACb,GAAW,EACX,eAAoB,EAAE,EACtB,QAAQ,GAAG,GAAG;QAEd,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YAClC,OAAO,YAAY,CAAC;QACtB,CAAC;QACD,OAAO,KAAK;aACT,KAAK,CAAC,QAAQ,CAAC;aACf,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,OAAO,CACZ,GAAW,EACX,aAAkB,EAClB,YAAgB;;QAEhB,MAAM,KAAK,GAAG,MAAA,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,mCAAI,YAAY,CAAC;QAC/C,IAAI,CAAC,KAAK,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAU,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CACb,OAAO,GAAG,mBAAmB,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,KAAK,EAAE,CAC5E,CAAC;QACJ,CAAC;QACD,OAAO,KAAU,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,GAAG,CAAC,GAAW;QACpB,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACxC,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAM,CAAC,GAAW;QACvB,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF","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"]}
+{"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 */\nimport { existsSync } from 'fs';\nimport { isAbsolute, resolve } from 'path';\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 Env.get('NODE_ENV', Environment.DEVELOPMENT) === Environment.DEVELOPMENT;\n  }\n\n  /**\n   * Checks if the current NODE_ENV is 'production'.\n   *\n   * @returns {boolean} `true` if NODE_ENV is 'production', else `false`.\n   */\n  static isProd(): boolean {\n    return Env.get('NODE_ENV') === Environment.PRODUCTION;\n  }\n\n  /**\n   * Checks if the current NODE_ENV is 'testing'.\n   *\n   * @returns {boolean} `true` if NODE_ENV is 'testing', else `false`.\n   */\n  static isTest(): boolean {\n    return Env.get('NODE_ENV') === Environment.TESTING;\n  }\n\n  /**\n   * Checks if the current NODE_ENV is 'staging'.\n   *\n   * @returns {boolean} `true` if NODE_ENV is 'staging', else `false`.\n   */\n  static isStaging(): boolean {\n    return Env.get('NODE_ENV') === Environment.STAGING;\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>(key: string, defaultValue: T[] = [], splitter = ','): 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>(key: string, allowedValues: T[], defaultValue?: T): T {\n    const value = process.env[key] ?? defaultValue;\n    if (!value || !allowedValues.includes(value as T)) {\n      throw new Error(`Env ${key} must be one of ${allowedValues.join(', ')}. Received: ${value}`);\n    }\n    return value as T;\n  }\n\n  /**\n   * Retrieves a URL environment variable and validates it.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string} [defaultValue] - Optional fallback value.\n   * @param {object} [options] - Validation options.\n   * @param {string[]} [options.protocols] - Allowed protocols.\n   * @param {boolean} [options.requireTld=true] - Whether TLD is required.\n   * @returns {string} The validated URL.\n   * @throws {Error} If URL is invalid.\n   */\n  static getUrl(\n    key: string,\n    defaultValue?: string,\n    options: { protocols?: string[]; requireTld?: boolean } = {}\n  ): string {\n    const value = Env.get(key, defaultValue);\n    if (!value) {\n      throw new Error(`Env ${key} is missing or empty`);\n    }\n\n    let url: URL;\n    try {\n      url = new URL(value);\n    } catch {\n      throw new Error(`Env ${key} is not a valid URL`);\n    }\n\n    if (options.protocols && options.protocols.length > 0) {\n      const protocol = url.protocol.replace(':', '');\n      if (!options.protocols.includes(protocol)) {\n        throw new Error(`Env ${key} must use one of the protocols: ${options.protocols.join(', ')}`);\n      }\n    }\n\n    if (options.requireTld === true) {\n      // Check if hostname has a TLD (contains at least one dot and doesn't end with a dot)\n      // localhost, 127.0.0.1, etc. don't have TLDs\n      const hostname = url.hostname;\n      if (\n        !hostname.includes('.') ||\n        hostname === 'localhost' ||\n        /^[\\d.]+$/.test(hostname) || // IP address\n        hostname.endsWith('.')\n      ) {\n        throw new Error(`Env ${key} must have a valid host with TLD`);\n      }\n    }\n\n    return value;\n  }\n\n  /**\n   * Retrieves an email environment variable and validates it.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string} [defaultValue] - Optional fallback value.\n   * @returns {string} The validated email address.\n   * @throws {Error} If email is invalid.\n   */\n  static getEmail(key: string, defaultValue?: string): string {\n    const value = Env.get(key, defaultValue);\n\n    if (!value) {\n      if (defaultValue === undefined) {\n        throw new Error(`Email env ${key} is missing`);\n      }\n      return defaultValue;\n    }\n\n    // Simple email validation regex\n    const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/;\n    if (!emailRegex.test(value)) {\n      throw new Error(`Env ${key} is not a valid email address`);\n    }\n\n    return value;\n  }\n\n  /**\n   * Retrieves a path environment variable and validates it exists.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string} [defaultValue] - Optional fallback value.\n   * @param {object} [options] - Validation options.\n   * @param {boolean} [options.mustExist=false] - Whether path must exist.\n   * @param {boolean} [options.makeAbsolute=true] - Convert relative paths to absolute.\n   * @returns {string} The validated path.\n   * @throws {Error} If path is invalid.\n   */\n  static getPath(\n    key: string,\n    defaultValue?: string,\n    options: { mustExist?: boolean; makeAbsolute?: boolean } = {}\n  ): string {\n    const value = Env.get(key, defaultValue);\n\n    if (!value) {\n      if (defaultValue === undefined) {\n        throw new Error(`Path env ${key} is missing`);\n      }\n      return defaultValue;\n    }\n\n    const path = options.makeAbsolute !== false && !isAbsolute(value) ? resolve(process.cwd(), value) : value;\n\n    if (options.mustExist && !existsSync(path)) {\n      throw new Error(`Path in env ${key} does not exist: ${path}`);\n    }\n\n    return path;\n  }\n\n  /**\n   * Retrieves a port environment variable and validates it.\n   *\n   * @param {string} key - The environment variable key.\n   * @param {number} [defaultValue=3000] - Optional fallback value.\n   * @returns {number} The validated port number.\n   * @throws {Error} If port is invalid.\n   */\n  static getPort(key: string, defaultValue: number = 3000): number {\n    const port = Env.getNumber(key, defaultValue);\n\n    if (port < 0 || port > 65535) {\n      throw new Error(`Env ${key} must be a valid port number (0-65535)`);\n    }\n\n    return port;\n  }\n\n  /**\n   * Retrieves a duration string and converts to milliseconds.\n   * Supports formats like \"1d\", \"2h\", \"30m\", \"45s\", \"100ms\" or combinations like \"1h30m\".\n   *\n   * @param {string} key - The environment variable key.\n   * @param {string|number} [defaultValue='0'] - Optional fallback value.\n   * @returns {number} The duration in milliseconds.\n   * @throws {Error} If duration format is invalid.\n   */\n  static getDuration(key: string, defaultValue: string | number = '0'): number {\n    const value = Env.get(key, String(defaultValue));\n\n    if (!value) return 0;\n\n    // Handle plain number input (assume milliseconds)\n    if (/^\\d+$/.test(value)) {\n      return parseInt(value, 10);\n    }\n\n    // Parse duration string like \"1d2h30m15s\"\n    const durationRegex = /(\\d+d)?(\\d+h)?(\\d+m)?(\\d+s)?(\\d+ms)?/;\n    const matches = value.match(durationRegex);\n\n    if (!matches || matches[0] === '') {\n      throw new Error(`Env ${key} has invalid duration format. Use 1d, 2h, 30m, 45s, or 100ms.`);\n    }\n\n    let ms = 0;\n\n    if (matches[1]) ms += parseInt(matches[1], 10) * 86400000; // days\n    if (matches[2]) ms += parseInt(matches[2], 10) * 3600000; // hours\n    if (matches[3]) ms += parseInt(matches[3], 10) * 60000; // minutes\n    if (matches[4]) ms += parseInt(matches[4], 10) * 1000; // seconds\n    if (matches[5]) ms += parseInt(matches[5], 10); // milliseconds\n\n    return ms;\n  }\n\n  /**\n   * Gets all environment variables with sensitive values masked for safe logging.\n   *\n   * @param {string[]} [sensitiveKeys=['password', 'secret', 'key', 'token', 'auth']] - Keys to mask.\n   * @returns {Record<string, string>} Environment variables with sensitive values masked.\n   */\n  static getSafeEnv(sensitiveKeys: string[] = ['password', 'secret', 'key', 'token', 'auth']): Record<string, string> {\n    const safeEnv: Record<string, string> = {};\n\n    for (const [key, value] of Object.entries(process.env)) {\n      if (!value) continue;\n\n      const isSensitive = sensitiveKeys.some(sensitiveKey => key.toLowerCase().includes(sensitiveKey.toLowerCase()));\n\n      safeEnv[key] = isSensitive ? '******' : value;\n    }\n\n    return safeEnv;\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

@@ -1,4 +1,4 @@
-import { ErrorResponse } from "./response.utils";
+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.
@@ -111,4 +111,120 @@ export declare class GatewayTimeoutException extends ErrorResponse {
      */
     constructor(message?: string);
 }
+/**
+ * Represents a 422 Unprocessable Entity Error.
+ * Used when the server understands the content type but cannot process the contained instructions.
+ */
+export declare class UnprocessableEntityException extends ErrorResponse {
+    details?: Record<string, any> | undefined;
+    /**
+     * @param message - Optional custom message. Defaults to "Unprocessable Entity".
+     * @param details - Optional validation details or additional error context.
+     */
+    constructor(message?: string, details?: Record<string, any> | undefined);
+}
+/**
+ * Represents a 405 Method Not Allowed Error.
+ * Used when the request method is not supported for the requested resource.
+ */
+export declare class MethodNotAllowedException extends ErrorResponse {
+    allowedMethods?: string[] | undefined;
+    /**
+     * @param message - Optional custom message. Defaults to "Method Not Allowed".
+     * @param allowedMethods - Optional array of allowed HTTP methods.
+     */
+    constructor(message?: string, allowedMethods?: string[] | undefined);
+}
+/**
+ * Represents a 406 Not Acceptable Error.
+ * Used when the server cannot produce a response matching the client's accepted content types.
+ */
+export declare class NotAcceptableException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Not Acceptable".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 408 Request Timeout Error.
+ * Used when the server times out waiting for the client to send a request.
+ */
+export declare class RequestTimeoutException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Request Timeout".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 415 Unsupported Media Type Error.
+ * Used when the request's Content-Type is not supported.
+ */
+export declare class UnsupportedMediaTypeException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Unsupported Media Type".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 413 Payload Too Large Error.
+ * Used when the request body exceeds server limits.
+ */
+export declare class PayloadTooLargeException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Payload Too Large".
+     */
+    constructor(message?: string);
+}
+/**
+ * Represents a 507 Insufficient Storage Error.
+ * Used when the server has insufficient storage to complete the request.
+ */
+export declare class InsufficientStorageException extends ErrorResponse {
+    /**
+     * @param message - Optional custom message. Defaults to "Insufficient Storage".
+     */
+    constructor(message?: string);
+}
+/**
+ * Checks if an error is an instance of HttpError or its subclasses.
+ *
+ * @param error - The error to check.
+ * @returns True if the error is an HttpError, false otherwise.
+ */
+export declare function isHttpError(error: unknown): error is ErrorResponse;
+/**
+ * Creates an HTTP error with the specified status code and message.
+ * Factory function for creating appropriate HTTP error instances.
+ *
+ * @param status - HTTP status code.
+ * @param message - Optional custom error message.
+ * @returns An instance of the appropriate HTTP error class.
+ */
+export declare function createHttpError(status: number, message?: string): ErrorResponse;
+/**
+ * Type guard to check if an object has specific error properties.
+ *
+ * @param error - The object to check.
+ * @returns True if object has error-like structure.
+ */
+export declare function hasErrorShape(error: unknown): error is {
+    message: string;
+    status?: number;
+    code?: string;
+};
+/**
+ * Safely extracts message from any error type.
+ *
+ * @param error - Any error object or value.
+ * @returns A string error message.
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Wraps a function and transforms any errors into HTTP errors.
+ * Useful for API handlers to ensure consistent error responses.
+ *
+ * @param handler - The async function to wrap.
+ * @returns A function that always returns or throws an HTTP error.
+ */
+export declare function withErrorHandling<T extends (...args: any[]) => Promise<any>>(handler: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 //# sourceMappingURL=exception.utils.d.ts.map