quickjs 0.17.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b94d34d52891a60158c8576ae818c1bc2d499d4c868bffbc9d20e15e048f509
-  data.tar.gz: c8143e0ad9aee153f401eb967e00a5d1cef6988174786b717883b3ad10af349d
+  metadata.gz: e7a32a1c083c824ccd0a1cbebc2fba793faf1f1fc743e19deaa9f0d7dd5b93cf
+  data.tar.gz: 669a202e7818baeae6966241b1cc1c0784de15b16682ac2713795fe8832ee605
 SHA512:
-  metadata.gz: bb986f81e0af8f8e7803080e9f4f4b0a6ae6a62ecc913460726ecac7e52b75ace087c9f6183fcc50c7d6bf2e1c44c7368d0d4893376609e14710da0ea6d8414c
-  data.tar.gz: edb095fa0e09ab1d439c0c98bfe56f2cbd44fcf9c7f5d40a14dbf0f961356f1aa6221a62195b00013c63b394503c68d3bf0fb1f02cb08eee3b5982925bc41c99
+  metadata.gz: 97e22453d9391a9a9056751371652a0561479f46d7bc9ead83d0f65208a09faad7a7d96a9ada99710df66a0790287ce714db3f30fec7ef22ca00f3e8fc93727b
+  data.tar.gz: 7292f78c043a8bd20702157e4481d72d9a835b03df76bee1a666796f96479b5e94cba4bcbfde18cdb61e759decb056c07bc94830b58fba6b80568c31cb607d18

data/README.md

@@ -100,6 +100,15 @@ runnable.run(on: { features: [::Quickjs::POLYFILL_INTL] }) # ad-hoc VM with opti
 
 `Runnable#to_s` returns the underlying bytecode as a frozen ASCII-8BIT `String`, suitable for caching to memory or disk. `Quickjs::Runnable.new(bytecode_string)` reconstructs a `Runnable` from that blob — validation happens lazily at `run` time, so a corrupt or wrong-build blob surfaces as `Quickjs::RuntimeError` when executed. The bytecode format is tied to the QuickJS build, so include the gem version in your cache key if you persist across upgrades.
 
+`Quickjs.compile` is a one-shot convenience that creates and immediately disposes a throwaway VM:
+
+```rb
+runnable = Quickjs.compile(File.read('big_bundle.js'), filename: 'big_bundle.js')
+runnable.run  # execute on a fresh VM, no parse cost
+```
+
+Accepts `filename:` and the same VM options as `Quickjs.eval_code` (`memory_limit:`, `timeout_msec:`, etc.) — useful when compiling large bundles that exceed the default limits.
+
 #### `Quickjs::VM#call`: ⚡ Call a JS function directly with Ruby arguments
 
 ```rb
@@ -176,9 +185,64 @@ vm.import(['a'], filename: 'a')
 vm.eval_code('a()') #=> 'a-b-result'
 ```
 
