module: runtime deprecate module.register()

doc/api/deprecations.md

@@ -4523,6 +4523,27 @@ Type: Runtime
 Passing a non-extractable [`CryptoKey`][] to [`KeyObject.from()`][] is
 deprecated and will throw an error in a future version.
 
+### DEP0205: `module.register()`
+
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62401
+    description: Runtime deprecation.
+-->
+
+Type: Runtime
+
+[`module.register()`][] is deprecated. Use [`module.registerHooks()`][]
+instead.
+
+The `module.register()` API provides async hooks for customizing ES modules;
+the `module.registerHooks()` API provides the same hooks, but as synchronous.
+Supporting async hooks has proven to be complex, involving worker threads, and
+there are issues that have proven unresolveable. Please migrate to
+`module.registerHooks()` as soon as possible as `module.register()` will be
+removed in a future version of Node.js.
+
 [DEP0142]: #dep0142-repl_builtinlibs
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -4627,6 +4648,8 @@ deprecated and will throw an error in a future version.
 [`message.trailersDistinct`]: http.md#messagetrailersdistinct
 [`message.trailers`]: http.md#messagetrailers
 [`module.createRequire()`]: module.md#modulecreaterequirefilename
+[`module.register()`]: module.md#moduleregisterspecifier-parenturl-options
+[`module.registerHooks()`]: module.md#moduleregisterhooksoptions
 [`os.networkInterfaces()`]: os.md#osnetworkinterfaces
 [`os.tmpdir()`]: os.md#ostmpdir
 [`process.env`]: process.md#processenv

doc/api/module.md

@@ -178,7 +178,11 @@ isBuiltin('wss'); // false
 added:
   - v20.6.0
   - v18.19.0
+deprecated: REPLACEME
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/62401
+    description: Runtime deprecation (DEP0205).
   - version:
     - v23.6.1
     - v22.13.1
@@ -193,7 +197,7 @@ changes:
     description: Add support for WHATWG URL instances.
 -->
 
-> Stability: 1.1 - Active development
+> Stability: 0 - Deprecated: Use [`module.registerHooks()`][] instead.
 
 * `specifier` {string|URL} Customization hooks to be registered; this should be
   the same string that would be passed to `import()`, except that if it is

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 emitRegisterDeprecation = getDeprecationWarningEmitter(
+  'DEP0205',
+  '`module.register()` is deprecated. Use `module.registerHooks()` instead.',
+  undefined,
+  false,
+);
+
 function register(specifier, parentURL = undefined, options) {
+  emitRegisterDeprecation();
+
   if (parentURL != null && typeof parentURL === 'object' && !isURL(parentURL)) {
     options = parentURL;
     parentURL = options.parentURL;

test/doctool/test-doc-api-json.mjs

@@ -159,5 +159,5 @@ for await (const dirent of await fs.opendir(new URL('../../out/doc/api/', import
   assert.partialDeepStrictEqual(allExpectedKeys, findAllKeys(json));
 }
 
-assert.strictEqual(numberOfDeprecatedSections, 44); // Increase this number every time a new API is deprecated.
+assert.strictEqual(numberOfDeprecatedSections, 45); // Increase this number every time a new API is deprecated.
 assert.strictEqual(numberOfRemovedAPIs, 46); // Increase this number every time a section is marked as removed.

test/es-module/test-esm-register-deprecation.mjs

@@ -0,0 +1,60 @@
+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() deprecation (DEP0205)', { concurrency: !process.env.TEST_PARALLEL }, () => {
+  it('emits DEP0205 when module.register() is called', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module'; register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.match(stderr, /\[DEP0205\]/);
+    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('[DEP0205]').length - 1, 1);
+    assert.strictEqual(code, 0);
+  });
+
+  it('does not emit when --no-deprecation is set', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--no-deprecation',
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module'; register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.doesNotMatch(stderr, /DEP0205/);
+    assert.strictEqual(code, 0);
+  });
+
+  it('throws when --throw-deprecation is set', async () => {
+    const { code, stderr } = await spawnPromisified(execPath, [
+      '--throw-deprecation',
+      '--input-type=module',
+      '--eval',
+      `import { register } from 'node:module'; register(${urlToRegisterEscaped});`,
+    ]);
+
+    assert.match(stderr, /DEP0205/);
+    assert.notStrictEqual(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-deprecation',
     '--no-experimental-require-module',
     '--import',
     fixtures.fileURL('es-module-loaders/builtin-named-exports.mjs'),