@theholocron/env-utils 1.1.2 → 1.2.0

package/dist/index.d.mts

@@ -26,6 +26,33 @@ interface EnvParserOptions {
    * native types. Defaults to true.
    */
   parseValues?: boolean;
+  /**
+   * Namespace prefixes to filter and strip from raw env var keys.
+   * When set, only vars whose names start with one of these prefixes
+   * (case-insensitive, followed by `_`) are visible to the parser.
+   * The prefix is stripped before the key is normalised and looked up.
+   *
+   * Uses a **cascade model** — later entries win when the same key
+   * exists under multiple prefixes. Put broad/global namespaces first
+   * and project-specific overrides last (same mental model as CSS
+   * specificity or `Object.assign`).
+   *
+   * This lets you share an org-wide namespace (e.g. `HOLOCRON_` set
+   * once in `~/.bashrc`) as a base, then override individual vars with
+   * a project-specific prefix in `.env`, without copying every global
+   * var into each project.
+   *
+   * @example
+   * // HOLOCRON_DEBUG is the global default; CLI_TEMPLATE_DEBUG overrides it.
+   * createEnvParser({ appName: "my-cli", namespaces: ["HOLOCRON", "CLI_TEMPLATE"] })
+   *
+   * // Single namespace — only HOLOCRON_* vars are visible
+   * createEnvParser({ appName: "my-cli", namespaces: ["HOLOCRON"] })
+   *
+   * // Completely custom — no org namespace at all
+   * createEnvParser({ appName: "my-cli", namespaces: ["MY_TOOL"] })
+   */
+  namespaces?: string[];
 }
 interface EnvParser<T extends EnvObject = EnvObject> {
   /**
@@ -141,4 +168,31 @@ declare class DotenvLoader implements EnvLoader {
   load(): Record<string, string | undefined>;
 }
 //#endregion
-export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, type EnvLoader, type EnvObject, type EnvParser, type EnvParserOptions, type Environment, type Primitive, createEnvParser, environment };
+//#region src/utils/filter-by-namespace.d.ts
+/**
+ * Filter raw env vars to only those matching a namespace prefix,
+ * stripping the prefix from each key before returning.
+ *
+ * Case-insensitive: "holocron_debug" and "HOLOCRON_DEBUG" both match
+ * namespace "HOLOCRON".
+ *
+ * @example
+ * filterByNamespace({ HOLOCRON_DEBUG: "true", PORT: "3000" }, "HOLOCRON")
+ * // → { DEBUG: "true" }
+ */
+declare function filterByNamespace(raw: Record<string, string | undefined>, namespace: string): Record<string, string | undefined>;
+/**
+ * Merge multiple namespace-filtered views of a raw env record.
+ *
+ * Uses a cascade model — **later entries win** over earlier ones when
+ * the same key exists under multiple prefixes. Put broad/global
+ * namespaces first and project-specific overrides last, the same way
+ * you would layer CSS rules or Object.assign calls.
+ *
+ * @example
+ * // HOLOCRON_DEBUG is the org-wide default; CLI_TEMPLATE_DEBUG overrides it.
+ * mergeNamespaces(raw, ["HOLOCRON", "CLI_TEMPLATE"])
+ */
+declare function mergeNamespaces(raw: Record<string, string | undefined>, namespaces: string[]): Record<string, string | undefined>;
+//#endregion
+export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, type EnvLoader, type EnvObject, type EnvParser, type EnvParserOptions, type Environment, type Primitive, createEnvParser, environment, filterByNamespace, mergeNamespaces };

package/dist/index.mjs

@@ -119,6 +119,42 @@ function collectKeys(obj, prefix = "") {
 	return keys;
 }
 //#endregion
+//#region src/utils/filter-by-namespace.ts
+/**
+* Filter raw env vars to only those matching a namespace prefix,
+* stripping the prefix from each key before returning.
+*
+* Case-insensitive: "holocron_debug" and "HOLOCRON_DEBUG" both match
+* namespace "HOLOCRON".
+*
+* @example
+* filterByNamespace({ HOLOCRON_DEBUG: "true", PORT: "3000" }, "HOLOCRON")
+* // → { DEBUG: "true" }
+*/
+function filterByNamespace(raw, namespace) {
+	const prefix = `${namespace.toUpperCase()}_`;
+	const result = {};
+	for (const [key, value] of Object.entries(raw)) if (key.toUpperCase().startsWith(prefix)) result[key.slice(prefix.length)] = value;
+	return result;
+}
+/**
+* Merge multiple namespace-filtered views of a raw env record.
+*
+* Uses a cascade model — **later entries win** over earlier ones when
+* the same key exists under multiple prefixes. Put broad/global
+* namespaces first and project-specific overrides last, the same way
+* you would layer CSS rules or Object.assign calls.
+*
+* @example
+* // HOLOCRON_DEBUG is the org-wide default; CLI_TEMPLATE_DEBUG overrides it.
+* mergeNamespaces(raw, ["HOLOCRON", "CLI_TEMPLATE"])
+*/
+function mergeNamespaces(raw, namespaces) {
+	const result = {};
+	for (const ns of namespaces) Object.assign(result, filterByNamespace(raw, ns));
+	return result;
+}
+//#endregion
 //#region src/utils/get-by-path.ts
 /**
 * Traverse an EnvObject by a path array.
@@ -226,8 +262,9 @@ var DotenvLoader = class {
 * }));
 */
 function createEnvParser(options) {
-	const { appName, loader = new DotenvLoader(), parseValues = true } = options;
-	const env = buildEnvObject(loader.load(), parseValues);
+	const { appName, loader = new DotenvLoader(), parseValues = true, namespaces } = options;
+	const loaded = loader.load();
+	const env = buildEnvObject(namespaces && namespaces.length > 0 ? mergeNamespaces(loaded, namespaces) : loaded, parseValues);
 	debug.log(appName, env);
 	function get(key) {
 		const path = normalizeKey(key);
@@ -249,4 +286,4 @@ function createEnvParser(options) {
 	};
 }
 //#endregion
-export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvParser, environment };
+export { DEFAULT_ENVIRONMENT, DEPLOYED_ENVIRONMENTS, DotenvLoader, ENVIRONMENTS, createEnvParser, environment, filterByNamespace, mergeNamespaces };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/env-utils",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Runtime environment detection and typed env-var parsing.",
   "homepage": "https://github.com/theholocron/utils/tree/main/packages/env#readme",
   "bugs": "https://github.com/theholocron/utils/issues",
@@ -22,8 +22,8 @@
     "README.md"
   ],
   "devDependencies": {
-    "@theholocron/tsdown-config": "^7.6.1",
-    "@theholocron/vitest-config": "^7.6.1",
+    "@theholocron/tsdown-config": "^7.8.1",
+    "@theholocron/vitest-config": "^7.8.1",
     "@tsconfig/node-lts": "^24.0.0",
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "^4.1.10",