@karmaniverous/get-dotenv 6.0.0 → 6.1.0

package/README.md

@@ -70,7 +70,7 @@ Embed a CLI quickly (shipped plugins wired for you):
 #!/usr/bin/env node
 import { createCli } from '@karmaniverous/get-dotenv/cli';
 
-await createCli({ alias: 'toolbox' }).run(process.argv.slice(2));
+await createCli({ alias: 'toolbox' })();
 ```
 
 More first steps and tips at [Getting Started](./guides/getting-started.md)

package/dist/cli.mjs

@@ -169,6 +169,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -404,14 +408,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * 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.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * - `.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();
@@ -483,6 +493,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -494,6 +508,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -711,6 +729,10 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
  * - Else if `requiredKeys` is present, check presence (value !== undefined).
  * - Returns a flat list of issue strings; caller decides warn vs fail.
+ *
+ * @param finalEnv - Final composed environment to validate.
+ * @param sources - Resolved config sources providing `schema` and/or `requiredKeys`.
+ * @returns A list of human-readable issue strings (empty when valid).
  */
 const validateEnvAgainstSources = (finalEnv, sources) => {
     const pick = (getter) => {
@@ -770,6 +792,11 @@ const validateEnvAgainstSources = (finalEnv, sources) => {
  * 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)
@@ -789,6 +816,12 @@ function applyDynamicMap(target, map, env) {
  * 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)))
