@catbee/utils 0.0.4 → 0.0.5

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

@@ -1,14 +1,3 @@
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !o };
-        }
-    };
-    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
-};
 var __read = (this && this.__read) || function (o, n) {
     var m = typeof Symbol === "function" && o[Symbol.iterator];
     if (!m) return o;
@@ -25,8 +14,28 @@ var __read = (this && this.__read) || function (o, n) {
     }
     return ar;
 };
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
 /* eslint-disable n/no-process-env */
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
 /**
  * Enum representing valid application environments.
@@ -59,7 +68,7 @@ var Env = /** @class */ (function () {
      * @returns {boolean} `true` if NODE_ENV is 'production', else `false`.
      */
     Env.isProd = function () {
-        return Env.get('NODE_ENV') === Environment.PRODUCTION;
+        return Env.get('NODE_ENV', Environment.DEVELOPMENT) === Environment.PRODUCTION;
     };
     /**
      * Checks if the current NODE_ENV is 'testing'.
@@ -67,7 +76,7 @@ var Env = /** @class */ (function () {
      * @returns {boolean} `true` if NODE_ENV is 'testing', else `false`.
      */
     Env.isTest = function () {
-        return Env.get('NODE_ENV') === Environment.TESTING;
+        return Env.get('NODE_ENV', Environment.DEVELOPMENT) === Environment.TESTING;
     };
     /**
      * Checks if the current NODE_ENV is 'staging'.
@@ -75,7 +84,7 @@ var Env = /** @class */ (function () {
      * @returns {boolean} `true` if NODE_ENV is 'staging', else `false`.
      */
     Env.isStaging = function () {
-        return Env.get('NODE_ENV') === Environment.STAGING;
+        return Env.get('NODE_ENV', Environment.DEVELOPMENT) === Environment.STAGING;
     };
     /**
      * Sets an environment variable (only affects runtime memory).
@@ -84,7 +93,25 @@ var Env = /** @class */ (function () {
      * @param {string} value - The value to set.
      */
     Env.set = function (key, value) {
+        var e_1, _a;
         process.env[key] = value;
+        // Clear all cached values for this key with any prefix
+        this.cache.delete(key);
+        try {
+            for (var _b = __values(__spreadArray([], __read(this.cache.keys()), false)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var cacheKey = _c.value;
+                if (cacheKey.includes(":".concat(key))) {
+                    this.cache.delete(cacheKey);
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
     };
     /**
      * Returns all environment variables as an object.
@@ -96,14 +123,28 @@ var Env = /** @class */ (function () {
     };
     /**
      * Retrieves a string environment variable with a fallback default.
+     * Supports variable expansion with ${VAR_NAME} syntax.
      *
      * @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.
+     * @returns {string} The env value or the fallback.
+     *
+     * @example
+     * // If DATABASE_URL is "postgres://localhost:5432/${DB_NAME}"
+     * // and DB_NAME is "myapp"
+     * const url = Env.get('DATABASE_URL', ''); // "postgres://localhost:5432/myapp"
      */
     Env.get = function (key, defaultValue) {
         var _a;
-        return (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        var value = (_a = process.env[key]) !== null && _a !== void 0 ? _a : defaultValue;
+        // Expand ${VAR} references
+        if (value && value.includes('${')) {
+            value = value.replace(/\${([A-Za-z0-9_]+)}/g, function (_, varName) {
+                var _a;
+                return (_a = process.env[varName]) !== null && _a !== void 0 ? _a : '';
+            });
+        }
+        return value;
     };
     /**
      * Retrieves a string environment variable and throws if it's missing.
@@ -115,9 +156,29 @@ var Env = /** @class */ (function () {
     Env.getRequired = function (key) {
         var value = process.env[key];
         if (value === undefined) {
-            throw new Error("Required env ".concat(key, " is missing"));
+            throw new Error("Required environment variable '".concat(key, "' is missing"));
         }
-        return value;
+        return Env.get(key, ''); // Use get to handle variable expansion
+    };
+    /**
+     * Retrieves a value using a default generating function if the key doesn't exist.
+     * Useful for expensive default calculations.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {() => string} defaultFn - Function that generates default value.
+     * @returns {string} The environment value or generated default.
+     *
+     * @example
+     * const hostname = Env.getWithDefault('HOSTNAME', () => {
+     *   // Only called if HOSTNAME is not set
+     *   return require('os').hostname();
+     * });
+     */
+    Env.getWithDefault = function (key, defaultFn) {
+        if (Env.has(key)) {
+            return Env.get(key, '');
+        }
+        return defaultFn();
     };
     /**
      * Retrieves an environment variable as a number, or returns a default.
@@ -128,12 +189,18 @@ var Env = /** @class */ (function () {
      * @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;
+        if (this.cache.has("number:".concat(key))) {
+            return this.cache.get("number:".concat(key));
+        }
+        var value = process.env[key];
+        if (value === undefined) {
+            return defaultValue;
+        }
         var numberValue = Number(value);
         if (isNaN(numberValue)) {
-            throw new Error("Env ".concat(key, " is not a number"));
+            throw new Error("Environment variable '".concat(key, "' is not a valid number, got: \"").concat(value, "\""));
         }
+        this.cache.set("number:".concat(key), numberValue);
         return numberValue;
     };
     /**
@@ -146,13 +213,38 @@ var Env = /** @class */ (function () {
     Env.getNumberRequired = function (key) {
         var value = process.env[key];
         if (value === undefined) {
-            throw new Error("Required env ".concat(key, " is missing"));
+            throw new Error("Required environment variable '".concat(key, "' is missing"));
         }
-        var numberValue = Number(value);
-        if (isNaN(numberValue)) {
-            throw new Error("Required env ".concat(key, " is not a number"));
+        return Env.getNumber(key, 0); // The default is ignored since we know the key exists
+    };
+    /**
+     * Retrieves an integer environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} defaultValue - Fallback number if key is not present.
+     * @param {object} [options] - Validation options.
+     * @param {number} [options.min] - Minimum allowed value.
+     * @param {number} [options.max] - Maximum allowed value.
+     * @returns {number} The parsed integer.
+     *
+     * @example
+     * // Require PORT to be between 1000 and 9999
+     * const port = Env.getInteger('PORT', 3000, { min: 1000, max: 9999 });
+     */
+    Env.getInteger = function (key, defaultValue, options) {
+        if (options === void 0) { options = {}; }
+        var num = Env.getNumber(key, defaultValue);
+        var intValue = Math.floor(num);
+        if (intValue !== num) {
+            throw new Error("Environment variable '".concat(key, "' must be an integer, got: ").concat(num));
         }
-        return numberValue;
+        if (options.min !== undefined && intValue < options.min) {
+            throw new Error("Environment variable '".concat(key, "' must be at least ").concat(options.min, ", got: ").concat(intValue));
+        }
+        if (options.max !== undefined && intValue > options.max) {
+            throw new Error("Environment variable '".concat(key, "' must be at most ").concat(options.max, ", got: ").concat(intValue));
+        }
+        return intValue;
     };
     /**
      * Retrieves an environment variable as a boolean.
@@ -162,16 +254,30 @@ var Env = /** @class */ (function () {
      * @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.
+     *
+     * @example
+     * // If DEBUG=yes
+     * const isDebug = Env.getBoolean('DEBUG', false); // true
      */
     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))
+        if (this.cache.has("bool:".concat(key))) {
+            return this.cache.get("bool:".concat(key));
+        }
+        var value = process.env[key];
+        if (value === undefined) {
+            return defaultValue;
+        }
+        var lowerValue = value.toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(lowerValue)) {
+            this.cache.set("bool:".concat(key), true);
             return true;
-        if (['false', '0', 'no', 'off'].includes(value))
+        }
+        if (['false', '0', 'no', 'off'].includes(lowerValue)) {
+            this.cache.set("bool:".concat(key), false);
             return false;
-        throw new Error("Env variable ".concat(key, " is not a boolean"));
+        }
+        throw new Error("Environment variable '".concat(key, "' is not a valid boolean, got: \"").concat(value, "\". Use true/false, yes/no, 1/0, or on/off."));
     };
     /**
      * Retrieves a required environment variable as a boolean.
@@ -183,9 +289,9 @@ var Env = /** @class */ (function () {
     Env.getBooleanRequired = function (key) {
         var value = process.env[key];
         if (value === undefined) {
-            throw new Error("Required env ".concat(key, " is missing"));
+            throw new Error("Required environment variable '".concat(key, "' is missing"));
         }
-        return this.getBoolean(key); // reuse logic
+        return Env.getBoolean(key);
     };
     /**
      * Parses a stringified JSON object from an environment variable.
@@ -195,18 +301,28 @@ var Env = /** @class */ (function () {
      * @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.
+     *
+     * @example
+     * // If CONFIG='{"debug":true,"api":{"url":"https://api.example.com"}}'
+     * const config = Env.getJSON('CONFIG', { debug: false });
+     * // { debug: true, api: { url: "https://api.example.com" }}
      */
     Env.getJSON = function (key, defaultValue) {
+        if (this.cache.has("json:".concat(key))) {
+            return this.cache.get("json:".concat(key));
+        }
         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"));
-            }
+        if (v === undefined) {
+            return defaultValue;
+        }
+        try {
+            var parsed = JSON.parse(v);
+            this.cache.set("json:".concat(key), parsed);
+            return parsed;
+        }
+        catch (error) {
+            throw new Error("Environment variable '".concat(key, "' is not valid JSON: ").concat(error.message));
         }
-        return defaultValue;
     };
     /**
      * Parses a comma-separated string as an array.
@@ -215,19 +331,69 @@ var Env = /** @class */ (function () {
      * @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.
+     * @param {(item: string) => T} [transform] - Optional function to transform each item.
+     * @returns {T[]} An array of items.
+     *
+     * @example
+     * // If ALLOWED_IPS=127.0.0.1,192.168.1.1,10.0.0.1
+     * const ips = Env.getArray('ALLOWED_IPS');
+     * // ["127.0.0.1", "192.168.1.1", "10.0.0.1"]
+     *
+     * // With transformation function
+     * const ports = Env.getArray('PORTS', [], ',', (p) => parseInt(p, 10));
      */
-    Env.getArray = function (key, defaultValue, splitter) {
+    Env.getArray = function (key, defaultValue, splitter, transform) {
         if (defaultValue === void 0) { defaultValue = []; }
         if (splitter === void 0) { splitter = ','; }
+        var cacheKey = "array:".concat(key, ":").concat(splitter, ":").concat(transform ? 'transformed' : 'raw');
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
         var value = process.env[key];
         if (!value || value.trim() === '') {
             return defaultValue;
         }
-        return value
+        var items = value
             .split(splitter)
             .map(function (item) { return item.trim(); })
             .filter(function (item) { return item.length > 0; });
+        if (transform) {
+            try {
+                var result_1 = items.map(transform);
+                this.cache.set(cacheKey, result_1);
+                return result_1;
+            }
+            catch (error) {
+                throw new Error("Failed to transform items in '".concat(key, "': ").concat(error.message));
+            }
+        }
+        var result = items;
+        this.cache.set(cacheKey, result);
+        return result;
+    };
+    /**
+     * Parses a comma-separated list of numbers.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number[]} [defaultValue=[]] - Default value if not present.
+     * @param {string} [splitter=','] - Delimiter to split on.
+     * @returns {number[]} Array of parsed numbers.
+     *
+     * @example
+     * // If ALLOWED_PORTS=80,443,3000,8080
+     * const ports = Env.getNumberArray('ALLOWED_PORTS');
+     * // [80, 443, 3000, 8080]
+     */
+    Env.getNumberArray = function (key, defaultValue, splitter) {
+        if (defaultValue === void 0) { defaultValue = []; }
+        if (splitter === void 0) { splitter = ','; }
+        return Env.getArray(key, defaultValue, splitter, function (item) {
+            var num = Number(item);
+            if (isNaN(num)) {
+                throw new Error("Value \"".concat(item, "\" in array '").concat(key, "' is not a valid number"));
+            }
+            return num;
+        });
     };
     /**
      * Retrieves an enum-like environment variable value, validating against allowed values.
@@ -238,12 +404,38 @@ var Env = /** @class */ (function () {
      * @param {T} [defaultValue] - Optional fallback value.
      * @returns {T} The validated environment value.
      * @throws {Error} If missing or invalid.
+     *
+     * @example
+     * // If LOG_LEVEL=debug
+     * const level = Env.getEnum('LOG_LEVEL', ['debug', 'info', 'warn', 'error'] as const, 'info');
+     * // 'debug' (typed as 'debug' | 'info' | 'warn' | 'error')
      */
     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));
+        var value = process.env[key];
+        if (!value) {
+            return defaultValue;
+        }
+        if (!allowedValues.includes(value)) {
+            throw new Error("Environment variable '".concat(key, "' must be one of: ").concat(allowedValues.join(', '), ". Received: \"").concat(value, "\""));
+        }
+        return value;
+    };
+    /**
+     * Retrieves an enum-like numeric environment variable.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number[]} allowedValues - Array of accepted values.
+     * @param {number} defaultValue - Default value if not present.
+     * @returns {number} The validated value.
+     *
+     * @example
+     * // If NODE_VERSION=16
+     * const version = Env.getNumberEnum('NODE_VERSION', [14, 16, 18], 16);
+     */
+    Env.getNumberEnum = function (key, allowedValues, defaultValue) {
+        var value = Env.getNumber(key, defaultValue);
+        if (!allowedValues.includes(value)) {
+            throw new Error("Environment variable '".concat(key, "' must be one of: ").concat(allowedValues.join(', '), ". Received: ").concat(value));
         }
         return value;
     };
@@ -252,42 +444,67 @@ var Env = /** @class */ (function () {
      *
      * @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.
+     * @param {UrlOptions} [options] - Validation options.
      * @returns {string} The validated URL.
      * @throws {Error} If URL is invalid.
+     *
+     * @example
+     * // Validate API URL requires HTTPS
+     * const apiUrl = Env.getUrl('API_URL', 'https://api.example.com', {
+     *   protocols: ['https'],
+     *   requireTld: true,
+     *   allowIp: false
+     * });
      */
     Env.getUrl = function (key, defaultValue, options) {
         if (options === void 0) { options = {}; }
+        var cacheKey = "url:".concat(key, ":").concat(JSON.stringify(options));
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
         var value = Env.get(key, defaultValue);
         if (!value) {
-            throw new Error("Env ".concat(key, " is missing or empty"));
+            throw new Error("URL environment variable '".concat(key, "' is missing or empty"));
         }
         var url;
         try {
             url = new URL(value);
         }
         catch (_a) {
-            throw new Error("Env ".concat(key, " is not a valid URL"));
+            throw new Error("Environment variable '".concat(key, "' is not a valid URL: \"").concat(value, "\""));
         }
+        // Validate protocol
         if (options.protocols && options.protocols.length > 0) {
             var protocol = url.protocol.replace(':', '');
             if (!options.protocols.includes(protocol)) {
-                throw new Error("Env ".concat(key, " must use one of the protocols: ").concat(options.protocols.join(', ')));
+                throw new Error("Environment variable '".concat(key, "' must use one of the protocols: ").concat(options.protocols.join(', '), ". Got: ").concat(protocol));
             }
         }
+        // Validate hostname
+        var hostname = url.hostname;
+        var isIp = /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(hostname);
+        var isLocalhost = hostname === 'localhost';
+        // Check if hostname is an IP address when not allowed
+        if (isIp && options.allowIp === false) {
+            throw new Error("Environment variable '".concat(key, "' cannot be an IP address: \"").concat(hostname, "\""));
+        }
+        // Check if hostname is localhost when not allowed
+        if (isLocalhost && options.allowLocalhost === false) {
+            throw new Error("Environment variable '".concat(key, "' cannot be localhost"));
+        }
+        // Check for TLD requirement - include localhost in check if requireTld is true and allowLocalhost is false
         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
-            var hostname = url.hostname;
-            if (!hostname.includes('.') ||
-                hostname === 'localhost' ||
-                /^[\d.]+$/.test(hostname) || // IP address
-                hostname.endsWith('.')) {
-                throw new Error("Env ".concat(key, " must have a valid host with TLD"));
+            if (isLocalhost && options.allowLocalhost !== false) {
+                // Localhost is allowed, so no TLD check needed for it
+            }
+            else if (isIp && options.allowIp !== false) {
+                // IP is allowed, so no TLD check needed for it
+            }
+            else if (!hostname.includes('.') || hostname.endsWith('.')) {
+                throw new Error("Environment variable '".concat(key, "' must have a valid host with TLD: \"").concat(hostname, "\""));
             }
         }
+        this.cache.set(cacheKey, value);
         return value;
     };
     /**
@@ -297,20 +514,27 @@ var Env = /** @class */ (function () {
      * @param {string} [defaultValue] - Optional fallback value.
      * @returns {string} The validated email address.
      * @throws {Error} If email is invalid.
+     *
+     * @example
+     * const supportEmail = Env.getEmail('SUPPORT_EMAIL', 'support@example.com');
      */
     Env.getEmail = function (key, defaultValue) {
+        if (this.cache.has("email:".concat(key))) {
+            return this.cache.get("email:".concat(key));
+        }
         var value = Env.get(key, defaultValue);
         if (!value) {
             if (defaultValue === undefined) {
-                throw new Error("Email env ".concat(key, " is missing"));
+                throw new Error("Email environment variable '".concat(key, "' is missing"));
             }
             return defaultValue;
         }
-        // Simple email validation regex
-        var emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+        // More comprehensive email validation regex
+        var emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
         if (!emailRegex.test(value)) {
-            throw new Error("Env ".concat(key, " is not a valid email address"));
+            throw new Error("Environment variable '".concat(key, "' is not a valid email address: \"").concat(value, "\""));
         }
+        this.cache.set("email:".concat(key), value);
         return value;
     };
     /**
@@ -318,78 +542,143 @@ var Env = /** @class */ (function () {
      *
      * @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.
+     * @param {PathOptions} [options] - Validation options.
      * @returns {string} The validated path.
      * @throws {Error} If path is invalid.
+     *
+     * @example
+     * // Require that the path exists and is a .json file
+     * const configPath = Env.getPath('CONFIG_PATH', './config.json', {
+     *   mustExist: true,
+     *   allowedExtensions: ['.json', '.yaml']
+     * });
      */
     Env.getPath = function (key, defaultValue, options) {
         if (options === void 0) { options = {}; }
+        var cacheKey = "path:".concat(key, ":").concat(JSON.stringify(options));
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
         var value = Env.get(key, defaultValue);
         if (!value) {
             if (defaultValue === undefined) {
-                throw new Error("Path env ".concat(key, " is missing"));
+                throw new Error("Path environment variable '".concat(key, "' is missing"));
             }
             return defaultValue;
         }
         var path = options.makeAbsolute !== false && !isAbsolute(value) ? resolve(process.cwd(), value) : value;
+        // Validate path exists if required
         if (options.mustExist && !existsSync(path)) {
-            throw new Error("Path in env ".concat(key, " does not exist: ").concat(path));
+            throw new Error("Path in environment variable '".concat(key, "' does not exist: \"").concat(path, "\""));
+        }
+        // Validate file extension if specified
+        if (options.allowedExtensions && options.allowedExtensions.length > 0) {
+            var hasValidExtension = options.allowedExtensions.some(function (ext) { return path.toLowerCase().endsWith(ext.toLowerCase()); });
+            if (!hasValidExtension) {
+                throw new Error("Path in environment variable '".concat(key, "' must have one of these extensions: ").concat(options.allowedExtensions.join(', '), ". Got: \"").concat(path, "\""));
+            }
         }
+        this.cache.set(cacheKey, 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.
+     * @param {number} [defaultValue] - Optional fallback value.
      * @returns {number} The validated port number.
      * @throws {Error} If port is invalid.
+     *
+     * @example
+     * const serverPort = Env.getPort('PORT', 3000);
      */
     Env.getPort = function (key, defaultValue) {
-        if (defaultValue === void 0) { defaultValue = 3000; }
-        var port = Env.getNumber(key, defaultValue);
-        if (port < 0 || port > 65535) {
-            throw new Error("Env ".concat(key, " must be a valid port number (0-65535)"));
+        try {
+            return Env.getInteger(key, defaultValue, { min: 0, max: 65535 });
+        }
+        catch (error) {
+            // Rewrite the error message to match the expected pattern
+            if (error.message.includes('must be at most 65535')) {
+                throw new Error("Environment variable '".concat(key, "' must be a valid port number (0-65535)"));
+            }
+            throw error;
+        }
+    };
+    /**
+     * Retrieves an ISO date string and converts it to a Date object.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string|Date} [defaultValue] - Optional fallback value.
+     * @returns {Date} The parsed Date object.
+     *
+     * @example
+     * // If EXPIRY_DATE=2023-12-31T23:59:59Z
+     * const expiryDate = Env.getDate('EXPIRY_DATE', new Date());
+     */
+    Env.getDate = function (key, defaultValue) {
+        if (defaultValue === void 0) { defaultValue = new Date(); }
+        var value = Env.get(key, defaultValue instanceof Date ? defaultValue.toISOString() : defaultValue);
+        if (!value) {
+            return defaultValue instanceof Date ? defaultValue : new Date();
+        }
+        var date = new Date(value);
+        if (isNaN(date.getTime())) {
+            throw new Error("Environment variable '".concat(key, "' is not a valid date: \"").concat(value, "\""));
         }
-        return port;
+        return date;
     };
     /**
-     * Retrieves a duration string and converts to milliseconds.
+     * Retrieves a duration string and converts it 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.
+     *
+     * @example
+     * // If CACHE_TTL=2h30m
+     * const cacheTtlMs = Env.getDuration('CACHE_TTL', '1h');
+     * // 9000000 (2.5 hours in milliseconds)
      */
     Env.getDuration = function (key, defaultValue) {
         if (defaultValue === void 0) { defaultValue = '0'; }
+        var cacheKey = "duration:".concat(key);
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
         var value = Env.get(key, String(defaultValue));
         if (!value)
             return 0;
         // Handle plain number input (assume milliseconds)
         if (/^\d+$/.test(value)) {
-            return parseInt(value, 10);
+            var ms_1 = parseInt(value, 10);
+            this.cache.set(cacheKey, ms_1);
+            return ms_1;
         }
-        // Parse duration string like "1d2h30m15s"
-        var durationRegex = /(\d+d)?(\d+h)?(\d+m)?(\d+s)?(\d+ms)?/;
+        // Enhanced duration parsing with more precise regex
+        var durationRegex = /^(?:(\d+)y)?(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?(?:(\d+)ms)?$/;
         var matches = value.match(durationRegex);
         if (!matches || matches[0] === '') {
-            throw new Error("Env ".concat(key, " has invalid duration format. Use 1d, 2h, 30m, 45s, or 100ms."));
+            throw new Error("Environment variable '".concat(key, "' has invalid duration format: \"").concat(value, "\". ") +
+                "Use formats like 1y, 2w, 3d, 4h, 5m, 6s, or 7ms.");
         }
         var ms = 0;
         if (matches[1])
-            ms += parseInt(matches[1], 10) * 86400000; // days
+            ms += parseInt(matches[1], 10) * 31536000000; // years (approximate)
         if (matches[2])
-            ms += parseInt(matches[2], 10) * 3600000; // hours
+            ms += parseInt(matches[2], 10) * 604800000; // weeks
         if (matches[3])
-            ms += parseInt(matches[3], 10) * 60000; // minutes
+            ms += parseInt(matches[3], 10) * 86400000; // days
         if (matches[4])
-            ms += parseInt(matches[4], 10) * 1000; // seconds
+            ms += parseInt(matches[4], 10) * 3600000; // hours
         if (matches[5])
-            ms += parseInt(matches[5], 10); // milliseconds
+            ms += parseInt(matches[5], 10) * 60000; // minutes
+        if (matches[6])
+            ms += parseInt(matches[6], 10) * 1000; // seconds
+        if (matches[7])
+            ms += parseInt(matches[7], 10); // milliseconds
+        this.cache.set(cacheKey, ms);
         return ms;
     };
     /**
@@ -397,9 +686,13 @@ var Env = /** @class */ (function () {
      *
      * @param {string[]} [sensitiveKeys=['password', 'secret', 'key', 'token', 'auth']] - Keys to mask.
      * @returns {Record<string, string>} Environment variables with sensitive values masked.
+     *
+     * @example
+     * console.log(Env.getSafeEnv(['password', 'secret', 'key']));
+     * // { DATABASE_URL: "postgres://...", API_KEY: "******", ... }
      */
     Env.getSafeEnv = function (sensitiveKeys) {
-        var e_1, _a;
+        var e_2, _a;
         if (sensitiveKeys === void 0) { sensitiveKeys = ['password', 'secret', 'key', 'token', 'auth']; }
         var safeEnv = {};
         var _loop_1 = function (key, value) {
@@ -414,15 +707,98 @@ var Env = /** @class */ (function () {
                 _loop_1(key, value);
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
         finally {
             try {
                 if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
             }
-            finally { if (e_1) throw e_1.error; }
+            finally { if (e_2) throw e_2.error; }
         }
         return safeEnv;
     };
+    /**
+     * Loads environment variables from a .env file.
+     * Does not override existing variables.
+     *
+     * @param {string} [path='.env'] - Path to the .env file.
+     * @returns {Record<string, string>} Loaded environment variables.
+     *
+     * @example
+     * // Load variables from .env.development
+     * Env.loadFromFile('.env.development');
+     */
+    Env.loadFromFile = function (path) {
+        if (path === void 0) { path = '.env'; }
+        if (!existsSync(path)) {
+            throw new Error("Environment file not found: \"".concat(path, "\""));
+        }
+        var content = readFileSync(path, 'utf8');
+        var variables = {};
+        var lines = content.split(/\r?\n/);
+        var i = 0;
+        while (i < lines.length) {
+            var line = lines[i].trim();
+            // Skip empty lines or comment-only lines
+            if (!line || line.startsWith('#')) {
+                i++;
+                continue;
+            }
+            var match = line.match(/^([^=]+)=(.*)$/);
+            if (!match) {
+                i++;
+                continue;
+            }
+            var key = match[1].trim();
+            var value = match[2].trim();
+            // Remove inline comment for unquoted values
+            if (!/^['"]/.test(value)) {
+                var hashIndex = value.indexOf(' #');
+                if (hashIndex !== -1) {
+                    value = value.slice(0, hashIndex).trim();
+                }
+            }
+            // Handle quoted values
+            if ((value.startsWith('"') || value.startsWith("'")) && value.length > 1) {
+                var quote = value[0];
+                if (!value.endsWith(quote) || value.length === 1) {
+                    // multiline quoted
+                    var multilineValue = value.slice(1);
+                    i++;
+                    while (i < lines.length) {
+                        var nextLine = lines[i];
+                        if (nextLine.endsWith(quote)) {
+                            multilineValue += '\n' + nextLine.slice(0, -1);
+                            break;
+                        }
+                        else {
+                            multilineValue += '\n' + nextLine;
+                        }
+                        i++;
+                    }
+                    value = multilineValue;
+                }
+                else {
+                    // single-line quoted
+                    value = value.slice(1, -1);
+                }
+            }
+            else {
+                // Handle unquoted multiline: continue collecting until next key=value or empty line
+                i++;
+                while (i < lines.length && !lines[i].includes('=') && lines[i].trim() !== '') {
+                    value += '\n' + lines[i];
+                    i++;
+                }
+                i--; // adjust for outer loop
+            }
+            if (!process.env[key]) {
+                process.env[key] = value;
+                variables[key] = value;
+            }
+            i++;
+        }
+        return variables;
+    };
     /**
      * Checks whether the specified environment variable exists.
      *
@@ -439,8 +815,35 @@ var Env = /** @class */ (function () {
      * @returns {void}
      */
     Env.delete = function (key) {
+        var e_3, _a;
         delete process.env[key];
+        this.cache.delete(key);
+        try {
+            // Also clear all cached variations of this key
+            for (var _b = __values(this.cache.keys()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var cacheKey = _c.value;
+                if (cacheKey.includes(":".concat(key))) {
+                    this.cache.delete(cacheKey);
+                }
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    };
+    /**
+     * Clears the internal cache of parsed environment values.
+     * Useful for testing or when environment variables might change.
+     */
+    Env.clearCache = function () {
+        this.cache.clear();
     };
+    // Cache for parsed values to avoid repeated parsing of complex values
+    Env.cache = new Map();
     return Env;
 }());
 export { Env };