fix(NODE-7603): emit dynamic import('os') via tsconfig

[PavelSafronov]

Description

Summary of Changes

Load os runtime adapter via dynamic import, so ESM bundle works again.

Notes for Reviewers

This PR supersedes #4979, which was an attempt to solve the same problem.

This PR follows the approach discussed offline: update tsc instructions and verify that we get the correct output from the build.

Verifying changes

The build-affecting change in this PR is three lines of tsconfig (module: node16,
moduleResolution: node16, esModuleInterop: false pinned to its previous effective value).
Its entire effect on the shipped lib/ output is one line in one file:

--- lib/runtime_adapters.js (module: commonjs)
+++ lib/runtime_adapters.js (module: node16)
-        os: options.runtimeAdapters?.os ?? (await Promise.resolve().then(() => require('os')))
+        os: options.runtimeAdapters?.os ?? (await import('os'))

All other 130 emitted files are byte-identical (modulo nothing — same helpers, same export
wiring, same comments). To reproduce this yourself:

npx tsc -p tsconfig.json --module commonjs --moduleResolution node --noEmitHelpers true \
  --outDir /tmp/old-emit --declaration false --declarationMap false --sourceMap false
npm run build:ts
diff -r -x '*.map' -x '*.d.ts' /tmp/old-emit lib   # one hunk, plus sourceMappingURL lines

Permanent guards (all wired into CI):

• test/unit/bundling.test.ts — the NODE-7603 acceptance test: replicates the emit for
  runtime_adapters.ts, bundles it to ESM the way a downstream Vite/esbuild build would, and
  runs it with no require in scope. Fails on the old module: commonjs emit.
• etc/check-lib-artifact.mjs (check:lib-artifact, part of check:lint) — loads the built
  lib/ via both require and import() and statically asserts the shipped
  lib/runtime_adapters.js retains import("os") and contains no downleveled
  require("os"). This is the guard wired to the real build output: if tsconfig ever
  regresses to module: commonjs, this fails even though the bundling test (which mirrors the
  node16 settings itself) would not.
• test/unit/nodeless.test.ts — audits every dynamic-import specifier in the driver test
  bundle against the sandbox allowlist (currently just os), so a future dynamic import of a
  Node built-in can't silently bypass the nodeless sandbox's restricted require.

Full check status on this change: unit suite 3178/0, check:ts, check:lint (api-extractor,
tsd, eslint), mongodb.d.ts byte-identical.

What is the motivation for this change?

Slack convo: https://mongodb.slack.com/archives/GGWBN4ZNK/p1782927460341129

Release Highlight

Bundling the driver into ESM no longer throws ReferenceError: require is not defined

v7.2.0 introduced the experimental runtimeAdapters option and, as part of it, replaced the driver’s static import of Node’s os module with a runtime require('os'). That works in a CommonJS build, but when the driver is bundled into ESM output (e.g. a Vite/esbuild/rollup server build with "type": "module"), there is no require in module scope, so constructing a client threw ReferenceError: require is not defined. The driver now loads the default os adapter through a dynamic import() that survives bundling, so new MongoClient() works in ESM bundles. CommonJS usage is unchanged, and supplying your own runtimeAdapters.os continues to work.

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[Copilot]

Pull request overview

This PR fixes ESM-bundled consumption of the driver by switching the default os runtime adapter resolution from require('os') to a dynamic import('os') that survives downstream ESM bundling, and updates the build pipeline to emit lib/ via an ESM intermediate (tsc → ESM, then esbuild → CJS) so that dynamic imports are preserved in the shipped artifact.

Changes:

• Make runtime-adapter resolution asynchronous and load the default os adapter via dynamic import('os') to avoid require in bundled ESM output.
• Replace the build:ts pipeline with a tsc-to-ESM intermediate followed by an esbuild ESM→CJS transform, plus add artifact/diff-gate verification scripts.
• Add/adjust unit tests to validate adapter async resolution and prevent regressions when downstream bundlers produce ESM.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tsconfig.build.json	New build tsconfig to emit ESM-shaped JS into an intermediate directory while sending declarations to lib/.
src/runtime_adapters.ts	Switch default os adapter loading to dynamic import() and make adapter resolution async.
src/mongo_client.ts	Update internal MongoOptions.runtime type to a Promise<Runtime>.
src/cmap/handshake/client_metadata.ts	Await runtime before reading the os adapter for client metadata.
src/cmap/connection.ts	Update internal connection options type to accept runtime: Promise<Runtime>.
src/cmap/auth/gssapi.ts	Await runtime before using os in the GSSAPI auth flow.
test/unit/runtime_adapters.test.ts	Update tests to await runtime resolution and validate adapter behavior.
test/unit/bundling.test.ts	New unit test that reproduces downstream ESM bundling and verifies no global require is needed.
test/tools/utils.ts	Update test runtime helper to match async runtime resolution while keeping a stub-friendly os.
test/tools/runner/vm_context_helper.ts	Configure vm harness to support dynamic import() when loading the bundled driver.
package.json	Route build:ts through the new build script and add lib artifact/diff-gate checks.
etc/build-lib.mjs	New build script: tsc emits ESM intermediate + declarations, esbuild transforms to shipped CJS.
etc/check-lib-artifact.mjs	New smoke test validating shipped lib/ loads under both loaders and preserves import('os').
etc/diff-lib-emit.mjs	New migration diff gate to compare old vs new lib/ emits and report residual diffs.
etc/lib-emit-classify.mjs	New AST-based classifier to mechanically validate export-surface equivalence across emits.
.gitignore	Ignore lib-intermediate/ and .diff-gate/ build artifacts.

[tadjik1]

Great work, thanks @PavelSafronov! It looks really solid.
The only my comments are about testing strategy, I might misunderstood the approach here, but it feels we can leave just a unit test which reads the actual tsconfig, and drop check-lib-artifact entirely.

[nbbeeken]

Can't comment on it, but this line in connection_string.ts

mongoOptions.runtime = resolveRuntimeAdapters(options);

Should mark the promise as handled to prevent the process from crashing if there's a failure

mongoOptions.runtime = resolveRuntimeAdapters(options);
mongoOptions.runtime.then(undefined, squashError);

[PavelSafronov]

Can't comment on it, but this line in connection_string.ts

mongoOptions.runtime = resolveRuntimeAdapters(options);

Should mark the promise as handled to prevent the process from crashing if there's a failure

mongoOptions.runtime = resolveRuntimeAdapters(options);
mongoOptions.runtime.then(undefined, squashError);

Good point, this follows our existing approach on line 87 of the same file. Updating.