@catbee/utils 2.0.0-next.0 → 2.0.0

package/env/index.d.ts

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -22,4 +22,393 @@
  * SOFTWARE.
  */
 
-export * from './env.utils';
+/**
+ * Enum representing valid application environments.
+ */
+declare enum Environment {
+    PRODUCTION = "production",
+    DEVELOPMENT = "development",
+    STAGING = "staging",
+    TESTING = "testing"
+}
+/**
+ * Options for validating URL environment variables
+ */
+interface UrlOptions {
+    /** List of allowed protocols (e.g., ['http', 'https']) */
+    protocols?: string[];
+    /** Whether a top-level domain is required (default: true) */
+    requireTld?: boolean;
+    /** Whether to allow IP addresses (default: true) */
+    allowIp?: boolean;
+    /** Whether to allow localhost (default: true) */
+    allowLocalhost?: boolean;
+}
+/**
+ * Options for validating path environment variables
+ */
+interface PathOptions {
+    /** Whether the path must exist on the filesystem (default: false) */
+    mustExist?: boolean;
+    /** Whether to convert relative paths to absolute (default: true) */
+    makeAbsolute?: boolean;
+    /** List of allowed file extensions */
+    allowedExtensions?: string[];
+}
+/**
+ * Utility class for accessing and managing environment variables.
+ * Provides typed getters with fallback defaults and validation.
+ */
+declare class Env {
+    private static readonly cache;
+    /**
+     * Checks if the current NODE_ENV is 'development'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'development', else `false`.
+     */
+    static isDev(): boolean;
+    /**
+     * Checks if the current NODE_ENV is 'production'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'production', else `false`.
+     */
+    static isProd(): boolean;
+    /**
+     * Checks if the current NODE_ENV is 'testing'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'testing', else `false`.
+     */
+    static isTest(): boolean;
+    /**
+     * Checks if the current NODE_ENV is 'staging'.
+     *
+     * @returns {boolean} `true` if NODE_ENV is 'staging', else `false`.
+     */
+    static isStaging(): 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.
+     * 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} 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"
+     */
+    static get(key: string, defaultValue: string): string;
+    /**
+     * 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 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();
+     * });
+     */
+    static getWithDefault(key: string, defaultFn: () => 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 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 });
+     */
+    static getInteger(key: string, defaultValue: number, options?: {
+        min?: number;
+        max?: number;
+    }): 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.
+     *
+     * @example
+     * // If DEBUG=yes
+     * const isDebug = Env.getBoolean('DEBUG', false); // true
+     */
+    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.
+     *
+     * @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" }}
+     */
+    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.
+     * @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));
+     */
+    static getArray<T = string>(key: string, defaultValue?: T[], splitter?: string, transform?: (item: string) => T): T[];
+    /**
+     * 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]
+     */
+    static getNumberArray(key: string, defaultValue?: number[], splitter?: string): number[];
+    /**
+     * 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} [defaultValue] - Optional fallback value.
+     * @param {T[]} allowedValues - Array of accepted string values.
+     * @returns {T} The validated environment value.
+     * @throws {Error} If missing or invalid.
+     *
+     * @example
+     * // If LOG_LEVEL=debug
+     * const level = Env.getEnum('LOG_LEVEL', 'info', ['debug', 'info', 'warn', 'error'] as const);
+     * // 'debug' (typed as 'debug' | 'info' | 'warn' | 'error')
+     */
+    static getEnum<T extends string>(key: string, defaultValue: T, allowedValues: readonly T[]): T;
+    /**
+     * Retrieves an enum-like numeric environment variable.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {number} defaultValue - Default value if not present.
+     * @param {number[]} allowedValues - Array of accepted values.
+     * @returns {number} The validated value.
+     *
+     * @example
+     * // If NODE_VERSION=16
+     * const version = Env.getNumberEnum('NODE_VERSION', 16, [14, 16, 18]);
+     */
+    static getNumberEnum(key: string, defaultValue: number, allowedValues: number[]): number;
+    /**
+     * Retrieves a URL environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Optional fallback value.
+     * @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
+     * });
+     */
+    static getUrl(key: string, defaultValue: string, options?: UrlOptions): string;
+    private static parseUrl;
+    private static validateProtocol;
+    private static isIp;
+    private static validateHostname;
+    /**
+     * 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.
+     *
+     * @example
+     * const supportEmail = Env.getEmail('SUPPORT_EMAIL', 'support@example.com');
+     */
+    static getEmail(key: string, defaultValue: string): string;
+    /**
+     * Retrieves a path environment variable and validates it exists.
+     *
+     * @param {string} key - The environment variable key.
+     * @param {string} [defaultValue] - Optional fallback value.
+     * @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']
+     * });
+     */
+    static getPath(key: string, defaultValue: string, options?: PathOptions): string;
+    /**
+     * Retrieves a port environment variable and validates it.
+     *
+     * @param {string} key - The environment variable key.
+     * @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);
+     */
+    static getPort(key: string, defaultValue: number): number;
+    /**
+     * 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());
+     */
+    static getDate(key: string, defaultValue?: string | Date): Date;
+    /**
+     * 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)
+     */
+    static getDuration(key: string, defaultValue?: string | number): number;
+    /**
+     * 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.
+     *
+     * @example
+     * console.log(Env.getSafeEnv(['password', 'secret', 'key']));
+     * // { DATABASE_URL: "postgres://...", API_KEY: "******", ... }
+     */
+    static getSafeEnv(sensitiveKeys?: string[]): Record<string, string>;
+    /**
+     * 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');
+     */
+    static loadFromFile(path?: string): Record<string, string>;
+    private static parseEnvContent;
+    private static isCommentOrEmpty;
+    private static extractKeyValue;
+    private static isQuoted;
+    private static stripInlineComment;
+    private static parseQuotedValue;
+    private static parseUnquotedMultiline;
+    /**
+     * 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;
+    /**
+     * Clears the internal cache of parsed environment values.
+     * Useful for testing or when environment variables might change.
+     */
+    static clearCache(): void;
+}
+
+export { Env, Environment };
+export type { PathOptions, UrlOptions };