-The Proc receives the (already normalized) module specifier and returns the module source as a `String`, or `nil` to signal "not found" (which raises `Quickjs::ReferenceError` on the JS side). Pass `nil` to clear a previously set loader.
+The Proc may accept one or two arguments. Single-arity (`->(specifier) { ... }`) is the legacy shape: the Proc gets the raw import specifier and returns the source for it. Two-arity (`->(specifier, importer) { ... }`) additionally receives the file that issued the `import`, which is what you need for importmap-style scoping. Pass `nil` to clear a previously set loader.
+
+Return value:
+
+- A `String` — that's the source. The canonical name used for QuickJS's module cache is the specifier itself.
+- A `Hash` `{ code:, as: }` — `code:` is the source, `as:` becomes the canonical name. Use this when the same specifier should resolve to different modules depending on the importer (importmap "scopes"), since QuickJS caches by canonical name and changing the canonical is what isolates the two modules.
+- `nil` or `false` — raises `Quickjs::ReferenceError` on the JS side ("module not found").
+- Anything else — `Quickjs::TypeError`.
+
+Importmap scope example:
+
+```rb
+modules = {
+  '/vendor/lodash.js'       => 'export default { v: "global" };',
+  '/vendor/lodash-admin.js' => 'export default { v: "admin"  };',
+  '/app/admin/main.js'      => "import _ from 'lodash'; export const tag = _.v;"
+}
+
+vm.module_loader = ->(specifier, importer) {
+  case specifier
+  when 'lodash'
+    importer.start_with?('/app/admin/') \
+      ? { code: modules['/vendor/lodash-admin.js'], as: '/vendor/lodash-admin.js' }
+      : { code: modules['/vendor/lodash.js'],       as: '/vendor/lodash.js' }
+  else
+    modules[specifier]
+  end
+}
+
+vm.import(['tag'], filename: '/app/admin/main.js')
+vm.eval_code('tag') #=> 'admin'
+```
+
+Without `as:`, the canonical equals the raw `specifier`. That means relative imports (`./foo.js`) from different importers all share one canonical (`./foo.js`) and therefore one cached module instance — which is rarely what you want. If you support relative imports from a plain `String` return, resolve them to absolute paths yourself before returning, or use the `Hash` form with `as:` set to the resolved path. The user-facing Proc is called at most once per `(specifier, importer)` pair across the VM's lifetime; subsequent imports hit a per-VM resolution cache.
+
+When `module_loader=` is set, pass `filename:` to `import` instead of `from:` to resolve a named specifier directly through the loader — no inline bridge source needed. Passing both `from:` and `filename:` raises `ArgumentError`.
 
-When `module_loader=` is set, pass `filename:` to `import` instead of `from:` to resolve a named specifier directly through the loader — no inline bridge source needed.
+`import` awaits the module's top-level evaluation — top-level `await`, synchronous body execution, and any chained dynamic `import()`. The call blocks until the module's settle promise resolves. A top-level throw, a failed dynamic `import()`, or a rejected top-level `await` propagates back to Ruby as the matching `Quickjs::*Error` instead of being silently dropped.
+
+#### `Quickjs::VM#on_unhandled_rejection`: 🚨 Catch promise rejections that have no handler
+
+Register a block to be notified when a JS Promise rejects with no `.catch` / `then(_, onRejected)` attached at the time of rejection — fire-and-forget chains, failed dynamic imports without `try`, etc.
+
+```rb
+vm = Quickjs::VM.new
+vm.on_unhandled_rejection do |err|
+  warn "[JS] unhandled rejection: #{err.class} #{err.message}"
+end
+
+vm.eval_code("void Promise.reject(new TypeError('drift'));")
+#=> warns: [JS] unhandled rejection: Quickjs::TypeError drift
+```
+
+Calling `on_unhandled_rejection` again with a new block replaces the previously registered one (matching `on_log`).
+
+The block receives a `Quickjs::*Error` matching the rejection reason (`Quickjs::TypeError` for `new TypeError`, etc.); non-`Error` rejections (`Promise.reject('str')`, `Promise.reject({})`) are wrapped in `Quickjs::RuntimeError`. The exception's `#backtrace` carries the JS-side stack frames (`at func (file:line:col)`) for `Error` rejections, so the rejection site shows up directly when you log or re-raise. Exceptions raised inside the block are swallowed — propagating them out would corrupt the QuickJS runtime.
+
+The tracker fires synchronously when QuickJS first observes the rejection. A `.catch` attached later in the same tick does **not** suppress the notification, and a chain like `Promise.reject(x).then(y).then(z)` without a terminating `.catch` may emit a notification per intermediate promise. If that noise is a problem, attach handlers synchronously or dedupe by reason identity in your block. The block runs on the QuickJS stack — heavy work blocks JS execution.
 
 #### `Quickjs::VM#define_function`: 💎 Define a global function for JS by Ruby
 
