@karmaniverous/get-dotenv 3.0.6 → 3.1.0

package/README.md

@@ -6,10 +6,14 @@ Load environment variables with a cascade of environment-aware dotenv files. You
 - Load variables for a specific environment or none.
 - Define dynamic variables progressively in terms of other variables and other logic.
 - Exclude public, private, global, environment-specific, or dynamic variables.
+- Specify explicit variables to include.
 - Extract the resulting variables to an object, `process.env`, a dotenv file, or a logger, in any combination.
+- Execute a shell command within the resulting environment. You can even nest additional `getdotenv` calls!
 - Specify the directories containing your dotenv files.
 - Specify the filename token that identifies dotenv files (e.g. '.env').
 - Specify the filename extension that identifies private variables (e.g. 'local').
+- Set defaults for all options in a [`getdotenv.config.json`](./getdotenv.config.json) file in your project root directory.
+- Generate a custom `getdotenv`-based CLI for use in your own projects.
 
 `getdotenv` relies on the excellent [`dotenv`](https://www.npmjs.com/package/dotenv) parser and uses [`dotenv-expand`](https://www.npmjs.com/package/dotenv-expand) for recursive variable expansion.
 
@@ -63,7 +67,6 @@ Since keys will be evaluated progressively, each successive key function will ha
 
 Implementation always runs a little behind documentation. These topics & improvements are coming soon:
 
-- Rationalize the package's JSDOC to improve the API documentation below.
 - An example of dotenv-based environment config.
 - Integrating `getdotenv` into your npm scripts.
 - Creating a `getdotenv`-based CLI.
@@ -71,57 +74,56 @@ Implementation always runs a little behind documentation. These topics & improve
 
 # Command Line Interface
 
-Note that the defaults below can be changed in your own environment by deriving your base CLI using the `getCli` function.
+Note that the defaults below can be changed in your own environment by deriving your base CLI using the `getDotenvCli` function or placing a `getdotenv.options.json` file in your project root directory.
 
 ```text
 Usage: getdotenv [options] [command]
 
-Base CLI. All options except delimiters follow dotenv-expand rules.
+Base CLI.
 
 Options:
-  -e, --env <string>           target environment
-  --default-env <string>       default target environment (default: "dev")
-  -p, --paths <string>         delimited list of paths to dotenv directory (default: "./")
-  --paths-delimiter <string>   regex paths delimiter (default: "\\s+")
-  -v, --vars <string>          delimited list KEY=VALUE pairs
-  --vars-delimiter <string>    regex vars delimiter (default: "\\s+")
-  --vars-assignor <string>     regex vars assignment operator (default: "=")
-  -y, --dynamic-path <string>  dynamic variables path
-  -o, --output-path <string>   consolidated output file, follows dotenv-expand rules using loaded env vars
-  -n, --exclude-env            exclude environment-specific variables
-  -N, --exclude-env-off        exclude environment-specific variables OFF (default)
-  -g, --exclude-global         exclude global variables
-  -G, --exclude-global-off     exclude global variables OFF (default)
-  -r, --exclude-private        exclude private variables
-  -R, --exclude-private-off    exclude private variables OFF (default)
-  -u, --exclude-public         exclude public variables
-  -U, --exclude-public-off     exclude public variables OFF (default)
-  -z, --exclude-dynamic        exclude dynamic variables
-  -Z, --exclude-dynamic-off    exclude dynamic variables OFF (default)
-  -l, --log                    console log extracted variables
-  -L, --log-off                console log extracted variables OFF (default)
-  -x, --suppress-dotenv        suppress dotenv loading (default: false)
-  -c, --command <string>       shell command string
-  --dotenv-token <string>      token indicating a dotenv file (default: ".env")
-  --private-token <string>     token indicating private variables (default: "local")
-  -D, --debug                  debug mode
-  -h, --help                   display help for command
+  -e, --env <string>                  target environment
+  -v, --vars <string>                 dotenv-expanded delimited key-value pairs: KEY1=VAL1 KEY2=VAL2 (default: "")
+  -c, --command <string>              dotenv-expanded shell command string
+  -o, --output-path <string>          consolidated output file, follows dotenv-expand rules using loaded env vars
+  -p, --load-process                  load variables to process.env ON (default)
+  -P, --load-process-off              load variables to process.env OFF
+  -a, --exclude-all                   exclude all dotenv variables from loading ON
+  -A, --exclude-all-off               exclude all dotenv variables from loading OFF (default)
+  -z, --exclude-dynamic               exclude dynamic dotenv variables from loading ON
+  -Z, --exclude-dynamic-off           exclude dynamic dotenv variables from loading OFF (default)
+  -n, --exclude-env                   exclude environment-specific dotenv variables from loading
+  -N, --exclude-env-off               exclude environment-specific dotenv variables from loading OFF (default)
+  -g, --exclude-global                exclude global dotenv variables from loading ON
+  -G, --exclude-global-off            exclude global dotenv variables from loading OFF (default)
+  -r, --exclude-private               exclude private dotenv variables from loading ON
+  -R, --exclude-private-off           exclude private dotenv variables from loading OFF (default)
+  -u, --exclude-public                exclude public dotenv variables from loading ON
+  -U, --exclude-public-off            exclude public dotenv variables from loading OFF (default)
+  -l, --log                           console log loaded variables ON
+  -L, --log-off                       console log loaded variables OFF (default)
+  -d, --debug                         debug mode ON
+  -D, --debug-off                     debug mode OFF (default)
+  --default-env <string>              default target environment (default: "dev")
+  --dotenv-token <string>             dotenv-expanded token indicating a dotenv file (default: ".env")
+  --dynamic-path <string>             dynamic variables path (default: "./env/dynamic.js")
+  --paths <string>                    dotenv-expanded delimited list of paths to dotenv directory (default: "./ ./env")
+  --paths-delimiter <string>          paths delimiter string (default: " ")
+  --paths-delimiter-pattern <string>  paths delimiter regex pattern (default: "\\s+")
+  --private-token <string>            dotenv-expanded token indicating private variables (default: "local")
+  --vars-delimiter <string>           vars delimiter string (default: " ")
+  --vars-delimiter-pattern <string>   vars delimiter regex pattern (default: "\\s+")
+  --vars-assignor <string>            vars assignment operator string (default: "=")
+  --vars-assignor-pattern <string>    vars assignment operator regex pattern (default: "=")
+  -h, --help                          display help for command
 
 Commands:
-  cmd                          execute shell command string (default command)
-  help [command]               display help for command
+  cmd                                 execute shell command string (default command)
+  help [command]                      display help for command
 ```
 
 # API Documentation
 
-## Constants
-
-<dl>
-<dt><a href="#getCli">getCli</a> ⇒ <code>object</code></dt>
-<dd><p>Generate a CLI for get-dotenv.</p>
-</dd>
-</dl>
-
 ## Functions
 
 <dl>
@@ -131,40 +133,25 @@ Commands:
 <dt><a href="#getDotenvSync">getDotenvSync([options])</a> ⇒ <code>Object</code></dt>
 <dd><p>Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]</p>
 </dd>
