nodejs · mcollina · May 4, 2023 · May 4, 2023 · May 4, 2023 · May 4, 2023
diff --git a/LICENSE b/LICENSE
@@ -2187,7 +2187,7 @@ The externally maintained libraries used by Node.js are:
     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   """
 
-- synchronous-worker, located at lib/internal/vm/localworker.js, is licensed as follows:
+- synchronous-worker, located at lib/internal/vm/node_realm.js, is licensed as follows:
   """
     The MIT License (MIT)
 

diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -530,15 +530,15 @@ changes:
 Specify the `module` of a custom experimental [ECMAScript module loader][].
 `module` may be any string accepted as an [`import` specifier][].
 
-### `--experimental-noderealm`
+### `--experimental-node-realm`
 
 <!-- YAML
 added: REPLACEME
 -->
 
 Enable experimental support for `vm.NodeRealm`.
 
-### `--no-experimental-noderealm`
+### `--no-experimental-node-realm`
 
 <!-- YAML
 added: REPLACEME
@@ -2129,7 +2129,7 @@ Node.js options that are allowed are:
 * `--experimental-import-meta-resolve`
 * `--experimental-json-modules`
 * `--experimental-loader`
-* `--experimental-noderealm`
+* `--experimental-node-realm`
 * `--experimental-modules`
 * `--experimental-network-imports`
 * `--experimental-permission`

diff --git a/doc/api/errors.md b/doc/api/errors.md
@@ -3536,6 +3536,17 @@ removed:
 
 The linker function returned a module for which linking has failed.
 
+<a id="ERR_VM_NODE_REALM_INVALID_PARENT"></a>
+
+### `ERR_VM_NODE_REALM_INVALID_PARENT`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The `createImport()` function was passed a valued that was neither
+a string or a `URL`.
+
 <a id="ERR_WORKER_UNSUPPORTED_EXTENSION"></a>
 
 ### `ERR_WORKER_UNSUPPORTED_EXTENSION`

diff --git a/doc/api/vm.md b/doc/api/vm.md
@@ -1575,7 +1575,8 @@ are not controllable through the timeout either.
 
 ### Class: `NodeRealm`
 
-> Stability: 1 - Experimental. Use `--experimental-noderealm` CLI flag to enable this feature.
+> Stability: 1 - Experimental. Use `--experimental-node-realm` CLI flag to
+> enable this feature.
 
 <!-- YAML
 added: REPLACEME
@@ -1584,12 +1585,17 @@ added: REPLACEME
 * Extends: {EventEmitter}
 
 A `NodeRealm` is effectively a Node.js environment that runs within the
-same thread.
+same thread. It similar to a [ShadowRealm][], but with a few main differences:
+
+* `NodeRealm` allows to load both commonjs and ESM modules.
+* Full interoperability between the host realm and the `NodeRealm` instance
+  is allowed
+* There is a deliberate `stop()` function.
 
 ```mjs
 import { NodeRealm } from 'node:vm';
-const noderealm = new NodeRealm();
-const myAsyncFunction = noderealm.createImport(import.meta.url)('my-module');
+const nodeRealm = new NodeRealm();
+const myAsyncFunction = nodeRealm.createImport(import.meta.url)('my-module');
 console.log(await myAsyncFunction());
 ```
 
@@ -1599,7 +1605,7 @@ console.log(await myAsyncFunction());
 added: REPLACEME
 -->
 
-#### `noderealm.stop()`
+#### `nodeRealm.stop()`
 
 <!-- YAML
 added: REPLACEME
@@ -1614,18 +1620,18 @@ This method returns a promise that will be resolved when all resources
 associated with this Node.js instance are released. This promise resolves on
 the event loop of the _outer_ Node.js instance.
 
-#### `noderealm.createImport(filename)`
+#### `nodeRealm.createImport(filename)`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* `filename` {string}
+* `specifier` {string} A module specifier like './file.js' or 'my-package'
 
 Create a function that can be used for loading
 modules inside the inner Node.js instance.
 
-#### `noderealm.globalThis`
+#### `nodeRealm.globalThis`
 
 <!-- YAML
 added: REPLACEME
@@ -1635,7 +1641,7 @@ added: REPLACEME
 
 Returns a reference to the global object of the inner Node.js instance.
 
