@karmaniverous/get-dotenv 4.5.2 → 5.0.0-0

package/dist/index.d.ts

@@ -1,74 +1,67 @@
-import { Command } from '@commander-js/extra-typings';
+import { Command } from 'commander';
 
-type Scripts = Record<string, string | {
-    cmd: string;
-    shell?: string | boolean;
-}>;
 /**
- * Options passed programmatically to `getDotenvCli`.
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
  */
-interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
-    /**
-     * Logs CLI internals when true.
-     */
+type RootOptionsShape = {
+    env?: string;
+    vars?: string;
+    command?: string;
+    outputPath?: string;
+    shell?: string | boolean;
+    loadProcess?: boolean;
+    excludeAll?: boolean;
+    excludeDynamic?: boolean;
+    excludeEnv?: boolean;
+    excludeGlobal?: boolean;
+    excludePrivate?: boolean;
+    excludePublic?: boolean;
+    log?: boolean;
     debug?: boolean;
-    /**
-     * A delimited string of paths to dotenv files.
-     */
+    capture?: boolean;
+    defaultEnv?: string;
+    dotenvToken?: string;
+    dynamicPath?: string;
+    trace?: boolean | string[];
     paths?: string;
-    /**
-     * A delimiter string with which to split `paths`. Only used if
-     * `pathsDelimiterPattern` is not provided.
-     */
     pathsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `paths`. Supersedes
-     * `pathsDelimiter`.
-     */
     pathsDelimiterPattern?: string;
-    /**
-     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
-     */
-    scripts?: Scripts;
-    /**
-     * Determines how commands and scripts are executed. If `false` or
-     * `undefined`, commands are executed as plain Javascript using the default
-     * execa parser. If `true`, commands are executed using the default OS shell
-     * parser. Otherwise the user may provide a specific shell string (e.g.
-     * `/bin/bash`)
-     */
-    shell?: string | boolean;
-    /**
-     * A delimited string of key-value pairs declaratively specifying variables &
-     * values to be loaded in addition to any dotenv files.
-     */
-    vars?: string;
-    /**
-     * A string with which to split keys from values in `vars`. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
-    varsAssignor?: string;
-    /**
-     * A regular expression pattern with which to split variable names from values
-     * in `vars`. Supersedes `varsAssignor`.
-     */
-    varsAssignorPattern?: string;
-    /**
-     * A string with which to split `vars` into key-value pairs. Only used if
-     * `varsDelimiterPattern` is not provided.
-     */
+    privateToken?: string;
     varsDelimiter?: string;
-    /**
-     * A regular expression pattern with which to split `vars` into key-value
-     * pairs. Supersedes `varsDelimiter`.
-     */
     varsDelimiterPattern?: string;
-}
+    varsAssignor?: string;
+    varsAssignorPattern?: string;
+    scripts?: ScriptsTable;
+};
+/**
+ * Scripts table shape (configurable shell type).
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | {
+    cmd: string;
+    shell?: TShell;
+}>;
 
+/**
+ * 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;
 type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
 type Logger = Record<string, (...args: unknown[]) => void> | typeof console;
+/**
+ * Helper to define a dynamic map with strong inference.
+ *
+ * @example
+ * const dynamic = defineDynamic(\{ KEY: (\{ FOO = '' \}) =\> FOO + '-x' \});
+ */
+declare const defineDynamic: <T extends GetDotenvDynamic>(d: T) => T;
 /**
  * Options passed programmatically to `getDotenv`.
  */
@@ -82,9 +75,14 @@ interface GetDotenvOptions {
      */
     dotenvToken: string;
     /**
-     * path to JS module default-exporting an object keyed to dynamic variable functions
+     * path to JS/TS module default-exporting an object keyed to dynamic variable functions
      */
     dynamicPath?: string;
+    /**
+     * Programmatic dynamic variables map. When provided, this takes precedence
+     * over {@link GetDotenvOptions.dynamicPath}.
+     */
+    dynamic?: GetDotenvDynamic;
     /**
      * target environment
      */
@@ -137,15 +135,22 @@ interface GetDotenvOptions {
      * explicit variables to include
      */
     vars?: ProcessEnv;
+    /**
+     * Reserved: config loader flag (no-op).
+     * The plugin-first host and generator paths already use the config
+     * loader/overlay pipeline unconditionally (no-op when no config files
+     * are present). This flag is accepted for forward compatibility but
+     * currently has no effect.
+     */
+    useConfigLoader?: boolean;
 }
 /**
- * Converts programmatic CLI options to `getDotenv` options.
- *
+ * Converts programmatic CLI options to `getDotenv` options. *
  * @param cliOptions - CLI options. Defaults to `{}`.
  *
  * @returns `getDotenv` options.
  */
-declare const getDotenvCliOptions2Options: ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }: GetDotenvCliOptions) => GetDotenvOptions;
+declare const getDotenvCliOptions2Options: ({ paths, pathsDelimiter, pathsDelimiterPattern, vars, varsAssignor, varsAssignorPattern, varsDelimiter, varsDelimiterPattern, ...rest }: RootOptionsShape) => GetDotenvOptions;
 
 /**
  * Recursively expands environment variables in a string. Variables may be
@@ -155,6 +160,18 @@ declare const getDotenvCliOptions2Options: ({ paths, pathsDelimiter, pathsDelimi
  * @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.
  */
 declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => string | undefined;
 /**
@@ -162,13 +179,27 @@ declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => str
  * 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.
- * @param progressive - Whether to progressively add expanded values to the
- * set of reference keys.
+ * @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).
  */
