envapt 4.0.2 → 4.1.1

package/dist/index.mjs

@@ -6,7 +6,7 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/Error.ts
-var EnvaptErrorCodes = /* @__PURE__ */ ((EnvaptErrorCodes2) => {
+var EnvaptErrorCodes = /* @__PURE__ */ (function(EnvaptErrorCodes2) {
   EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidFallback"] = 101] = "InvalidFallback";
   EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidFallbackType"] = 102] = "InvalidFallbackType";
   EnvaptErrorCodes2[EnvaptErrorCodes2["ArrayFallbackElementTypeMismatch"] = 103] = "ArrayFallbackElementTypeMismatch";
@@ -19,8 +19,9 @@ var EnvaptErrorCodes = /* @__PURE__ */ ((EnvaptErrorCodes2) => {
   EnvaptErrorCodes2[EnvaptErrorCodes2["MissingDelimiter"] = 301] = "MissingDelimiter";
   EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidUserDefinedConfig"] = 302] = "InvalidUserDefinedConfig";
   EnvaptErrorCodes2[EnvaptErrorCodes2["EnvFilesNotFound"] = 303] = "EnvFilesNotFound";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidKeyInput"] = 304] = "InvalidKeyInput";
   return EnvaptErrorCodes2;
-})(EnvaptErrorCodes || {});
+})({});
 var EnvaptError = class extends Error {
   static {
     __name(this, "EnvaptError");
@@ -95,19 +96,18 @@ var Validator = class {
    */
   static isValidArrayConverterType(value) {
     if (typeof value !== "string") return false;
-    const invalidTypes = ["array", "json", "regexp"];
+    const invalidTypes = [
+      "array",
+      "json",
+      "regexp"
+    ];
     if (invalidTypes.includes(value)) return false;
-    const validTypes = ListOfBuiltInConverters.filter(
-      (type) => !invalidTypes.includes(type)
-    );
+    const validTypes = ListOfBuiltInConverters.filter((type) => !invalidTypes.includes(type));
     return validTypes.includes(value);
   }
   static customConvertor(converter) {
     if (typeof converter !== "function") {
-      throw new EnvaptError(
-        203 /* InvalidCustomConverter */,
-        `Custom converter must be a function, got ${typeof converter}.`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidCustomConverter, `Custom converter must be a function, got ${typeof converter}.`);
     }
   }
   /**
@@ -115,13 +115,10 @@ var Validator = class {
    */
   static arrayConverter(value) {
     if (!this.isArrayConverter(value)) {
-      throw new EnvaptError(301 /* MissingDelimiter */, "Must have delimiter property");
+      throw new EnvaptError(EnvaptErrorCodes.MissingDelimiter, "Must have delimiter property");
     }
     if (value.type !== void 0 && !this.isValidArrayConverterType(value.type)) {
-      throw new EnvaptError(
-        201 /* InvalidArrayConverterType */,
-        `"${value.type}" is not a valid converter type`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidArrayConverterType, `"${value.type}" is not a valid converter type`);
     }
   }
   /**
@@ -129,13 +126,10 @@ var Validator = class {
    */
   static builtInConverter(value) {
     if (typeof value !== "string") {
-      throw new EnvaptError(204 /* InvalidConverterType */, `Expected string, got ${typeof value}`);
+      throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);
     }
     if (!ListOfBuiltInConverters.includes(value)) {
-      throw new EnvaptError(
-        202 /* InvalidBuiltInConverter */,
-        `"${value}" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(",")}`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidBuiltInConverter, `"${value}" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(",")}`);
     }
   }
   /**
@@ -144,10 +138,7 @@ var Validator = class {
   static validateBuiltInConverterFallback(converter, fallback) {
     const typeChecker = BuiltInConverterTypeCheckers[converter];
     if (!typeChecker(fallback)) {
-      throw new EnvaptError(
-        104 /* FallbackConverterTypeMismatch */,
-        `Fallback type does not match converter "${converter}". Expected ${converter} compatible type.`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.FallbackConverterTypeMismatch, `Fallback type does not match converter "${converter}". Expected ${converter} compatible type.`);
     }
   }
   /**
@@ -161,10 +152,7 @@ var Validator = class {
       return typeof element !== firstElementType;
     });
     if (hasInconsistentTypes) {
-      throw new EnvaptError(
-        103 /* ArrayFallbackElementTypeMismatch */,
-        `All elements in array fallback must have the same type. Found mixed types.`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.ArrayFallbackElementTypeMismatch, `All elements in array fallback must have the same type. Found mixed types.`);
     }
   }
   /**
@@ -175,10 +163,7 @@ var Validator = class {
     const firstElement = fallback[0];
     const typeChecker = BuiltInConverterTypeCheckers[converterType];
     if (!typeChecker(firstElement)) {
-      throw new EnvaptError(
-        103 /* ArrayFallbackElementTypeMismatch */,
-        `Array converter type "${converterType}" does not match fallback element type. Expected ${converterType} compatible elements.`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.ArrayFallbackElementTypeMismatch, `Array converter type "${converterType}" does not match fallback element type. Expected ${converterType} compatible elements.`);
     }
   }
   /**
@@ -216,33 +201,27 @@ var Validator = class {
       if (converter === BigInt) return BigInt(fallback);
       if (converter === Symbol) return Symbol.for(String(fallback));
     } catch (error) {
-      throw new EnvaptError(
-        205 /* PrimitiveCoercionFailed */,
-        `Failed to coerce fallback value using ${converter.name}: ${error.message}`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.PrimitiveCoercionFailed, `Failed to coerce fallback value using ${converter.name}: ${error.message}`);
     }