-#### `noderealm.process`
+#### `nodeRealm.process`
 
 <!-- YAML
 added: REPLACEME
@@ -1671,3 +1677,4 @@ Returns a reference to the `process` object of the inner Node.js instance.
 [global object]: https://es5.github.io/#x15.1
 [indirect `eval()` call]: https://es5.github.io/#x10.4.2
 [origin]: https://developer.mozilla.org/en-US/docs/Glossary/Origin
+[ShadowRealm]: https://github.com/tc39/proposal-shadowrealm
diff --git a/doc/node.1 b/doc/node.1
@@ -166,6 +166,9 @@ to use as a custom module loader.
 .It Fl -experimental-network-imports
 Enable experimental support for loading modules using `import` over `https:`.
 .
+.It Fl -experimental-node-realm
+Enable experimental support for vm.NodeRealm.
+.
 .It Fl -experimental-permission
 Enable the experimental permission model.
 .

diff --git a/lib/internal/errors.js b/lib/internal/errors.js
@@ -1706,6 +1706,7 @@ E('ERR_VM_MODULE_LINK_FAILURE', function(message, cause) {
 E('ERR_VM_MODULE_NOT_MODULE',
   'Provided module is not an instance of Module', Error);
 E('ERR_VM_MODULE_STATUS', 'Module status %s', Error);
+E('ERR_VM_NODE_REALM_INVALID_PARENT', 'createImport() must be called with a string or URL; received "%s"', Error);
 E('ERR_WASI_ALREADY_STARTED', 'WASI instance has already started', Error);
 E('ERR_WEBASSEMBLY_RESPONSE', 'WebAssembly response %s', TypeError);
 E('ERR_WORKER_INIT_FAILED', 'Worker initialization failure: %s', Error);

diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -269,10 +269,10 @@ function setupFetch() {
 }
 
 function setupNodeRealm() {
-  // Patch the vm module when --experimental-noderealm is on.
+  // Patch the vm module when --experimental-node-realm is on.
   // Please update the comments in vm.js when this block changes.
-  if (getOptionValue('--experimental-noderealm')) {
-    const NodeRealm = require('internal/vm/noderealm');
+  if (getOptionValue('--experimental-node-realm')) {
+    const NodeRealm = require('internal/vm/node_realm');
     const vm = require('vm');
     vm.NodeRealm = NodeRealm;
   }

diff --git a/lib/internal/vm/noderealm.js → lib/internal/vm/node_realm.js b/lib/internal/vm/noderealm.js → lib/internal/vm/node_realm.js
@@ -10,10 +10,19 @@ const {
   Promise,
 } = primordials;
 
+const {
+  emitExperimentalWarning,
+} = require('internal/util');
+
+const {
+  ERR_VM_NODE_REALM_INVALID_PARENT,
+} = require('internal/errors').codes;
+
 const {
   NodeRealm: NodeRealmImpl,
 } = internalBinding('contextify');
 
+const { URL } = require('internal/url');
 const EventEmitter = require('events');
 const { setTimeout } = require('timers');
 const { pathToFileURL } = require('url');
@@ -33,6 +42,7 @@ class NodeRealm extends EventEmitter {
    */
   constructor() {
     super();
+    emitExperimentalWarning('NodeRealm');
     this.#handle = new NodeRealmImpl();
     this.#handle.onexit = (code) => {
       this.stop();
@@ -78,7 +88,7 @@ class NodeRealm extends EventEmitter {
           // but at this point it seems like a premature optimization.
           // We cannot unref() this because we need to shut this down properly.
           // TODO(@mcollina): refactor to use a close callback
-          setTimeout(tryClosing, 100)
+          setTimeout(tryClosing, 100);
         } else {
 
           this.#handle.stop();
@@ -90,7 +100,7 @@ class NodeRealm extends EventEmitter {
       // phase of the event loop. This is important because the immediate queue
       // would crash if the environment it refers to has been already closed.
       // We cannot unref() this because we need to shut this down properly.
-      setTimeout(tryClosing, 100)
+      setTimeout(tryClosing, 100);
     });
   }
 
@@ -113,7 +123,7 @@ class NodeRealm extends EventEmitter {
         parentURL = pathToFileURL(parentURL);
       }
     } else if (!(parentURL instanceof URL)) {
-      throw new Error('createImport() must be called with a string or URL');
+      throw new ERR_VM_NODE_REALM_INVALID_PARENT(parentURL);
     }
 
     return (specifiers, importAssertions) => {

diff --git a/lib/vm.js b/lib/vm.js
@@ -344,4 +344,4 @@ module.exports = {
 // and vm.SyntheticModule in the pre-execution phase when
 // --experimental-vm-modules is on.
 // The vm module is also patched to include vm.NodeRealm in the
-// pre-execution phase when --experimental-noderealm is on.
+// pre-execution phase when --experimental-node-realm is on.
diff --git a/src/env.cc b/src/env.cc
@@ -1021,8 +1021,7 @@ void Environment::CleanupHandles() {
 
   CleanupHandlesNoUvRun();
 
-  while (handle_cleanup_waiting_ != 0 ||
-         request_waiting_ != 0 ||
+  while (handle_cleanup_waiting_ != 0 || request_waiting_ != 0 ||
          !handle_wrap_queue_.IsEmpty()) {
     uv_run(event_loop(), UV_RUN_ONCE);
   }

diff --git a/src/env_properties.h b/src/env_properties.h
@@ -366,7 +366,7 @@
   V(socketaddress_constructor_template, v8::FunctionTemplate)                  \
   V(streambaseentry_ctor_template, v8::FunctionTemplate)                       \
   V(streambaseoutputstream_constructor_template, v8::ObjectTemplate)           \
-  V(noderealm_constructor_template, v8::FunctionTemplate)                      \
+  V(node_realm_constructor_template, v8::FunctionTemplate)                     \
   V(streamentry_ctor_template, v8::FunctionTemplate)                           \
   V(streamentry_opaque_ctor_template, v8::FunctionTemplate)                    \
   V(qlogoutputstream_constructor_template, v8::ObjectTemplate)                 \

diff --git a/src/node_contextify.cc b/src/node_contextify.cc
@@ -21,8 +21,8 @@
 
 #include "node_contextify.h"
 
-#include "base_object-inl.h"
 #include "async_wrap-inl.h"
+#include "base_object-inl.h"
 #include "memory_tracker-inl.h"
 #include "module_wrap.h"
 #include "node_context_data.h"
@@ -1398,7 +1398,7 @@ void MicrotaskQueueWrap::RegisterExternalReferences(
 Local<FunctionTemplate> NodeRealm::GetConstructorTemplate(
     IsolateData* isolate_data) {
   Local<FunctionTemplate> tmpl =
-    isolate_data->noderealm_constructor_template();
+      isolate_data->node_realm_constructor_template();
   if (tmpl.IsEmpty()) {
     Isolate* isolate = isolate_data->isolate();
     tmpl = NewFunctionTemplate(isolate, New);
@@ -1412,13 +1412,13 @@ Local<FunctionTemplate> NodeRealm::GetConstructorTemplate(
     SetProtoMethod(isolate, tmpl, "tryCloseAllHandles", TryCloseAllHandles);
     SetProtoMethod(isolate, tmpl, "internalRequire", InternalRequire);
 
-    isolate_data->set_noderealm_constructor_template(tmpl);
+    isolate_data->set_node_realm_constructor_template(tmpl);
   }
   return tmpl;
 }
 
-void NodeRealm::CreatePerIsolateProperties(IsolateData* isolate_data,
-                                   v8::Local<v8::ObjectTemplate> target) {
+void NodeRealm::CreatePerIsolateProperties(
+    IsolateData* isolate_data, v8::Local<v8::ObjectTemplate> target) {
   SetConstructorFunction(isolate_data->isolate(),
                          target,
                          "NodeRealm",
@@ -1437,8 +1437,7 @@ void NodeRealm::RegisterExternalReferences(
   registry->Register(InternalRequire);
 }
 
-NodeRealm::NodeRealmScope::NodeRealmScope(
-    NodeRealm* w)
+NodeRealm::NodeRealmScope::NodeRealmScope(NodeRealm* w)
     : EscapableHandleScope(w->isolate_),
       Scope(w->context()),
       Isolate::SafeForTerminationScope(w->isolate_),
@@ -1464,8 +1463,7 @@ NodeRealm::NodeRealm(Environment* env, Local<Object> object)
   outer_context_.Reset(env->isolate(), outer_context);
 }
 
-NodeRealm* NodeRealm::Unwrap(
-    const FunctionCallbackInfo<Value>& args) {
+NodeRealm* NodeRealm::Unwrap(const FunctionCallbackInfo<Value>& args) {
   Local<Value> value = args.This();
   if (!value->IsObject() || value.As<Object>()->InternalFieldCount() < 1) {
     THROW_ERR_INVALID_THIS(Environment::GetCurrent(args.GetIsolate()));
@@ -1486,8 +1484,7 @@ void NodeRealm::Start(const FunctionCallbackInfo<Value>& args) {
   self->Start();
 }
 
-void NodeRealm::TryCloseAllHandles(
-    const FunctionCallbackInfo<Value>& args) {
+void NodeRealm::TryCloseAllHandles(const FunctionCallbackInfo<Value>& args) {
   auto count = 0;
   NodeRealm* self = Unwrap(args);
   if (self == nullptr) return;
@@ -1496,11 +1493,10 @@ void NodeRealm::TryCloseAllHandles(
   args.GetReturnValue().Set(v8::Number::New(self->isolate_, count));
 }
 
-void NodeRealm::InternalRequire(
-    const FunctionCallbackInfo<Value>& args) {
+void NodeRealm::InternalRequire(const FunctionCallbackInfo<Value>& args) {
   NodeRealm* self = Unwrap(args);
-  Local<Function> require = Realm::GetCurrent(
-      self->context())->builtin_module_require();
+  Local<Function> require =
+      Realm::GetCurrent(self->context())->builtin_module_require();
   args.GetReturnValue().Set(require);
 }
 
@@ -1540,7 +1536,7 @@ void NodeRealm::Start() {
   assert(loop != nullptr);
 
   MicrotaskQueue* microtask_queue =
-    outer_context_.Get(isolate_)->GetMicrotaskQueue();
+      outer_context_.Get(isolate_)->GetMicrotaskQueue();
 
   Local<Context> context = Context::New(
       isolate_,
@@ -1563,8 +1559,8 @@ void NodeRealm::Start() {
       GetArrayBufferAllocator(GetEnvironmentIsolateData(outer_env)));
   assert(isolate_data_ != nullptr);
   ThreadId thread_id = AllocateEnvironmentThreadId();
-  auto inspector_parent_handle = GetInspectorParentHandle(
-      outer_env, thread_id, "file:///noderealm.js");
+  auto inspector_parent_handle =
+      GetInspectorParentHandle(outer_env, thread_id, "file:///node_realm.js");
   env_ = CreateEnvironment(isolate_data_,
 env()->handle_wrap_queue()->PushBack(this); 
 env()->handle_wrap_queue()->PushBack(this); 
                            context,
                            {},

diff --git a/src/node_contextify.h b/src/node_contextify.h
@@ -4,9 +4,9 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include "base_object-inl.h"
+#include "memory_tracker-inl.h"
 #include "node_context_data.h"
 #include "node_errors.h"
-#include "memory_tracker-inl.h"
 
 namespace node {
 class ExternalReferenceRegistry;

diff --git a/src/node_options.cc b/src/node_options.cc
@@ -442,9 +442,9 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::experimental_vm_modules,
             kAllowedInEnvvar);
   AddOption("--experimental-worker", "", NoOp{}, kAllowedInEnvvar);
-  AddOption("--experimental-noderealm",
+  AddOption("--experimental-node-realm",
             "experimental NodeRealm support",
-            &EnvironmentOptions::experimental_noderealm,
+            &EnvironmentOptions::experimental_node_realm,
             kAllowedInEnvironment,
             false);
   AddOption("--experimental-report", "", NoOp{}, kAllowedInEnvvar);

diff --git a/src/node_options.h b/src/node_options.h
@@ -128,7 +128,7 @@ class EnvironmentOptions : public Options {
   bool experimental_repl_await = true;
   bool experimental_vm_modules = false;
   bool expose_internals = false;
-  bool experimental_noderealm = false;
+  bool experimental_node_realm = false;
 
   bool force_node_api_uncaught_exceptions_policy = false;
   bool frozen_intrinsics = false;