node:module: implement synchronous module.registerHooks() (+49 tests)

Draft
CI
9d ago
+2396-4

Implements the synchronous module customization hooks API — module.registerHooks() (Node 23+, the supported successor to module.register()) — and vendors the upstream test/module-hooks/ suite that exercises it.

What this does

module.registerHooks({ resolve, load }) now works in Bun for both require() and import:

  • resolve chain: hooks observe every user-visible resolution (require, require.resolve, static/dynamic import, import.meta.resolve), with Node's context contract (parentURL, conditions, importAttributes), nextResolve chaining, the shortCircuit requirement, and ERR_INVALID_RETURN_PROPERTY_VALUE validation.
  • load chain: hooks observe module loads with Node's {url, context.format} contract and can replace the source; returned format (module, commonjs, json, the *-typescript variants) maps onto Bun's loader + module-type pipeline. Builtins are observed with node:-prefixed URLs and a null default source (source overrides for builtins are ignored, like Node ignores them for builtin format).
  • hook.deregister(), hook chaining/merged contexts, and virtual specifiers (e.g. virtual:x ids produced by hooks) work.
  • module.register() stays a no-op but now emits Node's DEP0205 deprecation warning pointing at registerHooks().

How it's wired

  • src/js/internal/modules/customization_hooks.ts — port of Node's lib/internal/modules/customization_hooks.js chain/validation logic, plus the two Bun-facing entry points (runResolveHooksBun, runLoadHooksBun).
  • The native resolver funnel (VirtualMachine::resolve_maybe_needs_trailing_slash, and its jsc_hooks.rs twin) consults the JS resolve chain before the builtin-alias fast path; the module loader (transpile_file) consults the load chain before reading a module off disk; fetch_builtin_module consults it for builtins. All gated on plain integer counters mirrored onto VirtualMachine, so the hook-free hot path only pays an integer compare.
  • The chain's default steps call back into Bun's native resolution (with a reentrancy flag so the default step can't recurse into hooks) and fs.readFileSync.
  • New error codes ERR_INVALID_RETURN_PROPERTY_VALUE and ERR_UNKNOWN_MODULE_FORMAT (message builders match Node's text).

Tests

Vendored byte-verbatim from Node v26.3.0 (each verified failing on system Bun and passing on this build):

  • test/js/node/test/module-hooks/ — 47 of the 63 sync-hooks tests (the suite is added to the CI runner's inclusion list; a canary run verified the runner executes the new directory).
  • test/js/node/test/es-module/ — test-esm-import-meta-resolve-hooks.mjs and test-import-preload-require-cycle.js (the runner line matches the es-module suite PR; trivial merge overlap).

Not covered (dropped, with reasons)

  • Off-thread module.register() protocol — the 20 test-esm-loader-* failures in the es-module suite all depend on it (--experimental-loader/--loader children or direct register() calls); register() is deprecated upstream (DEP0205). Tests: gated on that feature.
  • custom-conditions* (3) — per-resolution context.conditions overrides need conditions plumbed through the native resolver per-call.
  • load-builtin-override-{commonjs,json,module} (3) — replacing a builtin's implementation via load-hook format override is unsupported.
  • *-inline-typescript* + preload (5) — depend on the 11 MB fixtures/snapshot/typescript.js upstream fixture.
  • load-async-and-sync, require-esm (2) — need off-thread register().
  • builtin-require, load-builtin-require (2) — require node:sea, which Bun does not implement.
  • create-require-with-url (1) — needs URL-string specifiers preserved through createRequire(url).
  • test-esm-import-attributes-identity.mjs (1) — needs the ES module map keyed by import attributes.
  • test-esm-register-deprecation.mjs (1) — the DEP0205 warning is implemented (with Bun-native tests in test/js/node/module/node-module-module.test.js), but the upstream test asserts Node's [DEP0205] stderr format and --throw-deprecation exit behavior, which Bun's warning printer does not produce.