+<dt><a href="#getDotenvCli">getDotenvCli([options])</a> ⇒ <code>object</code></dt>
+<dd><p>Generate a CLI for get-dotenv.</p>
+</dd>
 </dl>
 
 ## Typedefs
 
 <dl>
-<dt><a href="#GetDotenvCliOptions">GetDotenvCliOptions</a> : <code>Object</code></dt>
-<dd><p>GetDotenv CLI Options type</p>
+<dt><a href="#GetDotenvOptions">GetDotenvOptions</a> : <code>Object</code></dt>
+<dd><p>get-dotenv options type</p>
 </dd>
-<dt><a href="#GetDotenvPreHookCallback">GetDotenvPreHookCallback</a> ⇒ <code><a href="#GetDotenvCliOptions">GetDotenvCliOptions</a></code></dt>
+<dt><a href="#GetDotenvPreHookCallback">GetDotenvPreHookCallback</a> ⇒ <code>GetDotenvCliOptions</code></dt>
 <dd><p>GetDotenv CLI Pre-hook Callback type. Transforms inbound options &amp; executes side effects.</p>
 </dd>
 <dt><a href="#GetDotenvPostHookCallback">GetDotenvPostHookCallback</a> : <code>function</code></dt>
 <dd><p>GetDotenv CLI Post-hook Callback type. Executes side effects within getdotenv context.</p>
 </dd>
