util: add loadEnvFile programmatic API

anonrig · anonrig · commit 00927c345f15 · 2024-01-15T14:45:11.000-05:00
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -3305,6 +3305,29 @@ util.isUndefined(null);
 // Returns: false
 ```
 
+### `util.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 util = require('node:util');
+util.loadEnvFile();
+```
+
+```mjs
+import util from 'node:util';
+util.loadEnvFile();
+```
+
 ### `util.log(string)`
 
 <!-- YAML
diff --git a/lib/util.js b/lib/util.js
@@ -67,6 +67,7 @@ const { debuglog } = require('internal/util/debuglog');
 const {
   validateFunction,
   validateNumber,
+  validateString,
 } = require('internal/validators');
 const { isBuffer } = require('buffer').Buffer;
 const types = require('internal/util/types');
@@ -371,6 +372,23 @@ function _exceptionWithHostPort(...args) {
   return new ExceptionWithHostPort(...args);
 }
 
+let dotenv;
+
+/**
+ * Loads the .env file from the given path.
+ * @param {string | undefined} path
+ * @returns {void}
+ */
+function loadEnvFile(path) {
+  dotenv ??= internalBinding('dotenv');
+  if (path != null) {
+    validateString(path, 'path');
+    dotenv.load(path);
+  } else {
+    dotenv.load();
+  }
+}
+
 // Keep the `exports =` so that various functions can still be monkeypatched
 module.exports = {
   _errnoException,
@@ -465,6 +483,7 @@ module.exports = {
     return lazyAbortController().aborted;
   },
   types,
+  loadEnvFile,
 };
 
 defineLazyProperties(
diff --git a/src/base_object_types.h b/src/base_object_types.h
@@ -18,7 +18,8 @@ namespace node {
   V(process_binding_data, process::BindingData)                                \
   V(timers_binding_data, timers::BindingData)                                  \
   V(url_binding_data, url::BindingData)                                        \
-  V(modules_binding_data, modules::BindingData)
+  V(modules_binding_data, modules::BindingData)                                \
+  V(dotenv_binding_data, dotenv::BindingData)
 
 #define UNSERIALIZABLE_BINDING_TYPES(V)                                        \
   V(http2_binding_data, http2::BindingData)                                    \
diff --git a/src/node_binding.cc b/src/node_binding.cc
@@ -37,6 +37,7 @@
   V(constants)                                                                 \
   V(contextify)                                                                \
   V(credentials)                                                               \
+  V(dotenv)                                                                    \
   V(encoding_binding)                                                          \
   V(errors)                                                                    \
   V(fs)                                                                        \
diff --git a/src/node_binding.h b/src/node_binding.h
@@ -41,6 +41,7 @@ static_assert(static_cast<int>(NM_F_LINKED) ==
   V(blob)                                                                      \
   V(builtins)                                                                  \
   V(contextify)                                                                \
+  V(dotenv)                                                                    \
   V(encoding_binding)                                                          \
   V(fs)                                                                        \
   V(fs_dir)                                                                    \
diff --git a/src/node_dotenv.cc b/src/node_dotenv.cc
@@ -1,12 +1,22 @@
 #include "node_dotenv.h"
 #include "env-inl.h"
 #include "node_file.h"
+#include "util.h"
 #include "uv.h"
+#include "v8.h"
 
 namespace node {
 
+using v8::Context;
+using v8::FunctionCallbackInfo;
+using v8::HandleScope;
+using v8::Isolate;
+using v8::Local;
 using v8::NewStringType;
+using v8::Object;
+using v8::ObjectTemplate;
 using v8::String;
+using v8::Value;
 
 std::vector<std::string> Dotenv::GetPathFromArgs(
     const std::vector<std::string>& args) {
@@ -167,4 +177,79 @@ void Dotenv::ParseLine(const std::string_view line) {
   store_.insert_or_assign(std::string(key), value);
 }
 
+namespace dotenv {
+
+void BindingData::MemoryInfo(MemoryTracker* tracker) const {
+  // Do nothing
+}
+
+BindingData::BindingData(Realm* realm,
+                         v8::Local<v8::Object> object,
+                         InternalFieldInfo* info)
+    : SnapshotableObject(realm, object, type_int) {}
+
+bool BindingData::PrepareForSerialization(v8::Local<v8::Context> context,
+                                          v8::SnapshotCreator* creator) {
+  return true;
+}
+
+InternalFieldInfoBase* BindingData::Serialize(int index) {
+  DCHECK_IS_SNAPSHOT_SLOT(index);
+  InternalFieldInfo* info =
+      InternalFieldInfoBase::New<InternalFieldInfo>(type());
+  return info;
+}
+
+void BindingData::Deserialize(v8::Local<v8::Context> context,
+                              v8::Local<v8::Object> holder,
+                              int index,
+                              InternalFieldInfoBase* info) {
+  DCHECK_IS_SNAPSHOT_SLOT(index);
+  HandleScope scope(context->GetIsolate());
+  Realm* realm = Realm::GetCurrent(context);
+  BindingData* binding = realm->AddBindingData<BindingData>(holder);
+  CHECK_NOT_NULL(binding);
+}
+
+void BindingData::Load(const FunctionCallbackInfo<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();
+  }
+
+  Dotenv dotenv{};
+  dotenv.ParsePath(path);
+  dotenv.SetEnvironment(env);
+}
+
+void BindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
+                                             Local<ObjectTemplate> target) {
+  Isolate* isolate = isolate_data->isolate();
+  SetMethod(isolate, target, "load", Load);
+}
+
+void BindingData::CreatePerContextProperties(Local<Object> target,
+                                             Local<Value> unused,
+                                             Local<Context> context,
+                                             void* priv) {
+  Realm* realm = Realm::GetCurrent(context);
+  realm->AddBindingData<BindingData>(target);
+}
+
+void BindingData::RegisterExternalReferences(
+    ExternalReferenceRegistry* registry) {
+  registry->Register(Load);
+}
+
+}  // namespace dotenv
 }  // namespace node
+
+NODE_BINDING_CONTEXT_AWARE_INTERNAL(
+    dotenv, node::dotenv::BindingData::CreatePerContextProperties)
+NODE_BINDING_PER_ISOLATE_INIT(
+    dotenv, node::dotenv::BindingData::CreatePerIsolateProperties)
+NODE_BINDING_EXTERNAL_REFERENCE(
+    dotenv, node::dotenv::BindingData::RegisterExternalReferences)
diff --git a/src/node_dotenv.h b/src/node_dotenv.h
@@ -3,7 +3,10 @@
 
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
+#include "node.h"
+#include "node_snapshotable.h"
 #include "util-inl.h"
+#include "v8.h"
 
 #include <map>
 
@@ -30,6 +33,35 @@ class Dotenv {
   std::map<std::string, std::string> store_;
 };
 
+class ExternalReferenceRegistry;
+
+namespace dotenv {
+class BindingData : public SnapshotableObject {
+ public:
+  using InternalFieldInfo = InternalFieldInfoBase;
+
+  BindingData(Realm* realm,
+              v8::Local<v8::Object> obj,
+              InternalFieldInfo* info = nullptr);
+  SERIALIZABLE_OBJECT_METHODS()
+  SET_BINDING_ID(dotenv_binding_data)
+
+  void MemoryInfo(MemoryTracker* tracker) const override;
+  SET_SELF_SIZE(BindingData)
+  SET_MEMORY_INFO_NAME(BindingData)
+
+  static void Load(const v8::FunctionCallbackInfo<v8::Value>& args);
+
+  static void CreatePerIsolateProperties(IsolateData* isolate_data,
+                                         v8::Local<v8::ObjectTemplate> ctor);
+  static void CreatePerContextProperties(v8::Local<v8::Object> target,
+                                         v8::Local<v8::Value> unused,
+                                         v8::Local<v8::Context> context,
+                                         void* priv);
+  static void RegisterExternalReferences(ExternalReferenceRegistry* registry);
+};
+}  // namespace dotenv
+
 }  // namespace node
 
 #endif  // defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
diff --git a/src/node_external_reference.h b/src/node_external_reference.h
@@ -101,6 +101,7 @@ class ExternalReferenceRegistry {
   V(cares_wrap)                                                                \
   V(contextify)                                                                \
   V(credentials)                                                               \
+  V(dotenv)                                                                    \
   V(encoding_binding)                                                          \
   V(env_var)                                                                   \
   V(errors)                                                                    \
diff --git a/src/node_snapshotable.cc b/src/node_snapshotable.cc
@@ -14,6 +14,7 @@
 #include "node_blob.h"
 #include "node_builtins.h"
 #include "node_contextify.h"
+#include "node_dotenv.h"
 #include "node_errors.h"
 #include "node_external_reference.h"
 #include "node_file.h"
diff --git a/test/fixtures/dotenv/.env b/test/fixtures/dotenv/.env
@@ -0,0 +1 @@
+BASIC=basic
diff --git a/test/parallel/test-util-load-env-file.js b/test/parallel/test-util-load-env-file.js
@@ -0,0 +1,64 @@
+'use strict';
+
+const common = require('../common');
+const path = require('node:path');
+const assert = require('node:assert');
+const { describe, it } = require('node:test');
+
+let validEnvFilePath = path.join(__dirname, '../fixtures/dotenv/valid.env');
+let missingEnvFile = path.join(__dirname, '../fixtures/dotenv/non-existent-file.env');
+
+if (common.isWindows) {
+  validEnvFilePath = validEnvFilePath.replaceAll('\\', '\\\\');
+  missingEnvFile = missingEnvFile.replaceAll('\\', '\\\\');
+}
+
+describe('loadEnvFile()', () => {
+
+  it('supports passing path', async () => {
+    const code = `
+      const util = require('node:util');
+      util.loadEnvFile('${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 = `
+      const util = require('node:util');
+      util.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 = `
+      const util = require('node:util');
+      util.loadEnvFile('${missingEnvFile}');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+});
diff --git a/typings/globals.d.ts b/typings/globals.d.ts
@@ -15,6 +15,7 @@ import {URLBinding} from "./internalBinding/url";
 import {UtilBinding} from "./internalBinding/util";
 import {WorkerBinding} from "./internalBinding/worker";
 import {ModulesBinding} from "./internalBinding/modules";
+import {DotenvBinding} from "./internalBinding/dotenv";
 
 declare type TypedArray =
   | Uint8Array
@@ -34,6 +35,7 @@ interface InternalBindingMap {
   blob: BlobBinding;
   config: ConfigBinding;
   constants: ConstantsBinding;
+  dotenv: DotenvBinding;
   fs: FsBinding;
   http_parser: HttpParserBinding;
   messaging: MessagingBinding;
diff --git a/typings/internalBinding/dotenv.d.ts b/typings/internalBinding/dotenv.d.ts
@@ -0,0 +1,3 @@
+export interface DotenvBinding {
+  load(path: string | undefined): void;
+}
