Add Bun.unsafe.ModuleGraph: further instances of the ES module graph in one global object

packages/bun-types/bun.d.ts

@@ -5459,6 +5459,73 @@ declare module "bun" {
      */
     function setJITPolicy(scale: number): void;
 
+    interface ModuleGraphOptions {
+      /**
+       * Variables that only this graph's modules see. Each own enumerable string
+       * key becomes a free identifier in the graph's module code, in front of
+       * `globalThis`. Graphs constructed with the same set of names share
+       * compiled code.
+       *
+       * `undefined`, `NaN` and `Infinity` cannot be names (`ERR_INVALID_ARG_VALUE`).
+       */
+      globals?: Record<string, unknown>;
+      /**
+       * Receives uncaught exceptions and unhandled rejections raised by this
+       * graph's module code. Without it, and for anything it throws itself,
+       * errors take the normal process-wide path (`uncaughtException` /
+       * `unhandledRejection`).
+       *
+       * An error is attributed to the graph through its stack, so one thrown
+       * by code with no graph frame on the stack (e.g. a non-`Error` value
+       * rejected from a tail call) is reported process-wide.
+       */
+      onError?: (error: unknown) => void;
+    }
+
+    /**
+     * Another instance of the ES module graph inside the current global object.
+     *
+     * Modules imported through a `ModuleGraph` get their own module records,
+     * environments, namespaces, `import.meta` and top-level-await state, while
+     * compiled code is shared with every other instance of the same module.
+     * Everything else is shared with the rest of the process: `globalThis`,
+     * intrinsics, builtin modules, CommonJS modules and `require.cache`, timers
+     * and the event loop. ES modules only.
+     *
+     * @example
+     * ```ts
+     * using graph = new Bun.unsafe.ModuleGraph({ globals: { tenant: "a" } });
+     * const app = await graph.import("./app.ts");
+     * ```
+     */
+    class ModuleGraph implements Disposable {
+      constructor(options?: ModuleGraphOptions);
+
+      /**
+       * `import()` into this graph. `specifier` resolves relative to the caller.
+       * A static or dynamic import made by one of the graph's modules stays in
+       * the graph.
+       *
+       * Rejects with `ERR_INVALID_STATE` once the graph is disposed.
+       */
+      import<T = any>(specifier: string): Promise<T>;
+
+      /**
+       * Drop this graph's module registry, and nothing else: code from the graph
+       * that is still referenced keeps working, but a new `import()` from it (or
+       * through it) rejects with `ERR_INVALID_STATE`.
+       */
+      dispose(): void;
+      [Symbol.dispose](): void;
+
+      /**
+       * The resolved path of the first module imported through this graph, or
+       * `undefined` before that. `import.meta.main` is `true` in that module and
+       * `false` in the graph's other modules.
+       */
+      readonly mainModule: string | undefined;
+    }
+
     /**
      * Per-process memory footprint in bytes: the memory that only this
      * process keeps the machine from reusing.

src/js/builtins.d.ts

@@ -230,7 +230,7 @@ declare function $esmNamespaceForCjs(key: string): any | undefined;
 declare function $esmRegistryDelete(key: string): boolean;
 declare function $esmRegistryEvaluatedKeys(): string[];
 declare function $esmRegistryHasEvaluated(key: string): boolean;
-declare function $esmLoadSync(key: string): any;
+declare function $esmLoadSync(key: string, graph?: object): any;
 declare function $get(): TODO;
 declare function $handleEvent(): TODO;
 declare function $headers(): TODO;
@@ -258,7 +258,10 @@ declare function $removeAbortAlgorithmFromSignal(signal: AbortSignal, algorithmI
 declare function $redirect(): TODO;
 declare function $relative(): TODO;
 declare function $require(): TODO;
-declare function $requireESM(path: string): any;
+declare function $requireESM(path: string, graph?: object): any;
+declare function $requireESMExports(namespace: any): any;
+/** The Bun.unsafe.ModuleGraph of the `require()` call in progress, if its caller belongs to one. */
+declare function $requiringModuleGraph(): object | undefined;
 declare const $requireMap: Map<string, JSCommonJSModule>;
 declare const $internalModuleRegistry: InternalFieldObject<any[]>;
 declare function $resolve(name: string, from: string): Promise<string>;

src/js/builtins/BunBuiltinNames.h

@@ -75,6 +75,7 @@ using namespace JSC;
     macro(encoding) \
     macro(end) \
     macro(errno) \
+    macro(esModule) \
     macro(esmLoadSync) \
     macro(esmNamespaceForCjs) \
     macro(esmRegistryDelete) \
@@ -127,6 +128,7 @@ using namespace JSC;
     macro(min) \
     macro(mockedFunction) \
     macro(mode) \
+    macro(moduleGraph) \
     macro(mtimeMs) \
     macro(napiDlopenHandle) \
     macro(napiWrappedContents) \
@@ -159,8 +161,10 @@ using namespace JSC;
     macro(removeAbortAlgorithmFromSignal) \
     macro(require) \
     macro(requireESM) \
+    macro(requireESMExports) \
     macro(requireMap) \
     macro(requireNativeModule) \
+    macro(requiringModuleGraph) \
     macro(resolveSync) \
     macro(sameSite) \
     macro(secure) \

src/js/builtins/CommonJS.ts

@@ -34,6 +34,11 @@
     return this.$requireNativeModule(id);
   } else {
     const existing = $requireMap.$get(id);
+    if (existing && existing.$esModule && this.$moduleGraph !== undefined) {
+      // The entry is the host's instance of an ES module. A Bun.unsafe.ModuleGraph's
+      // modules get their graph's own, which never enters the require cache.
+      return $requireESMExports($requireESM(id, this.$moduleGraph));
+    }
     if (existing) {
       // Scenario where this is necessary:
       //
@@ -71,10 +76,13 @@
     return Bun.jest(this.filename);
   }
 
-  // To handle import/export cycles, we need to create a module object and put
-  // it into the map before we import it.
+  // To handle import/export cycles, the module object has to be in the map before
+  // the module evaluates. Whether `id` is an ES module is not known yet, and an ES
+  // module is not found in the map while it evaluates (a require cycle gets its live
+  // namespace from the module loader instead), so $require puts `mod` into the map
+  // itself, once `id` turns out to be anything else.
   const mod = $createCommonJSModule(id, {}, false, this);
-  $requireMap.$set(id, mod);
+  const graph = this.$moduleGraph;
 
   var out: LoaderModule | -1;
 
@@ -97,7 +105,7 @@
         $argument(1),
       );
     } catch (E) {
-      $assert($requireMap.$get(id) === undefined, "Module " + JSON.stringify(id) + " should no longer be in the map");
+      $assert($requireMap.$get(id) !== mod, "Module " + JSON.stringify(id) + " should no longer be in the map");
       throw E;
     }
   } else {
@@ -106,40 +114,17 @@
 
   // -1 means we need to lookup the module from the ESM registry.
   if (out === -1) {
-    try {
-      out = $requireESM(id);
-    } catch (exception) {
-      // Since the ESM code is mostly JS, we need to handle exceptions here.
-      $requireMap.$delete(id);
-      throw exception;
-    }
-
-    const namespace = out;
-    // In a require cycle the namespace is live while the module body is still
-    // running, so an export named `__esModule` / `module.exports` may be in TDZ.
-    let esModule, moduleExports;
-    try {
-      esModule = namespace.__esModule;
-      moduleExports = namespace["module.exports"];
-    } catch {}
-    // In Bun, when __esModule is not defined, it's a CustomAccessor on the prototype.
-    // Various libraries expect __esModule to be set when using ESM from require().
-    // We don't want to always inject the __esModule export into every module,
-    // And creating an Object wrapper causes the actual exports to not be own properties.
-    // So instead of either of those, we make it so that the __esModule property can be set at runtime.
-    // It only supports "true" and undefined. Anything non-truthy is treated as undefined.
-    // https://github.com/oven-sh/bun/issues/14411
-    if (esModule === undefined) {
-      try {
-        namespace.__esModule = true;
-      } catch {
-        // https://github.com/oven-sh/bun/issues/17816
-      }
-    }
-
-    return (mod.exports = moduleExports ?? namespace);
+    const exports = $requireESMExports($requireESM(id, graph));
+    // A Bun.unsafe.ModuleGraph's ES module instances never enter the (shared) require cache.
+    if (graph !== undefined) return exports;
+    mod.$esModule = true;
+    $requireMap.$set(id, mod);
+    return (mod.exports = exports);
   }
 
+  // A wrapped Module._extensions handler loaded the graph's instance of an ES module into `mod`.
+  if (graph !== undefined && mod.$esModule) return mod.exports;
+
   const c = $evaluateCommonJSModule(mod, this);
   if (c && c.indexOf(mod) === -1) {
     c.push(mod);
@@ -171,40 +156,35 @@
 }
 
 $visibility = "Private";
-export function loadEsmIntoCjs(resolvedSpecifier: string) {
+export function loadEsmIntoCjs(resolvedSpecifier: string, graph?: object) {
   // The JSC module loader pipeline is now pure C++. $esmLoadSync sets a VM
   // flag that makes the loader's internal promise reactions run immediately
   // (instead of queueing microtasks) whenever the upstream promise is already
   // settled. Because Bun resolves and reads source code synchronously, the
   // entire fetch → parse → link → evaluate chain completes within this call
   // for any module graph that does not use top-level await.
-  return $esmLoadSync(resolvedSpecifier);
+  return $esmLoadSync(resolvedSpecifier, graph);
 }
 
+// `graph` is the Bun.unsafe.ModuleGraph whose instance of the module to load, or
+// undefined for the global object's own.
 $visibility = "Private";
-export function requireESM(this, resolved: string) {
+export function requireESM(this, resolved: string, graph?: object) {
   // `$esmLoadSync` answers from the registry for a record that is already
   // Evaluated, or still Evaluating because this require() sits inside its own
   // evaluation (a require cycle), before it loads anything.
-  const exports = $loadEsmIntoCjs(resolved);
+  const exports = $loadEsmIntoCjs(resolved, graph);
   if (exports === undefined) {
     throw new TypeError(`require() failed to evaluate module "${resolved}". This is an internal consistentency error.`);
   }
   return exports;
 }
 
-export function requireESMFromHijackedExtension(this: JSCommonJSModule, id: string) {
-  $assert(this);
-  let namespace;
-  try {
-    namespace = $requireESM(id);
-  } catch (exception) {
-    // Since the ESM code is mostly JS, we need to handle exceptions here.
-    $requireMap.$delete(id);
-    throw exception;
-  }
-
-  // See `overridableRequire`: TDZ-safe reads for the require-cycle case.
+// What require() returns for an ES module's namespace.
+$visibility = "Private";
+export function requireESMExports(namespace) {
+  // In a require cycle the namespace is live while the module body is still
+  // running, so an export named `__esModule` / `module.exports` may be in TDZ.
   let esModule, moduleExports;
   try {
     esModule = namespace.__esModule;
@@ -225,7 +205,21 @@
     }
   }
 
-  this.exports = moduleExports ?? namespace;
+  return moduleExports ?? namespace;
+}
+
+export function requireESMFromHijackedExtension(this: JSCommonJSModule, id: string) {
+  $assert(this);
+  // The handler ran with `this` in the require cache, as handlers expect. See
+  // `overridableRequire`: an ES module is not found there while it evaluates.
+  if ($requireMap.$get(id) === this) $requireMap.$delete(id);
+  const graph = $requiringModuleGraph();
+  const namespace = $requireESM(id, graph);
+
+  this.$esModule = true;
+  this.exports = $requireESMExports(namespace);
+  // A Bun.unsafe.ModuleGraph's ES module instances never enter the (shared) require cache.
+  if (graph === undefined) $requireMap.$set(id, this);
 }
 
 $visibility = "Private";
@@ -254,6 +248,7 @@
         const namespace = $esmNamespaceForCjs(key);
         if (namespace !== undefined) {
           const mod = $createCommonJSModule(key, namespace, true, undefined);
+          mod.$esModule = true;
           $requireMap.$set(key, mod);
           return mod;
         }

src/js/private.d.ts

@@ -69,6 +69,10 @@ declare interface Error {
 interface JSCommonJSModule {
   $require(id: string, mod: any, args_count: number, args: Array): any;
   $requireNativeModule(id: string): any;
+  /** Set on a `$requireMap` entry whose exports are an ES module's. */
+  $esModule?: true;
+  /** Set on the module behind `import.meta.require` of a Bun.unsafe.ModuleGraph's module. */
+  $moduleGraph?: object;
   children: JSCommonJSModule[];
   exports: any;
   id: string;

src/jsc/VirtualMachine.rs

@@ -391,6 +391,10 @@ pub struct TestIsolationState {
 // `&JSGlobalObject` is ABI-identical to a non-null `JSGlobalObject*` and C++
 // mutating VM/process state through it is interior mutation invisible to Rust.
 unsafe extern "C" {
+    safe fn Bun__ModuleGraph__handleUncaughtException(
+        global: &JSGlobalObject,
+        err: JSValue,
+    ) -> bool;
     safe fn Bun__handleUncaughtException(
         global: &JSGlobalObject,
         err: JSValue,
@@ -1726,6 +1730,11 @@ impl VirtualMachine {
             return true;
         }
 
+        // A rejection's owner was decided when it was rejected (GlobalObject::handleRejectedPromises).
+        if !is_rejection && Bun__ModuleGraph__handleUncaughtException(global_object, err) {
+            return true;
+        }
+
         if isBunTest.load(core::sync::atomic::Ordering::Relaxed) {
             self.unhandled_error_counter += 1;
             (self.on_unhandled_rejection)(self, global_object, err);