Repository navigation
fix(core): report require() of an ES module with top-level await as ERR_REQUIRE_ASYNC_MODULE - #853
Merged
Merged
Conversation
β¦RR_REQUIRE_ASYNC_MODULE The `pirates` hook compiles a `require()`d ES module to CommonJS, which cannot express top-level await, so the transform failed with a bare `Failed to transform` GenericFailure. Code that catches Node.js' ERR_REQUIRE_ASYNC_MODULE to fall back to `import()` never saw it. When a CommonJS-target transform fails on an ES module that awaits at its top level (`await`, `for await`, `await using`), the binding now raises Node.js' message, and the `pirates` hook gives it the ERR_REQUIRE_ASYNC_MODULE code. A `.cts`/`.cjs` file, or an ambiguous one in a `"type": "commonjs"` package, is CommonJS whatever its syntax and keeps the transform error. Closes #842 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
βΉοΈ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with π while any review is running, comments if it has suggestions, and reacts with π once all reviews finish with no findings. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #842
Problem
The
pirateshook inregister.mjshandles.mjsand.mts, sorequire()of an ES module is compiled to CommonJS. CommonJS cannot express top-level await, so the transform failed with:Plain Node.js raises
ERR_REQUIRE_ASYNC_MODULEhere, and code that catches it to fall back toimport()never saw it.Why not drop
.mjs/.mtsfrompiratesThe issue suggests leaving them to Node.js'
require(esm), but that only works where the ESM hooks seerequire().register.mjsuses the synchronousmodule.registerHooks()from v26.2.0 only. Below that it usesmodule.register(), whose hooks never seerequire(). On Node.js 22 and 24, arequire()d.mtswould then skip oxc entirely and fall to Node.js' own type stripping. That would lose enums, decorators and tsconfigpaths.Fix
The issue's fallback: report the case with Node.js' error code.
Detection: when a CommonJS-target transform fails and the program awaits at its top level, the binding raises Node.js' message instead of the transform error. That means an
await, afor awaitor anawait usingoutside every function, found by a small AST visitor that runs on the failure path only.The code: the binding's errors can only carry napi's
GenericFailurestatus, so thepirateshook recognises that message and setscode: 'ERR_REQUIRE_ASYNC_MODULE'.Which files are ES modules:
.mts/.mjsERR_REQUIRE_ASYNC_MODULE"type": "module"packageERR_REQUIRE_ASYNC_MODULEtype(Node.js' syntax detection runs a file with top-level await as an ES module)ERR_REQUIRE_ASYNC_MODULE.cts/.cjs"type": "commonjs"packagePlain Node.js rejects top-level await in a CommonJS file as a
SyntaxErrorinstead.Tests
packages/integrate-vitest/__tests__/require-async-module.spec.ts, with all of theserequire()d from a.ctsfile:.mts,.mjs,for await, a re-export of an async module, a.tsin a"type": "module"package, and a.tsin a package with notype: allERR_REQUIRE_ASYNC_MODULE.mtswhoseawaitsits only inside a function still loadsimport()fallback works.tswith top-level await in a"type": "commonjs"package is not reported asERR_REQUIRE_ASYNC_MODULEVerification (macOS arm64)
cargo test --all-features,cargo clippy --all-targets --all-features -- -D warnings,vp run test(219 passed) andvp run lintall pass.π€ Generated with Claude Code