@karmaniverous/get-dotenv 0.0.2 → 0.1.1

package/README.md

@@ -12,11 +12,39 @@ Load environment variables with a cascade of environment-aware dotenv files. You
 - Log the result to the console.
 
 The command-line version can pull the environment designator from a number of sources, populate `process.env`, and execute a shell command.
+
+`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.
+
+**So why not just use the very popular [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) package to load dotenv file cascades?** A couple of reasons:
+
+- `dotenv-cli` assumes all your `.env` files are located in your root directory. If you have a lot of environments, you probably want to sequester them into their own directory.
+
+- The `dotenv-cli` syntax requires the environment to be set (the `-c` argument) _before_ the shell command is articulated (after the `--`). This doesn't work if you want to write an NPM script that takes the environment as an argument, since in that case it would have to go at the end.
+
+## Installation
+
+```bash
+npm install @karmaniverous/get-dotenv
+```
+
+## Usage
+
+```js
+import { getDotenv, getDotenvSync } from '@karmaniverous/get-dotenv';
+
+// asynchronous
+const dotenv = await getDotenv(options);
+
+// synchronous
+const dotenvSync = await getDotenvSync(options);
+```
+
+See [OptionsType](#optionstype--object) below for configuration options.
 
 # Command Line Interface
 
 ```text
-Usage: getdotenv [options]
+Usage: getdotenv [options] [-- [command]]
 
 Load environment variables with a cascade of environment-aware
 dotenv files. You can:
@@ -24,10 +52,12 @@ dotenv files. You can:
 * Specify the directory containing your dotenv files.
 * Specify the token that identifies dotenv files (e.g. '.env').
 * Specify the token that identifies private vatiables (e.g. '.local').
-* Specify a default environment, override the default with an
+* Specify a default environment, override the default with an existing
   environment variable, and override both with a direct setting.
 * Exclude public or private variables.
 * Execute a shell command after loading variables.
+* Place the shell command inside the invocation to support npm script
+  arguments for other options.
 
 Options:
   -p, --path <string>                path to dotenv directory (default './')
@@ -38,22 +68,18 @@ Options:
   -v, --variable <string>            environment from variable
   -r, --exclude-private              exclude private variables (default: false)
   -u, --exclude-public               exclude public variables (default: false)
-  -c, --command <string>             shell command
+  -c, --command <string>             shell command string
   -l, --log                          log extracted variables (default: false)
   -h, --help                         display help for command
 ```
 
 # API Documentation
 
-```js
-import { foo, PACKAGE_INFO } from '@karmaniverous/npm-package-template`;
-```
-
 ## Functions
 
 <dl>
 <dt><a href="#getDotenv">getDotenv([options])</a> ⇒ <code>Object</code></dt>
-<dd><p>Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]</p>
+<dd><p>Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATE_TOKEN>]</p>
 </dd>
 <dt><a href="#getDotenvSync">getDotenvSync([options])</a> ⇒ <code>Object</code></dt>
 <dd><p>Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]</p>
@@ -71,7 +97,7 @@ import { foo, PACKAGE_INFO } from '@karmaniverous/npm-package-template`;
 <a name="getDotenv"></a>
 
 ## getDotenv([options]) ⇒ <code>Object</code>
-Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATE_TOKEN>]
 
 **Kind**: global function  
 **Returns**: <code>Object</code> - The combined parsed dotenv object.  
@@ -108,7 +134,7 @@ get-dotenv options type
 | [excludePublic] | <code>bool</code> | exclude public variables (default: false) |
 | [loadProcess] | <code>bool</code> | load dotenv to process.env (default: false) |
 | [log] | <code>bool</code> | log result to console (default: false) |
-| [path] | <code>string</code> | path to target directory |
+| [path] | <code>string</code> | path to target directory (default './') |
 | [privateToken] | <code>string</code> | token indicating private variables (default: 'local'). |
 
 

package/bin/getdotenv/index.js

@@ -1,26 +1,35 @@
 #!/usr/bin/env node
 
+// Import npm packages.
+import spawn from 'cross-spawn';
+import { parseArgsStringToArgv } from 'string-argv';
+
 // Import package exports.
 import { getDotenvSync } from '@karmaniverous/get-dotenv';
-import { execSync } from 'child_process';
 
 // Create CLI.
 import { program } from 'commander';
 
 // CLI description.