-<dt><a href="#GetDotenvCliConfig">GetDotenvCliConfig</a> : <code>Object</code></dt>
-<dd><p>GetDotenv CLI Config type</p>
-</dd>
-<dt><a href="#OptionsType">OptionsType</a> : <code>Object</code></dt>
-<dd><p>get-dotenv options type</p>
-</dd>
 </dl>
 
-<a name="getCli"></a>
-
-## getCli ⇒ <code>object</code>
-Generate a CLI for get-dotenv.
-
-**Kind**: global constant  
-**Returns**: <code>object</code> - The CLI command.  
-
-| Param | Type | Description |
-| --- | --- | --- |
-| [config] | [<code>GetDotenvCliConfig</code>](#GetDotenvCliConfig) | config object |
-
 <a name="getDotenv"></a>
 
 ## getDotenv([options]) ⇒ <code>Promise.&lt;object&gt;</code>
@@ -175,7 +162,7 @@ Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATE_TOKEN>]
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [options] | [<code>OptionsType</code>](#OptionsType) | options object |
+| [options] | [<code>GetDotenvOptions</code>](#GetDotenvOptions) | options object |
 
 <a name="getDotenvSync"></a>
 
@@ -187,21 +174,57 @@ Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
 
 | Param | Type | Description |
 | --- | --- | --- |
-| [options] | [<code>OptionsType</code>](#OptionsType) | options object |
+| [options] | [<code>GetDotenvOptions</code>](#GetDotenvOptions) | options object |
 
-<a name="GetDotenvCliOptions"></a>
+<a name="getDotenvCli"></a>
 
-## GetDotenvCliOptions : <code>Object</code>
-GetDotenv CLI Options type
+## getDotenvCli([options]) ⇒ <code>object</code>
+Generate a CLI for get-dotenv.
+
+**Kind**: global function  
+**Returns**: <code>object</code> - The CLI command.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | <code>object</code> | options object |
+| [options.alias] | <code>string</code> | cli alias (used for cli help) |
+| [options.command] | <code>string</code> | [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) shell command string |
+| [options.debug] | <code>bool</code> | debug mode |
+| [options.defaultEnv] | <code>string</code> | default target environment |
+| [options.description] | <code>string</code> | cli description (used for cli help) |
+| [options.dotenvToken] | <code>string</code> | [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) token indicating a dotenv file |
+| [options.dynamicPath] | <code>string</code> | path to file exporting an object keyed to dynamic variable functions |
+| [options.excludeDynamic] | <code>bool</code> | exclude dynamic dotenv variables |
+| [options.excludeEnv] | <code>bool</code> | exclude environment-specific dotenv variables |
+| [options.excludeGlobal] | <code>bool</code> | exclude global dotenv variables |
+| [options.excludePrivate] | <code>bool</code> | exclude private dotenv variables |
+| [options.excludePublic] | <code>bool</code> | exclude public dotenv variables |
+| [options.loadProcess] | <code>bool</code> | load variables to process.env |
+| [options.log] | <code>bool</code> | log result to console |
+| [options.logger] | <code>function</code> | logger function |
+| [options.outputPath] | <code>string</code> | consolidated output file, [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) using loaded env vars |
+| [options.paths] | <code>string</code> | [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) delimited list of input directory paths |
+| [options.pathsDelimiter] | <code>string</code> | paths delimiter string |
+| [options.pathsDelimiterPattern] | <code>string</code> | paths delimiter regex pattern |
+| [config.preHook] | [<code>GetDotenvPreHookCallback</code>](#GetDotenvPreHookCallback) | transforms cli options & executes side effects |
+| [options.privateToken] | <code>string</code> | [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) token indicating private variables |
+| [config.postHook] | [<code>GetDotenvPostHookCallback</code>](#GetDotenvPostHookCallback) | executes side effects within getdotenv context |
+| [options.vars] | <code>string</code> | [dotenv-expanded](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env) delimited list of explicit environment variable key-value pairs |
+| [options.varsAssignor] | <code>string</code> | variable key-value assignor string |
+| [options.varsAssignorPattern] | <code>string</code> | variable key-value assignor regex pattern |
+| [options.varsDelimiter] | <code>string</code> | variable key-value pair delimiter string |
+| [options.varsDelimiterPattern] | <code>string</code> | variable key-value pair delimiter regex pattern |
+
+<a name="GetDotenvOptions"></a>
+
+## GetDotenvOptions : <code>Object</code>
+get-dotenv options type
 
 **Kind**: global typedef  
 **Properties**
 
 | Name | Type | Description |
 | --- | --- | --- |
-| [cliInvocation] | <code>string</code> | cli invocation string (used for cli help) |
-| [debug] | <code>bool</code> | debug mode |
-| [defaultEnv] | <code>string</code> | default target environment |
 | [dotenvToken] | <code>string</code> | token indicating a dotenv file |
 | [dynamicPath] | <code>string</code> | path to file exporting an object keyed to dynamic variable functions |
 | [env] | <code>string</code> | target environment |
@@ -210,24 +233,25 @@ GetDotenv CLI Options type
 | [excludeGlobal] | <code>bool</code> | exclude global & dynamic variables |
 | [excludePrivate] | <code>bool</code> | exclude private variables |
 | [excludePublic] | <code>bool</code> | exclude public variables |
-| [log] | <code>bool</code> | log result to console |
+| [loadProcess] | <code>bool</code> | load dotenv to process.env |
+| [log] | <code>bool</code> | log result to logger |
 | [logger] | <code>function</code> | logger function |
 | [outputPath] | <code>string</code> | if populated, writes consolidated .env file to this path (follows [dotenv-expand rules](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env)) |
-| [paths] | <code>string</code> | space-delimited list of input directory paths |
-| [privateToken] | <code>string</code> | token indicating private variables. |
-| [suppressDotenv] | <code>bool</code> | suppress dotenv loading |
+| [paths] | <code>Array.&lt;string&gt;</code> | array of input directory paths |
+| [privateToken] | <code>string</code> | token indicating private variables |
+| [vars] | <code>object</code> | explicit variables to include |
 
 <a name="GetDotenvPreHookCallback"></a>
 
-## GetDotenvPreHookCallback ⇒ [<code>GetDotenvCliOptions</code>](#GetDotenvCliOptions)
+## GetDotenvPreHookCallback ⇒ <code>GetDotenvCliOptions</code>
 GetDotenv CLI Pre-hook Callback type. Transforms inbound options & executes side effects.
 
 **Kind**: global typedef  
-**Returns**: [<code>GetDotenvCliOptions</code>](#GetDotenvCliOptions) - transformed GetDotenv CLI Options object (undefined return value is ignored)  
+**Returns**: <code>GetDotenvCliOptions</code> - transformed GetDotenv CLI Options object (undefined return value is ignored)  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| options | [<code>GetDotenvCliOptions</code>](#GetDotenvCliOptions) | inbound GetDotenv CLI Options object |
+| options | <code>GetDotenvCliOptions</code> | inbound GetDotenv CLI Options object |
 
 <a name="GetDotenvPostHookCallback"></a>
 
@@ -238,50 +262,8 @@ GetDotenv CLI Post-hook Callback type. Executes side effects within getdotenv co
 
 | Param | Type | Description |
 | --- | --- | --- |
-| options | [<code>GetDotenvCliOptions</code>](#GetDotenvCliOptions) | GetDotenv CLI Options object |
 | dotenv | <code>object</code> | dotenv object |
 
-<a name="GetDotenvCliConfig"></a>
-
-## GetDotenvCliConfig : <code>Object</code>
-GetDotenv CLI Config type
-
-**Kind**: global typedef  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| [config] | <code>object</code> | config options |
-| [config.defaultOptions] | [<code>GetDotenvCliOptions</code>](#GetDotenvCliOptions) | default options |
-| [config.preHook] | [<code>GetDotenvPreHookCallback</code>](#GetDotenvPreHookCallback) | transforms inbound options & executes side effects |
-| [config.postHook] | [<code>GetDotenvPostHookCallback</code>](#GetDotenvPostHookCallback) | executes side effects within getdotenv context |
-
-<a name="OptionsType"></a>
-
-## OptionsType : <code>Object</code>
-get-dotenv options type
-
-**Kind**: global typedef  
-**Properties**
-
-| Name | Type | Description |
-| --- | --- | --- |
-| [dotenvToken] | <code>string</code> | token indicating a dotenv file |
-| [dynamicPath] | <code>string</code> | path to file exporting an object keyed to dynamic variable functions |
-| [env] | <code>string</code> | target environment |
-| [excludeDynamic] | <code>bool</code> | exclude dynamic variables |
-| [excludeEnv] | <code>bool</code> | exclude environment-specific variables |
-| [excludeGlobal] | <code>bool</code> | exclude global & dynamic variables |
-| [excludePrivate] | <code>bool</code> | exclude private variables |
-| [excludePublic] | <code>bool</code> | exclude public variables |
-| [loadProcess] | <code>bool</code> | load dotenv to process.env |
-| [log] | <code>bool</code> | log result to logger |
-| [logger] | <code>function</code> | logger function |
-| [outputPath] | <code>string</code> | if populated, writes consolidated .env file to this path (follows [dotenv-expand rules](https://github.com/motdotla/dotenv-expand/blob/master/tests/.env)) |
-| [paths] | <code>Array.&lt;string&gt;</code> | array of input directory paths |
-| [privateToken] | <code>string</code> | token indicating private variables |
-| [vars] | <code>object</code> | explicit variables to include |
-
 
 ---
 

package/bin/getdotenv/index.js

@@ -1,8 +1,8 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 // lib imports
-import { getCli } from '../../lib/getCli.js';
+import { getDotenvCli } from '../../lib/getDotenvCli.js';
 
-const cli = getCli();
+const cli = getDotenvCli();
 
 await cli.parseAsync();

package/dist/default/lib/getDotenv.js

@@ -6,20 +6,25 @@ Object.defineProperty(exports, "__esModule", {
 exports.getDotenvSync = exports.getDotenv = void 0;
 var _dotenvExpand = require("dotenv-expand");
 var _fsExtra = _interopRequireDefault(require("fs-extra"));
+var _lodash = _interopRequireDefault(require("lodash.pickby"));
 var _path = _interopRequireDefault(require("path"));
 var _nanoid = require("nanoid");
-var _dotenvDefaults = require("./dotenvDefaults.js");
+var _options = require("./options.js");
 var _readDotenv = require("./readDotenv.js");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 // npm imports
 
 // lib imports
 
+const pruneVars = (getdotenvDefaultOptions, options) => (0, _lodash.default)({
+  ...(getdotenvDefaultOptions.vars ?? {}),
+  ...(options.vars ?? {})
+}, v => v === null || v === void 0 ? void 0 : v.length);
+
 /**
  * get-dotenv options type
  *
- * @typedef {Object} OptionsType
- *
+ * @typedef {Object} GetDotenvOptions
  * @property {string} [dotenvToken] - token indicating a dotenv file
  * @property {string} [dynamicPath] - path to file exporting an object keyed to dynamic variable functions
  * @property {string} [env] - target environment
@@ -43,7 +48,7 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * @async
  * @function getDotenv
  *
- * @param {OptionsType} [options] - options object
+ * @param {GetDotenvOptions} [options] - options object
  *
  * @returns {Promise<object>} The combined parsed dotenv object.
  */
@@ -52,8 +57,8 @@ const getDotenv = async function () {
   // Apply defaults.
   let {
     dotenvToken,
-    env,
     dynamicPath,
+    env,
     excludeDynamic,
     excludeEnv,
     excludeGlobal,
@@ -61,15 +66,15 @@ const getDotenv = async function () {
     excludePublic,
     loadProcess,
     log,
-    logger,
+    logger = console.log,
     outputPath,
     paths,
-    privateToken,
-    vars = {}
+    privateToken
   } = {
-    ..._dotenvDefaults.dotenvDefaults,
+    ..._options.getdotenvDefaultOptions,
     ...options
   };
+  const vars = pruneVars(_options.getdotenvDefaultOptions, options);
 
   // Read .env files.
   const loaded = await paths.reduce(async (e, p) => {
@@ -101,7 +106,7 @@ const getDotenv = async function () {
   });
 
   // Process dynamic variables.
-  if (dynamicPath && !excludeDynamic) {
+  if (dynamicPath && !excludeDynamic && (await _fsExtra.default.exists(dynamicPath))) {
     const dynamic = new Function(`return ${(await _fsExtra.default.readFile(dynamicPath)).toString()}`)()(dotenv);
     Object.keys(dynamic).forEach(key => {
       Object.assign(dotenv, {
@@ -129,8 +134,8 @@ const getDotenv = async function () {
   if (loadProcess) Object.assign(process.env, dotenv, {
     getdotenvOptions: JSON.stringify({
       dotenvToken,
-      env,
       dynamicPath,
+      env,
       excludeDynamic,
       excludeEnv,
       excludeGlobal,
@@ -151,7 +156,7 @@ const getDotenv = async function () {
  *
  * @function getDotenvSync
  *
- * @param {OptionsType} [options] - options object
+ * @param {GetDotenvOptions} [options] - options object
  *
  * @returns {Object} The combined parsed dotenv object.
  */
@@ -161,8 +166,8 @@ const getDotenvSync = function () {
   // Apply defaults.
   let {
     dotenvToken,
-    env,
     dynamicPath,
+    env,
     excludeDynamic,
     excludeEnv,
     excludeGlobal,
@@ -170,14 +175,15 @@ const getDotenvSync = function () {
     excludePublic,
     loadProcess,
     log,
+    logger = console.log,
     outputPath,
     paths,
-    privateToken,
-    vars
+    privateToken
   } = {
-    ..._dotenvDefaults.dotenvDefaults,
+    ..._options.getdotenvDefaultOptions,
     ...options
   };
+  const vars = pruneVars(_options.getdotenvDefaultOptions, options);
 
   // Read .env files.
   const loaded = paths.reduce((e, p) => {
@@ -208,7 +214,7 @@ const getDotenvSync = function () {
   });
 
   // Process dynamic variables.
-  if (dynamicPath && !excludeDynamic) {
+  if (dynamicPath && !excludeDynamic && _fsExtra.default.existsSync(dynamicPath)) {
     const dynamic = new Function(`return ${_fsExtra.default.readFileSync(dynamicPath).toString()}`)()(dotenv);
     Object.keys(dynamic).forEach(key => {
       Object.assign(dotenv, {
@@ -230,7 +236,7 @@ const getDotenvSync = function () {
   }
 
   // Log result.
-  if (log) console.log(dotenv);
+  if (log) logger(dotenv);
 
   // Load process.env.
   if (loadProcess) Object.assign(process.env, dotenv, {