envapt 4.0.2 → 4.1.0

package/README.md

@@ -34,6 +34,7 @@
 - 🔖 **Tagged Template Resolver** - Tagged template literals with environment variable resolution
 - 🌍 **Environment Detection** - Built-in development/staging/production handling
 - 💪 **Edge Case Handling** - Robust validation and parsing for all scenarios
+- 🔑 **Multi-Key Lookups** - Provide ordered lists of env keys and Envapt will use the first value it finds
 - 🛡️ **Type Safety** - Full TypeScript support with proper type inference _(TypeScript optional)_
 - 📂 **Multiple .env Files** - Load from multiple sources
 - ⚡ **Lightweight** - Minimal overhead with [`dotenv`](https://www.npmjs.com/package/dotenv) bundled
@@ -163,6 +164,10 @@ console.log(`URL: ${url}`); // "http://localhost:8443"
 const corsOrigins = Envapter.getUsing('ALLOWED_ORIGINS', Converters.Array, []);
 const dbConfig = Envapter.getUsing('DATABASE_CONFIG', Converters.Json, {});
 
+// Multi-key lookup: try primary, then replica, then fall back
+const dbUrl = Envapter.get(['PRIMARY_DB_URL', 'REPLICA_DB_URL'], 'sqlite://memory');
+const httpPort = Envapter.getNumber(['APP_PORT', 'PORT'], 3000);
+
 // Tagged template literals
 const message = Envapter.resolve`Server ${'APP_URL'} is ready!`;
 console.log(message); // "Server http://localhost:8443 is ready!"
@@ -182,6 +187,10 @@ class AppConfig extends Envapter {
     @Envapt('APP_URL', { fallback: new URL('http://localhost:3000'), converter: Converters.Url })
     static readonly url: URL;
 
+    // Prefer CLOUD_REDIS_URL but fall back to classic REDIS_URL when missing
+    @Envapt(['CLOUD_REDIS_URL', 'REDIS_URL'], 'redis://localhost:6379')
+    static readonly redisUrl: string;
+
     @Envapt('ALLOWED_ORIGINS', {
         fallback: ['http://localhost:3000'],
         converter: Converters.Array
@@ -241,6 +250,11 @@ The `@Envapt` decorator can be used on both **static** and **instance** class pr
 @Envapt('ENV_VAR', { fallback?: T, converter?: EnvConverter<T> })
 ```
 
+> [!NOTE]
+> The first argument can be a string **or** an ordered array of strings:
+> `@Envapt(['PRIMARY_URL', 'SECONDARY_URL'], { fallback: 'https://example.com' })`.
+> Envapt will resolve the first key that exists.
+>
 > [!TIP]
 > **Generic Typing for Better IntelliSense**
 >
@@ -261,6 +275,13 @@ The `@Envapt` decorator can be used on both **static** and **instance** class pr
 @Envapt('ENV_VAR', fallback?, converter?)
 ```
 
+Need to chain multiple keys with the classic API? Pass an array instead of a string:
+
+```ts
+@Envapt(['HOST_PRIMARY', 'HOST_SECONDARY'], 'localhost')
+static readonly host: string;
+```
+
 #### Automatic Runtime Type Detection
 
 Types are automatically inferred from fallback values.
@@ -557,6 +578,9 @@ const jsonData = Envapter.getUsing('CONFIG_JSON', Converters.Json);
 const urlArray = Envapter.getUsing('API_URLS', { delimiter: ',', type: Converters.Url });
 const customData = Envapter.getWith('RAW_DATA', (raw) => raw?.split('|').map((s) => s.trim()));
 
+// Multi-key inputs work everywhere: Envapt will read left-to-right
+const secretsHost = Envapter.get(['SECRETS_HOST', 'DEFAULT_HOST'], 'localhost');
+
 // Instance methods (same API available)
 const envapter = new Envapter();
 const value = envapter.get('VAR', 'default');
@@ -571,6 +595,7 @@ import { Envapter, Converters } from 'envapt';
 // Use built-in converters directly
 const config = Envapter.getUsing('API_CONFIG', Converters.Json, { default: 'value' });
 const urls = Envapter.getUsing('SERVICE_URLS', { delimiter: '|', type: Converters.Url });
+const pgUrl = Envapter.getUsing(['PRIMARY_PG_URL', 'SECONDARY_PG_URL'], Converters.Url);
 
 // TypeScript: Use type override for better type inference
 const typedConfig = Envapter.getUsing<{ host: string; port: number; ssl: boolean }>('DATABASE_CONFIG', Converters.Json);
@@ -846,6 +871,7 @@ try {
 | `MissingDelimiter` (301)         | Delimiter is missing in array converter config |
 | `InvalidUserDefinedConfig` (302) | Invalid user-defined configuration provided    |
 | `EnvFilesNotFound` (303)         | Specified environment file doesn't exist       |
+| `InvalidKeyInput` (304)          | Invalid key input (not string or string array) |
 
 <div align="right">
 

package/dist/index.cjs

@@ -26,6 +26,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 {
@@ -317,6 +318,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__default.default.env };
@@ -332,7 +353,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;
   }
 };
 
@@ -680,9 +701,10 @@ 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 */)
@@ -696,20 +718,19 @@ var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
   }
   /**
    * 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);
@@ -723,6 +744,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);
@@ -736,6 +758,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);
@@ -749,6 +772,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);
@@ -767,10 +791,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) {
@@ -778,13 +802,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