-program.name('getdotenv');
-program.description(
-  `Load environment variables with a cascade of environment-aware 
-dotenv files. You can:
-
-* Specify the directory containing your dotenv files.
-* Specify the token that identifies dotenv files (e.g. '.env').
-* Specify the token that identifies private vatiables (e.g. '.local').
-* Specify a default environment, override the default with an 
-  environment variable, and override both with a direct setting. 
-* Exclude public or private variables.
-* Execute a shell command after loading variables.`
-);
+program
+  .name('getdotenv')
+  .usage('[options] [-- [command]]')
+  .description(
+    [
+      `Load environment variables with a cascade of environment-aware`,
+      `dotenv files. You can:`,
+      ``,
+      `* Specify the directory containing your dotenv files.`,
+      `* Specify the token that identifies dotenv files (e.g. '.env').`,
+      `* Specify the token that identifies private vatiables (e.g. '.local').`,
+      `* Specify a default environment, override the default with an existing`,
+      `  environment variable, and override both with a direct setting.`,
+      `* Exclude public or private variables.`,
+      `* Execute a shell command after loading variables.`,
+      `* Place the shell command inside the invocation to support npm script`,
+      `  arguments for other options.`,
+    ].join('\n')
+  );
 
 // CLI options.
 program
@@ -38,7 +47,7 @@ program
   .option('-v, --variable <string>', 'environment from variable')
   .option('-r, --exclude-private', 'exclude private variables (default: false)')
   .option('-u, --exclude-public', 'exclude public variables (default: false)')
-  .option('-c, --command <string>', 'shell command')
+  .option('-c, --command <string>', 'shell command string')
   .option('-l, --log', 'log extracted variables (default: false)');
 
 // Parse CLI options from command line.
@@ -56,11 +65,13 @@ const {
   variable,
 } = program.opts();
 
+if (command && program.args) program.error('command specified twice');
+
 // Get environment.
 const env = environment ?? process.env[variable] ?? defaultEnvironment;
 
 // Load dotenvs.
-const dotenv = getDotenvSync({
+getDotenvSync({
   dotenvToken,
   env,
   excludePrivate,
@@ -72,4 +83,17 @@ const dotenv = getDotenvSync({
 });
 
 // Execute shell command.
-if (command) execSync(command, { env: dotenv, stdio: 'inherit' });
+if (command || program.args) {
+  const argv = program.args ?? parseArgsStringToArgv(command);
+
+  spawn(argv[0], argv.slice(1), { stdio: 'inherit' }).on(
+    'exit',
+    function (exitCode, signal) {
+      if (typeof exitCode === 'number') {
+        process.exit(exitCode);
+      } else {
+        process.kill(process.pid, signal);
+      }
+    }
+  );
+}

package/dist/default/lib/getDotenv/getDotenv.js

@@ -19,12 +19,12 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * @property {bool} [excludePublic] - exclude public variables (default: false)
  * @property {bool} [loadProcess] - load dotenv to process.env (default: false)
  * @property {bool} [log] - log result to console (default: false)
- * @property {string} [path] - path to target directory
+ * @property {string} [path] - path to target directory (default './')
  * @property {string} [privateToken] - token indicating private variables (default: 'local').
  */
 
 /**
- * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+ * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATE_TOKEN>]
  *
  * @async
  * @function getDotenv

package/lib/getDotenv/getDotenv.js

@@ -13,12 +13,12 @@ import { readDotenv, readDotenvSync } from '../readDotEnv/readDotenv.js';
  * @property {bool} [excludePublic] - exclude public variables (default: false)
  * @property {bool} [loadProcess] - load dotenv to process.env (default: false)
  * @property {bool} [log] - log result to console (default: false)
- * @property {string} [path] - path to target directory
+ * @property {string} [path] - path to target directory (default './')
  * @property {string} [privateToken] - token indicating private variables (default: 'local').
  */
 
 /**
- * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+ * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATE_TOKEN>]
  *
  * @async
  * @function getDotenv

package/package.json

@@ -3,7 +3,7 @@
   "bin": {
     "getdotenv": "bin/getdotenv/index.js"
   },
-  "version": "0.0.2",
+  "version": "0.1.1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,9 +32,11 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "commander": "^9.4.1",
+    "cross-spawn": "^7.0.3",
     "dotenv": "^16.0.3",
     "dotenv-expand": "^10.0.0",
-    "fs-extra": "^11.1.0"
+    "fs-extra": "^11.1.0",
+    "string-argv": "^0.3.1"
   },
   "devDependencies": {
     "@babel/cli": "^7.20.7",
@@ -46,7 +48,6 @@
     "@types/node": "^18.11.18",
     "chai": "^4.3.7",
     "concat-md": "^0.5.0",
-    "dotenv-cli": "^6.0.0",
     "eslint": "^8.31.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-plugin-mocha": "^10.1.0",
@@ -85,7 +86,7 @@
     "build": "babel lib -d dist/default/lib --delete-dir-on-start --config-file ./dist/default/.babelrc",
     "doc": "jsdoc2md -c doc/jsdoc.config.json -f lib/**/*.* -t doc/api-template.hbs > doc/3-api.md && concat-md doc --hide-anchor-links > README.md",
     "package": "npm run lint && npm run test && npm run build && npm run doc",
-    "release": "npm run package && dotenv -c -- release-it"
+    "release": "npm run package && node ./bin/getdotenv -- release-it"
   },
   "type": "module"
 }