@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/env-overlay.d.ts

@@ -1,35 +1,238 @@
 /**
- * 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;
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ *
+ * @public
+ */
+interface RootOptionsShape {
+    /** Target environment (dotenv-expanded). */
+    env?: string;
+    /** Explicit variable overrides (dotenv-expanded). */
+    vars?: string;
+    /** Command to execute (dotenv-expanded). */
+    command?: string;
+    /** Output path for the consolidated environment file (dotenv-expanded). */
+    outputPath?: string;
+    /**
+     * Shell execution strategy.
+     * - `true`: use default OS shell.
+     * - `false`: use plain execution (no shell).
+     * - string: use specific shell path.
+     */
     shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
+    /** Whether to load variables into `process.env`. */
     loadProcess?: boolean;
+    /** Exclude all variables from loading. */
+    excludeAll?: boolean;
+    /** Exclude dynamic variables. */
+    excludeDynamic?: boolean;
+    /** Exclude environment-specific variables. */
+    excludeEnv?: boolean;
+    /** Exclude global variables. */
+    excludeGlobal?: boolean;
+    /** Exclude private variables. */
+    excludePrivate?: boolean;
+    /** Exclude public variables. */
+    excludePublic?: boolean;
+    /** Enable console logging of loaded variables. */
     log?: boolean;
-    shell?: string | boolean;
+    /** Enable debug logging to stderr. */
+    debug?: boolean;
+    /** Capture child process stdio (useful for tests/CI). */
+    capture?: boolean;
+    /** Fail on validation errors (schema/requiredKeys). */
+    strict?: boolean;
+    /** Enable presentation-time redaction of secret-like keys. */
+    redact?: boolean;
+    /** Enable entropy warnings for high-entropy values. */
+    warnEntropy?: boolean;
+    /** Entropy threshold (bits/char) for warnings (default 3.8). */
+    entropyThreshold?: number;
+    /** Minimum string length to check for entropy (default 16). */
+    entropyMinLength?: number;
+    /** Regex patterns for keys to exclude from entropy checks. */
+    entropyWhitelist?: ReadonlyArray<string>;
+    /** Additional regex patterns for keys to redact. */
+    redactPatterns?: string[];
+    /** Default target environment when not specified. */
+    defaultEnv?: string;
+    /** Token indicating a dotenv file (default: ".env"). */
+    dotenvToken?: string;
+    /** Path to dynamic variables module (default: undefined). */
+    dynamicPath?: string;
+    /**
+     * Emit diagnostics for child env composition.
+     * - `true`: trace all keys.
+     * - `string[]`: trace selected keys.
+     */
+    trace?: boolean | string[];
+    /** Paths to search for dotenv files (space-delimited string or array). */
+    paths?: string;
+    /** Delimiter for paths string (default: space). */
+    pathsDelimiter?: string;
+    /** Regex pattern for paths delimiter. */
+    pathsDelimiterPattern?: string;
+    /** Token indicating private variables (default: "local"). */
+    privateToken?: string;
+    /** Delimiter for vars string (default: space). */
+    varsDelimiter?: string;
+    /** Regex pattern for vars delimiter. */
+    varsDelimiterPattern?: string;
+    /** Assignment operator for vars (default: "="). */
+    varsAssignor?: string;
+    /** Regex pattern for vars assignment operator. */
+    varsAssignorPattern?: string;
+    /** Table of named scripts for execution. */
+    scripts?: ScriptsTable;
+}
+/**
+ * Definition for a single script entry.
+ */
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
+    cmd: string;
+    /** Shell override for this script. */
+    shell?: TShell | undefined;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+
+/**
+ * Unify Scripts via the generic ScriptsTable<TShell> so shell types propagate.
+ */
+type Scripts = ScriptsTable;
+
+type GetDotenvConfigResolved = {
+    /**
+     * Help-time/runtime root defaults applied by the host (collapsed families; CLI‑like).
+     */
+    rootOptionDefaults?: Partial<RootOptionsShape>;
+    /**
+     * Help-time visibility for root flags; when a key is false the corresponding
+     * option(s) are hidden in root help output.
+     */
+    rootOptionVisibility?: Partial<Record<keyof RootOptionsShape, boolean>>;
+    /**
+     * Merged scripts table for resolving commands and shell behavior.
+     * Entries may be strings or objects with `cmd` and optional `shell`.
+     */
     scripts?: Scripts;
+    /**
+     * Keys required to be present in the final composed environment.
+     * Validation occurs after overlays and dynamics.
+     */
     requiredKeys?: string[];
+    /**
+     * Optional validation schema (e.g., Zod). When present and it exposes
+     * `safeParse(finalEnv)`, the host executes it once after overlays.
+     */
     schema?: unknown;
+    /**
+     * Public global variables (string‑only).
+     */
     vars?: Record<string, string>;
+    /**
+     * Public per‑environment variables (string‑only).
+     */
     envVars?: Record<string, Record<string, string>>;
+    /**
+     * Dynamic variable definitions (JS/TS configs only).
+     */
     dynamic?: unknown;
+    /**
+     * Per‑plugin configuration slices keyed by realized mount path
+     * (for example, "aws/whoami").
+     */
     plugins?: Record<string, unknown>;
 };
 