-    throw new EnvaptError(
-      205 /* PrimitiveCoercionFailed */,
-      `Unknown primitive converter: ${converter.name}`
-    );
+    throw new EnvaptError(EnvaptErrorCodes.PrimitiveCoercionFailed, `Unknown primitive converter: ${converter.name}`);
   }
   /**
    * Make sure the user hasn't provided prohibited options in their dotenv config
    */
   static validateDotenvConfig(config2) {
     if ("path" in config2 || "processEnv" in config2) {
-      throw new EnvaptError(
-        302 /* InvalidUserDefinedConfig */,
-        'Custom dotenvConfig should not include "path" or "processEnv" options. Those are managed by Envapter.'
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidUserDefinedConfig, 'Custom dotenvConfig should not include "path" or "processEnv" options. Those are managed by Envapter.');
     }
-    const validKeys = /* @__PURE__ */ new Set(["encoding", "quiet", "debug", "override", "DOTENV_KEY"]);
+    const validKeys = /* @__PURE__ */ new Set([
+      "encoding",
+      "quiet",
+      "debug",
+      "override",
+      "DOTENV_KEY"
+    ]);
     const invalidKeys = Object.keys(config2).filter((key) => !validKeys.has(key));
     if (invalidKeys.length > 0) {
-      throw new EnvaptError(
-        302 /* InvalidUserDefinedConfig */,
-        `Invalid dotenvConfig options: ${invalidKeys.join(", ")}. Allowed options: ${Array.from(validKeys).join(", ")}`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidUserDefinedConfig, `Invalid dotenvConfig options: ${invalidKeys.join(", ")}. Allowed options: ${Array.from(validKeys).join(", ")}`);
     }
     return true;
   }
@@ -259,10 +238,7 @@ var Validator = class {
       }
     });
     if (missing.length > 0) {
-      throw new EnvaptError(
-        303 /* EnvFilesNotFound */,
-        `Environment file not found at path: ${missing.join(", ")}`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.EnvFilesNotFound, `Environment file not found at path: ${missing.join(", ")}`);
     }
   }
 };
