Skip to content

lib: add internal/primordials_staging module#63464

Open
LiviaMedeiros wants to merge 1 commit into
nodejs:mainfrom
LiviaMedeiros:internal-primordials-staging
Open

lib: add internal/primordials_staging module#63464
LiviaMedeiros wants to merge 1 commit into
nodejs:mainfrom
LiviaMedeiros:internal-primordials-staging

Conversation

@LiviaMedeiros
Copy link
Copy Markdown
Member

@LiviaMedeiros LiviaMedeiros commented May 20, 2026

We have quite a few builtins that can not be included in primordials, usually because their existence is conditional (either they require experimental flag, or they can be disabled with --no- flag).
We have to retrieve such builtins from globalThis, which is exposed to userland and is mutable by design.
Additionally, in some modules that are part of early bootstrap we can not do top-level assignment synchronously, because the builtins are not defined yet. Because of that, we have to get them on demand from userland, making them extremely prone to prior mutation.

This PR adds internal/primordials_staging module which is populated on pre-execution stage (late enough to have them on global, and early enough to not be affected by userland code), and allows lazy loading of experimental builtins without relying on globalThis in runtime.

The name is subject to bikeshedding. I chose staging since objects in this module are expected to be included in primordials at some point in the future.

Some related PRs:

TODO:

  • add docs
  • add test
  • adjust linter suggestions

cc @nodejs/startup @Renegade334

@nodejs-github-bot
Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/loaders
  • @nodejs/startup

@nodejs-github-bot nodejs-github-bot added lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels May 20, 2026
@LiviaMedeiros LiviaMedeiros added the experimental Issues and PRs related to experimental features. label May 20, 2026
@codecov
Copy link
Copy Markdown

codecov Bot commented May 20, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.06%. Comparing base (4ee7567) to head (54db761).
⚠️ Report is 23 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #63464      +/-   ##
==========================================
+ Coverage   90.05%   90.06%   +0.01%     
==========================================
  Files         714      715       +1     
  Lines      225876   226009     +133     
  Branches    42737    42749      +12     
==========================================
+ Hits       203408   203562     +154     
+ Misses      14244    14234      -10     
+ Partials     8224     8213      -11     
Files with missing lines Coverage Δ
lib/internal/freeze_intrinsics.js 96.96% <100.00%> (-0.01%) ⬇️
lib/internal/fs/utils.js 98.43% <100.00%> (ø)
lib/internal/modules/esm/translators.js 97.51% <100.00%> (ø)
lib/internal/primordials_staging.js 100.00% <100.00%> (ø)
lib/internal/process/pre_execution.js 98.51% <100.00%> (+0.12%) ⬆️
lib/internal/util.js 96.63% <100.00%> (-0.20%) ⬇️
lib/internal/util/comparisons.js 99.71% <100.00%> (+<0.01%) ⬆️
lib/v8.js 98.77% <100.00%> (ø)

... and 26 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread lib/internal/primordials_staging.js Outdated
@LiviaMedeiros LiviaMedeiros added the request-ci Add this label to start a Jenkins CI on a PR. label May 21, 2026
@github-actions github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label May 21, 2026
@nodejs-github-bot
Copy link
Copy Markdown
Collaborator

nodejs-github-bot commented May 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

freeze_intrinsics also runs in pre-execution, so this wouldn't be necessary.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Agreed. Still, i'd prefer it to stay for consistency, so it doesn't differ from linter suggestion and the internals never take builtins from globalThis directly.
Unless there is another reason to keep globalThis here.

Comment on lines +59 to +73
_init({
AsyncDisposableStack,
DisposableStack,
Float16Array,
Intl,
Iterator,
ShadowRealm,
SharedArrayBuffer,
Temporal,
Uint8Array: {
fromBase64,
fromHex,
},
WebAssembly,
}) {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is only capturing the global object properties, not the object tree, so eg. Temporal.Instant.fromEpochNanoseconds(), new WebAssembly.Module() are still user-mutable.

Signed-off-by: LiviaMedeiros <livia@cirno.name>
@LiviaMedeiros LiviaMedeiros force-pushed the internal-primordials-staging branch from 54db761 to fcf2b27 Compare May 21, 2026 10:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

experimental Issues and PRs related to experimental features. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants