From c6ce9fd2e26674bf98f5f07c71e556e169fc759e Mon Sep 17 00:00:00 2001
From: Chengzhong Wu <legendecas@gmail.com>
Date: Wed, 13 Nov 2024 23:38:08 +0000
Subject: [PATCH] esm: experimental addon modules

---
 doc/api/cli.md                              | 13 +++-
 doc/api/esm.md                              | 19 +++--
 doc/node.1                                  |  3 +
 lib/internal/modules/esm/formats.js         |  5 ++
 lib/internal/modules/esm/load.js            |  3 +
 lib/internal/modules/esm/translators.js     | 81 ++++++++++++++++++---
 lib/internal/validators.js                  | 14 ++++
 src/node_options.cc                         |  4 +
 src/node_options.h                          |  1 +
 test/addons/esm/binding-export-default.cc   | 17 +++++
 test/addons/esm/binding-export-primitive.cc | 17 +++++
 test/addons/esm/binding.cc                  | 17 +++++
 test/addons/esm/binding.gyp                 | 19 +++++
 test/addons/esm/test-esm.mjs                | 48 ++++++++++++
 test/addons/esm/test.js                     |  9 +++
 15 files changed, 252 insertions(+), 18 deletions(-)
 create mode 100644 test/addons/esm/binding-export-default.cc
 create mode 100644 test/addons/esm/binding-export-primitive.cc
 create mode 100644 test/addons/esm/binding.cc
 create mode 100644 test/addons/esm/binding.gyp
 create mode 100644 test/addons/esm/test-esm.mjs
 create mode 100644 test/addons/esm/test.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 7b132e701327d1..e5778172a1f96e 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -48,7 +48,8 @@ Otherwise, the file is loaded using the CommonJS module loader. See
 When loading, the [ES module loader][Modules loaders] loads the program
 entry point, the `node` command will accept as input only files with `.js`,
 `.mjs`, or `.cjs` extensions; with `.wasm` extensions when
-[`--experimental-wasm-modules`][] is enabled; and with no extension when
+[`--experimental-wasm-modules`][] is enabled; with `.node` extensions when
+[`--experimental-addon-modules`][] is enabled; and with no extension when
 [`--experimental-default-type=module`][] is passed.
 
 ## Options
@@ -903,6 +904,14 @@ and `"` are usable.
 It is possible to run code containing inline types by passing
 [`--experimental-strip-types`][].
 
+### `--experimental-addon-modules`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental addon modules with extension `.node` support.
+
 ### `--experimental-default-type=type`
 
 <!-- YAML
@@ -3031,6 +3040,7 @@ one is included in the list below.
 * `--enable-source-maps`
 * `--entry-url`
 * `--experimental-abortcontroller`
+* `--experimental-addon-modules`
 * `--experimental-default-type`
 * `--experimental-detect-module`
 * `--experimental-eventsource`
