Skip to content

require(esm): read __esModule and "module.exports" in separate try blocks - #48743

Open
robobun wants to merge 5 commits into
mainfrom
robobun/6508bf3c/require-esm-cycle-tdz-interop
Open

robobun wants to merge 5 commits into
mainfrom
robobun/6508bf3c/require-esm-cycle-tdz-interop

Conversation

@robobun

@robobun robobun commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

  • In a require cycle, require() of an ES module returns the namespace ([object Module]), not its "module.exports" export. It happens while its __esModule export is in TDZ. require.cache keeps the namespace.
  • One try block holds both reads (src/js/builtins/CommonJS.ts:138 and :230). The __esModule read throws, so the "module.exports" read never runs.

Fix

  • Each read has its own try, in overridableRequire and in requireESMFromHijackedExtension, which the default Module._extensions handlers call.
  • An export in TDZ now hides only itself. The rest is as on main.
  • Verified: test/js/bun/resolve/require-esm-evaluating-cycle.test.ts, test/js/node/module/require-extensions.test.ts (main fails 12 new tests), one stored --aot program. Also test/js/node/module, test/js/bun/resolve, test/js/bun/test/mock.
  • Self-reviewed: 36 concerns raised on an earlier native version. The verdict was this guard. Its 8 steps are done.

Background

  • In a require cycle the namespace is live. A read of a let export throws a ReferenceError until its declaration runs (TDZ).
  • A "module.exports" export names what require() returns in place of the namespace. __esModule is the mark that transpiled CommonJS code reads.
  • src/js/ahead-of-time/builtins/CommonJS.ts is the builtin's second text, for bun build --compile --aot. Its header holds the SHA-256 of the first text.
  • Considered one native function for the rule. It breaks a warm __importDefault(require(esm)) until Give the module namespace prototype a Structure that prohibits property caching #48720 lands (Notes).

Downsides

  • A file compiled with --aot still returns the namespace: the engine answers require() there. test/aot/transpiler-parity-cases.ts and docs/compiler/compatibility.mdx record it.
  • Other callers pay one more jmp bytecode per first require(esm) and 56 bytes of text. User instructions per first require(esm): 140,160 to 140,334 (+0.12%), inside the 0.14% to 0.55% spread between runs.
Notes

Repro

bun entry.mjs prints inner [object Module] | later [object Module] on main and inner custom | later custom with this PR.

// a.mjs
const custom = { custom: true };
export { custom as "module.exports" };
require("./b.cjs");
export let __esModule = true;

// b.cjs
const v = require("./a.mjs");
globalThis.inner = v.custom === true ? "custom" : Object.prototype.toString.call(v);

// entry.mjs
import "./a.mjs";
const a = require("./a.mjs");
console.log("inner", globalThis.inner, "| later", a.custom === true ? "custom" : Object.prototype.toString.call(a));

Main is wrong in a fresh process and with the JIT off. After some tens of earlier require() calls of ES modules it is often right: the __esModule read then goes through the property cache that #48720 describes, and does not throw. This PR gives custom in each case.

10 runs each, count of right answers main this PR
fresh process 0 10
after 60 earlier require() calls of ES modules 7 10
after 150 10 10
after 300 10 10
BUN_JSC_useJIT=0, after 0, 60, 150 and 300 0, 0, 0, 0 10, 10, 10, 10

Where the state comes from

Tests

  • 6 cases in the cycle file: the module requires itself (require, import.meta.require, createRequire, Module.prototype.require), a CommonJS file requires it back, and a re-export of __esModule from a module that is still evaluating.
  • 6 cases in the handler file: the default handler of .mjs, .js, .ts, .cts and .mts called by a file on itself, and a handler that calls the handler it replaced.
  • Main fails these 12, each on the value ([object Module], expected custom).
  • One more test holds three states in which "module.exports" itself is in TDZ: require() returns the namespace. It passes on main too. Its second row (both exports in TDZ) is the check that the new second try of overridableRequire swallows its own throw.
  • Two more handler cases (.mjs and .ts, one for each native loader) call the default handler while both exports are in TDZ: the handler stores the namespace. They pass on main too. With the second try removed from requireESMFromHijackedExtension these two fail, and the other 28 tests of the file pass.
  • test/aot/parallel/code-from-disk-beside-the-compiled-library/it-requires-itself-before-its-mark-is-ready.cjs is a stored program for test/aot/run-parallel.ts. A compiled program loads an ES file from disk (--aot-allow-code-from-disk), and that file goes through require() of the compiled library, which is the second text. It is the only test that runs the second text's edit. A build of main prints [object Module] there, this PR prints custom, in all four build ways.

