@karmaniverous/get-dotenv 0.0.1

package/.env

@@ -0,0 +1 @@
+APP_SETTING=root_app_setting

package/.env.dev

@@ -0,0 +1 @@
+ENV_SETTING=root_dev_setting

package/.env.test

@@ -0,0 +1 @@
+ENV_SETTING=root_test_setting

package/README.md

@@ -0,0 +1,118 @@
+# get-dotenv
+
+Load environment variables with a cascade of environment-aware dotenv files. You can:
+
+- Load dotenv files synchronously or asynchronously.
+- 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').
+- Load variables for a specific environment or none.
+- Exclude public or private variables.
+- Extract variables to an object, to `process.env`, or both.
+- 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.
+
+# Command Line Interface
+
+```text
+Usage: getdotenv [options]
+
+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.
+
+Options:
+  -p, --path <string>                path to dotenv directory (default './')
+  -t, --dotenv-token <string>        token indicating a dotenv file (default: '.env')
+  -i, --private-token <string>       token indicating private variables (default: 'local')
+  -d, --defaultEnvironment <string>  default environment
+  -e, --environment <string>         designated environment
+  -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
+  -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>
+<dt><a href="#getDotenv">getDotenv([options])</a> ⇒ <code>Object</code></dt>
+<dd><p>Synchronously process dotenv files of the form .env[.<ENV>][.&lt;PRIVATEEXT]</p>
+</dd>
+</dl>
+
+## Typedefs
+
+<dl>
+<dt><a href="#OptionsType">OptionsType</a> : <code>Object</code></dt>
+<dd><p>get-dotenv options type</p>
+</dd>
+</dl>
+
+<a name="getDotenv"></a>
+
+## getDotenv([options]) ⇒ <code>Object</code>
+Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+
+**Kind**: global function  
+**Returns**: <code>Object</code> - The combined parsed dotenv object.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | [<code>OptionsType</code>](#OptionsType) | options object |
+
+<a name="getDotenv"></a>
+
+## getDotenv([options]) ⇒ <code>Object</code>
+Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATEEXT]
+
+**Kind**: global function  
+**Returns**: <code>Object</code> - The combined parsed dotenv object.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [options] | [<code>OptionsType</code>](#OptionsType) | options object |
+
+<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 (default: '.env') |
+| [env] | <code>string</code> | target environment |
+| [excludePrivate] | <code>bool</code> | exclude private variables (default: false) |
+| [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 |
+| [privateToken] | <code>string</code> | token indicating private variables (default: 'local'). |
+
+
+---
+
+See more great templates and other tools on
+[my GitHub Profile](https://github.com/karmaniverous)!

package/bin/getdotenv/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+// 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.`
+);
+
+// CLI options.
+program
+  .option('-p, --path <string>', "path to dotenv directory (default './')")
+  .option(
+    '-t, --dotenv-token <string>',
+    "token indicating a dotenv file (default: '.env')"
+  )
+  .option(
+    '-i, --private-token <string>',
+    "token indicating private variables (default: 'local')"
+  )
+  .option('-d, --defaultEnvironment <string>', 'default environment')
+  .option('-e, --environment <string>', 'designated environment')
+  .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('-l, --log', 'log extracted variables (default: false)');
+
+// Parse CLI options from command line.
+program.parse();
+const {
+  command,
+  defaultEnvironment,
+  dotenvToken,
+  environment,
+  excludePrivate,
+  excludePublic,
+  log,
+  path,
+  privateToken,
+  variable,
+} = program.opts();
+
+// Get environment.
+const env = environment ?? process.env[variable] ?? defaultEnvironment;
+
+// Load dotenvs.
+const dotenv = getDotenvSync({
+  dotenvToken,
+  env,
+  excludePrivate,
+  excludePublic,
+  loadProcess: true,
+  log,
+  path,
+  privateToken,
+});
+
+// Execute shell command.
+if (command) execSync(command, { env: dotenv, stdio: 'inherit' });

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