@@ -273,15 +249,20 @@ var EnvapterBase = class _EnvapterBase {
   static {
     __name(this, "EnvapterBase");
   }
-  static _envPaths = [".env"];
-  // default path
-  static _userDefinedDotenvConfig = { quiet: true };
+  static _envPaths = [
+    ".env"
+  ];
+  static _userDefinedDotenvConfig = {
+    quiet: true
+  };
   /**
    * Set custom .env file paths. Accepts either a single path or array of paths.
    * Setting new paths clears the cache and reloads environment variables.
    */
   static set envPaths(paths) {
-    const newPaths = Array.isArray(paths) ? paths : [paths];
+    const newPaths = Array.isArray(paths) ? paths : [
+      paths
+    ];
     Validator.validateEnvFilesExist(newPaths);
     this._envPaths = newPaths;
     this.refreshCache();
@@ -310,11 +291,45 @@ var EnvapterBase = class _EnvapterBase {
     EnvaptCache.clear();
     void this.config;
   }
+  static resolveKeyInput(keyInput) {
+    const keys = Array.isArray(keyInput) ? keyInput : [
+      keyInput
+    ];
+    const normalizedKeys = keys;
+    if (normalizedKeys.length === 0) {
+      throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, "At least one environment key must be provided.");
+    }
+    if (normalizedKeys.some((k) => typeof k !== "string")) {
+      throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, "Environment keys must be strings.");
+    }
+    if (normalizedKeys.some((k) => k.trim() === "")) {
+      throw new EnvaptError(EnvaptErrorCodes.InvalidKeyInput, "Environment keys cannot be empty strings.");
+    }
+    for (const candidate of normalizedKeys) {
+      const value = this.config.get(candidate);
+      if (value !== void 0) {
+        return {
+          key: candidate,
+          value
+        };
+      }
+    }
+    return {
+      key: normalizedKeys[0],
+      value: void 0
+    };
+  }
   static get config() {
     if (EnvaptCache.size === 0) {
-      const isolatedEnv = { ...process.env };
+      const isolatedEnv = {
+        ...process.env
+      };
       try {
-        config({ path: this._envPaths, processEnv: isolatedEnv, ...this._userDefinedDotenvConfig });
+        config({
+          path: this._envPaths,
+          processEnv: isolatedEnv,
+          ...this._userDefinedDotenvConfig
+        });
       } catch {
       }
       for (const [key, value] of Object.entries(isolatedEnv)) EnvaptCache.set(key, value);
@@ -325,7 +340,7 @@ var EnvapterBase = class _EnvapterBase {
    * Get raw environment variable value without parsing or conversion.
    */
   getRaw(key) {
-    return _EnvapterBase.config.get(key);
+    return _EnvapterBase.resolveKeyInput(key).value;
   }
 };
 
@@ -343,8 +358,18 @@ var BuiltInConverters = class _BuiltInConverters {
   }
   static boolean(raw, fallback) {
     const lower = raw.toLowerCase().trim();
-    const truthyValues = ["1", "yes", "true", "on"];
-    const falsyValues = ["0", "no", "false", "off"];
+    const truthyValues = [
+      "1",
+      "yes",
+      "true",
+      "on"
+    ];
+    const falsyValues = [
+      "0",
+      "no",
+      "false",
+      "off"
+    ];
     if (truthyValues.includes(lower)) return true;
     if (falsyValues.includes(lower)) return false;
     return fallback;
@@ -468,13 +493,14 @@ var BuiltInConverters = class _BuiltInConverters {
 
 // src/Parser.ts
 var Parser = class {
-  constructor(envService) {
-    this.envService = envService;
-  }
   static {
     __name(this, "Parser");
   }
+  envService;
   TEMPLATE_REGEX = /\${\w*}/g;
+  constructor(envService) {
+    this.envService = envService;
+  }
   /**
    * Resolve template variables in a string while handling circular references and missing variables
    * @internal
@@ -521,7 +547,7 @@ var Parser = class {
     if (primitiveConstructor === Boolean) return "boolean";
     if (primitiveConstructor === BigInt) return "bigint";
     if (primitiveConstructor === Symbol) return "symbol";
-    throw new EnvaptError(204 /* InvalidConverterType */, `Unknown primitive constructor`);
+    throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Unknown primitive constructor`);
   }
   processBuiltInConverter(key, fallback, resolvedConverter, hasFallback, wasOriginallyConstructor) {
     Validator.builtInConverter(resolvedConverter);
@@ -541,10 +567,7 @@ var Parser = class {
   processArrayConverter(key, fallback, resolvedConverter, hasFallback) {
     Validator.arrayConverter(resolvedConverter);
     if (hasFallback && fallback !== void 0 && !Array.isArray(fallback)) {
-      throw new EnvaptError(
-        101 /* InvalidFallback */,
-        `ArrayConverter requires that the fallback be an array, got ${typeof fallback}`
-      );
+      throw new EnvaptError(EnvaptErrorCodes.InvalidFallback, `ArrayConverter requires that the fallback be an array, got ${typeof fallback}`);
     }
     if (hasFallback && Array.isArray(fallback)) {
       Validator.validateArrayFallbackElementTypes(fallback);
@@ -575,12 +598,12 @@ var Parser = class {
 };
 
 // src/core/EnvironmentMethods.ts
-var Environment = /* @__PURE__ */ ((Environment2) => {
+var Environment = /* @__PURE__ */ (function(Environment2) {
   Environment2[Environment2["Development"] = 0] = "Development";
   Environment2[Environment2["Staging"] = 1] = "Staging";
   Environment2[Environment2["Production"] = 2] = "Production";
   return Environment2;
-})(Environment || {});
+})({});
 var EnvironmentMethods = class _EnvironmentMethods extends EnvapterBase {
   static {
     __name(this, "EnvironmentMethods");
@@ -589,7 +612,7 @@ var EnvironmentMethods = class _EnvironmentMethods extends EnvapterBase {
   static determineEnvironment(env) {
     const environment = env ?? this.getRawValue("ENVIRONMENT", this.getRawValue("ENV", this.getRawValue("NODE_ENV", "development")));
     if (typeof environment === "string") {
-      this._environment = environment.toLowerCase() === "production" ? 2 /* Production */ : environment === "staging" ? 1 /* Staging */ : 0 /* Development */;
+      this._environment = environment.toLowerCase() === "production" ? 2 : environment === "staging" ? 1 : 0;
     } else {
       this._environment = environment;
     }
@@ -628,37 +651,37 @@ var EnvironmentMethods = class _EnvironmentMethods extends EnvapterBase {
    * Check if the current environment is production
    */
   static get isProduction() {
-    return this.environment === 2 /* Production */;
+    return this.environment === 2;
   }
   /**
    * @see {@link EnvironmentMethods.isProduction}
    */
   get isProduction() {
-    return _EnvironmentMethods.environment === 2 /* Production */;
+    return _EnvironmentMethods.environment === 2;
   }
   /**
    * Check if the current environment is staging
    */
   static get isStaging() {
-    return this.environment === 1 /* Staging */;
+    return this.environment === 1;
   }
   /**
    * @see {@link EnvironmentMethods.isStaging}
    */
   get isStaging() {
-    return _EnvironmentMethods.environment === 1 /* Staging */;
+    return _EnvironmentMethods.environment === 1;
   }
   /**
    * Check if the current environment is development
    */
   static get isDevelopment() {
-    return this.environment === 0 /* Development */;
+    return this.environment === 0;
   }
   /**
    * @see {@link EnvironmentMethods.isDevelopment}
    */
   get isDevelopment() {
-    return _EnvironmentMethods.environment === 0 /* Development */;
+    return _EnvironmentMethods.environment === 0;
   }
   static refreshCache() {
     super.refreshCache();
@@ -673,84 +696,84 @@ var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
   }
   static parser = new Parser(new _PrimitiveMethods());
   static _get(key, type, def) {
-    const rawVal = this.config.get(key);
+    const { key: resolvedKey, value } = this.resolveKeyInput(key);
+    const rawVal = value;
     if (!rawVal) return def;
-    const parsed = this.parser.resolveTemplate(key, String(rawVal));
+    const parsed = this.parser.resolveTemplate(resolvedKey, String(rawVal));
     let result;
-    if (type === 1 /* Number */) result = BuiltInConverters.number(parsed, def);
-    else if (type === 2 /* Boolean */)
-      result = BuiltInConverters.boolean(parsed, def);
-    else if (type === 3 /* BigInt */)
-      result = BuiltInConverters.bigint(parsed, def);
-    else if (type === 4 /* Symbol */)
-      result = BuiltInConverters.symbol(parsed, def);
+    if (type === 1) result = BuiltInConverters.number(parsed, def);
+    else if (type === 2) result = BuiltInConverters.boolean(parsed, def);
+    else if (type === 3) result = BuiltInConverters.bigint(parsed, def);
+    else if (type === 4) result = BuiltInConverters.symbol(parsed, def);
     else result = BuiltInConverters.string(parsed, def);
     return result;
   }
   /**
    * Get a string environment variable with optional fallback.
-   * Supports template variable resolution using $\{VAR\} syntax.
+   * Supports template variable resolution using `${VAR}` syntax.
+   * Accepts a single key or an ordered array of keys (first match wins).
    */
   static get(key, def) {
-    return this._get(key, 0 /* String */, def);
+    return this._get(key, 0, def);
   }
-  /**
-   * @see {@link PrimitiveMethods.get}
-   */
   get(key, def) {
-    return _PrimitiveMethods._get(key, 0 /* String */, def);
+    return _PrimitiveMethods._get(key, 0, def);
   }
   /**
    * Get a number environment variable with optional fallback.
    * Automatically converts string values to numbers.
+   * Accepts a single key or an ordered array of keys (first match wins).
    */
   static getNumber(key, def) {
-    return this._get(key, 1 /* Number */, def);
+    return this._get(key, 1, def);
   }
   /**
    * @see {@link PrimitiveMethods.getNumber}
    */
   getNumber(key, def) {
-    return _PrimitiveMethods._get(key, 1 /* Number */, def);
+    return _PrimitiveMethods._get(key, 1, def);
   }
   /**
    * Get a boolean environment variable with optional fallback.
    * Recognizes: `1`, `yes`, `true`, 'on' as **true**; `0`, `no`, `false`, 'off' as **false** (case-insensitive).
+   * Accepts a single key or an ordered array of keys (first match wins).
    */
   static getBoolean(key, def) {
-    return this._get(key, 2 /* Boolean */, def);
+    return this._get(key, 2, def);
   }
   /**
    * @see {@link PrimitiveMethods.getBoolean}
    */
   getBoolean(key, def) {
-    return _PrimitiveMethods._get(key, 2 /* Boolean */, def);
+    return _PrimitiveMethods._get(key, 2, def);
   }
   /**
    * Get a bigint environment variable with optional fallback.
    * Automatically converts string values to bigint.
+   * Accepts a single key or an ordered array of keys (first match wins).
    */
   static getBigInt(key, def) {
-    return this._get(key, 3 /* BigInt */, def);
+    return this._get(key, 3, def);
   }
   /**
    * @see {@link PrimitiveMethods.getBigInt}
    */
   getBigInt(key, def) {
-    return _PrimitiveMethods._get(key, 3 /* BigInt */, def);
+    return _PrimitiveMethods._get(key, 3, def);
   }
   /**
    * Get a symbol environment variable with optional fallback.
    * Creates a symbol from the string value.
+   * Accepts a single key or an ordered array of keys (first match wins).
    */
   static getSymbol(key, def) {
-    return this._get(key, 4 /* Symbol */, def);
+    return this._get(key, 4, def);
   }
   /**
    * @see {@link PrimitiveMethods.getSymbol}
    */
   getSymbol(key, def) {
-    return _PrimitiveMethods._get(key, 4 /* Symbol */, def);
+    return _PrimitiveMethods._get(key, 4, def);
   }
 };
 
@@ -760,10 +783,10 @@ var AdvancedMethods = class _AdvancedMethods extends PrimitiveMethods {
     __name(this, "AdvancedMethods");
   }
   static getUsing(key, converter, fallback) {
-    const rawVal = this.config.get(key);
-    if (!rawVal) return fallback;
+    const { key: resolvedKey, value } = this.resolveKeyInput(key);
+    if (!value) return fallback;
     const hasFallback = fallback !== void 0;
-    const result = this.parser.convertValue(key, fallback, converter, hasFallback);
+    const result = this.parser.convertValue(resolvedKey, fallback, converter, hasFallback);
     return result;
   }
   getUsing(key, converter, fallback) {
@@ -771,17 +794,13 @@ var AdvancedMethods = class _AdvancedMethods extends PrimitiveMethods {
   }
   /**
    * Get an environment variable using a custom converter function.
+   * Accepts a single key or an ordered list for automatic fallback.
    */
   static getWith(key, converter, fallback) {
-    const rawVal = this.config.get(key);
-    if (!rawVal) return fallback;
+    const { key: resolvedKey, value } = this.resolveKeyInput(key);
+    if (!value) return fallback;
     const hasFallback = fallback !== void 0;
-    const result = this.parser.convertValue(
-      key,
-      fallback,
-      converter,
-      hasFallback
-    );
+    const result = this.parser.convertValue(resolvedKey, fallback, converter, hasFallback);
     return result;
   }
   /**
@@ -868,7 +887,7 @@ function Envapt(key, fallbackOrOptions, converter) {
 __name(Envapt, "Envapt");
 
 // src/Converters.ts
-var Converters = /* @__PURE__ */ ((Converters2) => {
+var Converters = /* @__PURE__ */ (function(Converters2) {
   Converters2["String"] = "string";
   Converters2["Number"] = "number";
   Converters2["Boolean"] = "boolean";
@@ -883,7 +902,7 @@ var Converters = /* @__PURE__ */ ((Converters2) => {
   Converters2["Date"] = "date";
   Converters2["Time"] = "time";
   return Converters2;
-})(Converters || {});
+})({});
 /* v8 ignore next -- @preserve */
 
 export { Converters, Envapt, EnvaptError, EnvaptErrorCodes, Envapter, Environment };