node:module: implement synchronous module.registerHooks() (+49 tests)
Draft
CI
9d ago+2396+2396+0123456789012345678901234567890123456789-4-4-0123456789
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/dynamicimport,import.meta.resolve), with Node's context contract (parentURL,conditions,importAttributes),nextResolvechaining, theshortCircuitrequirement, andERR_INVALID_RETURN_PROPERTY_VALUEvalidation. - load chain: hooks observe module loads with Node's
{url, context.format}contract and can replace the source; returnedformat(module,commonjs,json, the*-typescriptvariants) maps onto Bun's loader + module-type pipeline. Builtins are observed withnode:-prefixed URLs and anulldefault source (source overrides for builtins are ignored, like Node ignores them forbuiltinformat). hook.deregister(), hook chaining/merged contexts, and virtual specifiers (e.g.virtual:xids produced by hooks) work.module.register()stays a no-op but now emits Node'sDEP0205deprecation warning pointing atregisterHooks().
How it's wired
src/js/internal/modules/customization_hooks.ts— port of Node'slib/internal/modules/customization_hooks.jschain/validation logic, plus the two Bun-facing entry points (runResolveHooksBun,runLoadHooksBun).- The native resolver funnel (
VirtualMachine::resolve_maybe_needs_trailing_slash, and itsjsc_hooks.rstwin) 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_moduleconsults it for builtins. All gated on plain integer counters mirrored ontoVirtualMachine, 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_VALUEandERR_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.mjsandtest-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 20test-esm-loader-*failures in the es-module suite all depend on it (--experimental-loader/--loaderchildren or directregister()calls);register()is deprecated upstream (DEP0205). Tests: gated on that feature. custom-conditions*(3) — per-resolutioncontext.conditionsoverrides 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 MBfixtures/snapshot/typescript.jsupstream fixture.load-async-and-sync,require-esm(2) — need off-threadregister().builtin-require,load-builtin-require(2) — requirenode:sea, which Bun does not implement.create-require-with-url(1) — needs URL-string specifiers preserved throughcreateRequire(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 intest/js/node/module/node-module-module.test.js), but the upstream test asserts Node's[DEP0205]stderr format and--throw-deprecationexit behavior, which Bun's warning printer does not produce.