@@ -1951,6 +1984,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2463,6 +2500,10 @@ const toHelpConfig = (merged, plugins) => {
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 function composeNestedEnv(merged, dotenv) {
     const out = {};
@@ -2485,6 +2526,7 @@ function composeNestedEnv(merged, dotenv) {
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 const stripOne = (s) => {
     if (s.length < 2)
@@ -2497,6 +2539,9 @@ const stripOne = (s) => {
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 function maybePreserveNodeEvalArgv(args) {
     if (args.length >= 3) {
@@ -2963,7 +3008,10 @@ function applyRootVisibility(program, visibility) {
  * Apply resolved AWS context to `process.env` and `ctx.plugins`.
  * Centralizes logic shared between the plugin action and `afterResolve` hook.
  *
+ * @param out - Resolved AWS context to apply.
+ * @param ctx - Host context to publish non-sensitive metadata into.
  * @param setProcessEnv - Whether to write credentials/region to `process.env` (default true).
+ * @returns Nothing.
  */
 function applyAwsContext(out, ctx, setProcessEnv = true) {
     const { profile, region, credentials } = out;
@@ -2999,6 +3047,9 @@ const unquote = (s) => s.length >= 2 &&
     : s;
 /**
  * Parse AWS credentials from JSON output (AWS CLI v2 export-credentials).
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsJson = (txt) => {
     try {
@@ -3022,6 +3073,9 @@ const parseExportCredentialsJson = (txt) => {
 /**
  * Parse AWS credentials from environment-export output (shell-agnostic).
  * Supports POSIX `export KEY=VAL` and PowerShell `$Env:KEY=VAL`.
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsEnv = (txt) => {
     const lines = txt.split(/\r?\n/);
@@ -3107,6 +3161,7 @@ const exportCredentials = async (profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
  * Applies strategy (cli-export vs none) and handling for SSO login-on-demand.
  *
  * @param options - Context options including current dotenv and plugin config.
+ * @returns A `Promise\<AwsContext\>` containing any resolved profile, region, and credentials.
  */
 const resolveAwsContext = async ({ dotenv, cfg, }) => {
     const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';
@@ -14509,14 +14564,21 @@ const cmdPlugin = (options = {}) => {
 };
 
 /**
- * Ensure a directory exists.
+ * Ensure a directory exists (parents included).
+ *
+ * @param p - Directory path to create.
+ * @returns A `Promise\<string\>` resolving to the provided `p` value.
  */
 const ensureDir = async (p) => {
     await fs.ensureDir(p);
     return p;
 };
 /**
- * Write text content to a file, ensuring the parent directory exists.
+ * Write UTF-8 text content to a file, ensuring the parent directory exists.
+ *
+ * @param dest - Destination file path.
+ * @param data - File contents to write.
+ * @returns A `Promise\<void\>` which resolves when the file is written.
  */
 const writeFile$1 = async (dest, data) => {
     await ensureDir(path.dirname(dest));
@@ -14528,6 +14590,7 @@ const writeFile$1 = async (dest, data) => {
  * @param src - Source file path.
  * @param dest - Destination file path.
  * @param substitutions - Map of token literals to replacement strings.
+ * @returns A `Promise\<void\>` which resolves when the file has been copied.
  */
 const copyTextFile = async (src, dest, substitutions) => {
     const contents = await fs.readFile(src, 'utf-8');
@@ -14539,6 +14602,10 @@ const copyTextFile = async (src, dest, substitutions) => {
 /**
  * Ensure a set of lines exist (exact match) in a file. Creates the file
  * when missing. Returns whether it was created or changed.
+ *
+ * @param filePath - Target file path to create/update.
+ * @param lines - Lines which must be present (exact string match).
+ * @returns A `Promise\<object\>` describing whether the file was created and/or changed.
  */
 const ensureLines = async (filePath, lines) => {
     const exists = await fs.pathExists(filePath);
@@ -14566,11 +14633,23 @@ const ensureLines = async (filePath, lines) => {
     return { created: false, changed: false };
 };
 
-// Templates root used by the scaffolder
+/**
+ * Absolute path to the shipped templates directory.
+ *
+ * Used by the init scaffolder to locate files under `templates/` at runtime.
+ *
+ * @remarks
+ * This path is resolved relative to the current working directory. It assumes
+ * the `templates/` folder is present alongside the installed package (or in the
+ * repository when running from source).
+ */
 const TEMPLATES_ROOT = path.resolve('templates');
 
 /**
  * Plan the copy operations for configuration files.
+ *
+ * @param options - Planning options for config scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planConfigCopies = ({ format, withLocal, destRoot, }) => {
     const copies = [];
@@ -14614,6 +14693,9 @@ const planConfigCopies = ({ format, withLocal, destRoot, }) => {
 };
 /**
  * Plan the copy operations for the CLI skeleton.
+ *
+ * @param options - Planning options for CLI scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planCliCopies = ({ cliName, destRoot, }) => {
     const subs = { __CLI_NAME__: cliName };
@@ -14635,6 +14717,8 @@ const planCliCopies = ({ cliName, destRoot, }) => {
 /**
  * Determine whether the current environment should be treated as non-interactive.
  * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
+ *
+ * @returns `true` when running in a CI-like environment or when stdin/stdout are not TTYs.
  */
 const isNonInteractive = () => {
     const ciLike = process.env.CI ||
@@ -14647,6 +14731,11 @@ const isNonInteractive = () => {
 /**
  * Prompt the user for a file collision decision.
  * Returns a single-character code representing overwrite/example/skip (or 'all' variants).
+ *
+ * @param filePath - Path of the colliding file (for display).
+ * @param logger - Logger used for user-facing messages.
+ * @param rl - Readline interface used to capture user input.
+ * @returns A single-character decision code.
  */
 const promptDecision = async (filePath, logger, rl) => {
     logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);

package/dist/cliHost.d.ts

@@ -436,6 +436,11 @@ declare function definePlugin<TOptions extends GetDotenvOptions, Schema extends
 }): PluginWithInstanceHelpers<TOptions, z.output<Schema>>;
 declare function definePlugin<TOptions extends GetDotenvOptions>(spec: DefineSpec<TOptions>): PluginWithInstanceHelpers<TOptions, {}>;
 
+/**
+ * Helper to decide whether to capture child stdio.
+ * Checks GETDOTENV_STDIO env var or the provided bag capture flag.
+ */
+declare const shouldCapture: (bagCapture?: boolean) => boolean;
 /**
  * Options for runCommandResult (buffered execution).
  *
@@ -641,17 +646,25 @@ declare const getRootCommand: (cmd: CommandUnknownOpts) => CommandUnknownOpts;
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 declare function composeNestedEnv(merged: GetDotenvCliOptions | Record<string, unknown>, dotenv: Record<string, string | undefined>): Record<string, string>;
 /**
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 declare const stripOne: (s: string) => string;
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 declare function maybePreserveNodeEvalArgv(args: string[]): string[];
 
@@ -742,5 +755,5 @@ declare const resolveCliOptions: <T extends Partial<RootOptionsShape> & {
  */
 declare const buildSpawnEnv: (base?: NodeJS.ProcessEnv, overlay?: Record<string, string | undefined>) => NodeJS.ProcessEnv;
 
-export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, stripOne, toHelpConfig };
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };
 export type { BrandOptions, DefineSpec, GetDotenvCliCtx, GetDotenvCliOptions, GetDotenvCliPlugin, GetDotenvCliPublic, InferPluginConfig, PluginChildEntry, PluginFlattenedEntry, PluginNamespaceOverride, PluginWithInstanceHelpers, ResolveAndLoadOptions, ResolveCliOptionsResult, ResolvedHelpConfig, RootOptionsShape, RunCommandOptions, RunCommandResultOptions, ScriptDef, Scripts, ScriptsTable };

package/dist/cliHost.mjs

@@ -152,6 +152,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -387,14 +391,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * 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.
+ * 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.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @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();
@@ -466,6 +476,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -477,6 +491,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -691,6 +709,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * 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)
@@ -710,6 +733,12 @@ function applyDynamicMap(target, map, env) {
  * 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)))
@@ -1299,6 +1328,11 @@ const dbg = (...args) => {
         console.error('[getdotenv:run]', ...args);
     }
 };
+/**
+ * Helper to decide whether to capture child stdio.
+ * Checks GETDOTENV_STDIO env var or the provided bag capture flag.
+ */
+const shouldCapture = (bagCapture) => process.env.GETDOTENV_STDIO === 'pipe' || Boolean(bagCapture);
 // Strip repeated symmetric outer quotes (single or double) until stable.
 // This is safe for argv arrays passed to execa (no quoting needed) and avoids
 // passing quote characters through to Node (e.g., for `node -e "<code>"`).
@@ -1795,6 +1829,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2320,6 +2358,10 @@ const toHelpConfig = (merged, plugins) => {
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 function composeNestedEnv(merged, dotenv) {
     const out = {};
@@ -2342,6 +2384,7 @@ function composeNestedEnv(merged, dotenv) {
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 const stripOne = (s) => {
     if (s.length < 2)
@@ -2354,6 +2397,9 @@ const stripOne = (s) => {
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 function maybePreserveNodeEvalArgv(args) {
     if (args.length >= 3) {
@@ -2602,4 +2648,4 @@ const buildSpawnEnv = (base, overlay) => {
  */
 const defineScripts = () => (t) => t;
 
-export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, stripOne, toHelpConfig };
+export { GetDotenvCli, baseGetDotenvCliOptions, buildSpawnEnv, composeNestedEnv, definePlugin, defineScripts, getRootCommand, maybePreserveNodeEvalArgv, readMergedOptions, resolveCliOptions, resolveCommand, resolveShell, runCommand, runCommandResult, shouldCapture, stripOne, toHelpConfig };

package/dist/config.d.ts

@@ -226,6 +226,10 @@ declare const toFileUrl: (p: string) => string;
  * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
  * - Else if `requiredKeys` is present, check presence (value !== undefined).
  * - Returns a flat list of issue strings; caller decides warn vs fail.
+ *
+ * @param finalEnv - Final composed environment to validate.
+ * @param sources - Resolved config sources providing `schema` and/or `requiredKeys`.
+ * @returns A list of human-readable issue strings (empty when valid).
  */
 declare const validateEnvAgainstSources: (finalEnv: ProcessEnv, sources: ResolvedConfigSources) => string[];
 

package/dist/config.mjs

@@ -148,14 +148,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * 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.
+ * Load a module default export from a JS/TS file with robust fallbacks.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * 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();
@@ -372,6 +378,10 @@ const toFileUrl = (p) => pathToFileURL(path.resolve(p)).toString();
  * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
  * - Else if `requiredKeys` is present, check presence (value !== undefined).
  * - Returns a flat list of issue strings; caller decides warn vs fail.
+ *
+ * @param finalEnv - Final composed environment to validate.
+ * @param sources - Resolved config sources providing `schema` and/or `requiredKeys`.
+ * @returns A list of human-readable issue strings (empty when valid).
  */
 const validateEnvAgainstSources = (finalEnv, sources) => {
     const pick = (getter) => {

package/dist/env-overlay.d.ts

@@ -179,6 +179,11 @@ type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<Get
  * 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;
 /**
@@ -189,6 +194,12 @@ declare function applyDynamicMap(target: ProcessEnv, map?: GetDotenvDynamic, env
  * 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>;
 

package/dist/env-overlay.mjs

@@ -165,14 +165,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * 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.
+ * Load a module default export from a JS/TS file with robust fallbacks.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * 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();
@@ -250,6 +256,11 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
  * 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)
@@ -269,6 +280,12 @@ function applyDynamicMap(target, map, env) {
  * 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)))