envapt 4.0.2 → 4.1.0

package/dist/index.d.cts

@@ -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,7 +194,7 @@ 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
@@ -207,14 +212,14 @@ type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bi
  * }
  * ```
  */
-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
@@ -229,13 +234,13 @@ declare function Envapt<TFallback>(key: string, options: {
  * }
  * ```
  */
-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
@@ -250,17 +255,21 @@ declare function Envapt<TReturnType>(key: string, options: {
  *   // 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
@@ -284,14 +293,14 @@ declare function Envapt<TConverter extends BuiltInConverter>(key: string, option
  * }
  * ```
  */
-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
@@ -306,14 +315,14 @@ declare function Envapt<TConverter extends ArrayConverter>(key: string, options:
  * }
  * ```
  */
-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
@@ -328,14 +337,14 @@ declare function Envapt<TConstructor extends PrimitiveConstructor>(key: string,
  * }
  * ```
  */
-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
@@ -345,11 +354,11 @@ declare function Envapt<TFallback>(key: string, options: {
  * }
  * ```
  */
-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
@@ -367,14 +376,14 @@ declare function Envapt<_TReturnType = string | null>(key: string): PropertyDeco
  * }
  * ```
  */
-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
@@ -389,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;
@@ -424,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;
 }
 
 /**
@@ -500,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>;
 }
 
 /**
@@ -553,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>;
 }
 
 /**
@@ -584,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
@@ -639,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.
@@ -654,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.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,7 +194,7 @@ 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
@@ -207,14 +212,14 @@ type InferPrimitiveFallbackType<TFallback extends string | number | boolean | bi
  * }
  * ```
  */
-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
@@ -229,13 +234,13 @@ declare function Envapt<TFallback>(key: string, options: {
  * }
  * ```
  */
-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
@@ -250,17 +255,21 @@ declare function Envapt<TReturnType>(key: string, options: {
  *   // 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
@@ -284,14 +293,14 @@ declare function Envapt<TConverter extends BuiltInConverter>(key: string, option
  * }
  * ```
  */
-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
@@ -306,14 +315,14 @@ declare function Envapt<TConverter extends ArrayConverter>(key: string, options:
  * }
  * ```
  */
-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
@@ -328,14 +337,14 @@ declare function Envapt<TConstructor extends PrimitiveConstructor>(key: string,
  * }
  * ```
  */
-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
@@ -345,11 +354,11 @@ declare function Envapt<TFallback>(key: string, options: {
  * }
  * ```
  */
-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
@@ -367,14 +376,14 @@ declare function Envapt<_TReturnType = string | null>(key: string): PropertyDeco
  * }
  * ```
  */
-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
@@ -389,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;
@@ -424,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;
 }
 
 /**
@@ -500,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>;
 }
 
 /**
@@ -553,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>;
 }
 
 /**
@@ -584,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
@@ -639,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.
@@ -654,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 };