From 37169e4f1f1c9cb69e74a48ad6dfbec181b6ff1e Mon Sep 17 00:00:00 2001
From: Aviv Keller <38299977+RedYetiDev@users.noreply.github.com>
Date: Tue, 13 Aug 2024 19:56:56 -0400
Subject: [PATCH 1/3] src: don't match after `--` in `Dotenv::GetPathFromArgs`

Co-Authored-By: Cedric Staniewski <cedric@gmx.ca>
PR-URL: https://github.com/nodejs/node/pull/54237
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 src/node_dotenv.cc                      | 13 +++++++++++--
 test/parallel/test-dotenv-edge-cases.js | 14 ++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/node_dotenv.cc b/src/node_dotenv.cc
index 12eb0446de0a7a..dfbf0a0bfa0acb 100644
--- a/src/node_dotenv.cc
+++ b/src/node_dotenv.cc
@@ -14,13 +14,22 @@ using v8::String;
 std::vector<std::string> Dotenv::GetPathFromArgs(
     const std::vector<std::string>& args) {
   const auto find_match = [](const std::string& arg) {
-    const std::string_view flag = "--env-file";
-    return strncmp(arg.c_str(), flag.data(), flag.size()) == 0;
+    auto arg_chars = arg.c_str();
+    auto arg_len = arg.size();
+    if (arg_chars[0] != '-' || arg_chars[1] != '-') return false;
+    if (arg_len == 2) return true;  // arg == "--"
+    const std::string_view flag = "env-file";
+    const auto len = flag.size();
+    if (strncmp(arg_chars + 2, flag.data(), len) != 0) return false;
+    return arg_len == 2 + len || arg_chars[2 + len] == '=';
   };
   std::vector<std::string> paths;
   auto path = std::find_if(args.begin(), args.end(), find_match);
 
   while (path != args.end()) {
+    if (path->size() == 2 && strncmp(path->c_str(), "--", 2) == 0) {
+      return paths;
+    }
     auto equal_char = path->find('=');
 
     if (equal_char != std::string::npos) {
diff --git a/test/parallel/test-dotenv-edge-cases.js b/test/parallel/test-dotenv-edge-cases.js
index f8cd262c8a8092..baad85fa6b7988 100644
--- a/test/parallel/test-dotenv-edge-cases.js
+++ b/test/parallel/test-dotenv-edge-cases.js
@@ -98,4 +98,18 @@ describe('.env supports edge cases', () => {
     assert.strictEqual(child.stderr, '');
     assert.strictEqual(child.code, 0);
   });
+
+  it('should handle when --env-file is passed along with --', async () => {
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [
+        '--eval', 'assert.strictEqual(process.env.BASIC, undefined);',
+        '--', '--env-file', validEnvFilePath,
+      ],
+      { cwd: fixtures.path('dotenv') },
+    );
+    assert.strictEqual(child.stdout, '');
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
 });

From c4e38c42e7ca156536a4ea18966f898e14926ed0 Mon Sep 17 00:00:00 2001
From: Bosco Domingo <46006784+BoscoDomingo@users.noreply.github.com>
Date: Mon, 16 Sep 2024 02:58:16 +0200
Subject: [PATCH 2/3] src: add `--env-file-if-exists` flag

Fixes: https://github.com/nodejs/node/issues/50993
Refs: https://github.com/nodejs/node/issues/51451

test: remove unnecessary comment

src: conform to style guidelines

src: change flag to `--env-file-optional`

test: revert automatic linter changes

doc: fix typos

src: change flag to `--env-file-if-exists`

src: refactor `env_file_data` and `GetEnvFileDataFromArgs`

test: clean up tests

src: print error when file not found

test: remove unnecessary extras
PR-URL: https://github.com/nodejs/node/pull/53060
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/api/cli.md                          | 16 +++++++
 src/node.cc                             | 18 +++++---
 src/node_dotenv.cc                      | 55 ++++++++++++++++++-------
 src/node_dotenv.h                       |  6 ++-
 src/node_options.cc                     |  4 ++
 src/node_options.h                      |  1 +
 test/parallel/test-dotenv-edge-cases.js | 54 ++++++++++++++++++++----
 7 files changed, 122 insertions(+), 32 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 63d2d00efb8eb6..b408d1b6d022d2 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -801,6 +801,8 @@ in the file, the value from the environment takes precedence.
 You can pass multiple `--env-file` arguments. Subsequent files override
 pre-existing variables defined in previous files.
 
+An error is thrown if the file does not exist.
+
 ```bash
 node --env-file=.env --env-file=.development.env index.js
 ```
@@ -840,6 +842,9 @@ Export keyword before a key is ignored:
 export USERNAME="nodejs" # will result in `nodejs` as the value.
 ```
 
+If you want to load environment variables from a file that may not exist, you
+can use the [`--env-file-if-exists`][] flag instead.
+
 ### `-e`, `--eval "script"`
 
 <!-- YAML
@@ -1660,6 +1665,15 @@ is being linked to Node.js. Sharing the OpenSSL configuration may have unwanted
 implications and it is recommended to use a configuration section specific to
 Node.js which is `nodejs_conf` and is default when this option is not used.
 
+### `--env-file-if-exists=config`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Behavior is the same as [`--env-file`][], but an error is not thrown if the file
+does not exist.
+
 ### `--pending-deprecation`
 
 <!-- YAML
@@ -3315,6 +3329,8 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--build-snapshot`]: #--build-snapshot
 [`--cpu-prof-dir`]: #--cpu-prof-dir
 [`--diagnostic-dir`]: #--diagnostic-dirdirectory
+[`--env-file-if-exists`]: #--env-file-if-existsconfig
+[`--env-file`]: #--env-fileconfig
 [`--experimental-default-type=module`]: #--experimental-default-typetype
 [`--experimental-sea-config`]: single-executable-applications.md#generating-single-executable-preparation-blobs
 [`--experimental-wasm-modules`]: #--experimental-wasm-modules
diff --git a/src/node.cc b/src/node.cc
index 9f6f8e53abd7e4..4f422c7668849f 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -889,20 +889,26 @@ static ExitCode InitializeNodeWithArgsInternal(
   HandleEnvOptions(per_process::cli_options->per_isolate->per_env);
 
   std::string node_options;
-  auto file_paths = node::Dotenv::GetPathFromArgs(*argv);
+  auto env_files = node::Dotenv::GetDataFromArgs(*argv);
 
-  if (!file_paths.empty()) {
+  if (!env_files.empty()) {
     CHECK(!per_process::v8_initialized);
 
-    for (const auto& file_path : file_paths) {
-      switch (per_process::dotenv_file.ParsePath(file_path)) {
+    for (const auto& file_data : env_files) {
+      switch (per_process::dotenv_file.ParsePath(file_data.path)) {
         case Dotenv::ParseResult::Valid:
           break;
         case Dotenv::ParseResult::InvalidContent:
-          errors->push_back(file_path + ": invalid format");
+          errors->push_back(file_data.path + ": invalid format");
           break;
         case Dotenv::ParseResult::FileError:
-          errors->push_back(file_path + ": not found");
+          if (file_data.is_optional) {
+            fprintf(stderr,
+                    "%s not found. Continuing without it.\n",
+                    file_data.path.c_str());
+            continue;
+          }
+          errors->push_back(file_data.path + ": not found");
           break;
         default:
           UNREACHABLE();
diff --git a/src/node_dotenv.cc b/src/node_dotenv.cc
index dfbf0a0bfa0acb..2660e716ae2205 100644
--- a/src/node_dotenv.cc
+++ b/src/node_dotenv.cc
@@ -11,43 +11,66 @@ using v8::NewStringType;
 using v8::Object;
 using v8::String;
 
-std::vector<std::string> Dotenv::GetPathFromArgs(
+std::vector<Dotenv::env_file_data> Dotenv::GetDataFromArgs(
     const std::vector<std::string>& args) {
+  const std::string_view optional_env_file_flag = "--env-file-if-exists";
+
   const auto find_match = [](const std::string& arg) {
     auto arg_chars = arg.c_str();
     auto arg_len = arg.size();
     if (arg_chars[0] != '-' || arg_chars[1] != '-') return false;
     if (arg_len == 2) return true;  // arg == "--"
     const std::string_view flag = "env-file";
-    const auto len = flag.size();
+    auto len = flag.size();
     if (strncmp(arg_chars + 2, flag.data(), len) != 0) return false;
+    if (arg_len == 2 + len) return true;
+    const std::string_view flag2 = "-if-exists";
+    if (strncmp(arg_chars + 2 + len, flag2.data(), flag2.size()) == 0)
+      len += flag2.size();
     return arg_len == 2 + len || arg_chars[2 + len] == '=';
   };
-  std::vector<std::string> paths;
-  auto path = std::find_if(args.begin(), args.end(), find_match);
 
-  while (path != args.end()) {
-    if (path->size() == 2 && strncmp(path->c_str(), "--", 2) == 0) {
-      return paths;
+  std::vector<Dotenv::env_file_data> env_files;
+  // This will be an iterator, pointing to args.end() if no matches are found
+  auto matched_arg = std::find_if(args.begin(), args.end(), find_match);
+
+  while (matched_arg != args.end()) {
+    if (matched_arg->size() == 2 &&
+        strncmp(matched_arg->c_str(), "--", 2) == 0) {
+      return env_files;
     }
-    auto equal_char = path->find('=');
 
-    if (equal_char != std::string::npos) {
-      paths.push_back(path->substr(equal_char + 1));
+    auto equal_char_index = matched_arg->find('=');
+
+    if (equal_char_index != std::string::npos) {
+      // `--env-file=path`
+      auto flag = matched_arg->substr(0, equal_char_index);
+      auto file_path = matched_arg->substr(equal_char_index + 1);
+
+      struct env_file_data env_file_data = {
+          file_path, strncmp(matched_arg->c_str(),
+                             optional_env_file_flag.data(),
+                             optional_env_file_flag.size()) == 0};
+      env_files.push_back(env_file_data);
     } else {
-      auto next_path = std::next(path);
+      // `--env-file path`
+      auto file_path = std::next(matched_arg);
 
-      if (next_path == args.end()) {
-        return paths;
+      if (file_path == args.end()) {
+        return env_files;
       }
 
-      paths.push_back(*next_path);
+      struct env_file_data env_file_data = {
+          *file_path, strncmp(matched_arg->c_str(),
+                              optional_env_file_flag.data(),
+                              optional_env_file_flag.size()) == 0};
+      env_files.push_back(env_file_data);
     }
 
-    path = std::find_if(++path, args.end(), find_match);
+    matched_arg = std::find_if(++matched_arg, args.end(), find_match);
   }
 
-  return paths;
+  return env_files;
 }
 
 void Dotenv::SetEnvironment(node::Environment* env) {
diff --git a/src/node_dotenv.h b/src/node_dotenv.h
index ef9ee54a9e75ce..d508b13fc5db74 100644
--- a/src/node_dotenv.h
+++ b/src/node_dotenv.h
@@ -13,6 +13,10 @@ namespace node {
 class Dotenv {
  public:
   enum ParseResult { Valid, FileError, InvalidContent };
+  struct env_file_data {
+    std::string path;
+    bool is_optional;
+  };
 
   Dotenv() = default;
   Dotenv(const Dotenv& d) = delete;
@@ -27,7 +31,7 @@ class Dotenv {
   void SetEnvironment(Environment* env);
   v8::Local<v8::Object> ToObject(Environment* env) const;
 
-  static std::vector<std::string> GetPathFromArgs(
+  static std::vector<env_file_data> GetDataFromArgs(
       const std::vector<std::string>& args);
 
  private:
diff --git a/src/node_options.cc b/src/node_options.cc
index e325b082dec6ae..6950665e9f7476 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -648,6 +648,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "set environment variables from supplied file",
             &EnvironmentOptions::env_file);
   Implies("--env-file", "[has_env_file_string]");
+  AddOption("--env-file-if-exists",
+            "set environment variables from supplied file",
+            &EnvironmentOptions::optional_env_file);
+  Implies("--env-file-if-exists", "[has_env_file_string]");
   AddOption("--test",
             "launch test runner on startup",
             &EnvironmentOptions::test_runner);
diff --git a/src/node_options.h b/src/node_options.h
index 10c220f6612233..70eb01e9f147fc 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -177,6 +177,7 @@ class EnvironmentOptions : public Options {
   std::string redirect_warnings;
   std::string diagnostic_dir;
   std::string env_file;
+  std::string optional_env_file;
   bool has_env_file_string = false;
   bool test_runner = false;
   uint64_t test_runner_concurrency = 0;
diff --git a/test/parallel/test-dotenv-edge-cases.js b/test/parallel/test-dotenv-edge-cases.js
index baad85fa6b7988..a792a3fdbe88a5 100644
--- a/test/parallel/test-dotenv-edge-cases.js
+++ b/test/parallel/test-dotenv-edge-cases.js
@@ -10,30 +10,53 @@ const validEnvFilePath = '../fixtures/dotenv/valid.env';
 const nodeOptionsEnvFilePath = '../fixtures/dotenv/node-options.env';
 
 describe('.env supports edge cases', () => {
-
-  it('supports multiple declarations', async () => {
-    // process.env.BASIC is equal to `basic` because the second .env file overrides it.
+  it('supports multiple declarations, including optional ones', async () => {
     const code = `
       const assert = require('assert');
       assert.strictEqual(process.env.BASIC, 'basic');
       assert.strictEqual(process.env.NODE_NO_WARNINGS, '1');
     `.trim();
+    const children = await Promise.all(Array.from({ length: 4 }, (_, i) =>
+      common.spawnPromisified(
+        process.execPath,
+        [
+          // Bitwise AND to create all 4 possible combinations:
+          // i & 0b01 is truthy when i has value 0bx1 (i.e. 0b01 (1) and 0b11 (3)), falsy otherwise.
+          // i & 0b10 is truthy when i has value 0b1x (i.e. 0b10 (2) and 0b11 (3)), falsy otherwise.
+          `${i & 0b01 ? '--env-file' : '--env-file-if-exists'}=${nodeOptionsEnvFilePath}`,
+          `${i & 0b10 ? '--env-file' : '--env-file-if-exists'}=${validEnvFilePath}`,
+          '--eval', code,
+        ],
+        { cwd: __dirname },
+      )));
+    assert.deepStrictEqual(children, Array.from({ length: 4 }, () => ({
+      code: 0,
+      signal: null,
+      stdout: '',
+      stderr: '',
+    })));
+  });
+
+  it('supports absolute paths', async () => {
+    const code = `
+      require('assert').strictEqual(process.env.BASIC, 'basic');
+    `.trim();
     const child = await common.spawnPromisified(
       process.execPath,
-      [ `--env-file=${nodeOptionsEnvFilePath}`, `--env-file=${validEnvFilePath}`, '--eval', code ],
-      { cwd: __dirname },
+      [ `--env-file=${path.resolve(__dirname, validEnvFilePath)}`, '--eval', code ],
     );
     assert.strictEqual(child.stderr, '');
     assert.strictEqual(child.code, 0);
   });
 
-  it('supports absolute paths', async () => {
+  it('supports a space instead of \'=\' for the flag ', async () => {
     const code = `
       require('assert').strictEqual(process.env.BASIC, 'basic');
     `.trim();
     const child = await common.spawnPromisified(
       process.execPath,
-      [ `--env-file=${path.resolve(__dirname, validEnvFilePath)}`, '--eval', code ],
+      [ '--env-file', validEnvFilePath, '--eval', code ],
+      { cwd: __dirname },
     );
     assert.strictEqual(child.stderr, '');
     assert.strictEqual(child.code, 0);
@@ -48,10 +71,23 @@ describe('.env supports edge cases', () => {
       [ '--env-file=.env', '--eval', code ],
       { cwd: __dirname },
     );
-    assert.notStrictEqual(child.stderr.toString(), '');
+    assert.notStrictEqual(child.stderr, '');
     assert.strictEqual(child.code, 9);
   });
 
+  it('should handle non-existent optional .env file', async () => {
+    const code = `
+      require('assert').strictEqual(1,1);
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      ['--env-file-if-exists=.env', '--eval', code],
+      { cwd: __dirname },
+    );
+    assert.notStrictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
   it('should not override existing environment variables but introduce new vars', async () => {
     const code = `
       require('assert').strictEqual(process.env.BASIC, 'existing');
@@ -106,7 +142,7 @@ describe('.env supports edge cases', () => {
         '--eval', 'assert.strictEqual(process.env.BASIC, undefined);',
         '--', '--env-file', validEnvFilePath,
       ],
-      { cwd: fixtures.path('dotenv') },
+      { cwd: __dirname },
     );
     assert.strictEqual(child.stdout, '');
     assert.strictEqual(child.stderr, '');

From ab56ae8947bc4675c8459690943a9a76a871e491 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9?= <soyjuanarbol@gmail.com>
Date: Wed, 5 Feb 2025 00:34:10 -0500
Subject: [PATCH 3/3] doc: mark `--env-file-if-exists` flag as experimental
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As `--env-file` is experimental, this must be marked as experimental as
well.

Refs: https://github.com/nodejs/node/issues/56887
Signed-off-by: Juan José Arboleda <soyjuanarbol@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/56893
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
---
 doc/api/cli.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index b408d1b6d022d2..dabf9fdff2016c 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1671,6 +1671,8 @@ Node.js which is `nodejs_conf` and is default when this option is not used.
 added: REPLACEME
 -->
 
+> Stability: 1.1 - Active development
+
 Behavior is the same as [`--env-file`][], but an error is not thrown if the file
 does not exist.