@theholocron/env-utils 1.12.0 → 1.14.0

package/README.md

@@ -38,6 +38,17 @@ export const config = map((get) => ({
 }));
 ```
 
+### Precedence chains
+
+`firstEnv(env, names, fallback?)` returns the first variable in `names` that is set and non-empty, else `fallback`:
+
+```typescript
+import { createEnvLookup, firstEnv } from "@theholocron/env-utils";
+
+const env = createEnvLookup();
+const dsn = firstEnv(env, ["MYAPP_SENTRY_DSN", "SENTRY_DSN"], DEFAULT_DSN);
+```
+
 ### Logging
 
 Debug output (key-loaded counts, missing-key warnings, deprecation notices) goes to `console.info`/`console.warn` by default. Pass an `EnvLogger` (any object shaped `{ info(message, meta?), warn(message, meta?) }`) to route it elsewhere:

package/dist/index.d.mts

@@ -195,6 +195,18 @@ export declare const environment: {
 };
 type Environment = (typeof ENVIRONMENTS)[number];
 //#endregion
+//#region src/first-env.d.ts
+/**
+ * Return the value of the first variable in `names` that is set and
+ * non-empty, or `fallback` when none is. Use it for a precedence chain such
+ * as a product-specific name, then the vendor-native name, then a default.
+ *
+ * @example
+ * const dsn = firstEnv(env, ["HOLOCRON_SENTRY_DSN", "SENTRY_DSN"], DEFAULT_DSN);
+ */
+export declare function firstEnv(env: EnvLookup, names: readonly string[], fallback: string): string;
+export declare function firstEnv(env: EnvLookup, names: readonly string[], fallback?: string): string | undefined;
+//#endregion
 //#region src/loader.d.ts
 /**
  * Default loader — calls dotenv/config so the .env file is

package/dist/index.mjs

@@ -315,4 +315,13 @@ function createEnvParser(options) {
 	};
 }
 //#endregion
-export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvLookup, createEnvParser, environment, filterByNamespace, mergeNamespaces };
+//#region src/first-env.ts
+function firstEnv(env, names, fallback) {
+	for (const name of names) {
+		const value = env.get(name);
+		if (value !== void 0) return value;
+	}
+	return fallback;
+}
+//#endregion
+export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvLookup, createEnvParser, environment, filterByNamespace, firstEnv, mergeNamespaces };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/env-utils",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Runtime environment detection and typed env-var parsing.",
   "keywords": [
     "env",