@karmaniverous/get-dotenv 6.2.4 → 6.4.0

package/dist/chunks/readDotenvCascade-DfFkWMjs.mjs

@@ -0,0 +1,546 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { l as loadModuleDefault } from './loadModuleDefault-Dj8B3Stt.mjs';
+import { parse } from 'dotenv';
+import 'crypto';
+import 'path';
+import 'url';
+
+/**
+ * Dotenv expansion utilities.
+ *
+ * This module implements recursive expansion of environment-variable
+ * references in strings and records. It supports both whitespace and
+ * bracket syntaxes with optional defaults:
+ *
+ * - Whitespace: `$VAR[:default]`
+ * - Bracketed: `${VAR[:default]}`
+ *
+ * Escaped dollar signs (`\$`) are preserved.
+ * Unknown variables resolve to empty string unless a default is provided.
+ */
+/**
+ * Like String.prototype.search but returns the last index.
+ * @internal
+ */
+const searchLast = (str, rgx) => {
+    const matches = Array.from(str.matchAll(rgx));
+    return matches.length > 0 ? (matches.slice(-1)[0]?.index ?? -1) : -1;
+};
+const replaceMatch = (value, match, ref) => {
+    /**
+     * @internal
+     */
+    const group = match[0];
+    const key = match[1];
+    const defaultValue = match[2];
+    if (!key)
+        return value;
+    const replacement = value.replace(group, ref[key] ?? defaultValue ?? '');
+    return interpolate(replacement, ref);
+};
+const interpolate = (value = '', ref = {}) => {
+    /**
+     * @internal
+     */
+    // if value is falsy, return it as is
+    if (!value)
+        return value;
+    // get position of last unescaped dollar sign
+    const lastUnescapedDollarSignIndex = searchLast(value, /(?!(?<=\\))\$/g);
+    // return value if none found
+    if (lastUnescapedDollarSignIndex === -1)
+        return value;
+    // evaluate the value tail
+    const tail = value.slice(lastUnescapedDollarSignIndex);
+    // find whitespace pattern: $KEY:DEFAULT
+    const whitespacePattern = /^\$([\w]+)(?::([^\s]*))?/;
+    const whitespaceMatch = whitespacePattern.exec(tail);
+    if (whitespaceMatch != null)
+        return replaceMatch(value, whitespaceMatch, ref);
+    else {
+        // find bracket pattern: ${KEY:DEFAULT}
+        const bracketPattern = /^\${([\w]+)(?::([^}]*))?}/;
+        const bracketMatch = bracketPattern.exec(tail);
+        if (bracketMatch != null)
+            return replaceMatch(value, bracketMatch, ref);
+    }
+    return value;
+};
+/**
+ * Recursively expands environment variables in a string. Variables may be
+ * presented with optional default as `$VAR[:default]` or `${VAR[:default]}`.
+ * Unknown variables will expand to an empty string.
+ *
+ * @param value - The string to expand.
+ * @param ref - The reference object to use for variable expansion.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpand('Hello $FOO'); // "Hello bar"
+ * dotenvExpand('Hello $BAZ:world'); // "Hello world"
+ * ```
+ *
+ * @remarks
+ * The expansion is recursive. If a referenced variable itself contains
+ * references, those will also be expanded until a stable value is reached.
+ * Escaped references (e.g. `\$FOO`) are preserved as literals.
+ */
+const dotenvExpand = (value, ref = process.env) => {
+    const result = interpolate(value, ref);
+    return result ? result.replace(/\\\$/g, '$') : undefined;
+};
+/**
+ * Recursively expands environment variables in the values of a JSON object.
+ * Variables may be presented with optional default as `$VAR[:default]` or
+ * `${VAR[:default]}`. Unknown variables will expand to an empty string.
+ *
+ * @param values - The values object to expand.
+ * @param options - Expansion options.
+ * @returns The value object with expanded string values.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandAll({ A: '$FOO', B: 'x${FOO}y' });
+ * // => { A: "bar", B: "xbary" }
+ * ```
+ *
+ * @remarks
+ * Options:
+ * - ref: The reference object to use for expansion (defaults to process.env).
+ * - progressive: Whether to progressively add expanded values to the set of
+ *   reference keys.
+ *
+ * When `progressive` is true, each expanded key becomes available for
+ * subsequent expansions in the same object (left-to-right by object key order).
+ */
+function dotenvExpandAll(values, options = {}) {
+    const { ref = process.env, progressive = false, } = options;
+    const out = Object.keys(values).reduce((acc, key) => {
+        acc[key] = dotenvExpand(values[key], {
+            ...ref,
+            ...(progressive ? acc : {}),
+        });
+        return acc;
+    }, {});
+    // Key-preserving return with a permissive index signature to allow later additions.
+    return out;
+}
+/**
+ * Recursively expands environment variables in a string using `process.env` as
+ * the expansion reference. Variables may be presented with optional default as
+ * `$VAR[:default]` or `${VAR[:default]}`. Unknown variables will expand to an
+ * empty string.
+ *
+ * @param value - The string to expand.
+ * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
+ */
+const dotenvExpandFromProcessEnv = (value) => dotenvExpand(value, process.env);
+
+/**
+ * Dotenv provenance model (descriptor-only).
+ *
+ * Requirements addressed:
+ * - Host ctx carries a dotenv provenance mapping describing per-key origin and override history.
+ * - Provenance is descriptor-only (no value payloads).
+ * - Provenance is an ordered stack per key in ascending precedence; the last entry is effective.
+ * - Explicit unsets are represented as `op: 'unset'` without requiring deletion of keys from the env map.
+ */
+/**
+ * Create an empty provenance map.
+ *
+ * @public
+ */
+function createDotenvProvenance() {
+    return {};
+}
+/**
+ * Append a provenance entry for a key.
+ *
+ * @param prov - Provenance map to mutate.
+ * @param key - Variable name.
+ * @param entry - Descriptor-only provenance entry.
+ *
+ * @public
+ */
+function pushDotenvProvenance(prov, key, entry) {
+    (prov[key] ??= []).push(entry);
+}
+
+/** src/env/dynamic.ts
+ * Helpers for applying and loading dynamic variables (JS/TS).
+ *
+ * Requirements addressed:
+ * - Single service to apply a dynamic map progressively.
+ * - Single service to load a JS/TS dynamic module with robust fallbacks (util/loadModuleDefault).
+ * - Unify error messaging so callers show consistent guidance.
+ */
+/**
+ * Apply a dynamic map to the target progressively.
+ * - Functions receive (target, env) and may return string | undefined.
+ * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
+ */
+function applyDynamicMap(target, map, env) {
+    if (!map)
+        return;
+    for (const key of Object.keys(map)) {
+        const val = typeof map[key] === 'function'
+            ? map[key](target, env)
+            : map[key];
+        Object.assign(target, { [key]: val });
+    }
+}
+/**
+ * Load a default-export dynamic map from a JS/TS file (without applying it).
+ *
+ * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
+ * typescript.transpile fallback).
+ *
+ * Error behavior:
+ * - On failure to load/compile/evaluate the module, throws a unified message:
+ *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<GetDotenvDynamic | undefined\>` resolving to the module default export (if present).
+ *
+ * @public
+ */
+async function loadDynamicModuleDefault(absPath, cacheDirName) {
+    if (!(await fs.exists(absPath)))
+        return undefined;
+    try {
+        return await loadModuleDefault(absPath, cacheDirName);
+    }
+    catch {
+        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
+            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
+    }
+}
+/**
+ * Apply a dynamic map and append provenance entries per key.
+ *
+ * Requirements addressed:
+ * - Dynamic provenance entries record `dynamicSource` and optional `dynamicPath` (as provided).
+ * - Record `op: 'unset'` when the dynamic evaluation yields `undefined`.
+ *
+ * @param target - Mutable env map to assign into.
+ * @param map - Dynamic map (functions and/or literals).
+ * @param env - Selected environment name (if any).
+ * @param prov - Provenance map to append into.
+ * @param meta - Dynamic provenance metadata (source tier and optional dynamicPath).
+ *
+ * @public
+ */
+function applyDynamicMapWithProvenance(target, map, env, prov, meta) {
+    if (!map)
+        return;
+    for (const key of Object.keys(map)) {
+        const val = typeof map[key] === 'function'
+            ? map[key](target, env)
+            : map[key];
+        Object.assign(target, { [key]: val });
+        pushDotenvProvenance(prov, key, {
+            kind: 'dynamic',
+            op: typeof val === 'string' ? 'set' : 'unset',
+            dynamicSource: meta.dynamicSource,
+            ...(meta.dynamicSource === 'dynamicPath' &&
+                typeof meta.dynamicPath === 'string' &&
+                meta.dynamicPath.length > 0
+                ? { dynamicPath: meta.dynamicPath }
+                : {}),
+        });
+    }
+}
+/**
+ * Load a default-export dynamic map from a JS/TS file and apply it.
+ * Uses util/loadModuleDefault for robust TS handling (direct import, esbuild,
+ * typescript.transpile fallback).
+ *
+ * Error behavior:
+ * - On failure to load/compile/evaluate the module, throws a unified message:
+ *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
+ */
+async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
+    const dyn = await loadDynamicModuleDefault(absPath, cacheDirName);
+    if (!dyn)
+        return;
+    applyDynamicMap(target, dyn, env);
+}
+
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @param path - Path to dotenv file.
+ * @returns The parsed dotenv object.
+ */
+const readDotenv = async (path) => {
+    try {
+        return (await fs.exists(path)) ? parse(await fs.readFile(path)) : {};
+    }
+    catch {
+        return {};
+    }
+};
+
+/**
+ * Overlay config-provided values onto a base env while recording provenance.
+ *
+ * Requirements addressed:
+ * - Provenance entries for `kind: 'config'` include scope/privacy/env/configScope/configPrivacy.
+ * - Provenance entries for `kind: 'vars'` represent explicit vars overlays.
+ * - Provenance is recorded as layers are applied (no post-hoc reconstruction).
+ * - Record `op: 'unset'` when a layer writes an undefined result (e.g., expansion yields empty).
+ */
+const applyKv = (current, kv) => {
+    if (!kv || Object.keys(kv).length === 0)
+        return { env: current, expanded: {} };
+    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
+    return { env: { ...current, ...expanded }, expanded };
+};
+const opFrom = (v) => typeof v === 'string' ? 'set' : 'unset';
+const applyConfigSlice = (current, cfg, env, prov, meta) => {
+    if (!cfg)
+        return current;
+    // kind axis: global then env (env overrides global)
+    {
+        const { env: next, expanded } = applyKv(current, cfg.vars);
+        for (const key of Object.keys(expanded)) {
+            pushDotenvProvenance(prov, key, {
+                kind: 'config',
+                op: opFrom(expanded[key]),
+                scope: 'global',
+                privacy: meta.privacy,
+                configScope: meta.configScope,
+                configPrivacy: meta.configPrivacy,
+            });
+        }
+        current = next;
+    }
+    if (env && cfg.envVars) {
+        const envKv = cfg.envVars[env];
+        const { env: next, expanded } = applyKv(current, envKv);
+        for (const key of Object.keys(expanded)) {
+            pushDotenvProvenance(prov, key, {
+                kind: 'config',
+                op: opFrom(expanded[key]),
+                scope: 'env',
+                privacy: meta.privacy,
+                env,
+                configScope: meta.configScope,
+                configPrivacy: meta.configPrivacy,
+            });
+        }
+        current = next;
+    }
+    return current;
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars override all config slices.
+ *
+ * @param args - Overlay inputs.
+ * @returns The overlaid env and the updated provenance mapping.
+ *
+ * @public
+ */
+function overlayEnvWithProvenance(args) {
+    const { base, env, configs } = args;
+    const prov = args.provenance ?? createDotenvProvenance();
+    let current = { ...base };
+    // Source: packaged (public only)
+    current = applyConfigSlice(current, configs.packaged, env, prov, {
+        privacy: 'public',
+        configScope: 'packaged',
+        configPrivacy: 'public',
+    });
+    // Source: project (public -> local)
+    current = applyConfigSlice(current, configs.project?.public, env, prov, {
+        privacy: 'public',
+        configScope: 'project',
+        configPrivacy: 'public',
+    });
+    current = applyConfigSlice(current, configs.project?.local, env, prov, {
+        privacy: 'private',
+        configScope: 'project',
+        configPrivacy: 'local',
+    });
+    // Programmatic explicit vars (top of static tier)
+    const pv = args.programmaticVars ?? {};
+    const varsKv = {};
+    const unsetKeys = [];
+    for (const [k, v] of Object.entries(pv)) {
+        if (typeof v === 'string')
+            varsKv[k] = v;
+        else
+            unsetKeys.push(k);
+    }
+    if (Object.keys(varsKv).length > 0) {
+        const { env: next, expanded } = applyKv(current, varsKv);
+        for (const key of Object.keys(expanded)) {
+            const op = opFrom(expanded[key]);
+            pushDotenvProvenance(prov, key, { kind: 'vars', op });
+        }
+        current = next;
+    }
+    // Explicit unsets (rare in current CLI flow; supported for provenance completeness).
+    for (const key of unsetKeys) {
+        current[key] = undefined;
+        pushDotenvProvenance(prov, key, { kind: 'vars', op: 'unset' });
+    }
+    return { env: current, provenance: prov };
+}
+
+/**
+ * Read dotenv files from the deterministic cascade and record provenance.
+ *
+ * Requirements addressed:
+ * - Provenance entries for `kind: 'file'` include scope/privacy/env/path/file (descriptor-only).
+ * - Provenance is ordered in ascending precedence as layers are applied.
+ * - Uses the same file naming convention as get-dotenv (public/private × global/env).
+ */
+const resolveEnvName = (env, defaultEnv) => typeof env === 'string' && env.length > 0
+    ? env
+    : typeof defaultEnv === 'string' && defaultEnv.length > 0
+        ? defaultEnv
+        : undefined;
+const buildFileToken = (args) => {
+    const { dotenvToken, privateToken, scope, privacy, envName } = args;
+    const parts = [dotenvToken];
+    if (scope === 'env')
+        parts.push(envName ?? '');
+    if (privacy === 'private')
+        parts.push(privateToken);
+    return parts.join('.');
+};
+const recordFileLayer = (prov, vars, entry) => {
+    for (const key of Object.keys(vars)) {
+        const v = vars[key];
+        // Record empty-string values as an explicit unset to align with dotenvExpand semantics
+        // (empty string expands to `undefined` in the final progressive expansion step).
+        const op = typeof v === 'string' && v.length > 0 ? 'set' : 'unset';
+        pushDotenvProvenance(prov, key, { kind: 'file', op, ...entry });
+    }
+};
+/**
+ * Read and expand dotenv vars from the deterministic file cascade, recording file provenance.
+ *
+ * @param args - Cascade selector options (tokens/paths/excludes/env).
+ * @returns Expanded dotenv and provenance.
+ *
+ * @public
+ */
+async function readDotenvCascadeWithProvenance(args) {
+    const dotenvToken = args.dotenvToken ?? '.env';
+    const privateToken = args.privateToken ?? 'local';
+    const envName = resolveEnvName(args.env, args.defaultEnv);
+    const prov = createDotenvProvenance();
+    const shouldPublicGlobal = !(args.excludePublic || args.excludeGlobal);
+    const shouldPublicEnv = !(args.excludePublic || args.excludeEnv) && !!envName;
+    const shouldPrivateGlobal = !(args.excludePrivate || args.excludeGlobal);
+    const shouldPrivateEnv = !(args.excludePrivate || args.excludeEnv) && !!envName;
+    let loaded = {};
+    for (const p of args.paths) {
+        const readOne = async (fileToken) => {
+            const abs = path.resolve(p, fileToken);
+            return readDotenv(abs);
+        };
+        if (shouldPublicGlobal) {
+            const token = buildFileToken({
+                dotenvToken,
+                privateToken,
+                scope: 'global',
+                privacy: 'public',
+            });
+            const vars = await readOne(token);
+            recordFileLayer(prov, vars, {
+                scope: 'global',
+                privacy: 'public',
+                path: p,
+                file: token,
+            });
+            loaded = { ...loaded, ...vars };
+        }
+        if (shouldPublicEnv && envName) {
+            const token = buildFileToken({
+                dotenvToken,
+                privateToken,
+                scope: 'env',
+                privacy: 'public',
+                envName,
+            });
+            const vars = await readOne(token);
+            recordFileLayer(prov, vars, {
+                scope: 'env',
+                privacy: 'public',
+                env: envName,
+                path: p,
+                file: token,
+            });
+            loaded = { ...loaded, ...vars };
+        }
+        if (shouldPrivateGlobal) {
+            const token = buildFileToken({
+                dotenvToken,
+                privateToken,
+                scope: 'global',
+                privacy: 'private',
+            });
+            const vars = await readOne(token);
+            recordFileLayer(prov, vars, {
+                scope: 'global',
+                privacy: 'private',
+                path: p,
+                file: token,
+            });
+            loaded = { ...loaded, ...vars };
+        }
+        if (shouldPrivateEnv && envName) {
+            const token = buildFileToken({
+                dotenvToken,
+                privateToken,
+                scope: 'env',
+                privacy: 'private',
+                envName,
+            });
+            const vars = await readOne(token);
+            recordFileLayer(prov, vars, {
+                scope: 'env',
+                privacy: 'private',
+                env: envName,
+                path: p,
+                file: token,
+            });
+            loaded = { ...loaded, ...vars };
+        }
+    }
+    // Match getDotenv behavior: expand progressively across the merged file map.
+    const expanded = dotenvExpandAll(loaded, { progressive: true });
+    return { dotenv: expanded, provenance: prov };
+}
+
+export { applyDynamicMap as a, applyDynamicMapWithProvenance as b, loadAndApplyDynamic as c, dotenvExpandAll as d, createDotenvProvenance as e, readDotenv as f, dotenvExpand as g, dotenvExpandFromProcessEnv as h, loadDynamicModuleDefault as l, overlayEnvWithProvenance as o, pushDotenvProvenance as p, readDotenvCascadeWithProvenance as r };