-declare const dotenvExpandAll: (values?: ProcessEnv, { ref, progressive, }?: {
+declare const dotenvExpandAll: (values?: ProcessEnv, options?: {
     ref?: ProcessEnv;
     progressive?: boolean;
 }) => Record<string, string | undefined>;
@@ -180,9 +211,85 @@ declare const dotenvExpandAll: (values?: ProcessEnv, { ref, progressive, }?: {
  *
  * @param value - The string to expand.
  * @returns The expanded string.
+ *
+ * @example
+ * ```ts
+ * process.env.FOO = 'bar';
+ * dotenvExpandFromProcessEnv('Hello $FOO'); // "Hello bar"
+ * ```
  */
 declare const dotenvExpandFromProcessEnv: (value: string | undefined) => string | undefined;
 
+type Scripts = Record<string, string | {
+    cmd: string;
+    shell?: string | boolean;
+}>;
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: boolean;
+    /**
+     * When true, capture child stdout/stderr and re-emit after completion.
+     * Useful for tests/CI. Default behavior is streaming via stdio: 'inherit'.
+     */
+    capture?: boolean;
+    /**
+     * A delimited string of paths to dotenv files.
+     */
+    paths?: string;
+    /**
+     * A delimiter string with which to split `paths`. Only used if
+     * `pathsDelimiterPattern` is not provided.
+     */
+    pathsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `paths`. Supersedes
+     * `pathsDelimiter`.
+     */
+    pathsDelimiterPattern?: string;
+    /**
+     * Scripts that can be executed from the CLI, either individually or via the batch subcommand.
+     */
+    scripts?: Scripts;
+    /**
+     * Determines how commands and scripts are executed. If `false` or
+     * `undefined`, commands are executed as plain Javascript using the default
+     * execa parser. If `true`, commands are executed using the default OS shell
+     * parser. Otherwise the user may provide a specific shell string (e.g.
+     * `/bin/bash`)
+     */
+    shell?: string | boolean;
+    /**
+     * A delimited string of key-value pairs declaratively specifying variables &
+     * values to be loaded in addition to any dotenv files.
+     */
+    vars?: string;
+    /**
+     * A string with which to split keys from values in `vars`. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsAssignor?: string;
+    /**
+     * A regular expression pattern with which to split variable names from values
+     * in `vars`. Supersedes `varsAssignor`.
+     */
+    varsAssignorPattern?: string;
+    /**
+     * A string with which to split `vars` into key-value pairs. Only used if
+     * `varsDelimiterPattern` is not provided.
+     */
+    varsDelimiter?: string;
+    /**
+     * A regular expression pattern with which to split `vars` into key-value
+     * pairs. Supersedes `varsDelimiter`.
+     */
+    varsDelimiterPattern?: string;
+}
+
 /**
  * GetDotenv CLI Pre-hook Callback function type. Mutates inbound options &
  * executes side effects within the `getDotenv` context.
@@ -229,6 +336,7 @@ interface GetDotenvCliGenerateOptions extends GetDotenvCliOptions {
 
 /**
  * Generate a Commander CLI Command for get-dotenv.
+ * Orchestration only: delegates building and lifecycle hooks.
  */
 declare const generateGetDotenvCli: (customOptions: Pick<GetDotenvCliGenerateOptions, "importMetaUrl"> & Partial<Omit<GetDotenvCliGenerateOptions, "importMetaUrl">>) => Promise<Command>;
 
@@ -237,7 +345,38 @@ declare const generateGetDotenvCli: (customOptions: Pick<GetDotenvCliGenerateOpt
  *
  * @param options - `GetDotenvOptions` object
  * @returns The combined parsed dotenv object.
+ * * @example Load from the project root with default tokens
+ * ```ts
+ * const vars = await getDotenv();
+ * console.log(vars.MY_SETTING);
+ * ```
+ *
+ * @example Load from multiple paths and a specific environment
+ * ```ts
+ * const vars = await getDotenv({
+ *   env: 'dev',
+ *   dotenvToken: '.testenv',
+ *   privateToken: 'secret',
+ *   paths: ['./', './packages/app'],
+ * });
+ * ```
+ *
+ * @example Use dynamic variables
+ * ```ts
+ * // .env.js default-exports: { DYNAMIC: ({ PREV }) => `${PREV}-suffix` }
+ * const vars = await getDotenv({ dynamicPath: '.env.js' });
+ * ```
+ *
+ * @remarks
+ * - When {@link GetDotenvOptions.loadProcess} is true, the resulting variables are merged
+ *   into `process.env` as a side effect.
+ * - When {@link GetDotenvOptions.outputPath} is provided, a consolidated dotenv file is written.
+ *   The path is resolved after expansion, so it may reference previously loaded vars.
+ *
+ * @throws Error when a dynamic module is present but cannot be imported.
+ * @throws Error when an output path was requested but could not be resolved.
  */
 declare const getDotenv: (options?: Partial<GetDotenvOptions>) => Promise<ProcessEnv>;
 
-export { type GetDotenvDynamic, type GetDotenvOptions, type ProcessEnv, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options };
+export { defineDynamic, dotenvExpand, dotenvExpandAll, dotenvExpandFromProcessEnv, generateGetDotenvCli, getDotenv, getDotenvCliOptions2Options };
+export type { GetDotenvDynamic, GetDotenvOptions, ProcessEnv };