+/**
+ * Canonical programmatic options and helpers for get-dotenv.
+ *
+ * Requirements addressed:
+ * - GetDotenvOptions derives from the Zod schema output (single source of truth).
+ * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
+ * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
+ * - Preserve existing behavior for defaults resolution and compat converters.
+ */
+
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+type ProcessEnv = Record<string, string | undefined>;
+/**
+ * Dynamic variable function signature. Receives the current expanded variables
+ * and the selected environment (if any), and returns either a string to set
+ * or `undefined` to unset/skip the variable.
+ */
+type GetDotenvDynamicFunction = (vars: ProcessEnv, env: string | undefined) => string | undefined;
+/**
+ * A map of dynamic variable definitions.
+ * Keys are variable names; values are either literal strings or functions.
+ */
+type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+
+/**
+ * Apply a dynamic map to the target progressively.
+ * - Functions receive (target, env) and may return string | undefined.
+ * - Literals are assigned directly (including undefined).
+ */
+declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env?: string): void;
+/**
+ * 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'..."
+ */
+declare function loadAndApplyDynamic(target: ProcessEnv, absPath: string, env: string | undefined, cacheDirName: string): Promise<void>;
+
+/**
+ * Configuration sources for environment overlay.
+ * Organized by scope (packaged vs project) and privacy (public vs local).
+ *
+ * @public
+ */
 type OverlayConfigSources = {
+    /** Packaged configuration (public). */
     packaged?: GetDotenvConfigResolved;
+    /** Project configuration (public and local). */
     project?: {
+        /** Project public configuration. */
         public?: GetDotenvConfigResolved;
+        /** Project local configuration. */
         local?: GetDotenvConfigResolved;
     };
 };
