src: add support to override local env variables option

Author: ilyasShabiCS

doc/api/cli.md

@@ -730,6 +730,23 @@ Export keyword before a key is ignored:
 export USERNAME="nodejs" # will result in `nodejs` as the value.
 ```
 
+### `--env-file-override-local`
+
+> Stability: 1.1 - Active development
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Override existing environment variables on your machine with values specified in
+your environment files.
+
+```bash
+node --env-file=.env --env-file-override-local index.js
+```
+
+To override variables during runtime, use [`process.loadEnvFile({ override: true })`][]
+
 ### `-e`, `--eval "script"`
 
 <!-- YAML
@@ -3212,6 +3229,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
 [`import` specifier]: esm.md#import-specifiers
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
+[`process.loadEnvFile({ override: true })`]: process.md#processloadenvfilepath-options
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`process.setuid()`]: process.md#processsetuidid
 [`setuid(2)`]: https://man7.org/linux/man-pages/man2/setuid.2.html

doc/api/process.md

@@ -2280,17 +2280,25 @@ process.kill(process.pid, 'SIGHUP');
 When `SIGUSR1` is received by a Node.js process, Node.js will start the
 debugger. See [Signal Events][].
 
-## `process.loadEnvFile(path)`
+## `process.loadEnvFile(path, options)`
 
 <!-- YAML
 added:
   - v21.7.0
   - v20.12.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/52531
+    description: Add support to override local environment variables option.
 -->
 
 > Stability: 1.1 - Active development
 
 * `path` {string | URL | Buffer | undefined}. **Default:** `'./.env'`
+* `options` {Object} Used to provide arguments for parsing environment variables
+  files. `options` supports the following properties:
+  * `override` {boolean} to override local environment variables of your
+    machine. **Default:** `false`.
 
 Loads the `.env` file into `process.env`. Usage of `NODE_OPTIONS`
 in the `.env` file will not have any effect on Node.js.
@@ -2305,6 +2313,32 @@ import { loadEnvFile } from 'node:process';
 loadEnvFile();
 ```
 
+Override local environment variables using override option
+
+```cjs
+const { loadEnvFile } = require('node:process');
+loadEnvFile('.env', { override: true });
+```
+
+```mjs
+import { loadEnvFile } from 'node:process';
+loadEnvFile('.env', { override: true });
+```
+
+This API is available through the [`--env-file-override-local`][] flag.
+
+Load environment variables with options only
+
+```cjs
+const { loadEnvFile } = require('node:process');
+loadEnvFile({ override: true });
+```
+
+```mjs
+import { loadEnvFile } from 'node:process';
+loadEnvFile({ override: true });
+```
+
 ## `process.mainModule`
 
 <!-- YAML
@@ -4003,6 +4037,7 @@ cases:
 [`'exit'`]: #event-exit
 [`'message'`]: child_process.md#event-message
 [`'uncaughtException'`]: #event-uncaughtexception
+[`--env-file-override-local`]: cli.md#--env-file-override-local
 [`--experimental-permission`]: cli.md#--experimental-permission
 [`--no-deprecation`]: cli.md#--no-deprecation
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode

lib/internal/process/per_thread.js

