@karmaniverous/get-dotenv 3.1.18 → 4.0.0-0

package/dist/index.d.cts

@@ -0,0 +1,234 @@
+import { Command } from '@commander-js/extra-typings';
+
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: 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;
+    /**
+     * 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;
+}
+
+type ProcessEnv = Record<string, string | undefined>;
+type GetDotenvDynamicFunction = (vars: ProcessEnv) => string | undefined;
+type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+type Logger = Record<string, (...args: unknown[]) => void>;
+/**
+ * Options passed programmatically to `getDotenv` and `getDotEnvSync`.
+ */
+interface GetDotenvOptions {
+    /**
+     * default target environment (used if `env` is not provided)
+     */
+    defaultEnv?: string;
+    /**
+     * token indicating a dotenv file
+     */
+    dotenvToken?: string;
+    /**
+     * path to file exporting an object keyed to dynamic variable functions
+     */
+    dynamicPath?: string;
+    /**
+     * target environment
+     */
+    env?: string;
+    /**
+     * 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;
+    /**
+     * load dotenv to process.env
+     */
+    loadProcess?: boolean;
+    /**
+     * log result to logger
+     */
+    log?: boolean;
+    /**
+     * logger object (defaults to console)
+     */
+    logger?: Logger;
+    /**
+     * if populated, writes consolidated .env file to this path (follows dotenvExpand rules)
+     */
+    outputPath?: string;
+    /**
+     * array of input directory paths
+     */
+    paths?: string[];
+    /**
+     * filename token indicating private variables
+     */
+    privateToken?: string;
+    /**
+     * explicit variables to include
+     */
+    vars?: ProcessEnv;
+}
+
+/**
+ * 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.
+ */
+declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => string | 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 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.
+ * @returns The value object with expanded string values.
+ */
+declare const dotenvExpandAll: (values?: ProcessEnv, { ref, progressive, }?: {
+    ref?: ProcessEnv;
+    progressive?: boolean;
+}) => Record<string, string | undefined>;
+
+/**
+ * GetDotenv CLI Pre-hook Callback function type. Mutates inbound options &
+ * executes side effects within the `getDotenv` context.
+ */
+type GetDotenvCliPreHookCallback = (options: GetDotenvCliOptions) => Promise<void>;
+/**
+ * GetDotenv CLI Post-hook Callback function type. Executes side effects within
+ * the `getDotenv` context.
+ */
+type GetDotenvCliPostHookCallback = (dotenv: ProcessEnv) => Promise<void>;
+/**
+ * `generateGetDotenvCli` options. Defines local instance of the GetDotenv CLI and
+ * sets defaults that can be overridden by local `getdotenv.config.json` in
+ * projects that import the CLI.
+ */
+interface GetDotenvCliGenerateOptions extends Omit<GetDotenvCliOptions, 'env'> {
+    /**
+     * Cli alias. Should align with the `bin` property in `package.json`.
+     */
+    alias?: string;
+    /**
+     * Cli description (appears in CLI help).
+     */
+    description?: string;
+    /**
+     * Mutates inbound options & executes side effects within the `getDotenv`
+     * context before executing CLI commands.
+     */
+    preHook?: GetDotenvCliPreHookCallback;
+    /**
+     * Executes side effects within the `getDotenv` context after executing CLI
+     * commands.
+     */
+    postHook?: GetDotenvCliPostHookCallback;
+}
+/**
+ * Generate a Commander CLI Command for get-dotenv.
+ */
+declare const generateGetDotenvCli: ({ logger, preHook, postHook, ...cliOptionsCustom }?: GetDotenvCliGenerateOptions) => Command<[], {
+    env?: string | undefined;
+    vars?: string | undefined;
+    command?: string | undefined;
+    outputPath?: string | undefined;
+    loadProcess?: true | undefined;
+    loadProcessOff?: true | undefined;
+    excludeAll?: true | undefined;
+    excludeAllOff?: true | undefined;
+    excludeDynamic?: true | undefined;
+    excludeDynamicOff?: true | undefined;
+    excludeEnv?: true | undefined;
+    excludeEnvOff?: true | undefined;
+    excludeGlobal?: true | undefined;
+    excludeGlobalOff?: true | undefined;
+    excludePrivate?: true | undefined;
+    excludePrivateOff?: true | undefined;
+    excludePublic?: true | undefined;
+    excludePublicOff?: true | undefined;
+    log?: true | undefined;
+    logOff?: true | undefined;
+    debug?: true | undefined;
+    debugOff?: true | undefined;
+    defaultEnv?: string | undefined;
+    dotenvToken?: string | undefined;
+    dynamicPath?: string | undefined;
+    paths?: string | undefined;
+    pathsDelimiter: string;
+    pathsDelimiterPattern: string;
+    privateToken?: string | undefined;
+    varsDelimiter: string;
+    varsDelimiterPattern: string;
+    varsAssignor: string;
+    varsAssignorPattern: string;
+}>;
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ */
+declare const getDotenv: (options?: GetDotenvOptions) => Promise<ProcessEnv>;
+
+export { type GetDotenvDynamic, type GetDotenvOptions, type ProcessEnv, dotenvExpand, dotenvExpandAll, generateGetDotenvCli, getDotenv };

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+import { Command } from '@commander-js/extra-typings';
+
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: 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;
+    /**
+     * 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;
+}
+
+type ProcessEnv = Record<string, string | undefined>;
+type GetDotenvDynamicFunction = (vars: ProcessEnv) => string | undefined;
+type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+type Logger = Record<string, (...args: unknown[]) => void>;
+/**
+ * Options passed programmatically to `getDotenv` and `getDotEnvSync`.
+ */
+interface GetDotenvOptions {
+    /**
+     * default target environment (used if `env` is not provided)
+     */
+    defaultEnv?: string;
+    /**
+     * token indicating a dotenv file
+     */
+    dotenvToken?: string;
+    /**
+     * path to file exporting an object keyed to dynamic variable functions
+     */
+    dynamicPath?: string;
+    /**
+     * target environment
+     */
+    env?: string;
+    /**
+     * 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;
+    /**
+     * load dotenv to process.env
+     */
+    loadProcess?: boolean;
+    /**
+     * log result to logger
+     */
+    log?: boolean;
+    /**
+     * logger object (defaults to console)
+     */
+    logger?: Logger;
+    /**
+     * if populated, writes consolidated .env file to this path (follows dotenvExpand rules)
+     */
+    outputPath?: string;
+    /**
+     * array of input directory paths
+     */
+    paths?: string[];
+    /**
+     * filename token indicating private variables
+     */
+    privateToken?: string;
+    /**
+     * explicit variables to include
+     */
+    vars?: ProcessEnv;
+}
+
+/**
+ * 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.
+ */
+declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => string | 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 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.
+ * @returns The value object with expanded string values.
+ */
+declare const dotenvExpandAll: (values?: ProcessEnv, { ref, progressive, }?: {
+    ref?: ProcessEnv;
+    progressive?: boolean;
+}) => Record<string, string | undefined>;
+
+/**
+ * GetDotenv CLI Pre-hook Callback function type. Mutates inbound options &
+ * executes side effects within the `getDotenv` context.
+ */
+type GetDotenvCliPreHookCallback = (options: GetDotenvCliOptions) => Promise<void>;
+/**
+ * GetDotenv CLI Post-hook Callback function type. Executes side effects within
+ * the `getDotenv` context.
+ */
+type GetDotenvCliPostHookCallback = (dotenv: ProcessEnv) => Promise<void>;
+/**
+ * `generateGetDotenvCli` options. Defines local instance of the GetDotenv CLI and
+ * sets defaults that can be overridden by local `getdotenv.config.json` in
+ * projects that import the CLI.
+ */
+interface GetDotenvCliGenerateOptions extends Omit<GetDotenvCliOptions, 'env'> {
+    /**
+     * Cli alias. Should align with the `bin` property in `package.json`.
+     */
+    alias?: string;
+    /**
+     * Cli description (appears in CLI help).
+     */
+    description?: string;
+    /**
+     * Mutates inbound options & executes side effects within the `getDotenv`
+     * context before executing CLI commands.
+     */
+    preHook?: GetDotenvCliPreHookCallback;
+    /**
+     * Executes side effects within the `getDotenv` context after executing CLI
+     * commands.
+     */
+    postHook?: GetDotenvCliPostHookCallback;
+}
+/**
+ * Generate a Commander CLI Command for get-dotenv.
+ */
+declare const generateGetDotenvCli: ({ logger, preHook, postHook, ...cliOptionsCustom }?: GetDotenvCliGenerateOptions) => Command<[], {
+    env?: string | undefined;
+    vars?: string | undefined;
+    command?: string | undefined;
+    outputPath?: string | undefined;
+    loadProcess?: true | undefined;
+    loadProcessOff?: true | undefined;
+    excludeAll?: true | undefined;
+    excludeAllOff?: true | undefined;
+    excludeDynamic?: true | undefined;
+    excludeDynamicOff?: true | undefined;
+    excludeEnv?: true | undefined;
+    excludeEnvOff?: true | undefined;
+    excludeGlobal?: true | undefined;
+    excludeGlobalOff?: true | undefined;
+    excludePrivate?: true | undefined;
+    excludePrivateOff?: true | undefined;
+    excludePublic?: true | undefined;
+    excludePublicOff?: true | undefined;
+    log?: true | undefined;
+    logOff?: true | undefined;
+    debug?: true | undefined;
+    debugOff?: true | undefined;
+    defaultEnv?: string | undefined;
+    dotenvToken?: string | undefined;
+    dynamicPath?: string | undefined;
+    paths?: string | undefined;
+    pathsDelimiter: string;
+    pathsDelimiterPattern: string;
+    privateToken?: string | undefined;
+    varsDelimiter: string;
+    varsDelimiterPattern: string;
+    varsAssignor: string;
+    varsAssignorPattern: string;
+}>;
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ */
+declare const getDotenv: (options?: GetDotenvOptions) => Promise<ProcessEnv>;
+
+export { type GetDotenvDynamic, type GetDotenvOptions, type ProcessEnv, dotenvExpand, dotenvExpandAll, generateGetDotenvCli, getDotenv };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { Command } from '@commander-js/extra-typings';
+
+/**
+ * Options passed programmatically to `getDotenvCli`.
+ */
+interface GetDotenvCliOptions extends Omit<GetDotenvOptions, 'paths' | 'vars'> {
+    /**
+     * Logs CLI internals when true.
+     */
+    debug?: 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;
+    /**
+     * 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;
+}
+
+type ProcessEnv = Record<string, string | undefined>;
+type GetDotenvDynamicFunction = (vars: ProcessEnv) => string | undefined;
+type GetDotenvDynamic = Record<string, GetDotenvDynamicFunction | ReturnType<GetDotenvDynamicFunction>>;
+type Logger = Record<string, (...args: unknown[]) => void>;
+/**
+ * Options passed programmatically to `getDotenv` and `getDotEnvSync`.
+ */
+interface GetDotenvOptions {
+    /**
+     * default target environment (used if `env` is not provided)
+     */
+    defaultEnv?: string;
+    /**
+     * token indicating a dotenv file
+     */
+    dotenvToken?: string;
+    /**
+     * path to file exporting an object keyed to dynamic variable functions
+     */
+    dynamicPath?: string;
+    /**
+     * target environment
+     */
+    env?: string;
+    /**
+     * 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;
+    /**
+     * load dotenv to process.env
+     */
+    loadProcess?: boolean;
+    /**
+     * log result to logger
+     */
+    log?: boolean;
+    /**
+     * logger object (defaults to console)
+     */
+    logger?: Logger;
+    /**
+     * if populated, writes consolidated .env file to this path (follows dotenvExpand rules)
+     */
+    outputPath?: string;
+    /**
+     * array of input directory paths
+     */
+    paths?: string[];
+    /**
+     * filename token indicating private variables
+     */
+    privateToken?: string;
+    /**
+     * explicit variables to include
+     */
+    vars?: ProcessEnv;
+}
+
+/**
+ * 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.
+ */
+declare const dotenvExpand: (value: string | undefined, ref?: ProcessEnv) => string | 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 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.
+ * @returns The value object with expanded string values.
+ */
+declare const dotenvExpandAll: (values?: ProcessEnv, { ref, progressive, }?: {
+    ref?: ProcessEnv;
+    progressive?: boolean;
+}) => Record<string, string | undefined>;
+
+/**
+ * GetDotenv CLI Pre-hook Callback function type. Mutates inbound options &
+ * executes side effects within the `getDotenv` context.
+ */
+type GetDotenvCliPreHookCallback = (options: GetDotenvCliOptions) => Promise<void>;
+/**
+ * GetDotenv CLI Post-hook Callback function type. Executes side effects within
+ * the `getDotenv` context.
+ */
+type GetDotenvCliPostHookCallback = (dotenv: ProcessEnv) => Promise<void>;
+/**
+ * `generateGetDotenvCli` options. Defines local instance of the GetDotenv CLI and
+ * sets defaults that can be overridden by local `getdotenv.config.json` in
+ * projects that import the CLI.
+ */
+interface GetDotenvCliGenerateOptions extends Omit<GetDotenvCliOptions, 'env'> {
+    /**
+     * Cli alias. Should align with the `bin` property in `package.json`.
+     */
+    alias?: string;
+    /**
+     * Cli description (appears in CLI help).
+     */
+    description?: string;
+    /**
+     * Mutates inbound options & executes side effects within the `getDotenv`
+     * context before executing CLI commands.
+     */
+    preHook?: GetDotenvCliPreHookCallback;
+    /**
+     * Executes side effects within the `getDotenv` context after executing CLI
+     * commands.
+     */
+    postHook?: GetDotenvCliPostHookCallback;
+}
+/**
+ * Generate a Commander CLI Command for get-dotenv.
+ */
+declare const generateGetDotenvCli: ({ logger, preHook, postHook, ...cliOptionsCustom }?: GetDotenvCliGenerateOptions) => Command<[], {
+    env?: string | undefined;
+    vars?: string | undefined;
+    command?: string | undefined;
+    outputPath?: string | undefined;
+    loadProcess?: true | undefined;
+    loadProcessOff?: true | undefined;
+    excludeAll?: true | undefined;
+    excludeAllOff?: true | undefined;
+    excludeDynamic?: true | undefined;
+    excludeDynamicOff?: true | undefined;
+    excludeEnv?: true | undefined;
+    excludeEnvOff?: true | undefined;
+    excludeGlobal?: true | undefined;
+    excludeGlobalOff?: true | undefined;
+    excludePrivate?: true | undefined;
+    excludePrivateOff?: true | undefined;
+    excludePublic?: true | undefined;
+    excludePublicOff?: true | undefined;
+    log?: true | undefined;
+    logOff?: true | undefined;
+    debug?: true | undefined;
+    debugOff?: true | undefined;
+    defaultEnv?: string | undefined;
+    dotenvToken?: string | undefined;
+    dynamicPath?: string | undefined;
+    paths?: string | undefined;
+    pathsDelimiter: string;
+    pathsDelimiterPattern: string;
+    privateToken?: string | undefined;
+    varsDelimiter: string;
+    varsDelimiterPattern: string;
+    varsAssignor: string;
+    varsAssignorPattern: string;
+}>;
+
+/**
+ * Asynchronously process dotenv files of the form `.env[.<ENV>][.<PRIVATE_TOKEN>]`
+ *
+ * @param options - `GetDotenvOptions` object
+ * @returns The combined parsed dotenv object.
+ */
+declare const getDotenv: (options?: GetDotenvOptions) => Promise<ProcessEnv>;
+
+export { type GetDotenvDynamic, type GetDotenvOptions, type ProcessEnv, dotenvExpand, dotenvExpandAll, generateGetDotenvCli, getDotenv };