envapt 4.0.1 → 4.1.0

package/dist/index.d.ts

@@ -76,6 +76,11 @@ interface ArrayConverter {
  * @public
  */
 type BaseInput = string | undefined;
+/**
+ * Accepted shape for environment variable lookups. Either a single key or an ordered list of keys.
+ * @public
+ */
+type EnvKeyInput = string | readonly [string, ...string[]];
 /**
  * Custom parser function type for environment variables
  * @param raw - Raw string value from environment
@@ -189,90 +194,196 @@ type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bi
 /**
  * Usage 1: Custom converter function with fallback provided
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name to load (string or ordered array of strings)
  * @param options - Configuration options with custom converter and required fallback
  * @public
+ * @example
+ * ```ts
+ * // Custom converter that validates a non-empty API key
+ * class Config extends Envapter {
+ *   \@Envapt('API_KEY', {
+ *     fallback: 'default-key',
+ *     converter(raw, _fallback) {
+ *       if (!raw || raw.trim() === '') throw new Error('API_KEY required');
+ *       return raw.trim();
+ *     }
+ *   })
+ *   static readonly apiKey: string;
+ * }
+ * ```
  */
-declare function Envapt<TFallback>(key: string, options: {
+declare function Envapt<TFallback>(key: EnvKeyInput, options: {
     converter: (raw: string | undefined, fallback: TFallback) => TFallback;
     fallback: TFallback;
 }): PropertyDecorator;
 /**
  * Usage 2: Custom converter function without fallback
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param options - Configuration options with custom converter only
  * @public
+ * @example
+ * ```ts
+ * // Custom converter without providing a fallback
+ * class Config extends Envapter {
+ *   \@Envapt('FEATURE_FLAGS', { converter(raw) {
+ *     // raw may be undefined — handle that here
+ *     return raw ? raw.split('|').map(s => s.trim()) : [];
+ *   } })
+ *   static readonly featureFlags: string[];
+ * }
+ * ```
  */
-declare function Envapt<TReturnType>(key: string, options: {
+declare function Envapt<TReturnType>(key: EnvKeyInput, options: {
     converter: ConverterFunction<TReturnType>;
 }): PropertyDecorator;
 /**
  * Usage 3: Built-in converter with optional fallback
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param options - Configuration options with built-in converter
  * @public
+ * @example
+ * ```ts
+ * import { Converters } from 'envapt';
+ *
+ * class Config extends Envapter {
+ *   // Use built-in Number converter with a numeric fallback
+ *   \@Envapt('APP_PORT', { converter: Converters.Number, fallback: 3000 })
+ *   static readonly port: number;
+ *
+ *   // Use Url converter with a string fallback (must match converter type)
+ *   \@Envapt('APP_URL', { converter: Converters.Url, fallback: 'http://localhost:3000' })
+ *   static readonly url: URL;
+ *
+ *   // Prefer CANARY_URL when present, otherwise fall back to APP_URL
+ *   \@Envapt(['CANARY_URL', 'APP_URL'], { converter: Converters.Url })
+ *   static readonly canaryUrl: URL | null;
+ * }
+ * ```
  */
-declare function Envapt<TConverter extends BuiltInConverter>(key: string, options: {
+declare function Envapt<TConverter extends BuiltInConverter>(key: EnvKeyInput, options: {
     converter: TConverter;
     fallback?: InferConverterReturnType<TConverter> | undefined;
 }): PropertyDecorator;
 /**
  * Usage 4: Array converter with optional fallback
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param options - Configuration options with array converter
  * @public
+ * @example
+ * ```ts
+ * import { Converters } from 'envapt';
+ *
+ * class Config extends Envapter {
+ *   // Comma-separated list of origins -> string[]
+ *   \@Envapt('ALLOWED_ORIGINS', {
+ *     converter: { delimiter: ',', type: Converters.String },
+ *     fallback: ['https://example.com']
+ *   })
+ *   static readonly allowedOrigins: string[];
+ *
+ *   // Pipe-separated ports -> number[]
+ *   \@Envapt('PORTS', {
+ *     converter: { delimiter: '|', type: Converters.Number },
+ *     fallback: [3000]
+ *   })
+ *   static readonly ports: number[];
+ * }
+ * ```
  */
-declare function Envapt<TConverter extends ArrayConverter>(key: string, options: {
+declare function Envapt<TConverter extends ArrayConverter>(key: EnvKeyInput, options: {
     converter: TConverter;
     fallback?: InferConverterReturnType<TConverter> | undefined;
 }): PropertyDecorator;
 /**
  * Usage 5: Primitive constructor with optional fallback
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param options - Configuration options with primitive constructor
  * @public
+ * @example
+ * ```ts
+ * // Use primitive constructors to coerce values
+ * class Config extends Envapter {
+ *   \@Envapt('MAX_CONNECTIONS', { converter: Number, fallback: 100 })
+ *   static readonly maxConnections: number;
+ *
+ *   \@Envapt('FEATURE_ENABLED', { converter: Boolean, fallback: false })
+ *   static readonly featureEnabled: boolean;
+ * }
+ * ```
  */
-declare function Envapt<TConstructor extends PrimitiveConstructor>(key: string, options: {
+declare function Envapt<TConstructor extends PrimitiveConstructor>(key: EnvKeyInput, options: {
     converter: TConstructor;
     fallback?: InferPrimitiveReturnType<TConstructor>;
 }): PropertyDecorator;
 /**
  * Usage 6: Fallback only (no converter)
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param options - Configuration options with fallback only
  * @public
+ * @example
+ * ```ts
+ * // Fallback-only usage (no converter)
+ * class Config extends Envapter {
+ *   \@Envapt('LOG_FILE', { fallback: '/var/log/app.log' })
+ *   static readonly logFile: string;
+ *
+ *   \@Envapt('RETRY_POLICY', { fallback: { retries: 3, backoff: 'exponential' } })
+ *   static readonly retryPolicy: unknown;
+ * }
+ * ```
  */
-declare function Envapt<TFallback>(key: string, options: {
+declare function Envapt<TFallback>(key: EnvKeyInput, options: {
     fallback: TFallback;
     converter?: undefined;
 }): PropertyDecorator;
 /**
  * Classic API: No fallback
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
+ * @example
+ * ```ts
+ * // Classic API: no fallback — property will resolve from env or be null
+ * class Config extends Envapter {
+ *   \@Envapt('SIMPLE_VALUE')
+ *   static readonly simple?: string | null;
+ * }
+ * ```
  */
-declare function Envapt<_TReturnType = string | null>(key: string): PropertyDecorator;
+declare function Envapt<_TReturnType = string | null>(key: EnvKeyInput): PropertyDecorator;
 /**
  * Classic API: Primitive fallback only
  *
- * @param key - Environment variable name to load
+ * @param key - Environment variable name(s) to load
  * @param fallback - Default primitive value
  * @param converter - Optional primitive constructor (String, Number, etc.)
  * @public
+ * @example
+ * ```ts
+ * // Classic API with primitive fallback and optional primitive converter
+ * class Config extends Envapter {
+ *   // Provide fallback only
+ *   \@Envapt('HOST', 'localhost')
+ *   static readonly host: string;
+ *
+ *   // Provide fallback and converter
+ *   \@Envapt('PORT', 8080, Number)
+ *   static readonly port: number;
+ * }
+ * ```
  */
-declare function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(key: string, fallback: InferPrimitiveFallbackType<TFallback>, converter?: PrimitiveConstructor): PropertyDecorator;
+declare function Envapt<TFallback extends string | number | boolean | bigint | symbol | undefined>(key: EnvKeyInput, fallback: InferPrimitiveFallbackType<TFallback>, converter?: PrimitiveConstructor): PropertyDecorator;
 
 /**
  * @internal
  */
 interface EnvapterService {
-    getRaw(key: string): string | undefined;
-    get(key: string, def?: string): string | undefined;
+    getRaw(key: EnvKeyInput): string | undefined;
+    get(key: EnvKeyInput, def?: string): string | undefined;
 }
 /**
  * Parser class for handling environment variable template resolution and type conversion
@@ -287,7 +398,7 @@ declare class Parser {
      * @internal
      */
     resolveTemplate(key: string, value: string, stack?: Set<string>): string;
-    convertValue<TFallback>(key: string, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
+    convertValue<TFallback>(key: EnvKeyInput, fallback: TFallback | undefined, converter: EnvaptConverter<TFallback> | undefined, hasFallback: boolean): TFallback | null | undefined;
     private processFallbackForConverter;
     private convertPrimitiveToString;
     private processBuiltInConverter;
@@ -322,11 +433,15 @@ declare abstract class EnvapterBase {
      */
     static get dotenvConfig(): PermittedDotenvConfig;
     protected static refreshCache(): void;
+    protected static resolveKeyInput(keyInput: EnvKeyInput): {
+        key: string;
+        value: string | undefined;
+    };
     protected static get config(): Map<string, unknown>;
     /**
      * Get raw environment variable value without parsing or conversion.
      */
-    getRaw(key: string): string | undefined;
+    getRaw(key: EnvKeyInput): string | undefined;
 }
 
 /**
@@ -398,49 +513,54 @@ declare class PrimitiveMethods extends EnvironmentMethods implements EnvapterSer
     private static _get;
     /**
      * 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<Default extends string | undefined = undefined>(key: string, def?: Default): ConditionalReturn<string, Default>;
+    static get<Default extends string | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<string, Default>;
     /**
      * @see {@link PrimitiveMethods.get}
      */
-    get<Default extends string | undefined = undefined>(key: string, def?: Default): ConditionalReturn<string, Default>;
+    get(key: EnvKeyInput, def?: string): string | undefined;
     /**
      * 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<Default extends number | undefined = undefined>(key: string, def?: Default): ConditionalReturn<number, Default>;
+    static getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
     /**
      * @see {@link PrimitiveMethods.getNumber}
      */
-    getNumber<Default extends number | undefined = undefined>(key: string, def?: Default): ConditionalReturn<number, Default>;
+    getNumber<Default extends number | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<number, Default>;
     /**
      * 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<Default extends boolean | undefined = undefined>(key: string, def?: Default): ConditionalReturn<boolean, Default>;
+    static getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
     /**
      * @see {@link PrimitiveMethods.getBoolean}
      */
-    getBoolean<Default extends boolean | undefined = undefined>(key: string, def?: Default): ConditionalReturn<boolean, Default>;
+    getBoolean<Default extends boolean | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<boolean, Default>;
     /**
      * 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<Default extends bigint | undefined = undefined>(key: string, def?: Default): ConditionalReturn<bigint, Default>;
+    static getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
     /**
      * @see {@link PrimitiveMethods.getBigInt}
      */
-    getBigInt<Default extends bigint | undefined = undefined>(key: string, def?: Default): ConditionalReturn<bigint, Default>;
+    getBigInt<Default extends bigint | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<bigint, Default>;
     /**
      * 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<Default extends symbol | undefined = undefined>(key: string, def?: Default): ConditionalReturn<symbol, Default>;
+    static getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
     /**
      * @see {@link PrimitiveMethods.getSymbol}
      */
-    getSymbol<Default extends symbol | undefined = undefined>(key: string, def?: Default): ConditionalReturn<symbol, Default>;
+    getSymbol<Default extends symbol | undefined = undefined>(key: EnvKeyInput, def?: Default): ConditionalReturn<symbol, Default>;
 }
 
 /**
@@ -451,22 +571,24 @@ declare class AdvancedMethods extends PrimitiveMethods {
     /**
      * Get an environment variable using a built-in converter.
      * Supports both Converter enum values and array converter configurations.
+     * The key can be a single name or an ordered list; the first defined value wins.
      */
-    static getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: string, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
-    static getUsing<TReturn>(key: string, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
+    static getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+    static getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
     /**
      * @see {@link AdvancedMethods.getUsing}
      */
-    getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: string, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
-    getUsing<TReturn>(key: string, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
+    getUsing<TConverter extends BuiltInConverter | ArrayConverter, TFallback = undefined>(key: EnvKeyInput, converter: TConverter, fallback?: TFallback): AdvancedConverterReturn<TConverter, TFallback>;
+    getUsing<TReturn>(key: EnvKeyInput, converter: BuiltInConverter | ArrayConverter, fallback?: TReturn): TReturn;
     /**
      * Get an environment variable using a custom converter function.
+     * Accepts a single key or an ordered list for automatic fallback.
      */
-    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: string, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+    static getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
     /**
      * @see {@link AdvancedMethods.getWith}
      */
-    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: string, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
+    getWith<TReturnType, TFallback extends TReturnType | undefined = undefined>(key: EnvKeyInput, converter: ConverterFunction<TReturnType>, fallback?: TFallback): ConditionalReturn<TReturnType, TFallback>;
 }
 
 /**
@@ -482,10 +604,12 @@ declare class AdvancedMethods extends PrimitiveMethods {
  * // Static usage
  * const port = Envapter.getNumber('PORT', 3000);
  * const url = Envapter.get('API_URL', 'http://localhost');
+ * const replica = Envapter.get(['READONLY_URL', 'DATABASE_URL'], 'sqlite://memory');
  *
  * // Instance usage
  * const env = new Envapter();
  * const dbUrl = env.get('DATABASE_URL', 'sqlite://memory');
+ * const primaryHost = env.get(['PRIMARY_HOST', 'SECONDARY_HOST']);
  * ```
  *
  * @public
@@ -537,7 +661,9 @@ declare enum EnvaptErrorCodes {
     /** Thrown when invalid user-defined configuration is provided */
     InvalidUserDefinedConfig = 302,
     /** Thrown when specified environment files don't exist */
-    EnvFilesNotFound = 303
+    EnvFilesNotFound = 303,
+    /** Thrown when no valid environment key is provided */
+    InvalidKeyInput = 304
 }
 /**
  * Custom error for better DX and debugging when using Envapt.
@@ -552,4 +678,4 @@ declare class EnvaptError extends Error {
     constructor(code: EnvaptErrorCodes, message: string);
 }
 
-export { type AdvancedConverterReturn, type ArrayConverter, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, Converters, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type JsonValue, type MapOfConverterFunctions, type PermittedDotenvConfig, type PrimitiveConstructor, type TimeUnit, type ValidArrayConverterBuiltInType };
+export { type AdvancedConverterReturn, type ArrayConverter, type BuiltInConverter, type BuiltInConverterFunction, type ConditionalReturn, type ConverterFunction, Converters, type EnvKeyInput, Envapt, type EnvaptConverter, EnvaptError, EnvaptErrorCodes, type EnvaptOptions, Envapter, Environment, type InferConverterReturnType, type InferPrimitiveFallbackType, type InferPrimitiveReturnType, type JsonValue, type MapOfConverterFunctions, type PermittedDotenvConfig, type PrimitiveConstructor, type TimeUnit, type ValidArrayConverterBuiltInType };

package/dist/index.mjs

@@ -19,6 +19,7 @@ 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 {
@@ -221,7 +222,10 @@ var Validator = class {
         `Failed to coerce fallback value using ${converter.name}: ${error.message}`
       );
     }
-    throw new EnvaptError(205 /* PrimitiveCoercionFailed */, `Unknown primitive converter: ${converter.name}`);
+    throw new EnvaptError(
+      205 /* PrimitiveCoercionFailed */,
+      `Unknown primitive converter: ${converter.name}`
+    );
   }
   /**
    * Make sure the user hasn't provided prohibited options in their dotenv config
@@ -307,6 +311,26 @@ 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(304 /* InvalidKeyInput */, "At least one environment key must be provided.");
+    }
+    if (normalizedKeys.some((k) => typeof k !== "string")) {
+      throw new EnvaptError(304 /* InvalidKeyInput */, "Environment keys must be strings.");
+    }
+    if (normalizedKeys.some((k) => k.trim() === "")) {
+      throw new EnvaptError(304 /* 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 };
@@ -322,7 +346,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;
   }
 };
 
@@ -331,8 +355,8 @@ var BuiltInConverters = class _BuiltInConverters {
   static {
     __name(this, "BuiltInConverters");
   }
-  static string(raw, fallback) {
-    return String(raw) || fallback;
+  static string(raw, _fallback) {
+    return String(raw);
   }
   static number(raw, fallback) {
     const parsed = Number(raw);
@@ -670,33 +694,36 @@ 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);
+    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);
     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);
   }
-  /**
-   * @see {@link PrimitiveMethods.get}
-   */
   get(key, def) {
     return _PrimitiveMethods._get(key, 0 /* String */, 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);
@@ -710,6 +737,7 @@ var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
   /**
    * 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);
@@ -723,6 +751,7 @@ var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
   /**
    * 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);
@@ -736,6 +765,7 @@ var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
   /**
    * 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);
@@ -754,10 +784,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) {
@@ -765,13 +795,14 @@ 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,
+      resolvedKey,
       fallback,
       converter,
       hasFallback
@@ -878,6 +909,7 @@ var Converters = /* @__PURE__ */ ((Converters2) => {
   Converters2["Time"] = "time";
   return Converters2;
 })(Converters || {});
+/* v8 ignore next -- @preserve */
 
 export { Converters, Envapt, EnvaptError, EnvaptErrorCodes, Envapter, Environment };
 //# sourceMappingURL=index.mjs.map