@@ -0,0 +1,107 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getDotenvSync = exports.getDotenv = void 0;
+var _path = _interopRequireDefault(require("path"));
+var _dotenvExpand = require("dotenv-expand");
+var _readDotenv = require("../readDotEnv/readDotenv.js");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * get-dotenv options type
+ *
+ * @typedef {Object} OptionsType
+ *
+ * @property {string} [dotenvToken] - token indicating a dotenv file (default: '.env')
+ * @property {string} [env] - target environment
+ * @property {bool} [excludePrivate] - exclude private variables (default: false)
+ * @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} [privateToken] - token indicating private variables (default: 'local').
+ */
+
+/**
+ * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+ *
+ * @async
+ * @function getDotenv
+ *
+ * @param {OptionsType} [options] - options object
+ *
+ * @returns {Object} The combined parsed dotenv object.
+ */
+const getDotenv = async function () {
+  let {
+    dotenvToken = '.env',
+    env,
+    excludePrivate = false,
+    excludePublic = false,
+    loadProcess = false,
+    log = false,
+    path: dotenvPath = './',
+    privateToken = 'local'
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  // Read .env files.
+  const dotenv = (0, _dotenvExpand.expand)({
+    ...(excludePublic ? {} : {
+      ...(await (0, _readDotenv.readDotenv)(_path.default.resolve(dotenvPath, dotenvToken))),
+      ...(env ? await (0, _readDotenv.readDotenv)(_path.default.resolve(dotenvPath, `${dotenvToken}.${env}`)) : {})
+    }),
+    ...(excludePrivate ? {} : {
+      ...(await (0, _readDotenv.readDotenv)(_path.default.resolve(dotenvPath, `${dotenvToken}.${privateToken}`))),
+      ...(env ? await (0, _readDotenv.readDotenv)(_path.default.resolve(dotenvPath, `${dotenvToken}.${env}.${privateToken}`)) : {})
+    })
+  });
+
+  // Log result.
+  if (log) console.log(dotenv);
+
+  // Load process.env.
+  if (loadProcess) Object.assign(process.env, dotenv);
+  return dotenv;
+};
+
+/**
+ * Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATEEXT]
+ *
+ * @function getDotenv
+ *
+ * @param {OptionsType} [options] - options object
+ *
+ * @returns {Object} The combined parsed dotenv object.
+ */
+exports.getDotenv = getDotenv;
+const getDotenvSync = function () {
+  let {
+    dotenvToken = '.env',
+    env,
+    excludePrivate = false,
+    excludePublic = false,
+    loadProcess = false,
+    log = false,
+    path: dotenvPath = './',
+    privateToken = 'local'
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  // Read .env files.
+  const dotenv = (0, _dotenvExpand.expand)({
+    ...(excludePublic ? {} : {
+      ...(0, _readDotenv.readDotenvSync)(_path.default.resolve(dotenvPath, dotenvToken)),
+      ...(env ? (0, _readDotenv.readDotenvSync)(_path.default.resolve(dotenvPath, `${dotenvToken}.${env}`)) : {})
+    }),
+    ...(excludePrivate ? {} : {
+      ...(0, _readDotenv.readDotenvSync)(_path.default.resolve(dotenvPath, `${dotenvToken}.${privateToken}`)),
+      ...(env ? (0, _readDotenv.readDotenvSync)(_path.default.resolve(dotenvPath, `${dotenvToken}.${env}.${privateToken}`)) : {})
+    })
+  });
+
+  // Log result.
+  if (log) console.log(dotenv);
+
+  // Load process.env.
+  if (loadProcess) Object.assign(process.env, dotenv);
+  return dotenv;
+};
+exports.getDotenvSync = getDotenvSync;

package/dist/default/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "getDotenv", {
+  enumerable: true,
+  get: function () {
+    return _getDotenv.getDotenv;
+  }
+});
+Object.defineProperty(exports, "getDotenvSync", {
+  enumerable: true,
+  get: function () {
+    return _getDotenv.getDotenvSync;
+  }
+});
+var _getDotenv = require("./getDotenv/getDotenv.js");

package/dist/default/lib/readDotEnv/readDotenv.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.readDotenvSync = exports.readDotenv = void 0;
+var _dotenv = require("dotenv");
+var _fsExtra = _interopRequireDefault(require("fs-extra"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @async
+ * @private
+ * @function readDotenv
+ *
+ * @param {string} path - Any value.
+ *
+ * @returns {Object} The parsed dotenv object.
+ */
+const readDotenv = async path => {
+  try {
+    return (0, _dotenv.parse)(await _fsExtra.default.readFile(path));
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * Synchronously reads a dotenv file & parses it into an object.
+ *
+ * @private
+ * @function readDotenvSync
+ *
+ * @param {string} path - Any value.
+ *
+ * @returns {Object} The parsed dotenv object.
+ */
+exports.readDotenv = readDotenv;
+const readDotenvSync = path => {
+  try {
+    return (0, _dotenv.parse)(_fsExtra.default.readFileSync(path));
+  } catch {
+    return {};
+  }
+};
+exports.readDotenvSync = readDotenvSync;

package/dist/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/getDotenv/getDotenv.js

@@ -0,0 +1,131 @@
+import path from 'path';
+import { expand } from 'dotenv-expand';
+import { readDotenv, readDotenvSync } from '../readDotEnv/readDotenv.js';
+
+/**
+ * get-dotenv options type
+ *
+ * @typedef {Object} OptionsType
+ *
+ * @property {string} [dotenvToken] - token indicating a dotenv file (default: '.env')
+ * @property {string} [env] - target environment
+ * @property {bool} [excludePrivate] - exclude private variables (default: false)
+ * @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} [privateToken] - token indicating private variables (default: 'local').
+ */
+
+/**
+ * Asynchronously process dotenv files of the form .env[.<ENV>][.<PRIVATETOKEN>]
+ *
+ * @async
+ * @function getDotenv
+ *
+ * @param {OptionsType} [options] - options object
+ *
+ * @returns {Object} The combined parsed dotenv object.
+ */
+export const getDotenv = async ({
+  dotenvToken = '.env',
+  env,
+  excludePrivate = false,
+  excludePublic = false,
+  loadProcess = false,
+  log = false,
+  path: dotenvPath = './',
+  privateToken = 'local',
+} = {}) => {
+  // Read .env files.
+  const dotenv = expand({
+    ...(excludePublic
+      ? {}
+      : {
+          ...(await readDotenv(path.resolve(dotenvPath, dotenvToken))),
+          ...(env
+            ? await readDotenv(
+                path.resolve(dotenvPath, `${dotenvToken}.${env}`)
+              )
+            : {}),
+        }),
+    ...(excludePrivate
+      ? {}
+      : {
+          ...(await readDotenv(
+            path.resolve(dotenvPath, `${dotenvToken}.${privateToken}`)
+          )),
+          ...(env
+            ? await readDotenv(
+                path.resolve(
+                  dotenvPath,
+                  `${dotenvToken}.${env}.${privateToken}`
+                )
+              )
+            : {}),
+        }),
+  });
+
+  // Log result.
+  if (log) console.log(dotenv);
+
+  // Load process.env.
+  if (loadProcess) Object.assign(process.env, dotenv);
+
+  return dotenv;
+};
+
+/**
+ * Synchronously process dotenv files of the form .env[.<ENV>][.<PRIVATEEXT]
+ *
+ * @function getDotenv
+ *
+ * @param {OptionsType} [options] - options object
+ *
+ * @returns {Object} The combined parsed dotenv object.
+ */
+export const getDotenvSync = ({
+  dotenvToken = '.env',
+  env,
+  excludePrivate = false,
+  excludePublic = false,
+  loadProcess = false,
+  log = false,
+  path: dotenvPath = './',
+  privateToken = 'local',
+} = {}) => {
+  // Read .env files.
+  const dotenv = expand({
+    ...(excludePublic
+      ? {}
+      : {
+          ...readDotenvSync(path.resolve(dotenvPath, dotenvToken)),
+          ...(env
+            ? readDotenvSync(path.resolve(dotenvPath, `${dotenvToken}.${env}`))
+            : {}),
+        }),
+    ...(excludePrivate
+      ? {}
+      : {
+          ...readDotenvSync(
+            path.resolve(dotenvPath, `${dotenvToken}.${privateToken}`)
+          ),
+          ...(env
+            ? readDotenvSync(
+                path.resolve(
+                  dotenvPath,
+                  `${dotenvToken}.${env}.${privateToken}`
+                )
+              )
+            : {}),
+        }),
+  });
+
+  // Log result.
+  if (log) console.log(dotenv);
+
+  // Load process.env.
+  if (loadProcess) Object.assign(process.env, dotenv);
+
+  return dotenv;
+};

package/lib/index.js

@@ -0,0 +1 @@
+export { getDotenv, getDotenvSync } from './getDotenv/getDotenv.js';

package/lib/readDotEnv/readDotenv.js

@@ -0,0 +1,39 @@
+import { parse } from 'dotenv';
+import fs from 'fs-extra';
+
+/**
+ * Asynchronously read a dotenv file & parse it into an object.
+ *
+ * @async
+ * @private
+ * @function readDotenv
+ *
+ * @param {string} path - Any value.
+ *
+ * @returns {Object} The parsed dotenv object.
+ */
+export const readDotenv = async (path) => {
+  try {
+    return parse(await fs.readFile(path));
+  } catch {
+    return {};
+  }
+};
+
+/**
+ * Synchronously reads a dotenv file & parses it into an object.
+ *
+ * @private
+ * @function readDotenvSync
+ *
+ * @param {string} path - Any value.
+ *
+ * @returns {Object} The parsed dotenv object.
+ */
+export const readDotenvSync = (path) => {
+  try {
+    return parse(fs.readFileSync(path));
+  } catch {
+    return {};
+  }
+};

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@karmaniverous/get-dotenv",
+  "bin": {
+    "getdotenv": "bin/getdotenv/index.js"
+  },
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/karmaniverous/get-dotenv"
+  },
+  "author": "Jason G. Williscroft",
+  "bugs": {
+    "url": "https://github.com/karmaniverous/get-dotenv/issues"
+  },
+  "description": "Process dotenv files in an arbitrary location & optionally populate environment variables.",
+  "homepage": "https://github.com/karmaniverous/get-dotenv#readme",
+  "keywords": [
+    "chai",
+    "docs",
+    "es6",
+    "javascript",
+    "npm",
+    "mocha",
+    "package",
+    "release",
+    "testing",
+    "template"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "commander": "^9.4.1",
+    "dotenv": "^16.0.3",
+    "dotenv-expand": "^10.0.0",
+    "fs-extra": "^11.1.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.20.7",
+    "@babel/core": "^7.20.7",
+    "@babel/eslint-parser": "^7.19.1",
+    "@babel/plugin-syntax-import-assertions": "^7.20.0",
+    "@babel/preset-env": "^7.20.2",
+    "@babel/register": "^7.18.9",
+    "@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",
+    "jsdoc-to-markdown": "^8.0.0",
+    "mocha": "^10.2.0",
+    "prettier": "^2.8.1",
+    "release-it": "^15.6.0"
+  },
+  "exports": {
+    ".": {
+      "import": "./lib/index.js",
+      "require": "./dist/default/lib/index.js"
+    }
+  },
+  "mocha": {
+    "exclude": [
+      "./dist/**",
+      "./node_modules/**"
+    ],
+    "require": [
+      "@babel/register"
+    ],
+    "spec": "./**/*.test.!(*.*)"
+  },
+  "release-it": {
+    "github": {
+      "release": true
+    },
+    "npm": {
+      "publish": true
+    }
+  },
+  "scripts": {
+    "lint": "eslint lib/** bin/**",
+    "test": "mocha",
+    "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"
+  },
+  "type": "module"
+}