What this PR does not change

  • A file that is compiled with --aot. The engine has its own copy of the rule (Modules::whatRequireMakesOfNamespace in oven-sh/WebKit), and it reads "module.exports" only after a successful read of __esModule. Five of the six cycle cases return the namespace when compiled, and the sixth is refused (this executable can't load a module from a dynamic path). Six rows in test/aot/transpiler-parity-cases.ts list them as expected failures.
  • A require() after a read of require.cache[key] for an ES module that an import loaded. The read makes a cache entry with the namespace, and require() returns it, without a cycle. Main does the same.
  • The cached answer. A module that is required while its "module.exports" export is in TDZ stays in require.cache as the namespace after the export has its value.
  • A cycle that a require() began: the inner call returns {}. That is the subject of require(esm): return the live namespace in a cycle that a require() began #48610.

The native version that this PR replaced

An earlier version of this branch moved the rule into one native function, which require() and the default handlers called, and deleted both JS tails. A self-review of it (36 concerns) ended with the verdict to send this guard first. The main reasons:

  • The native read sees the real __esModule export and does not lay the mark. Main's JS tail, once the JIT has compiled it, lays the mark through the property cache of Give the module namespace prototype a Structure that prohibits property caching #48720, and a warm reader of mod.__esModule reads that mark. So tsc's __importDefault(require(esm)) for a module that exports __esModule = true failed with TypeError: lib.default is not a function after 130 earlier calls: in 10 of 20 runs with the native version, and in 1 of 20 on main. With BUN_JSC_useConcurrentJIT=0 it was 20 of 20 and 0 of 20. This PR leaves those lines as they are: the same probe works in 10 of 10 runs after 130 calls, with the concurrent JIT on and off, as on main.
  • The native version deleted requireESMFromHijackedExtension, which require(esm): return the live namespace in a cycle that a require() began #48610 calls from new native code.
  • It did not give one implementation: the engine's copy and the require.cache read stay.

The native version is on the branch robobun/6508bf3c/require-esm-native-interop. It fits after #48720 and #48610.

The 8 steps of the verdict, all done here: the source files back to main except the two texts, the split at the four sites, the new SHA-256, the 12 tests, the six parity rows, the stored program, the line in docs/compiler/compatibility.mdx, and no assertion on the cached answer of the other TDZ states.

Measurements

Release builds of main at 7f964e6 and of the same commit with this PR's two source files, on one machine. #48677, the one commit on main after that, does not touch these two files.

main this PR
overridableRequire bytecode 201 instructions, 975 B, 3 handlers 204 instructions, 987 B, 4 handlers
requireESMFromHijackedExtension bytecode 27 instructions, 213 B 30 instructions, 221 B
text section 149,161,685 B 149,161,741 B (+56)
data and bss sections 124,976 B and 1,862,960 B the same
user instructions per first require(esm), minimum of 9 runs 140,160 140,334 (+0.12%)
the same, median of 9 runs 140,266 140,424 (+0.11%)
  • The three new bytecode instructions are one jmp to the next instruction between the two reads, which the normal path runs, and a catch with a jmp for the new handler, which run only after a throw.
  • The instruction count is perf_event_open (user mode) around a process that requires 2,000 small ES modules, minus a process that requires none, divided by 2,000. The runs of one binary differ by 0.14% to 0.55%, so the difference between the binaries is inside the noise.
  • No new allocation, call or property read.

Other open PRs

Suites

Release builds, main and this PR back to back:

  • test/js/node/module: 163 pass, 0 fail. Main: 157 pass, and it fails the 6 new handler tests.
  • test/js/bun/resolve: 843 pass, 0 fail in the best of three runs. Main fails the 6 new cycle tests. Both builds have runs with timeouts (5 s limit) in load-same-js-file-a-lot.test.ts and import-meta-glob.test.ts on this machine. import-meta-glob.test.ts alone passes 399 of 399 on both, three times each.
  • test/js/bun/test/mock: 1,314 pass on both.
  • The parity run of the cycle file with its six rows (parity() of test/aot/transpiler-parity-cases.ts): pass.
  • The stored program: pass in all four build ways. With a build of main: it does not print what its last comment says.
  • test/internal/second-texts-of-modules.test.ts, test/internal/export-lists-of-both-texts-of-modules.test.ts, test/internal/arms-of-modules-for-compiled-programs.test.ts, test/aot/the-two-texts-of-a-library-file-read-the-same-names.test.ts: pass.

Debug ASAN build of this branch on ccb3611, with the include of #48722 added locally: the two test files pass (9 and 30 tests), and the stored program passes in all four build ways.

…blocks

In a require cycle the namespace is live. One try block held both reads,
so a TDZ `__esModule` export hid an initialized "module.exports" export,
and require() returned and cached the namespace. The default
Module._extensions handlers have the same two lines.
…"module.exports"

A compiled file still returns the namespace: six expected failures in
the parity run, and one line in the compatibility page. An ES file that
a compiled program loads from disk goes through require() of the compiled
library (the second text of builtins/CommonJS): a stored program covers it.
@robobun

robobun commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator Author

Status: ready for review. No CI failure comes from this change.

How I reproduced it: the three files under "Repro" in the description. bun entry.mjs prints inner [object Module] | later [object Module] on a release build of main (fresh process) and inner custom | later custom with this PR. The 12 new tests fail on that build of main and pass with this PR.

CI (build 140781, finished): 186 jobs passed, also the ASAN lanes. The new tests ran and passed, for example require-esm-evaluating-cycle.test.ts, require-extensions.test.ts and test/aot/transpiler-parity-3.test.ts on debian 13 x64. Two jobs failed, on tests that this change does not touch:

  • ubuntu 25.04 x64: test/aot/parallel/lists/elements-beside-numeric-arrays.js is over its memory bound (it held 229 MB at most, and plain Bun 78 MB). The same program fails in the same way on main (build 140651, ubuntu 25.04 aarch64). It has no require and no import.
  • Windows 11 aarch64: test/aot/engine/ir-5, ir-6 and ir-12 (there is no testaot), five files of test/internal/builtins-table (no aot-engine folder beside the binary), and test/js/bun/util/which.test.ts (the runner has a bun.exe in C:\Windows\system32). These depend on the state of that runner.

Four other tests failed once and passed on a retry.

@robobun

robobun commented Nov 12, 2026 •

Copy link
Copy Markdown
Collaborator Author
Updated 3:06 PM PT - Nov 12th, 2026

❌ @robobun, your commit d2218c2 has 10 failures in Build #140781 (All Failures):


🧪   To try this PR locally:

bunx bun-pr 48743

That installs a local version of the PR into your bun-48743 executable, so you can run:

bun-48743 --bun

@coderabbitai

coderabbitai Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

CommonJS conversion paths now read __esModule and module.exports independently. Tests cover require behavior during ES module evaluation across require mechanisms, cycles, extension handlers, and ahead-of-time execution. Compatibility documentation records the behavior.

Changes

ESM require during evaluation

Layer / File(s) Summary
Independent export reads
src/js/builtins/CommonJS.ts, src/js/ahead-of-time/builtins/CommonJS.ts, docs/compiler/compatibility.mdx
The CommonJS conversion paths use separate try blocks for reads of __esModule and module.exports. The ahead-of-time source hash and compatibility documentation are updated.
Evaluating-module test coverage
test/js/bun/resolve/require-esm-evaluating-cycle.test.ts, test/js/node/module/require-extensions.test.ts, test/aot/parallel/code-from-disk-beside-the-compiled-library/it-requires-itself-before-its-mark-is-ready.cjs, test/aot/transpiler-parity-cases.ts
Tests cover initialized and uninitialized exports during evaluation across require mechanisms, cycles, re-exports, extension handlers, and ahead-of-time execution.

Suggested reviewers: jarred-sumner, dylan-conway

Merge Risk: Minimal · up to d2218

Merge Risk: ⚪ Minimal · up to d2218

This change lets require() of an ES module that is still evaluating return the module.exports value when __esModule is not yet initialized. The change is small and backed by new tests, and no merge-blocking risk remains.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: the __esModule and "module.exports" reads in require(esm) now sit in separate try blocks. The changeset does exactly this in src/js/builtins/CommonJS.ts and …
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Description check Passed The description follows the template's two required sections. The 'What does this PR do?' content appears under 'Problem', 'Fix', and 'Background', and the verification content appears under 'Fix' and…
Full details: Title check

Explanation

The title names the main change: the __esModule and "module.exports" reads in require(esm) now sit in separate try blocks. The changeset does exactly this in src/js/builtins/CommonJS.ts and its AOT copy, and the new tests cover the behavior. The title is specific and single-sentence, though it is somewhat long at 75 characters.

Full details: Description check

Explanation

The description follows the template's two required sections. The 'What does this PR do?' content appears under 'Problem', 'Fix', and 'Background', and the verification content appears under 'Fix' and the 'Suites' details. It states the bug, the fix (separate try blocks in overridableRequire and requireESMFromHijackedExtension), the new tests and their expected results on main versus this PR, the known limitations (--aot still returns the namespace, cached answers unchanged), and measurements. The 'How did you verify your code works?' content is thorough and specific, listing the test files, the release and debug builds, and the results. The template headings are not used verbatim, and the description is long. Its core content is complete and specific, so the check passes.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 2ae885b and ce15f5f.

Files selected for processing: 1

  • test/js/node/module/require-extensions.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

Beyond the inline findings, I also checked the AOT second text: the SHA-256 in the header of src/js/ahead-of-time/builtins/CommonJS.ts matches the primary file after this change, and the two edited hunks are identical in both texts (the remaining differences are the pre-existing AOT-only lines). I found no other in-tree site that reads __esModule and "module.exports" from a live namespace in one try block; the engine's copy (whatRequireMakesOfNamespace) is in oven-sh/WebKit, outside this repo. I did not run the test suite or the AOT parallel fixture, so the claim that the 12 new tests fail on main and pass here is unverified by this review.

Extended reasoning...

The change splits one try block into two at four sites (overridableRequire and requireESMFromHijackedExtension in the primary and AOT copies of CommonJS.ts), updates the AOT header hash, adds tests for the require-cycle TDZ case across require/import.meta.require/createRequire/Module.prototype.require/_extensions handlers, registers six AOT expected failures, adds one AOT fixture, and adds one line to docs/compiler/compatibility.mdx. It touches the module loader but no auth, crypto, or input-parsing surface. Inline findings already exist (a nit about an unproven second try, and two pre-existing namespace-caching gaps the PR description itself excludes), so this note only records what else was ruled out by reading.

Additional findings (outside the current diff — GitHub can't attach inline comments there):

  • 🟣 src/js/builtins/CommonJS.ts — Callers who read require.cache[path] for an import-loaded ES module, then require() it, still get the namespace instead of its "module.exports" value. The split at src/js/builtins/CommonJS.ts:141-143 fixes only the two require tails. createRequireCache at src/js/builtins/CommonJS.ts:280-284 is a third site that turns a namespace into a cache entry and never applies the "module.exports" / __esModule rule, so mod.exports is the namespace and the later require() at :181-185 hands it out. Fix: apply the same two reads (each in its own try) wherever a namespace becomes mod.exports, by extracting one helper used at :138-159, :232-253 and :280-284.

    Why this was flagged

    Trigger: an ES module with export { x as "module.exports" } is loaded by import; some CJS code (patchers like require-in-the-middle, or any code that touches require.cache[key]) reads the proxy at src/js/builtins/CommonJS.ts:274-289 before anyone calls require() on that path. The get trap at :280-284 calls $esmNamespaceForCjs and $createCommonJSModule(key, namespace, true, owner), storing the raw namespace as mod.exports and inserting it into requireMap. The next require() of that path hits the loaded branch of the require path and returns the namespace, never the "module.exports" value. The base branch behaves the same, but this PR's stated rule is 'one export in TDZ hides only itself' and REVIEW.md says to fix every sibling site of the same pattern in the same PR; this is the one site that produces mod.exports from a namespace without the rule, and the PR excludes it only by description. Remedy: route :280-284 through the same read-both-exports helper as the two require tails.

    Verification: Pre-existing: the diff does not touch this path and the base fails the same way. The proxy get trap at src/js/builtins/CommonJS.ts:280-284 calls $esmNamespaceForCjs(key, owner) and then $createCommonJSModule(key, namespace, true, owner); neither reads "module.exports" or __esModule. The next require() then hits requireMap.$get(id) at CommonJS.ts:46-47 and returns existing.exports at :69, the namespace.

Comment thread src/js/builtins/CommonJS.ts Resolved
Comment thread src/js/builtins/CommonJS.ts Resolved
…s in TDZ

The read of "module.exports" throws there, and the second try block of
requireESMFromHijackedExtension swallows it. Without that block these two
tests fail.
@robobun

robobun commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator Author

About the read of require.cache[key] (createRequireCache): confirmed, and main gives the same answer. After void require.cache[require.resolve("./a.mjs")] for an imported module with a "module.exports" export, require("./a.mjs") returns the namespace. Without the read it returns the value of the export.

I did not put the two reads into the get trap. A read of require.cache[key], also one from console.log(require.cache), would then read the exports of each ES module that it touches and lay the __esModule mark on it. The rule fits at the point where require() takes an entry that the trap made, and that is a change of its own. The description lists this site under "What this PR does not change".

The other two findings have replies in their threads. The handler test for the second try is in ce15f5f.

@claude claude Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM — the new commit covers the one gap I raised earlier (the second try in requireESMFromHijackedExtension is now exercised by the both-in-TDZ handler tests), and the source change itself is a two-line split at each of the four sites.

What was reviewed:

  • Both texts of CommonJS.ts: the split is identical at all four read sites, and the SHA-256 recorded in the ahead-of-time header matches src/js/builtins/CommonJS.ts at HEAD; no other runtime site in this repo reads namespace["module.exports"].
  • Behaviour when only __esModule is in TDZ now falls through to the already-initialized "module.exports" value; every other state (both in TDZ, "module.exports" alone in TDZ, __esModule false) ends at the same moduleExports ?? namespace as before.
  • Tests follow the harness shape (tempDir, bunExe/bunEnv, Promise.all drain, whole-object toEqual, test.each / describe.concurrent); the AOT parity rows and the compatibility.mdx line record the engine-side gap rather than hide it.
  • Not run here: the USE_SYSTEM_BUN=1 fail-on-unfixed-build check and the --aot stored program; the claim that main fails the 12 new cases rests on the author's description.
Extended reasoning...

The diff splits one shared try block into two at the __esModule / "module.exports" reads in overridableRequire and requireESMFromHijackedExtension, mirrored in src/js/builtins/CommonJS.ts and src/js/ahead-of-time/builtins/CommonJS.ts with the header hash updated, plus tests, six AOT parity expected-failure rows, a stored AOT program and one docs line. It touches the CommonJS require loader but no auth, crypto, permission or input-parsing surface. The source change is small and purely additive (an export in TDZ now hides only its own read), the AOT twin is kept in sync, and the latest commit ce15f5f added the test I had asked for, so no open objection of mine remains; no CODEOWNERS entry covers the changed paths and the hunt ran dry with no findings.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant