src: add process.loadEnvFile programmatic API

doc/api/process.md

@@ -2260,6 +2260,29 @@ 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)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active development
+
+* `path` {string | undefined}
+
+Loads the `.env` file into `process.env`. By default, the path is resolved to
+`path.resolve(process.cwd(), '.env')`. If file is not found, no error is thrown.
+
+```cjs
+const { loadEnvFile } = require('node:process');
+loadEnvFile();
+```
+
+```mjs
+import { loadEnvFile } from 'node:process';
+loadEnvFile();
+```
+
 ## `process.mainModule`
 
 <!-- YAML

lib/internal/bootstrap/node.js

@@ -172,6 +172,7 @@ const rawMethods = internalBinding('process_methods');
   process._kill = rawMethods._kill;
 
   const wrapped = perThreadSetup.wrapProcessMethods(rawMethods);
+  process.loadEnvFile = wrapped.loadEnvFile;
   process._rawDebug = wrapped._rawDebug;
   process.cpuUsage = wrapped.cpuUsage;
   process.resourceUsage = wrapped.resourceUsage;

lib/internal/process/per_thread.js

@@ -45,6 +45,7 @@ const {
   validateArray,
   validateNumber,
   validateObject,
+  validateString,
 } = require('internal/validators');
 const constants = internalBinding('constants').os.signals;
 
@@ -108,6 +109,7 @@ function wrapProcessMethods(binding) {
     memoryUsage: _memoryUsage,
     rss,
     resourceUsage: _resourceUsage,
+    loadEnvFile: _loadEnvFile,
   } = binding;
 
   function _rawDebug(...args) {
@@ -258,6 +260,15 @@ function wrapProcessMethods(binding) {
     };
   }
 
+  function loadEnvFile(path) {
+    if (path != null) {
+      validateString(path, 'path');
+      _loadEnvFile(path);
+    } else {
+      _loadEnvFile();
+    }
+  }
+
 
   return {
     _rawDebug,
@@ -266,6 +277,7 @@ function wrapProcessMethods(binding) {
     memoryUsage,
     kill,
     exit,
+    loadEnvFile,
   };
 }
 

src/node_process.h

@@ -84,6 +84,8 @@ class BindingData : public SnapshotableObject {
 
   static void SlowBigInt(const v8::FunctionCallbackInfo<v8::Value>& args);
 
+  static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args);
+
  private:
   // Buffer length in uint32.
   static constexpr size_t kHrTimeBufferLength = 3;

src/node_process_methods.cc

@@ -4,6 +4,7 @@
 #include "env-inl.h"
 #include "memory_tracker-inl.h"
 #include "node.h"
+#include "node_dotenv.h"
 #include "node_errors.h"
 #include "node_external_reference.h"
 #include "node_internals.h"
@@ -463,6 +464,23 @@ static void ReallyExit(const FunctionCallbackInfo<Value>& args) {
   env->Exit(code);
 }
 
+static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  std::string path = ".env";
+  if (args.Length() == 1) {
+    CHECK(args[0]->IsString());
+    Utf8Value path_value(args.GetIsolate(), args[0]);
+    path = path_value.ToString();
+  }
+
+  THROW_IF_INSUFFICIENT_PERMISSIONS(
+      env, permission::PermissionScope::kFileSystemRead, path);
+
+  Dotenv dotenv{};
+  dotenv.ParsePath(path);
+  dotenv.SetEnvironment(env);
+}
+
 namespace process {
 
 BindingData::BindingData(Realm* realm,
@@ -616,6 +634,8 @@ static void CreatePerIsolateProperties(IsolateData* isolate_data,
   SetMethod(isolate, target, "reallyExit", ReallyExit);
   SetMethodNoSideEffect(isolate, target, "uptime", Uptime);
   SetMethod(isolate, target, "patchProcessObject", PatchProcessObject);
+
+  SetMethod(isolate, target, "loadEnvFile", LoadEnvFile);
 }
 
 static void CreatePerContextProperties(Local<Object> target,
@@ -653,6 +673,8 @@ void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(ReallyExit);
   registry->Register(Uptime);
   registry->Register(PatchProcessObject);
+
+  registry->Register(LoadEnvFile);
 }
 
 }  // namespace process

test/fixtures/dotenv/.env

@@ -0,0 +1 @@
+BASIC=basic

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

@@ -0,0 +1,72 @@
+'use strict';
+
+const common = require('../common');
+const fixtures = require('../../test/common/fixtures');
+const path = require('node:path');
+const assert = require('node:assert');
+const { describe, it } = require('node:test');
+
+const validEnvFilePath = fixtures.path('dotenv/valid.env');
+const missingEnvFile = fixtures.path('dotenv/non-existent-file.env');
+
+describe('process.loadEnvFile()', () => {
+
+  it('supports passing path', async () => {
+    const code = `
+      process.loadEnvFile(${JSON.stringify(validEnvFilePath)});
+      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 not-passing a path', async () => {
+    // Uses `../fixtures/dotenv/.env` file.
+    const code = `
+      process.loadEnvFile();
+      const assert = require('assert');
+      assert.strictEqual(process.env.BASIC, 'basic');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: path.join(__dirname, '../fixtures/dotenv') },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('should handle non-existent files', async () => {
+    const code = `
+      process.loadEnvFile(${JSON.stringify(missingEnvFile)});
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
+  it('should check for permissions', async () => {
+    const code = `
+      process.loadEnvFile(${JSON.stringify(missingEnvFile)});
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code, '--experimental-permission' ],
+      { cwd: __dirname },
+    );
+    assert.match(child.stderr, /Error: Access to this API has been restricted/);
+    assert.match(child.stderr, /code: 'ERR_ACCESS_DENIED'/);
+    assert.match(child.stderr, /permission: 'FileSystemRead'/);
+    assert.strictEqual(child.code, 1);
+  });
+});