module: emit experimental warning for module.register()

Author: GeoffreyBooth

doc/api/module.md

@@ -179,6 +179,9 @@ added:
   - v20.6.0
   - v18.19.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/REPLACEME
+    description: Runtime experimental warning added.
   - version:
     - v23.6.1
     - v22.13.1

lib/internal/modules/esm/loader.js

@@ -31,7 +31,10 @@ const {
 } = require('internal/errors').codes;
 const { getOptionValue } = require('internal/options');
 const { isURL, pathToFileURL } = require('internal/url');
-const { kEmptyObject } = require('internal/util');
+const {
+  getDeprecationWarningEmitter,
+  kEmptyObject,
+} = require('internal/util');
 const {
   compileSourceTextModule,
   SourceTextModuleTypes: { kUser },
@@ -955,7 +958,16 @@ function isCascadedLoaderInitialized() {
  * });
  * ```
  */
+const emitRegisterExperimentalWarning = getDeprecationWarningEmitter(
+  'ExperimentalWarning',
+  '`module.register()` is an experimental feature and will be removed in a future version of Node.js. ' +
+    'Use `module.registerHooks()` instead.',
+  undefined,
+  false,
+);
+
 function register(specifier, parentURL = undefined, options) {
+  emitRegisterExperimentalWarning();
   if (parentURL != null && typeof parentURL === 'object' && !isURL(parentURL)) {
     options = parentURL;
     parentURL = options.parentURL;

test/es-module/test-esm-register-experimental-warning.mjs

@@ -0,0 +1,48 @@
+import { spawnPromisified } from '../common/index.mjs';
+import * as fixtures from '../common/fixtures.mjs';
+
+import assert from 'node:assert';
+import { execPath } from 'node:process';
+import { describe, it } from 'node:test';
+
+const urlToRegister = fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs');
+const urlToRegisterEscaped = JSON.stringify(urlToRegister.href);
+
+
+describe('module.register() experimental warning', { concurrency: !process.env.TEST_PARALLEL }, () => {
+  it('emits ExperimentalWarning when module.register() is called', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module'; register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.ok(stderr.includes('ExperimentalWarning: `module.register()` is an experimental feature and will be removed in a future version of Node.js. Use `module.registerHooks()` instead.'));
+    assert.strictEqual(code, 0);
+  });
+
+  it('only emits the warning once per process', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module';
+       register(${urlToRegisterEscaped});
+       register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.strictEqual(stderr.split('module.register()').length - 1, 1);
+    assert.strictEqual(code, 0);
+  });
+
+  it('does not emit when --no-warnings is set', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--no-warnings',
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module'; register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.doesNotMatch(stderr, /ExperimentalWarning/);
+    assert.strictEqual(code, 0);
+  });
+});

test/module-hooks/test-async-loader-hooks-use-hooks-require-esm.mjs

@@ -7,6 +7,7 @@ import { spawnSyncAndAssert } from '../common/child_process.js';
 spawnSyncAndAssert(
   execPath,
   [
+    '--no-warnings',
     '--no-experimental-require-module',
     '--import',
     fixtures.fileURL('es-module-loaders/builtin-named-exports.mjs'),