@theholocron/env-utils 1.13.0 → 1.15.0

package/README.md

@@ -38,6 +38,34 @@ 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);
+```
+
+`withEnvPrefix(env, prefix)` wraps an `EnvLookup` so `get("KEY")` tries `<prefix>_KEY` first, then `KEY`. The prefix is matched with exact case, so pass it in upper case. Name the variable once and let the namespaced override win:
+
+```typescript
+import { createEnvLookup, withEnvPrefix } from "@theholocron/env-utils";
+
+const env = withEnvPrefix(createEnvLookup(), "MYAPP");
+env.get("SENTRY_DSN"); // MYAPP_SENTRY_DSN, else SENTRY_DSN
+```
+
+### Importing without side effects
+
+The package entry also exports `DotenvLoader`, whose module runs `import "dotenv/config"` and so loads `.env` into `process.env` the moment the package is imported. Libraries that only read variables should import from the `/lookup` subpath, which has `createEnvLookup`, `firstEnv` and `withEnvPrefix` and never touches dotenv:
+
+```typescript
+import { createEnvLookup, firstEnv } from "@theholocron/env-utils/lookup";
+```
+
 ### 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

@@ -1,27 +1,5 @@
+import { i as createEnvLookup, n as firstEnv, r as EnvLookup, t as withEnvPrefix } from "./with-env-prefix-BtxbH3HN.mjs";
 import "dotenv/config";
-//#region src/create-env-lookup.d.ts
-interface EnvLookup {
-  /** Return the string value for `key`, or `undefined` if absent or empty. */
-  get(key: string): string | undefined;
-}
-/**
- * Create a lightweight env lookup backed by a fixed source dict or, when
- * called with no arguments, by a lazy read of `process.env` on every call.
- *
- * Use the no-arg form for the application singleton — it always reflects the
- * current state of `process.env` so tests can mutate it freely:
- *
- * @example
- * // singleton — reads process.env lazily
- * export const env = createEnvLookup();
- *
- * // injectable — tests pass a fake dict
- * export function makeEnv(source?: Record<string, string | undefined>) {
- *   return createEnvLookup(source);
- * }
- */
-export declare function createEnvLookup(source?: Record<string, string | undefined>): EnvLookup;
-//#endregion
 //#region src/types.d.ts
 type Primitive = string | number | boolean;
 type EnvObject = {
@@ -234,4 +212,4 @@ export declare function filterByNamespace(raw: Record<string, string | undefined
  */
 export declare function mergeNamespaces(raw: Record<string, string | undefined>, namespaces: string[]): Record<string, string | undefined>;
 //#endregion
-export type { EnvLoader, EnvLogger, EnvLookup, EnvObject, EnvParser, EnvParserOptions, Environment, Primitive };
+export { type EnvLoader, type EnvLogger, type EnvLookup, type EnvObject, type EnvParser, type EnvParserOptions, type Environment, type Primitive, createEnvLookup, firstEnv, withEnvPrefix };

package/dist/index.mjs

@@ -1,28 +1,5 @@
+import { n as firstEnv, r as createEnvLookup, t as withEnvPrefix } from "./with-env-prefix-CC-WUj7Q.mjs";
 import "dotenv/config";
-//#region src/create-env-lookup.ts
-/**
-* Create a lightweight env lookup backed by a fixed source dict or, when
-* called with no arguments, by a lazy read of `process.env` on every call.
-*
-* Use the no-arg form for the application singleton — it always reflects the
-* current state of `process.env` so tests can mutate it freely:
-*
-* @example
-* // singleton — reads process.env lazily
-* export const env = createEnvLookup();
-*
-* // injectable — tests pass a fake dict
-* export function makeEnv(source?: Record<string, string | undefined>) {
-*   return createEnvLookup(source);
-* }
-*/
-function createEnvLookup(source) {
-	return { get(key) {
-		const val = (source ?? process.env)[key];
-		return typeof val === "string" && val ? val : void 0;
-	} };
-}
-//#endregion
 //#region src/environment.ts
 const ENVIRONMENTS = [
 	"local",
@@ -315,4 +292,4 @@ function createEnvParser(options) {
 	};
 }
 //#endregion
-export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvLookup, createEnvParser, environment, filterByNamespace, mergeNamespaces };
+export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvLookup, createEnvParser, environment, filterByNamespace, firstEnv, mergeNamespaces, withEnvPrefix };

package/dist/lookup.d.mts

@@ -0,0 +1,2 @@
+import { i as createEnvLookup, n as firstEnv, r as EnvLookup, t as withEnvPrefix } from "./with-env-prefix-BtxbH3HN.mjs";
+export { type EnvLookup, createEnvLookup, firstEnv, withEnvPrefix };

package/dist/lookup.mjs

@@ -0,0 +1,2 @@
+import { n as firstEnv, r as createEnvLookup, t as withEnvPrefix } from "./with-env-prefix-CC-WUj7Q.mjs";
+export { createEnvLookup, firstEnv, withEnvPrefix };

package/dist/with-env-prefix-BtxbH3HN.d.mts

@@ -0,0 +1,57 @@
+//#region src/create-env-lookup.d.ts
+interface EnvLookup {
+  /** Return the string value for `key`, or `undefined` if absent or empty. */
+  get(key: string): string | undefined;
+}
+/**
+ * Create a lightweight env lookup backed by a fixed source dict or, when
+ * called with no arguments, by a lazy read of `process.env` on every call.
+ *
+ * Use the no-arg form for the application singleton — it always reflects the
+ * current state of `process.env` so tests can mutate it freely:
+ *
+ * @example
+ * // singleton — reads process.env lazily
+ * export const env = createEnvLookup();
+ *
+ * // injectable — tests pass a fake dict
+ * export function makeEnv(source?: Record<string, string | undefined>) {
+ *   return createEnvLookup(source);
+ * }
+ */
+declare function createEnvLookup(source?: Record<string, string | undefined>): EnvLookup;
+//#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);
+ */
+declare function firstEnv(env: EnvLookup, names: readonly string[], fallback: string): string;
+declare function firstEnv(env: EnvLookup, names: readonly string[], fallback?: string): string | undefined;
+//#endregion
+//#region src/with-env-prefix.d.ts
+/**
+ * Wrap an {@link EnvLookup} so every `get(key)` tries `<prefix>_<key>` first
+ * and falls back to the bare `key`. Callers name the variable once, and the
+ * namespaced override wins when it is set.
+ *
+ * Pass the prefix without a trailing underscore. Empty values are skipped,
+ * as in {@link EnvLookup.get}.
+ *
+ * The prefix is matched with exact case: `"holocron"` looks up
+ * `holocron_TOKEN`, not `HOLOCRON_TOKEN`. An {@link EnvLookup} only answers
+ * exact-name `get` calls, so unlike `filterByNamespace` (which scans a whole
+ * env record) this cannot match case-insensitively. Environment variable
+ * names are conventionally upper case, so pass an upper-case prefix.
+ *
+ * @example
+ * const env = withEnvPrefix(createEnvLookup(), "HOLOCRON");
+ * env.get("SENTRY_DSN"); // HOLOCRON_SENTRY_DSN, else SENTRY_DSN
+ */
+declare function withEnvPrefix(env: EnvLookup, prefix: string): EnvLookup;
+//#endregion
+export { createEnvLookup as i, firstEnv as n, EnvLookup as r, withEnvPrefix as t };

package/dist/with-env-prefix-CC-WUj7Q.mjs

@@ -0,0 +1,59 @@
+//#region src/create-env-lookup.ts
+/**
+* Create a lightweight env lookup backed by a fixed source dict or, when
+* called with no arguments, by a lazy read of `process.env` on every call.
+*
+* Use the no-arg form for the application singleton — it always reflects the
+* current state of `process.env` so tests can mutate it freely:
+*
+* @example
+* // singleton — reads process.env lazily
+* export const env = createEnvLookup();
+*
+* // injectable — tests pass a fake dict
+* export function makeEnv(source?: Record<string, string | undefined>) {
+*   return createEnvLookup(source);
+* }
+*/
+function createEnvLookup(source) {
+	return { get(key) {
+		const val = (source ?? process.env)[key];
+		return typeof val === "string" && val ? val : void 0;
+	} };
+}
+//#endregion
+//#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
+//#region src/with-env-prefix.ts
+/**
+* Wrap an {@link EnvLookup} so every `get(key)` tries `<prefix>_<key>` first
+* and falls back to the bare `key`. Callers name the variable once, and the
+* namespaced override wins when it is set.
+*
+* Pass the prefix without a trailing underscore. Empty values are skipped,
+* as in {@link EnvLookup.get}.
+*
+* The prefix is matched with exact case: `"holocron"` looks up
+* `holocron_TOKEN`, not `HOLOCRON_TOKEN`. An {@link EnvLookup} only answers
+* exact-name `get` calls, so unlike `filterByNamespace` (which scans a whole
+* env record) this cannot match case-insensitively. Environment variable
+* names are conventionally upper case, so pass an upper-case prefix.
+*
+* @example
+* const env = withEnvPrefix(createEnvLookup(), "HOLOCRON");
+* env.get("SENTRY_DSN"); // HOLOCRON_SENTRY_DSN, else SENTRY_DSN
+*/
+function withEnvPrefix(env, prefix) {
+	return { get(key) {
+		return env.get(`${prefix}_${key}`) ?? env.get(key);
+	} };
+}
+//#endregion
+export { firstEnv as n, createEnvLookup as r, withEnvPrefix as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/env-utils",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Runtime environment detection and typed env-var parsing.",
   "keywords": [
     "env",
@@ -24,6 +24,11 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
+    },
+    "./lookup": {
+      "types": "./dist/lookup.d.mts",
+      "import": "./dist/lookup.mjs",
+      "default": "./dist/lookup.mjs"
     }
   },
   "files": [