FEATURE: opt-in JavaScript host namespace (Context.new(host_namespace:))

[ursm]

What

Adds an opt-in JavaScript host namespace: Context.new(host_namespace: "MiniRacer") installs a single globalThis.MiniRacer object and hangs mini_racer's non-standard JS helpers off it. The first such helper is MiniRacer.drainMicrotasks().

context = MiniRacer::Context.new(host_namespace: "MiniRacer")
context.eval(<<~JS)
  globalThis.log = [];
  Promise.resolve().then(() => log.push("microtask"));
  log.push("before");
  MiniRacer.drainMicrotasks();
  log.push("after");
JS
context.eval("log")
# => ["before", "microtask", "after"]

By default (host_namespace unset) nothing is injected and the global stays clean.

Why

drainMicrotasks() is the inline, JS-callable companion to Context#perform_microtask_checkpoint (#418 / #419). That Ruby method was added for spec-compliant dispatchEvent ordering, but in practice the drain often has to happen from within JavaScript — e.g. between each listener in a synchronous dispatchEvent chain. Doing that today requires attach-ing a Ruby callback that round-trips JS→Ruby→V8 on every drain. drainMicrotasks() runs the same MicrotasksScope::PerformCheckpoint inline on the isolate thread with no rendezvous.

Design — opt-in namespace (Deno/Bun model)

Rather than injecting a bare global, helpers live under one opt-in namespace object, in the spirit of Deno's Deno / Bun's Bun. This keeps the default global clean (nothing injected unless asked) and gives a single, named extension point for future host helpers instead of introducing a new top-level global each time.

host_namespace: accepts a String (the global name), true (the default name "MiniRacer"), or nil/false (off).

The namespace object is installed non-enumerable — matching every built-in global (in a bare context Object.keys(globalThis) is []; Math/JSON are non-enumerable). Its methods are ordinary enumerable own-properties, so Object.keys(MiniRacer) → ["drainMicrotasks"].

drainMicrotasks() semantics

• Uses MicrotasksScope::PerformCheckpoint — a guarded no-op while a checkpoint is already in progress; it never force-nests microtask runs.
• Runs inline — no v8_reply / rendezvous.
• Takes no v8::Locker (safe under :single_threaded, where V8 shares the Ruby thread).
• Leaves termination active, so watchdog timeout / OOM surface to the enclosing eval / call.
• Microtask exceptions are routed to V8's handlers (as with perform_microtask_checkpoint), not propagated to the caller.

The namespace closes over native code pointers, so it is not serialized into snapshots; it is (re)installed on every fresh context (multi-threaded, single-threaded, and snapshot-backed).

TruffleRuby

V8-only, like perform_microtask_checkpoint. The option is accepted/validated but the namespace is not installed on the TruffleRuby backend.

Tests / docs

New tests cover: default-off; true / custom name; off-paths (false, empty string) and wrong-type rejection; non-enumerable namespace + discoverable methods; inline drain order; nested-call guarded no-op (constructed to distinguish a true no-op from re-entry); microtask-exception isolation; snapshot-backed install; and watchdog + OOM termination surfacing (asserted via a trailing side effect so the tests fail if the drain becomes a no-op). A single-threaded test guards the no-Locker invariant. README and CHANGELOG updated.

Known edge cases

• If a snapshot pre-defines a non-configurable global with the same name as the chosen host_namespace, the install is silently skipped (V8 DefineOwnProperty returns false) with no diagnostic. Only reachable by an embedder colliding their own snapshot global with their own chosen name.
• A pathologically long name (> V8 String::kMaxLength) likewise skips installation silently.
• A wrong-type host_namespace raises TypeError on CRuby vs ArgumentError on TruffleRuby — consistent with the existing per-backend validation split for other options.

🤖 Generated with Claude Code