@karmaniverous/get-dotenv 6.0.0-1 → 6.1.0

package/dist/env-overlay.d.ts

@@ -1,42 +1,249 @@
 /**
- * Scripts table shape (configurable shell type).
+ * 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;
+    /** 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;
+    /** 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.
  */
-type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
     cmd: string;
+    /** Shell override for this script. */
     shell?: TShell | undefined;
-}>;
-
-type Scripts = ScriptsTable;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
 
 /**
- * A minimal representation of an environment key/value mapping.
- * Values may be `undefined` to represent "unset".
+ * Unify Scripts via the generic ScriptsTable<TShell> so shell types propagate.
  */
-type ProcessEnv = Record<string, string | undefined>;
+type Scripts = ScriptsTable;
 
 type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
-    loadProcess?: boolean;
-    log?: boolean;
-    shell?: string | boolean;
+    /**
+     * 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).
+ *
+ * @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.
+ */
+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'..."
+ *
+ * @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.
+ */
+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
@@ -58,5 +265,5 @@ declare function overlayEnv<B extends ProcessEnv | Readonly<Record<string, strin
     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.
  *
@@ -122,6 +127,181 @@ function dotenvExpandAll(values, options = {}) {
     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.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
+ *
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
+ */
+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).
+ *
+ * @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;
@@ -136,7 +316,8 @@ const applyConfigSlice = (current, cfg, env) => {
     const envKv = env && cfg.envVars ? cfg.envVars[env] : undefined;
     return applyKv(afterGlobal, envKv);
 };
-function 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);
@@ -146,11 +327,11 @@ function 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 };