quickjs 0.15.1 → 0.17.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54fe50175028245be99548bdb43a1884ceb956f77a999fca6c4cdf9ea9085a13
-  data.tar.gz: ddbf8d46cfec89db687899ec083e7ef2859ebd4ff9d711c9a18801d15c8d4ad0
+  metadata.gz: 7b233c0e106654a50f4af274fef6a4dd77f0b53cc0a703473cda844da6ba3763
+  data.tar.gz: 50dfeaf56422ee74e8cb8711a58e1678c8141ac4bb7256a4d8861fa1a9415c93
 SHA512:
-  metadata.gz: ce86220556d6e2bbf06f2da42227876f972a991e4beca36ecce89efcfc84f11ee6d62172813442368af11632f33f970db97535eab435f3fa6046be955c98529d
-  data.tar.gz: 255c23efa72230afbac3760e1cd8efd8ba29038263371ed4a4bc591dfbc58da9e48e2524bde82151cb8b10d14cda87255170fe0c46377efec8cb114ea8e9a855
+  metadata.gz: 9f77f8b802055b1ec67ad9b4f45fb54cbdb1349a473457572c1c1b72115283bed9b99b15029e101256147ce0bbc72b64371fcbdd0ede6e8e9ba5e8d4a0bb0376
+  data.tar.gz: 9387e82c41c0242caa67c16a67b48a204c32512b116c5e4cc61d83e892bec053393facaf7ac2553642b876cacecb3622ddb37a846fd1eea959c21ea7df70b569

data/CLAUDE.md

@@ -55,6 +55,14 @@ Tests use minitest with `describe`/`it` blocks. Key test files:
 - `test/quickjs_test.rb` — Main test suite (value conversion, errors, VM features, ESM imports, function definitions)
 - `test/quickjs_polyfill_test.rb` — Intl polyfill tests
 
+## Release Process
+
+1. On `main`, run `bundle exec rake polyfills:build` — rebuilds polyfill bundles and syncs `polyfills/package.json` version to match the gem version
+2. Bump `lib/quickjs/version.rb` and `Gemfile.lock` to the new version
+3. Commit `lib/quickjs/version.rb`, `Gemfile.lock`, `polyfills/package.json`, `polyfills/package-lock.json` as `"prepare vX.Y.Z"` — do NOT push; `rake release` handles that
+4. Run `bundle exec rake release` — tags, pushes to GitHub, and publishes to RubyGems (human step; do not run this as Claude)
+5. Create a GitHub release via `gh release create` with notes following the pattern of previous releases
+
 ## Build Notes
 
 - `extconf.rb` compiles with `-DNDEBUG` to avoid conflicts with Ruby 4.0 GC assertions

data/README.md

@@ -85,6 +85,21 @@ vm.eval_code('a.b = "d";')
 vm.eval_code('a.b;') #=> "d"
 ```
 
+#### `Quickjs::VM#compile`: 🚀 Cache parsed bundles as a `Quickjs::Runnable`
+
+Parsing large JS bundles is the dominant cost of a fresh evaluation. `compile` parses once and returns a `Quickjs::Runnable` wrapping the serialized bytecode; `run(on:)` executes it on any VM of the same QuickJS build, skipping the parser. Useful when the same bundle is evaluated repeatedly across short-lived VMs (test environments, page-per-VM web emulators).
+
+```rb
+runnable = Quickjs::VM.new.compile(File.read('big_bundle.js'), filename: 'big_bundle.js')
+
+vm = Quickjs::VM.new
+runnable.run(on: vm)                                     # use the given VM (no parse cost)
+runnable.run                                             # spin up a fresh VM with default options
+runnable.run(on: { features: [::Quickjs::POLYFILL_INTL] }) # ad-hoc VM with options
+```
+
+`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::VM#call`: ⚡ Call a JS function directly with Ruby arguments
 
 ```rb
@@ -129,6 +144,26 @@ vm.import('DefaultExport', from: File.read('exports.esm.js'))
 vm.import('* as all', from: File.read('exports.esm.js'))
 ```
 
+#### `Quickjs::VM#module_loader=`: 🧩 Resolve `import` specifiers from Ruby
+
+By default, `import` specifiers that aren't already loaded fall through to QuickJS's filesystem loader. Set a `module_loader` Proc to resolve specifiers in-memory instead — useful when the source code lives in a database, an importmap, or a virtual filesystem.
+
+```rb
+vm = Quickjs::VM.new
+modules = {
+  'a' => "import { b } from 'b'; export const a = () => `a-${b()}`;",
+  'b' => "export const b = () => 'b-result';"
+}
+vm.module_loader = ->(name) { modules[name] }
+
+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.
+
+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.
+
 #### `Quickjs::VM#define_function`: 💎 Define a global function for JS by Ruby
 
 ```rb
@@ -193,6 +228,37 @@ vm.eval_code('console.log("hello", 42)')
 # log.raw      #=> Array of raw Ruby values
 ```
 
+#### Memory management: 🔍 Inspect and control VM memory
+
+```rb
+vm = Quickjs::VM.new
+
+vm.memory_usage
+# => { malloc_size: Integer, malloc_limit: Integer, memory_used_size: Integer,
+#      atom_count: Integer, str_count: Integer, obj_count: Integer,
+#      prop_count: Integer, shape_count: Integer,
+#      js_func_count: Integer, js_func_code_size: Integer,
+#      c_func_count: Integer, array_count: Integer }
+
+vm.gc!             # trigger a QuickJS GC cycle; returns nil
+
+vm.memory_poisoned? #=> false (true once the VM has hit out-of-memory)
+```
+
+When the JS heap exhausts its memory limit, QuickJS enters a fragile state where further evaluation can segfault the process. `memory_poisoned?` flips to `true` after such an event, and subsequent `eval_code` / `call` calls raise `Quickjs::RuntimeError` immediately instead of risking a crash. Rescue it and recreate the VM.
+
+```rb
+vm = Quickjs::VM.new(memory_limit: 256 * 1024 * 1024)
+
+begin
+  vm.eval_code(js)
+rescue Quickjs::RuntimeError => e
+  raise unless vm.memory_poisoned?
+  vm = Quickjs::VM.new(memory_limit: 256 * 1024 * 1024)
+  retry
+end
+```
+
 ### Value Conversion
 
 | JavaScript | | Ruby | Note |