+/**
+ * Base options for overlaying config-provided values onto a dotenv map.
+ *
+ * @typeParam B - base env shape
+ * @public
+ */
+interface OverlayEnvOptionsBase<B extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>> {
+    /** Base environment variables. */
+    base: B;
+    /** Target environment name. */
+    env: string | undefined;
+    /** Configuration sources to overlay. */
+    configs: OverlayConfigSources;
+}
+/**
+ * Options including explicit programmatic variables which take top precedence.
+ *
+ * @typeParam B - base env shape
+ * @typeParam P - programmatic vars shape
+ * @public
+ */
+interface OverlayEnvOptionsWithProgrammatic<B extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>, P extends Record<string, string | undefined> | Readonly<Record<string, string | undefined>>> extends OverlayEnvOptionsBase<B> {
+    programmaticVars: P;
+}
 /**
  * Overlay config-provided values onto a base ProcessEnv using precedence axes:
  * - kind: env \> global
@@ -39,12 +242,17 @@ type OverlayConfigSources = {
  * 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;
+declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, string | undefined>>>(args: {
+    base: B;
+    env: string | undefined;
+    configs: OverlayConfigSources;
+}): B;
+declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, string | undefined>>, P extends ProcessEnv | Readonly<Record<string, string | undefined>>>(args: {
+    base: B;
     env: string | undefined;
     configs: OverlayConfigSources;
-    programmaticVars?: ProcessEnv;
-}) => ProcessEnv;
+    programmaticVars: P;
+}): B & P;
 
-export { overlayEnv };
-export type { OverlayConfigSources };
+export { applyDynamicMap, loadAndApplyDynamic, overlayEnv };
+export type { OverlayConfigSources, OverlayEnvOptionsBase, OverlayEnvOptionsWithProgrammatic };

package/dist/env-overlay.mjs

@@ -1,3 +1,8 @@
+import fs from 'fs-extra';
+import { createHash } from 'crypto';
+import path from 'path';
+import url from 'url';
+
 /**
  * Dotenv expansion utilities.
  *
@@ -109,14 +114,176 @@ const dotenvExpand = (value, ref = process.env) => {
  * 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;
-}, {});
+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;
+}
+
+const importDefault = async (fileUrl) => {
+    const mod = (await import(fileUrl));
+    return mod.default;
+};
+const cacheHash = (absPath, mtimeMs) => createHash('sha1')
+    .update(absPath)
+    .update(String(mtimeMs))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
+ */
+const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
+    try {
+        const entries = await fs.readdir(cacheDir);
+        const mine = entries
+            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
+            .map((f) => path.join(cacheDir, f));
+        if (mine.length <= keep)
+            return;
+        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const toDelete = stats.slice(keep).map((s) => s.p);
+        await Promise.all(toDelete.map(async (p) => {
+            try {
+                await fs.remove(p);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }));
+    }
+    catch {
+        // best-effort cleanup
+    }
+};
+/**
+ * Load a module default export from a JS/TS file with robust fallbacks:
+ * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
+ *   1) try direct import (if a TS loader is active),
+ *   2) esbuild bundle to a temp ESM file,
+ *   3) typescript.transpileModule fallback for simple modules.
+ *
+ * @param absPath - absolute path to source file
+ * @param cacheDirName - cache subfolder under .tsbuild
+ */
+const loadModuleDefault = async (absPath, cacheDirName) => {
+    const ext = path.extname(absPath).toLowerCase();
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
+        return importDefault(fileUrl);
+    }
+    // Try direct import first (TS loader active)
+    try {
+        const dyn = await importDefault(fileUrl);
+        if (dyn)
+            return dyn;
+    }
+    catch {
+        /* fall through */
+    }
+    const stat = await fs.stat(absPath);
+    const hash = cacheHash(absPath, stat.mtimeMs);
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
+    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
+    // Try esbuild
+    try {
+        const esbuild = (await import('esbuild'));
+        await esbuild.build({
+            entryPoints: [absPath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            target: 'node20',
+            outfile: cacheFile,
+            sourcemap: false,
+            logLevel: 'silent',
+        });
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        /* fall through to TS transpile */
+    }
+    // TypeScript transpile fallback
+    try {
+        const ts = (await import('typescript'));
+        const code = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(code, {
+            compilerOptions: {
+                module: 'ESNext',
+                target: 'ES2022',
+                moduleResolution: 'NodeNext',
+            },
+        }).outputText;
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
+    }
+    catch {
+        // Caller decides final error wording; rethrow for upstream mapping.
+        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
+    }
+};
+
+/** 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).
+ */
+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'..."
+ */
+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)
@@ -132,16 +299,8 @@ const applyConfigSlice = (current, cfg, env) => {
     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, }) => {
+function overlayEnv(args) {
+    const { base, env, configs } = args;
     let current = { ...base };
     // Source: packaged (public -> local)
     current = applyConfigSlice(current, configs.packaged, env);
@@ -151,11 +310,11 @@ const overlayEnv = ({ base, env, configs, programmaticVars, }) => {
     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'));
+    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 { overlayEnv };
+export { applyDynamicMap, loadAndApplyDynamic, overlayEnv };