package/env/index.mjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -24,6 +24,8 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { isAbsolute, resolve } from 'path';
+import { parseDuration } from '@catbee/utils/date';
+import { isEmail } from '@catbee/utils/validation';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -81,9 +83,7 @@ var Env = class _Env {
   static set(key, value) {
     process.env[key] = value;
     this.cache.delete(key);
-    for (const cacheKey of [
-      ...this.cache.keys()
-    ]) {
+    for (const cacheKey of this.cache.keys()) {
       if (cacheKey.includes(`:${key}`)) {
         this.cache.delete(cacheKey);
       }
@@ -112,7 +112,7 @@ var Env = class _Env {
   */
   static get(key, defaultValue) {
     let value = process.env[key] ?? defaultValue;
-    if (value && value.includes("${")) {
+    if (value?.includes("${")) {
       value = value.replace(/\${([A-Za-z0-9_]+)}/g, (_, varName) => {
         return process.env[varName] ?? "";
       });
@@ -170,7 +170,7 @@ var Env = class _Env {
       return defaultValue;
     }
     const numberValue = Number(value);
-    if (isNaN(numberValue)) {
+    if (Number.isNaN(numberValue)) {
       throw new Error(`Environment variable '${key}' is not a valid number, got: "${value}"`);
     }
     this.cache.set(`number:${key}`, numberValue);
@@ -361,7 +361,7 @@ var Env = class _Env {
   static getNumberArray(key, defaultValue = [], splitter = ",") {
     return _Env.getArray(key, defaultValue, splitter, (item) => {
       const num = Number(item);
-      if (isNaN(num)) {
+      if (Number.isNaN(num)) {
         throw new Error(`Value "${item}" in array '${key}' is not a valid number`);
       }
       return num;
@@ -437,20 +437,33 @@ var Env = class _Env {
     if (!value) {
       throw new Error(`URL environment variable '${key}' is missing or empty`);
     }
-    let url;
+    const url = this.parseUrl(value, key);
+    this.validateProtocol(url, key, options);
+    this.validateHostname(url, key, options);
+    this.cache.set(cacheKey, value);
+    return value;
+  }
+  static parseUrl(value, key) {
     try {
-      url = new URL(value);
+      return new URL(value);
     } catch {
       throw new Error(`Environment variable '${key}' is not a valid URL: "${value}"`);
     }
+  }
+  static validateProtocol(url, key, options) {
     if (options.protocols && options.protocols.length > 0) {
       const protocol = url.protocol.replace(":", "");
       if (!options.protocols.includes(protocol)) {
         throw new Error(`Environment variable '${key}' must use one of the protocols: ${options.protocols.join(", ")}. Got: ${protocol}`);
       }
     }
+  }
+  static isIp(hostname) {
+    return /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(hostname);
+  }
+  static validateHostname(url, key, options) {
     const { hostname } = url;
-    const isIp = /^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(hostname);
+    const isIp = _Env.isIp(hostname);
     const isLocalhost = hostname === "localhost";
     if (isIp && options.allowIp === false) {
       throw new Error(`Environment variable '${key}' cannot be an IP address: "${hostname}"`);
@@ -463,8 +476,6 @@ var Env = class _Env {
         throw new Error(`Environment variable '${key}' must have a valid host with TLD: "${hostname}"`);
       }
     }
-    this.cache.set(cacheKey, value);
-    return value;
   }
   /**
   * Retrieves an email environment variable and validates it.
@@ -488,8 +499,7 @@ var Env = class _Env {
       }
       return defaultValue;
     }
-    const 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)) {
+    if (!isEmail(value)) {
       throw new Error(`Environment variable '${key}' is not a valid email address: "${value}"`);
     }
     this.cache.set(`email:${key}`, value);
@@ -577,7 +587,7 @@ var Env = class _Env {
       return defaultValue instanceof Date ? defaultValue : /* @__PURE__ */ new Date();
     }
     const date = new Date(value);
-    if (isNaN(date.getTime())) {
+    if (Number.isNaN(date.getTime())) {
       throw new Error(`Environment variable '${key}' is not a valid date: "${value}"`);
     }
     return date;
@@ -601,26 +611,9 @@ var Env = class _Env {
     if (this.cache.has(cacheKey)) {
       return this.cache.get(cacheKey);
     }
-    const value = _Env.get(key, String(defaultValue));
-    if (!value) return 0;
-    if (/^\d+$/.test(value)) {
-      const ms2 = parseInt(value, 10);
-      this.cache.set(cacheKey, ms2);
-      return ms2;
-    }
-    const durationRegex = /^(?:(\d+)y)?(?:(\d+)w)?(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?(?:(\d+)ms)?$/;
-    const matches = value.match(durationRegex);
-    if (!matches || matches[0] === "") {
-      throw new Error(`Environment variable '${key}' has invalid duration format: "${value}". Use formats like 1y, 2w, 3d, 4h, 5m, 6s, or 7ms.`);
-    }
-    let ms = 0;
-    if (matches[1]) ms += parseInt(matches[1], 10) * 31536e6;
-    if (matches[2]) ms += parseInt(matches[2], 10) * 6048e5;
-    if (matches[3]) ms += parseInt(matches[3], 10) * 864e5;
-    if (matches[4]) ms += parseInt(matches[4], 10) * 36e5;
-    if (matches[5]) ms += parseInt(matches[5], 10) * 6e4;
-    if (matches[6]) ms += parseInt(matches[6], 10) * 1e3;
-    if (matches[7]) ms += parseInt(matches[7], 10);
+    const raw = _Env.get(key, String(defaultValue));
+    if (!raw) return 0;
+    const ms = parseDuration(raw);
     this.cache.set(cacheKey, ms);
     return ms;
   }
@@ -665,63 +658,102 @@ var Env = class _Env {
       throw new Error(`Environment file not found: "${path}"`);
     }
     const content = readFileSync(path, "utf8");
+    const variables = this.parseEnvContent(content);
+    for (const [k, v] of Object.entries(variables)) {
+      if (!process.env[k]) {
+        process.env[k] = v;
+      }
+    }
+    return variables;
+  }
+  static parseEnvContent(content) {
     const variables = {};
     const lines = content.split(/\r?\n/);
     let i = 0;
     while (i < lines.length) {
       let line = lines[i].trim();
-      if (!line || line.startsWith("#")) {
+      if (this.isCommentOrEmpty(line)) {
         i++;
         continue;
       }
-      const match = line.match(/^([^=]+)=(.*)$/);
+      const match = this.extractKeyValue(line);
       if (!match) {
         i++;
         continue;
       }
       const key = match[1].trim();
       let value = match[2].trim();
-      if (!/^['"]/.test(value)) {
-        const hashIndex = value.indexOf(" #");
-        if (hashIndex !== -1) {
-          value = value.slice(0, hashIndex).trim();
-        }
+      if (!this.isQuoted(value)) {
+        value = this.stripInlineComment(value);
       }
-      if ((value.startsWith('"') || value.startsWith("'")) && value.length > 1) {
-        const quote = value[0];
-        if (!value.endsWith(quote) || value.length === 1) {
-          let multilineValue = value.slice(1);
-          i++;
-          while (i < lines.length) {
-            const nextLine = lines[i];
-            if (nextLine.endsWith(quote)) {
-              multilineValue += "\n" + nextLine.slice(0, -1);
-              break;
-            } else {
-              multilineValue += "\n" + nextLine;
-            }
-            i++;
-          }
-          value = multilineValue;
-        } else {
-          value = value.slice(1, -1);
-        }
+      if (this.isQuoted(value) && value.length > 1) {
+        const result = this.parseQuotedValue(lines, i, value);
+        value = result.value;
+        i = result.nextIndex;
       } else {
-        i++;
-        while (i < lines.length && !lines[i].includes("=") && lines[i].trim() !== "") {
-          value += "\n" + lines[i];
-          i++;
-        }
-        i--;
+        const result = this.parseUnquotedMultiline(lines, i, value);
+        value = result.value;
+        i = result.nextIndex;
       }
       if (!process.env[key]) {
-        process.env[key] = value;
         variables[key] = value;
       }
       i++;
     }
     return variables;
   }
+  static isCommentOrEmpty(line) {
+    return !line || line.startsWith("#");
+  }
+  static extractKeyValue(line) {
+    return line.match(/^([^=]+)=(.*)$/);
+  }
+  static isQuoted(value) {
+    return /^['"]/.test(value);
+  }
+  static stripInlineComment(value) {
+    const hashIndex = value.indexOf(" #");
+    if (hashIndex !== -1) {
+      return value.slice(0, hashIndex).trim();
+    }
+    return value;
+  }
+  static parseQuotedValue(lines, currentIndex, value) {
+    const quote = value[0];
+    if (!value.endsWith(quote) || value.length === 1) {
+      let multilineValue = value.slice(1);
+      let i = currentIndex + 1;
+      while (i < lines.length) {
+        const nextLine = lines[i];
+        if (nextLine.endsWith(quote)) {
+          multilineValue += "\n" + nextLine.slice(0, -1);
+          break;
+        } else {
+          multilineValue += "\n" + nextLine;
+        }
+        i++;
+      }
+      return {
+        value: multilineValue,
+        nextIndex: i
+      };
+    }
+    return {
+      value: value.slice(1, -1),
+      nextIndex: currentIndex
+    };
+  }
+  static parseUnquotedMultiline(lines, currentIndex, value) {
+    let i = currentIndex + 1;
+    while (i < lines.length && !lines[i].includes("=") && lines[i].trim() !== "") {
+      value += "\n" + lines[i];
+      i++;
+    }
+    return {
+      value,
+      nextIndex: i - 1
+    };
+  }
   /**
   * Checks whether the specified environment variable exists.
   *

package/exception/index.cjs

@@ -1,7 +1,7 @@
 /*
  * The MIT License
  * 
- * Copyright (c) 2025 Catbee Technologies. https://catbee.in/license
+ * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal