@karmaniverous/get-dotenv 6.3.0 → 6.4.0

package/dist/chunks/overlayEnv-Bqh_kPGA.mjs

@@ -1,235 +0,0 @@
-import fs from 'fs-extra';
-import 'node:path';
-import { l as loadModuleDefault } from './loadModuleDefault-Dj8B3Stt.mjs';
-
-/**
- * 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);
-
-/** 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 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) {
-    if (!(await fs.exists(absPath)))
-        return;
-    let dyn;
-    try {
-        dyn = await loadModuleDefault(absPath, cacheDirName);
-    }
-    catch {
-        // Preserve legacy/clear guidance used by tests and docs.
-        throw new Error(`Unable to load dynamic TypeScript file: ${absPath}. ` +
-            `Install 'esbuild' (devDependency) to enable TypeScript dynamic modules.`);
-    }
-    applyDynamicMap(target, dyn, env);
-}
-
-const applyKv = (current, kv) => {
-    if (!kv || Object.keys(kv).length === 0)
-        return current;
-    const expanded = dotenvExpandAll(kv, { ref: current, progressive: true });
-    return { ...current, ...expanded };
-};
-const applyConfigSlice = (current, cfg, env) => {
-    if (!cfg)
-        return current;
-    // kind axis: global then env (env overrides global)
-    const afterGlobal = applyKv(current, cfg.vars);
-    const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
-    return applyKv(afterGlobal, envKv);
-};
-function overlayEnv(args) {
-    const { base, env, configs } = args;
-    let current = { ...base };
-    // Source: packaged (public -> local)
-    current = applyConfigSlice(current, configs.packaged, env);
-    // Packaged "local" is not expected by policy; if present, honor it.
-    // We do not have a separate object for packaged.local in sources, keep as-is.
-    // Source: project (public -> local)
-    current = applyConfigSlice(current, configs.project?.public, env);
-    current = applyConfigSlice(current, configs.project?.local, env);
-    // Programmatic explicit vars (top of static tier)
-    if ('programmaticVars' in args) {
-        const toApply = Object.fromEntries(Object.entries(args.programmaticVars).filter(([_k, v]) => typeof v === 'string'));
-        current = applyKv(current, toApply);
-    }
-    return current;
-}
-
-export { applyDynamicMap as a, dotenvExpandAll as b, dotenvExpandFromProcessEnv as c, dotenvExpand as d, loadAndApplyDynamic as l, overlayEnv as o };