@@ -251,14 +251,23 @@ function wrapProcessMethods(binding) {
   /**
    * Loads the `.env` file to process.env.
    * @param {string | URL | Buffer | undefined} path
+   * @param {{
+   *    override?: boolean;
+   * }} [options]
    */
-  function loadEnvFile(path = undefined) { // Provide optional value so that `loadEnvFile.length` returns 0
+  function loadEnvFile(path = undefined, options = { override: false }) {
+    // Provide optional value so that `loadEnvFile.length` returns 0
+    if (arguments.length === 1 && typeof path === 'object') {
+      options = path;
+      path = undefined;
+    }
+    validateObject(options, 'options');
     if (path != null) {
       path = getValidatedPath(path);
-      _loadEnvFile(toNamespacedPath(path));
     } else {
-      _loadEnvFile();
+      path = getValidatedPath('.env');
     }
+    _loadEnvFile(toNamespacedPath(path), options.override);
   }
 
 

src/node.cc

@@ -360,7 +360,8 @@ MaybeLocal<Value> StartExecution(Environment* env, StartExecutionCallback cb) {
 #endif
 
   if (env->options()->has_env_file_string) {
-    per_process::dotenv_file.SetEnvironment(env);
+    per_process::dotenv_file.SetEnvironment(
+        env, env->options()->env_file_override_local);
   }
 
   // TODO(joyeecheung): move these conditions into JS land and let the

src/node_dotenv.cc

@@ -41,7 +41,7 @@ std::vector<std::string> Dotenv::GetPathFromArgs(
   return paths;
 }
 
-void Dotenv::SetEnvironment(node::Environment* env) {
+void Dotenv::SetEnvironment(node::Environment* env, bool should_override) {
   if (store_.empty()) {
     return;
   }
@@ -52,9 +52,7 @@ void Dotenv::SetEnvironment(node::Environment* env) {
     auto key = entry.first;
     auto value = entry.second;
 
-    auto existing = env->env_vars()->Get(key.data());
-
-    if (existing.IsNothing()) {
+    if (!env->env_vars()->Get(key.data()).IsJust() || should_override) {
       env->env_vars()->Set(
           isolate,
           v8::String::NewFromUtf8(

src/node_dotenv.h

@@ -24,7 +24,7 @@ class Dotenv {
   void ParseContent(const std::string_view content);
   ParseResult ParsePath(const std::string_view path);
   void AssignNodeOptionsIfAvailable(std::string* node_options);
-  void SetEnvironment(Environment* env);
+  void SetEnvironment(Environment* env, bool should_override);
   v8::Local<v8::Object> ToObject(Environment* env);
 
   static std::vector<std::string> GetPathFromArgs(

src/node_options.cc

@@ -629,6 +629,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "set environment variables from supplied file",
             &EnvironmentOptions::env_file);
   Implies("--env-file", "[has_env_file_string]");
+  AddOption(
+      "--env-file-override-local",
+      "override environment variables set on machine with variables from "
+      "supplied files via --env-file flag or loadEnvFile() process function",
+      &EnvironmentOptions::env_file_override_local);
+  Implies("--env-file-override-local", "[has_env_file_string]");
   AddOption("--test",
             "launch test runner on startup",
             &EnvironmentOptions::test_runner);

src/node_options.h

@@ -166,6 +166,7 @@ class EnvironmentOptions : public Options {
   std::string diagnostic_dir;
   std::string env_file;
   bool has_env_file_string = false;
+  bool env_file_override_local = false;
   bool test_runner = false;
   uint64_t test_runner_concurrency = 0;
   uint64_t test_runner_timeout = 0;

src/node_process_methods.cc

@@ -470,11 +470,15 @@ static void ReallyExit(const FunctionCallbackInfo<Value>& args) {
 
 static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args) {
   Environment* env = Environment::GetCurrent(args);
-  std::string path = ".env";
-  if (args.Length() == 1) {
-    Utf8Value path_value(args.GetIsolate(), args[0]);
-    path = path_value.ToString();
-  }
+
+  CHECK_EQ(args.Length(), 2);
+  CHECK(args[0]->IsString());
+  CHECK(args[1]->IsBoolean());
+
+  Utf8Value path_value(args.GetIsolate(), args[0]);
+  std::string path = path_value.ToString();
+
+  bool env_file_override_local = args[1]->IsTrue();
 
   THROW_IF_INSUFFICIENT_PERMISSIONS(
       env, permission::PermissionScope::kFileSystemRead, path);
@@ -483,7 +487,7 @@ static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args) {
 
   switch (dotenv.ParsePath(path)) {
     case dotenv.ParseResult::Valid: {
-      dotenv.SetEnvironment(env);
+      dotenv.SetEnvironment(env, env_file_override_local);
       break;
     }
     case dotenv.ParseResult::InvalidContent: {

test/parallel/test-process-load-env-file.js

@@ -87,3 +87,55 @@ describe('process.loadEnvFile()', () => {
     assert.strictEqual(child.code, 0);
   });
 });
+
+describe('process.loadEnvFile(path, { override: true })', () => {
+
+  it('should not override the original value', async () => {
+    process.env.BASIC = 'Original value';
+    const code = `
+      process.loadEnvFile(${JSON.stringify(validEnvFilePath)});
+      const assert = require('assert');
+      assert.strictEqual(process.env.BASIC, 'Original value');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('should override the original value', async () => {
+    process.env.BASIC = 'Original value';
+    const code = `
+      process.loadEnvFile(${JSON.stringify(validEnvFilePath)}, {override: true});
+      const assert = require('assert');
+      assert.strictEqual(process.env.BASIC, 'basic');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('supports passing options only', async () => {
+    process.env.BASIC = 'Original value';
+    const code = `
+      process.loadEnvFile({override: true});
+      const assert = require('assert');
+      assert.strictEqual(process.env.BASIC, 'basic');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: fixtures.path('dotenv/') },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+});