dotenv-extended 2.9.0 → 3.1.0

package/README.md

@@ -1,9 +1,12 @@
 # dotenv-extended
 
-[![Build Status](https://travis-ci.org/keithmorris/node-dotenv-extended.svg?branch=develop)](https://travis-ci.org/keithmorris/node-dotenv-extended)
-[![Coverage Status](https://coveralls.io/repos/github/keithmorris/node-dotenv-extended/badge.svg?branch=develop)](https://coveralls.io/github/keithmorris/node-dotenv-extended?branch=develop)
-[![Dependency Status](https://david-dm.org/keithmorris/node-dotenv-extended.svg)](https://david-dm.org/keithmorris/node-dotenv-extended)
+Extended `.env` loading with defaults and schema validation.
 
+## Supported Node Versions
+
+- Node `20.x`
+- Node `22.x`
+- Node `24.x`
 
 I've been a big fan of the [dotenv] for a quite some time (in fact, this library uses [dotenv] under the hood for the `.env` file parsing). However, while working on some bigger projects, we realized that the managing of the `.env` files became a bit of a chore. As the files changed in the development environments, it became a tedious manual process to compare and figure out what needed to be added or removed in the other environments.
 
@@ -29,7 +32,6 @@ Common configuration defaults across all environments (commited to source contro
 
 Defines a schema of what variables _should_ be defined in the combination of `.env` and `.env.defaults`. Optionally, you can have the library throw an error if all values are not configured or if there are extra values that shouldn't be there.
 
-
 The `.env.schema` file should only have the name of the variable and the `=` without any value:
 
 ```
@@ -49,6 +51,24 @@ I have tried to stay as compatible as possible with the [dotenv] library but the
 npm i --save dotenv-extended
 ```
 
+## Development
+
+```bash
+npm run check
+```
+
+`npm run check` runs linting, formatting checks, and tests.
+
+Use individual commands only when needed:
+
+```bash
+npm run build
+npm run lint
+npm run format
+npm run test:unit
+npm test
+```
+
 ## Usage
 
 As early as possible in your main script:
@@ -61,7 +81,7 @@ Or if you prefer import syntax:
 
 ```javascript
 import dotEnvExtended from 'dotenv-extended';
-dotEnvExtended.load(); 
+dotEnvExtended.load();
 ```
 
 Create a `.env` file in the root directory of your project. Add environment-specific variables on new lines in the form of `NAME=VALUE`.
@@ -80,7 +100,7 @@ MONGO_PASS=dbpassword!
 ```javascript
 mongoose.connect('mongodb://' + process.env.MONGO_HOST + '/' + process.env.MONGO_DATABASE, {
     user: process.env.MONGO_USER,
-    pass: process.env.MONGO_PASS
+    pass: process.env.MONGO_PASS,
 });
 ```
 
@@ -98,28 +118,54 @@ Or to specify load options:
 node -r dotenv-extended/config your_script.js dotenv_config_path=./env/.env dotenv_config_defaults=./env/.env.defaults
 ```
 
+`dotenv_config_*` values are normalized to the same option names as `load()`, supporting both snake_case and kebab-case style keys.
+
 ### Load Environment Variables and pass to non-NodeJS script
 
 New in 2.0.0, is a feature inspired by [cross-env](https://www.npmjs.com/package/cross-env) to allow you to load environment variables from your `.env` files and then pass them into a non-NodeJS script such as a shell script. This can simplify the process of maintaining variables used in both your Node app and other scripts. To use this command line executable, you will either need to install globally with the `-g` flag, or install `dotenv-extended` in your project and reference it from your npm scripts.
 
+The package exposes two equivalent CLI commands:
+
+- `dotenv-extended` (original)
+- `dee` (short alias)
+
 Install Globally:
 
 ```bash
 npm install -g dotenv-extended
 ```
 
-Now call your shell scripts through `dotenv-extended` (this uses the defaults):
+Now call your shell scripts through `dee` (this uses the defaults):
+
+```bash
+dee ./myshellscript.sh --whatever-flags-my-script-takes
+```
+
+Configure `dee` (or `dotenv-extended`) by passing any of the dotenv-extended options before your command. Preceed each option with two dashes `--`:
+
+```bash
+dee --path=/path/to/.env --defaults=/path/to/.env.defaults --errorOnMissing=true ./myshellscript.sh --whatever-flags-my-script-takes
+```
+
+`--path` and `--defaults` also support comma-separated layered files:
 
 ```bash
-dotenv-extended ./myshellscript.sh --whatever-flags-my-script-takes
+dee \
+  --defaults=./env/.env.defaults.base,./env/.env.defaults.local \
+  --path=./env/.env.base,./env/.env.development \
+  ./myshellscript.sh
 ```
 
-Configure `dotenv-extended` by passing any of the dotenv-extended options before your command. Preceed each option with two dashes `--`:
+You can also print the merged dotenv configuration (without full `process.env`) instead of executing a command:
 
 ```bash
-dotenv-extended --path=/path/to/.env --defaults=/path/to/.env.defaults --errorOnMissing=true ./myshellscript.sh --whatever-flags-my-script-takes
+dee --print
+dee --print=dotenv
 ```
 
+- `--print` outputs JSON
+- `--print=dotenv` outputs `KEY=value` lines
+
 The following are the flags you can pass to the `dotenv-extended` cli with their default values. these options detailed later in this document:
 
 ```bash
@@ -142,19 +188,23 @@ Defaults are shown below:
 
 ```javascript
 require('dotenv-extended').load({
-	encoding: 'utf8',
-	silent: true,
-	path: '.env',
-	defaults: '.env.defaults',
-	schema: '.env.schema',
-	errorOnMissing: false,
-	errorOnExtra: false,
-	errorOnRegex: false,
-	includeProcessEnv: false,
-	assignToProcessEnv: true,
-	overrideProcessEnv: false
+    encoding: 'utf8',
+    silent: true,
+    path: '.env',
+    defaults: '.env.defaults',
+    schema: '.env.schema',
+    schemaExtends: undefined, // string | string[]
+    errorOnMissing: false,
+    errorOnExtra: false,
+    errorOnRegex: false,
+    errorOnMissingFiles: false,
+    includeProcessEnv: false,
+    returnSchemaOnly: false,
+    assignToProcessEnv: true,
+    overrideProcessEnv: false,
 });
 ```
+
 ### Configure via Environment Variables (New in 2.8.0)
 
 You may also set the configuration values via environment variables loaded from `process.env` shown below with defaults:
@@ -165,14 +215,19 @@ DOTENV_CONFIG_SILENT=true
 DOTENV_CONFIG_PATH=.env
 DOTENV_CONFIG_DEFAULTS=.env.defaults
 DOTENV_CONFIG_SCHEMA=.env.schema
+DOTENV_CONFIG_SCHEMA_EXTENDS=
 DOTENV_CONFIG_ERROR_ON_MISSING=false
 DOTENV_CONFIG_ERROR_ON_EXTRA=false
 DOTENV_CONFIG_ERROR_ON_REGEX=false
+DOTENV_CONFIG_ERROR_ON_MISSING_FILES=false
 DOTENV_CONFIG_INCLUDE_PROCESS_ENV=false
+DOTENV_CONFIG_RETURN_SCHEMA_ONLY=false
 DOTENV_CONFIG_ASSIGN_TO_PROCESS_ENV=true
 DOTENV_CONFIG_OVERRIDE_PROCESS_ENV=false
 ```
 
+`DOTENV_CONFIG_PATH`, `DOTENV_CONFIG_DEFAULTS`, and `DOTENV_CONFIG_SCHEMA_EXTENDS` can each be set to comma-separated file paths for layered loading.
+
 The `load()` function always returns an object containing the variables loaded from the `.env` and `.env.defaults` files. By default the returned object does not contain the properties held in `process.env` but rather only the ones that are loaded from the `.env` and `.env.defaults` files.
 
 ```javascript
@@ -191,14 +246,41 @@ Sets whether a log message is shown when missing the `.env` or `.env.defaults` f
 
 The main `.env` file that contains your variables.
 
+- Accepts `string` or `string[]` in code.
+- Accepts comma-separated paths via environment variable:
+    - `DOTENV_CONFIG_PATH=./.env.base,./.env.dev`
+- Merge order is deterministic:
+    - load each `path` entry in order
+    - later entries override earlier keys
+
 ### defaults (_default: .env.defaults_)
 
 The file that default values are loaded from.
 
+- Accepts `string` or `string[]` in code.
+- Accepts comma-separated paths via environment variable:
+    - `DOTENV_CONFIG_DEFAULTS=./.env.defaults.base,./.env.defaults.shared`
+- Merge order is deterministic:
+    - load each `defaults` entry in order
+    - later entries override earlier keys
+    - `path` layers are applied after all `defaults` layers, so `path` still overrides `defaults`
+
 ### schema (_default: .env.schema_)
 
 The file that contains the schema of what values should be available from combining `.env` and `.env.defaults`
 
+### schemaExtends (_default: undefined_)
+
+Optional schema extension file(s) layered on top of `schema`.
+
+- Accepts `string` or `string[]` in code.
+- Accepts comma-separated paths via environment variable:
+    - `DOTENV_CONFIG_SCHEMA_EXTENDS=./.env.production.schema,./.env.region.schema`
+- Merge order is deterministic:
+    - load base `schema` first
+    - then apply `schemaExtends` in order
+    - later layers override earlier keys
+
 ### errorOnMissing (_default: false_)
 
 Causes the library to throw a `MISSING CONFIG VALUES` error listing all of the variables missing the combined `.env` and `.env.defaults` files.
@@ -211,18 +293,51 @@ Causes the library to throw a `EXTRA CONFIG VALUES` error listing all of the ext
 
 Causes the library to throw a `REGEX MISMATCH` error listing all of the invalid variables from the combined `.env` and `.env.defaults` files. Also a `SyntaxError` is thrown in case `.env.schema` contains a syntactically invalid regex.
 
+### errorOnMissingFiles (_default: false_)
+
+Causes the library to throw a `MISSING CONFIG FILE` error when configured dotenv files cannot be found. This applies to `path`, `defaults`, and `schema` when they are loaded.
+
 ### includeProcessEnv (_default: false_)
 
 Causes the library add process.env variables to error checking. The variables in process.env overrides the variables in .env and .env.defaults while checking
 
+### returnSchemaOnly (_default: false_)
+
+Causes the returned object to include only variables present in `.env.schema`. This is useful when using `includeProcessEnv` for validation but you only want schema-defined keys in the final result.
+
 ### assignToProcessEnv (_default: true_)
 
-Sets whether the loaded values are assigned to the `process.env` object. If this is set, you must capture the return value of the call to `.load()` or you will not be able to use your variables.
+Sets whether the loaded values are assigned to the `process.env` object. If this is `false`, values are only available in the returned object from `.load()`.
 
 ### overrideProcessEnv (_default: false_)
 
 By defaut, `dotenv-entended` will not overwrite any varibles that are already set in the `process.env` object. If you would like to enable overwriting any already existing values, set this value to `true`.
 
+### Layered File Precedence
+
+When using multiple files, merge precedence is:
+
+1. `defaults` layers in order (last wins)
+2. `path` layers in order (last wins)
+3. `process.env` values, if `includeProcessEnv` is true and `overrideProcessEnv` is false
+
+Example:
+
+```javascript
+const config = require('dotenv-extended').load({
+    defaults: ['./env/.env.defaults.base', './env/.env.defaults.region'],
+    path: ['./env/.env.base', './env/.env.production'],
+});
+```
+
+Equivalent via environment variables:
+
+```bash
+DOTENV_CONFIG_DEFAULTS=./env/.env.defaults.base,./env/.env.defaults.region \
+DOTENV_CONFIG_PATH=./env/.env.base,./env/.env.production \
+node app.js
+```
+
 ## Examples
 
 Consider the following three files:
@@ -255,18 +370,18 @@ API_KEY=
 ```javascript
 const myConfig = require('dotenv-extended').load();
 
-myConfig.DB_HOST === process.env.DB_HOST === "localhost"
-myConfig.DB_USER === process.env.DB_USER === "databaseuser-local"
-myConfig.DB_PASS === process.env.DB_PASS === "localhost"
-myConfig.DB_DATABASE === process.env.DB_DATABASE === "MyAppDB"
-myConfig.SHARE_URL === process.env.SHARE_URL === "http://www.example.com"
+(myConfig.DB_HOST === process.env.DB_HOST) === 'localhost';
+(myConfig.DB_USER === process.env.DB_USER) === 'databaseuser-local';
+(myConfig.DB_PASS === process.env.DB_PASS) === 'localhost';
+(myConfig.DB_DATABASE === process.env.DB_DATABASE) === 'MyAppDB';
+(myConfig.SHARE_URL === process.env.SHARE_URL) === 'http://www.example.com';
 ```
 
 ### Load files with `errorOnMissing`
 
 ```javascript
 const myConfig = require('dotenv-extended').load({
-    errorOnMissing: true
+    errorOnMissing: true,
 });
 
 // Throws ERROR `MISSING CONFIG VALUES: API_KEY`
@@ -276,7 +391,7 @@ const myConfig = require('dotenv-extended').load({
 
 ```javascript
 const myConfig = require('dotenv-extended').load({
-    errorOnExtra: true
+    errorOnExtra: true,
 });
 
 // Throws ERROR `EXTRA CONFIG VALUES: SHARE_URL`
@@ -286,7 +401,7 @@ const myConfig = require('dotenv-extended').load({
 
 ```javascript
 const myConfig = require('dotenv-extended').load({
-    errorOnRegex: true
+    errorOnRegex: true,
 });
 
 // Throws ERROR `REGEX MISMATCH: DB_USER`
@@ -296,6 +411,18 @@ const myConfig = require('dotenv-extended').load({
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)
 
+## Migration Notes
+
+### Migrating from legacy 2.x tooling
+
+- Node `>=20` is now required.
+- Build/test tooling no longer uses `gulp`, Babel, `esm`, or Mocha/NYC.
+- The project now uses:
+    - `tsup` for build output in `lib/`
+    - `vitest` for tests
+    - modern `eslint` config and `prettier`
+- Public API is kept compatible (`load`, `config`, `parse`, CLI behavior, and `dotenv-extended/config` preload entry).
+
 ## Change Log
 
 See [CHANGELOG.md](CHANGELOG.md)

package/dotenv-extended.d.ts

@@ -27,17 +27,19 @@ export interface IDotenvExtendedOptions {
 
     /**
      * Path to the main .env file that contains your variables.
+     * Can be a string path or layered string[] where later entries override earlier ones.
      *
      * @default '.env'
      */
-    path?: string;
+    path?: string | string[];
 
     /**
      * The path to the file that default values are loaded from.
+     * Can be a string path or layered string[] where later entries override earlier ones.
      *
      * @default '.env.defaults'
      */
-    defaults?: string;
+    defaults?: string | string[];
 
     /**
      * The path to the file that contains the schema of what values should be available
@@ -47,6 +49,12 @@ export interface IDotenvExtendedOptions {
      */
     schema?: string;
 
+    /**
+     * Optional schema extension path(s). These are layered on top of `schema` in order.
+     * Later entries override earlier keys (including base schema keys).
+     */
+    schemaExtends?: string | string[];
+
     /**
      * Causes the library to throw a MISSING CONFIG VALUES error listing all of the variables
      * missing the combined .env and .env.defaults files.
@@ -72,17 +80,32 @@ export interface IDotenvExtendedOptions {
     errorOnRegex?: boolean;
 
     /**
-     * Causes the library add process.env variables to error checking. The variables in process.env overrides the 
+     * Causes the library to throw when a configured dotenv file path cannot be found.
+     * Applies to `path`, `defaults`, and `schema` when they are loaded.
+     *
+     * @default false
+     */
+    errorOnMissingFiles?: boolean;
+
+    /**
+     * Causes the library add process.env variables to error checking. The variables in process.env overrides the
      * variables in .env and .env.defaults while checking
      *
      * @default false
      */
     includeProcessEnv?: boolean;
 
+    /**
+     * Causes the returned object (and any process assignment) to include only variables present in the schema file.
+     * This is useful when `includeProcessEnv` is enabled for validation, but you only want schema-defined keys.
+     *
+     * @default false
+     */
+    returnSchemaOnly?: boolean;
+
     /**
      * Sets whether the loaded values are assigned to the process.env object.
-     * If this is set, you must capture the return value of the call to .load() or you will not be
-     * able to use your variables.
+     * If this is false, values are only available from the returned object.
      *
      * @default true
      */