@@ -275,6 +339,42 @@ rescue Quickjs::RuntimeError => e
 end
 ```
 
+#### `Quickjs::VM#dispose!`: 🧹 Release the underlying C-side runtime eagerly
+
+By default, the `JSRuntime` / `JSContext` behind a `Quickjs::VM` lives until Ruby's GC reclaims the wrapping object. Ruby's GC sizes its trigger by the Ruby-side object footprint (a few pointers) and doesn't see the C-side JS heap, so a workload that rebuilds VMs frequently — per-request, per-page-visit, throwaway pool — can let several megabytes per dead VM accumulate before a major GC fires.
+
+`dispose!` frees the runtime immediately and marks the VM unusable:
+
+```rb
+vm = Quickjs::VM.new(features: [::Quickjs::POLYFILL_INTL])
+vm.eval_code('…')
+vm.dispose!           # frees JSContext + JSRuntime now
+vm.disposed?          #=> true
+vm.eval_code('1 + 1') # raises Quickjs::RuntimeError "VM has been disposed"
+```
+
+`dispose!` is idempotent and safe to call before letting Ruby drop the reference — the dfree handler is a no-op on an already-disposed VM. The teardown itself can take tens of milliseconds on a VM with polyfills loaded; the GVL is released during the free so other Ruby threads (e.g. a background pool builder) keep running. For fire-and-forget teardown that doesn't block the caller, wrap it in a thread:
+
+```rb
+Thread.new { vm.dispose! }
+```
+
+#### `Quickjs::VM#drain_jobs!`: Run pending JS jobs to completion
+
+QuickJS does not automatically drain the job queue at the end of a synchronous `eval_code` / `call`. Continuations scheduled via `Promise.resolve().then(...)` or `JS_EnqueueJob` stay pending until something explicitly runs them — `await` inside JS does, but a sync return path does not.
+
+```rb
+vm = Quickjs::VM.new
+vm.eval_code('globalThis.x = 0; Promise.resolve().then(() => { x = 1 }); void 0')
+vm.eval_code('x')    #=> 0  (the .then() callback hasn't run yet)
+vm.drain_jobs!       #=> 1  (number of jobs executed)
+vm.eval_code('x')   #=> 1
+```
+
+`drain_jobs!` keeps running until the queue empties, so jobs that schedule further jobs all run in a single call. The drain is bounded by the VM's `timeout_msec`; exceeding it raises `Quickjs::InterruptedError`.
+
+Useful when porting JS that assumed V8's implicit-drain semantics — V8 (and therefore [mini_racer](https://github.com/rubyjs/mini_racer)) flushes pending jobs at every eval boundary, so `eval_code` already sees `.then()` continuations run by the time it returns. QuickJS doesn't. Patterns like `Promise.resolve().then(() => { ... })` and Stimulus/Hotwire callbacks that assume "the next microtask tick" silently fall through unless you call `drain_jobs!` explicitly.
+
 ### Value Conversion
 
 | JavaScript | | Ruby | Note |
@@ -310,7 +410,6 @@ end
     - [@formatjs/intl-pluralrules](https://github.com/formatjs/formatjs/blob/main/packages/intl-pluralrules/LICENSE.md)
     - [@formatjs/intl-numberformat](https://github.com/formatjs/formatjs/blob/main/packages/intl-numberformat/LICENSE.md)
     - [@formatjs/intl-datetimeformat](https://github.com/formatjs/formatjs/blob/main/packages/intl-datetimeformat/LICENSE.md)
-    - [@formatjs/ecma402-abstract](https://github.com/formatjs/formatjs/blob/main/packages/ecma402-abstract/LICENSE.md)
     - [@formatjs/fast-memoize](https://github.com/formatjs/formatjs/blob/main/packages/fast-memoize/LICENSE.md)
     - [@formatjs/intl-localematcher](https://github.com/formatjs/formatjs/blob/main/packages/intl-localematcher/LICENSE.md)
   - MIT License Copyright (c) 2026 FormatJS