@karmaniverous/get-dotenv 4.5.2 → 5.0.0-0

package/dist/env-overlay.cjs

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * 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).
+ */
+const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
+    const { ref = process.env, progressive = false } = options;
+    acc[key] = dotenvExpand(values[key], {
+        ...ref,
+        ...(progressive ? acc : {}),
+    });
+    return acc;
+}, {});
+
+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);
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    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) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
+exports.overlayEnv = overlayEnv;

package/dist/env-overlay.d.cts

@@ -0,0 +1,50 @@
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+type ProcessEnv = Record<string, string | undefined>;
+
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+
+type GetDotenvConfigResolved = {
+    dotenvToken?: string;
+    privateToken?: string;
+    paths?: string[];
+    loadProcess?: boolean;
+    log?: boolean;
+    shell?: string | boolean;
+    scripts?: Scripts;
+    vars?: Record<string, string>;
+    envVars?: Record<string, Record<string, string>>;
+    dynamic?: unknown;
+    plugins?: Record<string, unknown>;
+};
+
+type OverlayConfigSources = {
+    packaged?: GetDotenvConfigResolved;
+    project?: {
+        public?: GetDotenvConfigResolved;
+        local?: GetDotenvConfigResolved;
+    };
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+declare const overlayEnv: ({ base, env, configs, programmaticVars, }: {
+    base: ProcessEnv;
+    env: string | undefined;
+    configs: OverlayConfigSources;
+    programmaticVars?: ProcessEnv;
+}) => ProcessEnv;
+
+export { overlayEnv };
+export type { OverlayConfigSources };

package/dist/env-overlay.d.mts

@@ -0,0 +1,50 @@
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+type ProcessEnv = Record<string, string | undefined>;
+
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+
+type GetDotenvConfigResolved = {
+    dotenvToken?: string;
+    privateToken?: string;
+    paths?: string[];
+    loadProcess?: boolean;
+    log?: boolean;
+    shell?: string | boolean;
+    scripts?: Scripts;
+    vars?: Record<string, string>;
+    envVars?: Record<string, Record<string, string>>;
+    dynamic?: unknown;
+    plugins?: Record<string, unknown>;
+};
+
+type OverlayConfigSources = {
+    packaged?: GetDotenvConfigResolved;
+    project?: {
+        public?: GetDotenvConfigResolved;
+        local?: GetDotenvConfigResolved;
+    };
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+declare const overlayEnv: ({ base, env, configs, programmaticVars, }: {
+    base: ProcessEnv;
+    env: string | undefined;
+    configs: OverlayConfigSources;
+    programmaticVars?: ProcessEnv;
+}) => ProcessEnv;
+
+export { overlayEnv };
+export type { OverlayConfigSources };

package/dist/env-overlay.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+type ProcessEnv = Record<string, string | undefined>;
+
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+
+type GetDotenvConfigResolved = {
+    dotenvToken?: string;
+    privateToken?: string;
+    paths?: string[];
+    loadProcess?: boolean;
+    log?: boolean;
+    shell?: string | boolean;
+    scripts?: Scripts;
+    vars?: Record<string, string>;
+    envVars?: Record<string, Record<string, string>>;
+    dynamic?: unknown;
+    plugins?: Record<string, unknown>;
+};
+
+type OverlayConfigSources = {
+    packaged?: GetDotenvConfigResolved;
+    project?: {
+        public?: GetDotenvConfigResolved;
+        local?: GetDotenvConfigResolved;
+    };
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+declare const overlayEnv: ({ base, env, configs, programmaticVars, }: {
+    base: ProcessEnv;
+    env: string | undefined;
+    configs: OverlayConfigSources;
+    programmaticVars?: ProcessEnv;
+}) => ProcessEnv;
+
+export { overlayEnv };
+export type { OverlayConfigSources };

package/dist/env-overlay.mjs

@@ -0,0 +1,161 @@
+/**
+ * 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).
+ */
+const dotenvExpandAll = (values = {}, options = {}) => Object.keys(values).reduce((acc, key) => {
+    const { ref = process.env, progressive = false } = options;
+    acc[key] = dotenvExpand(values[key], {
+        ...ref,
+        ...(progressive ? acc : {}),
+    });
+    return acc;
+}, {});
+
+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);
+};
+/**
+ * Overlay config-provided values onto a base ProcessEnv using precedence axes:
+ * - kind: env \> global
+ * - privacy: local \> public
+ * - source: project \> packaged \> base
+ *
+ * Programmatic explicit vars (if provided) override all config slices.
+ * Progressive expansion is applied within each slice.
+ */
+const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
+    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) {
+        const toApply = Object.fromEntries(Object.entries(programmaticVars).filter(([_k, v]) => typeof v === 'string'));
+        current = applyKv(current, toApply);
+    }
+    return current;
+};
+
+export { overlayEnv };