dotenv-extended 3.0.1 → 3.1.0

package/README.md

@@ -124,24 +124,48 @@ node -r dotenv-extended/config your_script.js dotenv_config_path=./env/.env dote
 
 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
-dotenv-extended ./myshellscript.sh --whatever-flags-my-script-takes
+dee ./myshellscript.sh --whatever-flags-my-script-takes
 ```
 
-Configure `dotenv-extended` by passing any of the dotenv-extended options before your command. Preceed each option with two dashes `--`:
+Configure `dee` (or `dotenv-extended`) by passing any of the dotenv-extended options before your command. Preceed each option with two dashes `--`:
 
 ```bash
-dotenv-extended --path=/path/to/.env --defaults=/path/to/.env.defaults --errorOnMissing=true ./myshellscript.sh --whatever-flags-my-script-takes
+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
+dee \
+  --defaults=./env/.env.defaults.base,./env/.env.defaults.local \
+  --path=./env/.env.base,./env/.env.development \
+  ./myshellscript.sh
+```
+
+You can also print the merged dotenv configuration (without full `process.env`) instead of executing a command:
+
+```bash
+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
@@ -169,10 +193,13 @@ require('dotenv-extended').load({
     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,
 });
@@ -188,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
@@ -214,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.
@@ -234,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:

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.
@@ -71,6 +79,14 @@ export interface IDotenvExtendedOptions {
      */
     errorOnRegex?: boolean;
 
+    /**
+     * 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
@@ -79,10 +95,17 @@ export interface IDotenvExtendedOptions {
      */
     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
      */

package/lib/bin/cli.js

@@ -93,11 +93,14 @@ var config_from_env_default = getConfigFromEnv;
 // src/utils/load-environment-file.js
 var import_fs = __toESM(require("fs"));
 var import_dotenv = __toESM(require("dotenv"));
-var loadEnvironmentFile = (path, encoding, silent) => {
+var loadEnvironmentFile = (path, encoding, silent, errorOnMissingFiles = false) => {
   try {
     const data = import_fs.default.readFileSync(path, encoding);
     return import_dotenv.default.parse(data);
   } catch (err) {
+    if (errorOnMissingFiles && err && err.code === "ENOENT") {
+      throw new Error(`MISSING CONFIG FILE: ${path}`);
+    }
     if (!silent) {
       console.error(err.message);
     }
@@ -107,6 +110,27 @@ var loadEnvironmentFile = (path, encoding, silent) => {
 var load_environment_file_default = loadEnvironmentFile;
 
 // src/index.js
+var normalizeLayeredFiles = (value) => {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+};
+var loadLayeredFiles = (files, options) => normalizeLayeredFiles(files).reduce((acc, filePath) => {
+  const fileData = load_environment_file_default(
+    filePath,
+    options.encoding,
+    options.silent,
+    options.errorOnMissingFiles
+  );
+  return Object.assign(acc, fileData);
+}, {});
 var parse = import_dotenv2.default.parse.bind(import_dotenv2.default);
 var config = (options) => {
   let defaultsData, environmentData, defaultOptions = {
@@ -115,23 +139,44 @@ var config = (options) => {
     path: ".env",
     defaults: ".env.defaults",
     schema: ".env.schema",
+    schemaExtends: void 0,
     errorOnMissing: false,
     errorOnExtra: false,
     errorOnRegex: false,
+    errorOnMissingFiles: false,
+    returnSchemaOnly: false,
     includeProcessEnv: false,
     assignToProcessEnv: true,
     overrideProcessEnv: false
   }, processEnvOptions = config_from_env_default(process.env);
   options = Object.assign({}, defaultOptions, processEnvOptions, options);
-  defaultsData = load_environment_file_default(options.defaults, options.encoding, options.silent);
-  environmentData = load_environment_file_default(options.path, options.encoding, options.silent);
+  defaultsData = loadLayeredFiles(options.defaults, options);
+  environmentData = loadLayeredFiles(options.path, options);
   let configData = Object.assign({}, defaultsData, environmentData);
   const config2 = options.includeProcessEnv ? Object.assign({}, configData, process.env) : configData;
   const configOnlyKeys = Object.keys(configData);
   const configKeys = Object.keys(config2);
-  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex) {
-    const schema = load_environment_file_default(options.schema, options.encoding, options.silent);
-    const schemaKeys = Object.keys(schema);
+  let schemaKeys = null;
+  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex || options.returnSchemaOnly) {
+    const baseSchema = load_environment_file_default(
+      options.schema,
+      options.encoding,
+      options.silent,
+      options.errorOnMissingFiles
+    );
+    const schema = normalizeLayeredFiles(options.schemaExtends).reduce(
+      (acc, schemaPath) => {
+        const schemaLayer = load_environment_file_default(
+          schemaPath,
+          options.encoding,
+          options.silent,
+          options.errorOnMissingFiles
+        );
+        return Object.assign(acc, schemaLayer);
+      },
+      Object.assign({}, baseSchema)
+    );
+    schemaKeys = Object.keys(schema);
     let missingKeys = schemaKeys.filter(function(key) {
       return configKeys.indexOf(key) < 0;
     });
@@ -163,6 +208,14 @@ var config = (options) => {
         configData[configKeys[i]] = process.env[configKeys[i]];
     }
   }
+  if (options.returnSchemaOnly && schemaKeys) {
+    configData = schemaKeys.reduce((acc, key) => {
+      if (typeof config2[key] !== "undefined") {
+        acc[key] = config2[key];
+      }
+      return acc;
+    }, {});
+  }
   if (options.assignToProcessEnv) {
     if (options.overrideProcessEnv) {
       Object.assign(process.env, configData);
@@ -176,6 +229,7 @@ var config = (options) => {
 
 // src/utils/parse-command.js
 var dotEnvFlagRegex = /^--(.+)=(.+)/;
+var dotEnvBooleanFlagRegex = /^--(.+)$/;
 var parseCommand = (args) => {
   const config2 = {};
   let command = null;
@@ -184,6 +238,11 @@ var parseCommand = (args) => {
     const match = dotEnvFlagRegex.exec(args[i]);
     if (match) {
       config2[normalize_option_key_default(match[1])] = parse_primitive_default(match[2]);
+      continue;
+    }
+    const booleanFlagMatch = dotEnvBooleanFlagRegex.exec(args[i]);
+    if (booleanFlagMatch && normalize_option_key_default(booleanFlagMatch[1]) === "print") {
+      config2.print = true;
     } else {
       command = args[i];
       commandArgs = args.slice(i + 1);
@@ -197,15 +256,42 @@ var parse_command_default = parseCommand;
 // src/bin/index.js
 var import_node_child_process = require("child_process");
 var spawnCommand = (command, commandArgs, options) => (0, import_node_child_process.spawn)(command, commandArgs, options);
+var writeStdout = (value) => process.stdout.write(value);
+var writeStderr = (value) => process.stderr.write(value);
+var toDotenvString = (values) => Object.keys(values).map((key) => `${key}=${values[key]}`).join("\n");
 function loadAndExecute(args, dependencies = {}) {
   const {
     spawnCommandFn = spawnCommand,
     processOn = process.on.bind(process),
-    processExit = process.exit
+    processExit = process.exit,
+    writeStdoutFn = writeStdout,
+    writeStderrFn = writeStderr
   } = dependencies;
   const [dotEnvConfig, command, commandArgs] = parse_command_default(args);
+  const { print, ...configOptions } = dotEnvConfig;
+  if (print && command) {
+    writeStderrFn("dotenv-extended: --print mode cannot be combined with command execution.\n");
+    processExit(1);
+    return;
+  }
+  if (print) {
+    const mergedConfig = config({
+      ...configOptions,
+      assignToProcessEnv: false,
+      includeProcessEnv: false
+    });
+    const format = typeof print === "string" ? print.toLowerCase() : "json";
+    if (format === "dotenv") {
+      writeStdoutFn(`${toDotenvString(mergedConfig)}
+`);
+      return mergedConfig;
+    }
+    writeStdoutFn(`${JSON.stringify(mergedConfig, null, 2)}
+`);
+    return mergedConfig;
+  }
   if (command) {
-    config(dotEnvConfig);
+    config(configOptions);
     const proc = spawnCommandFn(command, commandArgs, {
       stdio: "inherit",
       shell: true,

package/lib/bin/index.js

@@ -31,7 +31,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var bin_exports = {};
 __export(bin_exports, {
   loadAndExecute: () => loadAndExecute,
-  spawnCommand: () => spawnCommand
+  spawnCommand: () => spawnCommand,
+  writeStderr: () => writeStderr,
+  writeStdout: () => writeStdout
 });
 module.exports = __toCommonJS(bin_exports);
 
@@ -106,11 +108,14 @@ var config_from_env_default = getConfigFromEnv;
 // src/utils/load-environment-file.js
 var import_fs = __toESM(require("fs"));
 var import_dotenv = __toESM(require("dotenv"));
-var loadEnvironmentFile = (path, encoding, silent) => {
+var loadEnvironmentFile = (path, encoding, silent, errorOnMissingFiles = false) => {
   try {
     const data = import_fs.default.readFileSync(path, encoding);
     return import_dotenv.default.parse(data);
   } catch (err) {
+    if (errorOnMissingFiles && err && err.code === "ENOENT") {
+      throw new Error(`MISSING CONFIG FILE: ${path}`);
+    }
     if (!silent) {
       console.error(err.message);
     }
@@ -120,6 +125,27 @@ var loadEnvironmentFile = (path, encoding, silent) => {
 var load_environment_file_default = loadEnvironmentFile;
 
 // src/index.js
+var normalizeLayeredFiles = (value) => {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+};
+var loadLayeredFiles = (files, options) => normalizeLayeredFiles(files).reduce((acc, filePath) => {
+  const fileData = load_environment_file_default(
+    filePath,
+    options.encoding,
+    options.silent,
+    options.errorOnMissingFiles
+  );
+  return Object.assign(acc, fileData);
+}, {});
 var parse = import_dotenv2.default.parse.bind(import_dotenv2.default);
 var config = (options) => {
   let defaultsData, environmentData, defaultOptions = {
@@ -128,23 +154,44 @@ var config = (options) => {
     path: ".env",
     defaults: ".env.defaults",
     schema: ".env.schema",
+    schemaExtends: void 0,
     errorOnMissing: false,
     errorOnExtra: false,
     errorOnRegex: false,
+    errorOnMissingFiles: false,
+    returnSchemaOnly: false,
     includeProcessEnv: false,
     assignToProcessEnv: true,
     overrideProcessEnv: false
   }, processEnvOptions = config_from_env_default(process.env);
   options = Object.assign({}, defaultOptions, processEnvOptions, options);
-  defaultsData = load_environment_file_default(options.defaults, options.encoding, options.silent);
-  environmentData = load_environment_file_default(options.path, options.encoding, options.silent);
+  defaultsData = loadLayeredFiles(options.defaults, options);
+  environmentData = loadLayeredFiles(options.path, options);
   let configData = Object.assign({}, defaultsData, environmentData);
   const config2 = options.includeProcessEnv ? Object.assign({}, configData, process.env) : configData;
   const configOnlyKeys = Object.keys(configData);
   const configKeys = Object.keys(config2);
-  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex) {
-    const schema = load_environment_file_default(options.schema, options.encoding, options.silent);
-    const schemaKeys = Object.keys(schema);
+  let schemaKeys = null;
+  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex || options.returnSchemaOnly) {
+    const baseSchema = load_environment_file_default(
+      options.schema,
+      options.encoding,
+      options.silent,
+      options.errorOnMissingFiles
+    );
+    const schema = normalizeLayeredFiles(options.schemaExtends).reduce(
+      (acc, schemaPath) => {
+        const schemaLayer = load_environment_file_default(
+          schemaPath,
+          options.encoding,
+          options.silent,
+          options.errorOnMissingFiles
+        );
+        return Object.assign(acc, schemaLayer);
+      },
+      Object.assign({}, baseSchema)
+    );
+    schemaKeys = Object.keys(schema);
     let missingKeys = schemaKeys.filter(function(key) {
       return configKeys.indexOf(key) < 0;
     });
@@ -176,6 +223,14 @@ var config = (options) => {
         configData[configKeys[i]] = process.env[configKeys[i]];
     }
   }
+  if (options.returnSchemaOnly && schemaKeys) {
+    configData = schemaKeys.reduce((acc, key) => {
+      if (typeof config2[key] !== "undefined") {
+        acc[key] = config2[key];
+      }
+      return acc;
+    }, {});
+  }
   if (options.assignToProcessEnv) {
     if (options.overrideProcessEnv) {
       Object.assign(process.env, configData);
@@ -189,6 +244,7 @@ var config = (options) => {
 
 // src/utils/parse-command.js
 var dotEnvFlagRegex = /^--(.+)=(.+)/;
+var dotEnvBooleanFlagRegex = /^--(.+)$/;
 var parseCommand = (args) => {
   const config2 = {};
   let command = null;
@@ -197,6 +253,11 @@ var parseCommand = (args) => {
     const match = dotEnvFlagRegex.exec(args[i]);
     if (match) {
       config2[normalize_option_key_default(match[1])] = parse_primitive_default(match[2]);
+      continue;
+    }
+    const booleanFlagMatch = dotEnvBooleanFlagRegex.exec(args[i]);
+    if (booleanFlagMatch && normalize_option_key_default(booleanFlagMatch[1]) === "print") {
+      config2.print = true;
     } else {
       command = args[i];
       commandArgs = args.slice(i + 1);
@@ -210,15 +271,42 @@ var parse_command_default = parseCommand;
 // src/bin/index.js
 var import_node_child_process = require("child_process");
 var spawnCommand = (command, commandArgs, options) => (0, import_node_child_process.spawn)(command, commandArgs, options);
+var writeStdout = (value) => process.stdout.write(value);
+var writeStderr = (value) => process.stderr.write(value);
+var toDotenvString = (values) => Object.keys(values).map((key) => `${key}=${values[key]}`).join("\n");
 function loadAndExecute(args, dependencies = {}) {
   const {
     spawnCommandFn = spawnCommand,
     processOn = process.on.bind(process),
-    processExit = process.exit
+    processExit = process.exit,
+    writeStdoutFn = writeStdout,
+    writeStderrFn = writeStderr
   } = dependencies;
   const [dotEnvConfig, command, commandArgs] = parse_command_default(args);
+  const { print, ...configOptions } = dotEnvConfig;
+  if (print && command) {
+    writeStderrFn("dotenv-extended: --print mode cannot be combined with command execution.\n");
+    processExit(1);
+    return;
+  }
+  if (print) {
+    const mergedConfig = config({
+      ...configOptions,
+      assignToProcessEnv: false,
+      includeProcessEnv: false
+    });
+    const format = typeof print === "string" ? print.toLowerCase() : "json";
+    if (format === "dotenv") {
+      writeStdoutFn(`${toDotenvString(mergedConfig)}
+`);
+      return mergedConfig;
+    }
+    writeStdoutFn(`${JSON.stringify(mergedConfig, null, 2)}
+`);
+    return mergedConfig;
+  }
   if (command) {
-    config(dotEnvConfig);
+    config(configOptions);
     const proc = spawnCommandFn(command, commandArgs, {
       stdio: "inherit",
       shell: true,
@@ -235,5 +323,7 @@ function loadAndExecute(args, dependencies = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   loadAndExecute,
-  spawnCommand
+  spawnCommand,
+  writeStderr,
+  writeStdout
 });

package/lib/config.js

@@ -92,11 +92,14 @@ var config_from_env_default = getConfigFromEnv;
 // src/utils/load-environment-file.js
 var import_fs = __toESM(require("fs"));
 var import_dotenv = __toESM(require("dotenv"));
-var loadEnvironmentFile = (path, encoding, silent) => {
+var loadEnvironmentFile = (path, encoding, silent, errorOnMissingFiles = false) => {
   try {
     const data = import_fs.default.readFileSync(path, encoding);
     return import_dotenv.default.parse(data);
   } catch (err) {
+    if (errorOnMissingFiles && err && err.code === "ENOENT") {
+      throw new Error(`MISSING CONFIG FILE: ${path}`);
+    }
     if (!silent) {
       console.error(err.message);
     }
@@ -106,6 +109,27 @@ var loadEnvironmentFile = (path, encoding, silent) => {
 var load_environment_file_default = loadEnvironmentFile;
 
 // src/index.js
+var normalizeLayeredFiles = (value) => {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+};
+var loadLayeredFiles = (files, options2) => normalizeLayeredFiles(files).reduce((acc, filePath) => {
+  const fileData = load_environment_file_default(
+    filePath,
+    options2.encoding,
+    options2.silent,
+    options2.errorOnMissingFiles
+  );
+  return Object.assign(acc, fileData);
+}, {});
 var parse = import_dotenv2.default.parse.bind(import_dotenv2.default);
 var config = (options2) => {
   let defaultsData, environmentData, defaultOptions = {
@@ -114,23 +138,44 @@ var config = (options2) => {
     path: ".env",
     defaults: ".env.defaults",
     schema: ".env.schema",
+    schemaExtends: void 0,
     errorOnMissing: false,
     errorOnExtra: false,
     errorOnRegex: false,
+    errorOnMissingFiles: false,
+    returnSchemaOnly: false,
     includeProcessEnv: false,
     assignToProcessEnv: true,
     overrideProcessEnv: false
   }, processEnvOptions = config_from_env_default(process.env);
   options2 = Object.assign({}, defaultOptions, processEnvOptions, options2);
-  defaultsData = load_environment_file_default(options2.defaults, options2.encoding, options2.silent);
-  environmentData = load_environment_file_default(options2.path, options2.encoding, options2.silent);
+  defaultsData = loadLayeredFiles(options2.defaults, options2);
+  environmentData = loadLayeredFiles(options2.path, options2);
   let configData = Object.assign({}, defaultsData, environmentData);
   const config2 = options2.includeProcessEnv ? Object.assign({}, configData, process.env) : configData;
   const configOnlyKeys = Object.keys(configData);
   const configKeys = Object.keys(config2);
-  if (options2.errorOnMissing || options2.errorOnExtra || options2.errorOnRegex) {
-    const schema = load_environment_file_default(options2.schema, options2.encoding, options2.silent);
-    const schemaKeys = Object.keys(schema);
+  let schemaKeys = null;
+  if (options2.errorOnMissing || options2.errorOnExtra || options2.errorOnRegex || options2.returnSchemaOnly) {
+    const baseSchema = load_environment_file_default(
+      options2.schema,
+      options2.encoding,
+      options2.silent,
+      options2.errorOnMissingFiles
+    );
+    const schema = normalizeLayeredFiles(options2.schemaExtends).reduce(
+      (acc, schemaPath) => {
+        const schemaLayer = load_environment_file_default(
+          schemaPath,
+          options2.encoding,
+          options2.silent,
+          options2.errorOnMissingFiles
+        );
+        return Object.assign(acc, schemaLayer);
+      },
+      Object.assign({}, baseSchema)
+    );
+    schemaKeys = Object.keys(schema);
     let missingKeys = schemaKeys.filter(function(key) {
       return configKeys.indexOf(key) < 0;
     });
@@ -162,6 +207,14 @@ var config = (options2) => {
         configData[configKeys[i]] = process.env[configKeys[i]];
     }
   }
+  if (options2.returnSchemaOnly && schemaKeys) {
+    configData = schemaKeys.reduce((acc, key) => {
+      if (typeof config2[key] !== "undefined") {
+        acc[key] = config2[key];
+      }
+      return acc;
+    }, {});
+  }
   if (options2.assignToProcessEnv) {
     if (options2.overrideProcessEnv) {
       Object.assign(process.env, configData);

package/lib/index.js

@@ -105,11 +105,14 @@ var config_from_env_default = getConfigFromEnv;
 // src/utils/load-environment-file.js
 var import_fs = __toESM(require("fs"));
 var import_dotenv = __toESM(require("dotenv"));
-var loadEnvironmentFile = (path, encoding, silent) => {
+var loadEnvironmentFile = (path, encoding, silent, errorOnMissingFiles = false) => {
   try {
     const data = import_fs.default.readFileSync(path, encoding);
     return import_dotenv.default.parse(data);
   } catch (err) {
+    if (errorOnMissingFiles && err && err.code === "ENOENT") {
+      throw new Error(`MISSING CONFIG FILE: ${path}`);
+    }
     if (!silent) {
       console.error(err.message);
     }
@@ -119,6 +122,27 @@ var loadEnvironmentFile = (path, encoding, silent) => {
 var load_environment_file_default = loadEnvironmentFile;
 
 // src/index.js
+var normalizeLayeredFiles = (value) => {
+  if (!value) {
+    return [];
+  }
+  if (Array.isArray(value)) {
+    return value.filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+};
+var loadLayeredFiles = (files, options) => normalizeLayeredFiles(files).reduce((acc, filePath) => {
+  const fileData = load_environment_file_default(
+    filePath,
+    options.encoding,
+    options.silent,
+    options.errorOnMissingFiles
+  );
+  return Object.assign(acc, fileData);
+}, {});
 var parse = import_dotenv2.default.parse.bind(import_dotenv2.default);
 var config = (options) => {
   let defaultsData, environmentData, defaultOptions = {
@@ -127,23 +151,44 @@ var config = (options) => {
     path: ".env",
     defaults: ".env.defaults",
     schema: ".env.schema",
+    schemaExtends: void 0,
     errorOnMissing: false,
     errorOnExtra: false,
     errorOnRegex: false,
+    errorOnMissingFiles: false,
+    returnSchemaOnly: false,
     includeProcessEnv: false,
     assignToProcessEnv: true,
     overrideProcessEnv: false
   }, processEnvOptions = config_from_env_default(process.env);
   options = Object.assign({}, defaultOptions, processEnvOptions, options);
-  defaultsData = load_environment_file_default(options.defaults, options.encoding, options.silent);
-  environmentData = load_environment_file_default(options.path, options.encoding, options.silent);
+  defaultsData = loadLayeredFiles(options.defaults, options);
+  environmentData = loadLayeredFiles(options.path, options);
   let configData = Object.assign({}, defaultsData, environmentData);
   const config2 = options.includeProcessEnv ? Object.assign({}, configData, process.env) : configData;
   const configOnlyKeys = Object.keys(configData);
   const configKeys = Object.keys(config2);
-  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex) {
-    const schema = load_environment_file_default(options.schema, options.encoding, options.silent);
-    const schemaKeys = Object.keys(schema);
+  let schemaKeys = null;
+  if (options.errorOnMissing || options.errorOnExtra || options.errorOnRegex || options.returnSchemaOnly) {
+    const baseSchema = load_environment_file_default(
+      options.schema,
+      options.encoding,
+      options.silent,
+      options.errorOnMissingFiles
+    );
+    const schema = normalizeLayeredFiles(options.schemaExtends).reduce(
+      (acc, schemaPath) => {
+        const schemaLayer = load_environment_file_default(
+          schemaPath,
+          options.encoding,
+          options.silent,
+          options.errorOnMissingFiles
+        );
+        return Object.assign(acc, schemaLayer);
+      },
+      Object.assign({}, baseSchema)
+    );
+    schemaKeys = Object.keys(schema);
     let missingKeys = schemaKeys.filter(function(key) {
       return configKeys.indexOf(key) < 0;
     });
@@ -175,6 +220,14 @@ var config = (options) => {
         configData[configKeys[i]] = process.env[configKeys[i]];
     }
   }
+  if (options.returnSchemaOnly && schemaKeys) {
+    configData = schemaKeys.reduce((acc, key) => {
+      if (typeof config2[key] !== "undefined") {
+        acc[key] = config2[key];
+      }
+      return acc;
+    }, {});
+  }
   if (options.assignToProcessEnv) {
     if (options.overrideProcessEnv) {
       Object.assign(process.env, configData);

package/package.json

@@ -1,11 +1,14 @@
 {
     "name": "dotenv-extended",
-    "version": "3.0.1",
+    "version": "3.1.0",
     "description": "A module for loading .env files and optionally loading defaults and a schema for validating all values are present.",
     "repository": "git@github.com:keithmorris/node-dotenv-extended.git",
     "main": "lib/index.js",
     "types": "dotenv-extended.d.ts",
-    "bin": "lib/bin/cli.js",
+    "bin": {
+        "dotenv-extended": "lib/bin/cli.js",
+        "dee": "lib/bin/cli.js"
+    },
     "exports": {
         ".": {
             "require": "./lib/index.js",