@@ -3589,6 +3599,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--diagnostic-dir`]: #--diagnostic-dirdirectory
 [`--env-file-if-exists`]: #--env-file-if-existsconfig
 [`--env-file`]: #--env-fileconfig
+[`--experimental-addon-modules`]: #--experimental-addon-modules
 [`--experimental-default-type=module`]: #--experimental-default-typetype
 [`--experimental-sea-config`]: single-executable-applications.md#generating-single-executable-preparation-blobs
 [`--experimental-strip-types`]: #--experimental-strip-types
diff --git a/doc/api/esm.md b/doc/api/esm.md
index 6473fbae5cc4ad..be570c72d3d75e 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -1027,18 +1027,21 @@ _isImports_, _conditions_)
 > 5. If `--experimental-wasm-modules` is enabled and _url_ ends in
 >    _".wasm"_, then
 >    1. Return _"wasm"_.
-> 6. Let _packageURL_ be the result of **LOOKUP\_PACKAGE\_SCOPE**(_url_).
-> 7. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_).
-> 8. Let _packageType_ be **null**.
-> 9. If _pjson?.type_ is _"module"_ or _"commonjs"_, then
->    1. Set _packageType_ to _pjson.type_.
-> 10. If _url_ ends in _".js"_, then
+> 6. If `--experimental-addon-modules` is enabled and _url_ ends in
+>    _".node"_, then
+>    1. Return _"addon"_.
+> 7. Let _packageURL_ be the result of **LOOKUP\_PACKAGE\_SCOPE**(_url_).
+> 8. Let _pjson_ be the result of **READ\_PACKAGE\_JSON**(_packageURL_).
+> 9. Let _packageType_ be **null**.
+> 10. If _pjson?.type_ is _"module"_ or _"commonjs"_, then
+>     1. Set _packageType_ to _pjson.type_.
+> 11. If _url_ ends in _".js"_, then
 >     1. If _packageType_ is not **null**, then
 >        1. Return _packageType_.
 >     2. If the result of **DETECT\_MODULE\_SYNTAX**(_source_) is true, then
 >        1. Return _"module"_.
 >     3. Return _"commonjs"_.
-> 11. If _url_ does not have any extension, then
+> 12. If _url_ does not have any extension, then
 >     1. If _packageType_ is _"module"_ and `--experimental-wasm-modules` is
 >        enabled and the file at _url_ contains the header for a WebAssembly
 >        module, then
@@ -1048,7 +1051,7 @@ _isImports_, _conditions_)
 >     3. If the result of **DETECT\_MODULE\_SYNTAX**(_source_) is true, then
 >        1. Return _"module"_.
 >     4. Return _"commonjs"_.
-> 12. Return **undefined** (will throw during load phase).
+> 13. Return **undefined** (will throw during load phase).
 
 **LOOKUP\_PACKAGE\_SCOPE**(_url_)
 
diff --git a/doc/node.1 b/doc/node.1
index 3d92fcd7858b98..b77384d7a3c61c 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -163,6 +163,9 @@ Enable Source Map V3 support for stack traces.
 .It Fl -entry-url
 Interpret the entry point as a URL.
 .
+.It Fl -experimental-addon-modules
+Enable experimental addon module support.
+.
 .It Fl -experimental-default-type Ns = Ns Ar type
 Interpret as either ES modules or CommonJS modules input via --eval or STDIN, when --input-type is unspecified;
 .js or extensionless files with no sibling or parent package.json;
diff --git a/lib/internal/modules/esm/formats.js b/lib/internal/modules/esm/formats.js
index 608b69caf3fe49..426e5a9f7ae7ec 100644
--- a/lib/internal/modules/esm/formats.js
+++ b/lib/internal/modules/esm/formats.js
@@ -10,6 +10,7 @@ const fsBindings = internalBinding('fs');
 const { fs: fsConstants } = internalBinding('constants');
 
 const experimentalWasmModules = getOptionValue('--experimental-wasm-modules');
+const experimentalAddonModules = getOptionValue('--experimental-addon-modules');
 
 const extensionFormatMap = {
   '__proto__': null,
@@ -23,6 +24,10 @@ if (experimentalWasmModules) {
   extensionFormatMap['.wasm'] = 'wasm';
 }
 
+if (experimentalAddonModules) {
+  extensionFormatMap['.node'] = 'addon';
+}
+
 if (getOptionValue('--experimental-strip-types')) {
   extensionFormatMap['.ts'] = 'module-typescript';
   extensionFormatMap['.mts'] = 'module-typescript';
diff --git a/lib/internal/modules/esm/load.js b/lib/internal/modules/esm/load.js
index 5ba13096b98047..6acfe47591b5f9 100644
--- a/lib/internal/modules/esm/load.js
+++ b/lib/internal/modules/esm/load.js
@@ -109,6 +109,9 @@ async function defaultLoad(url, context = kEmptyObject) {
   if (urlInstance.protocol === 'node:') {
     source = null;
     format ??= 'builtin';
+  } else if (format === 'addon') {
+    // Skip loading addon file content. It must be loaded with dlopen.
+    source = null;
   } else if (format !== 'commonjs' || defaultType === 'module') {
     if (source == null) {
       ({ responseURL, source } = await getSource(urlInstance, context));
diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
index a9a3234befe10f..c2864972b16ad9 100644
--- a/lib/internal/modules/esm/translators.js
+++ b/lib/internal/modules/esm/translators.js
@@ -52,6 +52,7 @@ const {
   ERR_UNKNOWN_BUILTIN_MODULE,
 } = require('internal/errors').codes;
 const { maybeCacheSourceMap } = require('internal/source_map/source_map_cache');
+const { validateNull } = require('internal/validators');
 const moduleWrap = internalBinding('module_wrap');
 const { ModuleWrap } = moduleWrap;
 
@@ -225,6 +226,48 @@ function createCJSModuleWrap(url, source, isMain, loadCJS = loadCJSModule) {
   }, module);
 }
 
+/**
+ * Creates a ModuleWrap object for a CommonJS module without source texts.
+ * @param {string} url - The URL of the module.
+ * @param {boolean} isMain - Whether the module is the main module.
+ * @returns {ModuleWrap} The ModuleWrap object for the CommonJS module.
+ */
+function createCJSNoSourceModuleWrap(url, isMain) {
+  debug(`Translating CJSModule without source ${url}`);
+
+  const filename = urlToFilename(url);
+
+  const { exportNames, module } = cjsEmplaceModuleCacheEntry(filename);
+  if (exportNames === undefined) {
+    // Addon export names are not known until the addon is loaded.
+    module[kModuleExportNames] = ['default', 'module.exports'];
+  }
+  cjsCache.set(url, module);
+
+  if (isMain) {
+    setOwnProperty(process, 'mainModule', module);
+  }
+
+  const wrapperNames = module[kModuleExportNames];
+  return new ModuleWrap(url, undefined, wrapperNames, function() {
+    debug(`Loading CJSModule ${url}`);
+
+    if (!module.loaded) {
+      wrapModuleLoad(filename, null, isMain);
+    }
+
+    let exports;
+    if (module[kModuleExport] !== undefined) {
+      exports = module[kModuleExport];
+      module[kModuleExport] = undefined;
+    } else {
+      ({ exports } = module);
+    }
+    this.setExport('default', exports);
+    this.setExport('module.exports', exports);
+  }, module);
+}
+
 translators.set('commonjs-sync', function requireCommonJS(url, source, isMain) {
   initCJSParseSync();
 
@@ -276,12 +319,7 @@ translators.set('commonjs', function commonjsStrategy(url, source, isMain) {
   return createCJSModuleWrap(url, source, isMain, cjsLoader);
 });
 
-/**
- * Pre-parses a CommonJS module's exports and re-exports.
- * @param {string} filename - The filename of the module.
- * @param {string} [source] - The source code of the module.
- */
-function cjsPreparseModuleExports(filename, source) {
+function cjsEmplaceModuleCacheEntry(filename) {
   // TODO: Do we want to keep hitting the user mutable CJS loader here?
   let module = CJSModule._cache[filename];
   if (module && module[kModuleExportNames] !== undefined) {
@@ -293,10 +331,23 @@ function cjsPreparseModuleExports(filename, source) {
     module.filename = filename;
     module.paths = CJSModule._nodeModulePaths(module.path);
     module[kIsCachedByESMLoader] = true;
-    module[kModuleSource] = source;
     CJSModule._cache[filename] = module;
   }
 
+  return { module };
+}
+
+/**
+ * Pre-parses a CommonJS module's exports and re-exports.
+ * @param {string} filename - The filename of the module.
+ * @param {string} [source] - The source code of the module.
+ */
+function cjsPreparseModuleExports(filename, source) {
+  const { module, exportNames: cachedExportNames } = cjsEmplaceModuleCacheEntry(filename);
+  if (cachedExportNames !== undefined) {
+    return { module, exportNames: cachedExportNames };
+  }
+
   let exports, reexports;
   try {
     ({ exports, reexports } = cjsParse(source || ''));
@@ -308,11 +359,10 @@ function cjsPreparseModuleExports(filename, source) {
   const exportNames = new SafeSet(new SafeArrayIterator(exports));
 
   // Set first for cycles.
+  module[kModuleSource] = source;
   module[kModuleExportNames] = exportNames;
 
   if (reexports.length) {
-    module.filename = filename;
-    module.paths = CJSModule._nodeModulePaths(module.path);
     for (let i = 0; i < reexports.length; i++) {
       const reexport = reexports[i];
       let resolved;
@@ -459,6 +509,19 @@ translators.set('wasm', async function(url, source) {
   }).module;
 });
 
+// Strategy for loading a addon
+translators.set('addon', async function(url, source, isMain) {
+  emitExperimentalWarning('Importing addons');
+
+  // The addon must be loaded from file system with dlopen. Assert
+  // the source is null.
+  validateNull(source, 'source');
+
+  debug(`Translating addon ${url}`);
+
+  return createCJSNoSourceModuleWrap(url, isMain);
+});
+
 // Strategy for loading a commonjs TypeScript module
 translators.set('commonjs-typescript', function(url, source) {
   emitExperimentalWarning('Type Stripping');
diff --git a/lib/internal/validators.js b/lib/internal/validators.js
index 9798e0b5fe353c..5c7cbbee3bbe6c 100644
--- a/lib/internal/validators.js
+++ b/lib/internal/validators.js
@@ -487,6 +487,19 @@ const validateUndefined = hideStackFrames((value, name) => {
     throw new ERR_INVALID_ARG_TYPE(name, 'undefined', value);
 });
 
+/**
+ * @callback validateNull
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts value is null}
+ */
+
+/** @type {validateNull} */
+const validateNull = hideStackFrames((value, name) => {
+  if (value !== null)
+    throw new ERR_INVALID_ARG_TYPE(name, 'null', value);
+});
+
 /**
  * @template T
  * @param {T} value
@@ -623,6 +636,7 @@ module.exports = {
   validateFunction,
   validateInt32,
   validateInteger,
+  validateNull,
   validateNumber,
   validateObject,
   kValidateObjectNone,
diff --git a/src/node_options.cc b/src/node_options.cc
index 4b36a516c80121..83a6235df6ae15 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -411,6 +411,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "Treat the entrypoint as a URL",
             &EnvironmentOptions::entry_is_url,
             kAllowedInEnvvar);
+  AddOption("--experimental-addon-modules",
+            "experimental ES Module support for addons",
+            &EnvironmentOptions::experimental_addon_modules,
+            kAllowedInEnvvar);
   AddOption("--experimental-abortcontroller", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--experimental-eventsource",
             "experimental EventSource API",
diff --git a/src/node_options.h b/src/node_options.h
index a3521e9aea88b1..d463932f8e4acf 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -120,6 +120,7 @@ class EnvironmentOptions : public Options {
   bool require_module = true;
   std::string dns_result_order;
   bool enable_source_maps = false;
+  bool experimental_addon_modules = false;
   bool experimental_eventsource = false;
   bool experimental_fetch = true;
   bool experimental_websocket = true;
diff --git a/test/addons/esm/binding-export-default.cc b/test/addons/esm/binding-export-default.cc
new file mode 100644
index 00000000000000..d3bb03ea3e4acb
--- /dev/null
+++ b/test/addons/esm/binding-export-default.cc
@@ -0,0 +1,17 @@
+#include <node.h>
+#include <uv.h>
+#include <v8.h>
+
+static void Method(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  args.GetReturnValue().Set(
+      v8::String::NewFromUtf8(isolate, "hello world").ToLocalChecked());
+}
+
+static void InitModule(v8::Local<v8::Object> exports,
+                       v8::Local<v8::Value> module,
+                       v8::Local<v8::Context> context) {
+  NODE_SET_METHOD(exports, "default", Method);
+}
+
+NODE_MODULE_CONTEXT_AWARE(Binding, InitModule)
diff --git a/test/addons/esm/binding-export-primitive.cc b/test/addons/esm/binding-export-primitive.cc
new file mode 100644
index 00000000000000..b4dd1ddeda993a
--- /dev/null
+++ b/test/addons/esm/binding-export-primitive.cc
@@ -0,0 +1,17 @@
+#include <node.h>
+#include <uv.h>
+#include <v8.h>
+
+static void InitModule(v8::Local<v8::Object> exports,
+                       v8::Local<v8::Value> module_val,
+                       v8::Local<v8::Context> context) {
+  v8::Isolate* isolate = context->GetIsolate();
+  v8::Local<v8::Object> module = module_val.As<v8::Object>();
+  module
+      ->Set(context,
+            v8::String::NewFromUtf8(isolate, "exports").ToLocalChecked(),
+            v8::String::NewFromUtf8(isolate, "hello world").ToLocalChecked())
+      .FromJust();
+}
+
+NODE_MODULE_CONTEXT_AWARE(Binding, InitModule)
diff --git a/test/addons/esm/binding.cc b/test/addons/esm/binding.cc
new file mode 100644
index 00000000000000..a3f0bf76d3a988
--- /dev/null
+++ b/test/addons/esm/binding.cc
@@ -0,0 +1,17 @@
+#include <node.h>
+#include <uv.h>
+#include <v8.h>
+
+static void Method(const v8::FunctionCallbackInfo<v8::Value>& args) {
+  v8::Isolate* isolate = args.GetIsolate();
+  args.GetReturnValue().Set(
+      v8::String::NewFromUtf8(isolate, "world").ToLocalChecked());
+}
+
+static void InitModule(v8::Local<v8::Object> exports,
+                       v8::Local<v8::Value> module,
+                       v8::Local<v8::Context> context) {
+  NODE_SET_METHOD(exports, "hello", Method);
+}
+
+NODE_MODULE_CONTEXT_AWARE(Binding, InitModule)
diff --git a/test/addons/esm/binding.gyp b/test/addons/esm/binding.gyp
new file mode 100644
index 00000000000000..cb155238cd1ba2
--- /dev/null
+++ b/test/addons/esm/binding.gyp
@@ -0,0 +1,19 @@
+{
+  'targets': [
+    {
+      'target_name': 'binding',
+      'sources': [ 'binding.cc' ],
+      'includes': ['../common.gypi'],
+    },
+    {
+      'target_name': 'binding-export-default',
+      'sources': [ 'binding-export-default.cc' ],
+      'includes': ['../common.gypi'],
+    },
+    {
+      'target_name': 'binding-export-primitive',
+      'sources': [ 'binding-export-primitive.cc' ],
+      'includes': ['../common.gypi'],
+    }
+  ]
+}
diff --git a/test/addons/esm/test-esm.mjs b/test/addons/esm/test-esm.mjs
new file mode 100644
index 00000000000000..19b9c721d2a489
--- /dev/null
+++ b/test/addons/esm/test-esm.mjs
@@ -0,0 +1,48 @@
+// eslint-disable-next-line node-core/require-common-first
+import { buildType } from '../../common/index.mjs';
+import assert from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// binding.node
+{
+  const bindingPath = require.resolve(`./build/${buildType}/binding.node`);
+  const { default: binding, 'module.exports': exports } = await import(bindingPath);
+  assert.strictEqual(binding, exports);
+  assert.strictEqual(binding.hello(), 'world');
+
+  const bindingRequire = require(bindingPath);
+  assert.strictEqual(binding, bindingRequire);
+  assert.strictEqual(binding.hello, bindingRequire.hello);
+
+  // Test multiple loading of the same addon.
+  // ESM cache can not be removed.
+  delete require.cache[bindingPath];
+  const { default: rebinding } = await import(bindingPath);
+  assert.strictEqual(rebinding.hello(), 'world');
+  assert.strictEqual(binding.hello, rebinding.hello);
+}
+
+// binding-export-default.node
+{
+  const bindingPath = require.resolve(`./build/${buildType}/binding-export-default.node`);
+  const binding = await import(bindingPath);
+
+  // As same as ESM-import-CJS, the default export is the value of `module.exports`.
+  assert.strictEqual(binding.default, binding['module.exports']);
+  assert.strictEqual(binding.default.default(), 'hello world');
+
+  const bindingRequire = require(bindingPath);
+  assert.strictEqual(binding.default, bindingRequire);
+}
+
+// binding-export-primitive.node
+{
+  const bindingPath = require.resolve(`./build/${buildType}/binding-export-primitive.node`);
+  const binding = await import(bindingPath);
+
+  // As same as ESM-import-CJS, the default export is the value of `module.exports`.
+  assert.strictEqual(binding.default, binding['module.exports']);
+  assert.strictEqual(binding.default, 'hello world');
+}
diff --git a/test/addons/esm/test.js b/test/addons/esm/test.js
new file mode 100644
index 00000000000000..0504dbd07148f6
--- /dev/null
+++ b/test/addons/esm/test.js
@@ -0,0 +1,9 @@
+// Flags: --experimental-addon-modules
+
+// FIXME(legendecas): AddonTestConfiguration does not support '.mjs' extension.
+// Eslint complains about ESM syntax in a file with '.js' in 'test/addons'.
+'use strict';
+const common = require('../../common');
+
+import('./test-esm.mjs')
+  .then(common.mustCall(), common.mustNotCall());