quickjs 0.18.0 → 0.19.0.pre1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7a32a1c083c824ccd0a1cbebc2fba793faf1f1fc743e19deaa9f0d7dd5b93cf
-  data.tar.gz: 669a202e7818baeae6966241b1cc1c0784de15b16682ac2713795fe8832ee605
+  metadata.gz: 40b6432886ae2f54e4b38466b0916b7cdf94ff2e7c3ac94f6f3b66ebd762f09a
+  data.tar.gz: 4720748aaec1473b7c5a9a9ea2348196f45bbe9ac27ed6009a467d7e37ae0761
 SHA512:
-  metadata.gz: 97e22453d9391a9a9056751371652a0561479f46d7bc9ead83d0f65208a09faad7a7d96a9ada99710df66a0790287ce714db3f30fec7ef22ca00f3e8fc93727b
-  data.tar.gz: 7292f78c043a8bd20702157e4481d72d9a835b03df76bee1a666796f96479b5e94cba4bcbfde18cdb61e759decb056c07bc94830b58fba6b80568c31cb607d18
+  metadata.gz: 97aa1ca89e4bc79c12fe11f228202426d3b95ffa2558a6803f1045e58a983f7d0abb3b597185182bf1e507c5dc48ccecf237596c70feb1d21a2f862a64635472
+  data.tar.gz: 5c0932632f6f619fd7cb720b3ae6f0444ca20fd08413af42fa235bf6b5741e872e8e5139fe9a38df6c9810e8a50e5653e7da56ae1ff303134a1833e6521a034d

data/README.md

@@ -392,6 +392,25 @@ Useful when porting JS that assumed V8's implicit-drain semantics — V8 (and th
 | `File` | → | `Quickjs::File` — `.name`, `.last_modified` + Blob attrs | requires `POLYFILL_FILE` |
 | `File` proxy | ← | `::File` | requires `POLYFILL_FILE`; applies to `define_function` return values |
 
+## Extending: registering polyfills
+
+`Quickjs.register_polyfill(name, source:, init: nil)` adds a polyfill to a process-wide registry. Any VM constructed with `name` in its `features:` list runs the registered bundle on top of the JS runtime. Companion gems use this hook to ship additional polyfills (e.g. `Intl.Collator`, `DisplayNames`) without bundling them into the main gem.
+
+```rb
+Quickjs.register_polyfill(
+  :polyfill_my_thing,
+  source: File.read('vendor/my-polyfill.min.js'),
+  init: 'globalThis.MyThing ||= {};'  # optional, runs before the bundle
+)
+
+vm = Quickjs::VM.new(features: [:polyfill_my_thing])
+vm.eval_code('MyThing.greet("hi")')
+```
+
+The first VM with a given polyfill pays the parse cost (the source is compiled to QuickJS bytecode on a disposable VM with a generous timeout); subsequent VMs reuse the cached bytecode. The polyfill body runs without consuming the user VM's `timeout_msec` budget — that's reserved for user code.
+
+The bundled `POLYFILL_INTL` (FormatJS Intl, `en` locale) is itself registered through this API at gem load time.
+
 ## Acknowledgements
 
 - [@ursm](https://github.com/ursm) — for continuous contributions improving performance and developer experience
@@ -401,7 +420,7 @@ Useful when porting JS that assumed V8's implicit-drain semantics — V8 (and th
 
 - `ext/quickjsrb/quickjs`
   - [MIT License Copyright (c) 2017-2021 by Fabrice Bellard and Charlie Gordon](https://github.com/bellard/quickjs/blob/6e2e68fd0896957f92eb6c242a2e048c1ef3cae0/LICENSE).
-- `ext/quickjsrb/vendor/polyfill-intl-en.min.js` ([bundled and minified from `polyfills/`](https://github.com/hmsk/quickjs.rb/tree/main/polyfills))
+- `lib/quickjs/polyfills/intl-en.min.js` ([bundled and minified from `polyfills/`](https://github.com/hmsk/quickjs.rb/tree/main/polyfills))
   - MIT License Copyright (c) 2022 FormatJS
     - [@formatjs/intl-supportedvaluesof](https://github.com/formatjs/formatjs/blob/main/packages/intl-supportedvaluesof/LICENSE.md)
   - MIT License Copyright (c) 2023 FormatJS

data/ext/quickjsrb/extconf.rb

@@ -12,7 +12,6 @@ $srcs = [
   'cutils.c',
   'quickjs.c',
   'quickjs-libc.c',
-  'polyfill-intl-en.min.c',
   'polyfill-file.min.c',
   'polyfill-encoding.min.c',
   'polyfill-url.min.c',
@@ -62,10 +61,6 @@ POLYFILL_OPTS=-fno-string-normalize -fno-typedarray -fno-typedarray -fno-eval -f
 
 qjsc: ./qjsc.o $(QJS_LIB_OBJS)
 		$(CC) -g -o $@ $^ -lm -ldl -lpthread
-polyfill-intl-en.min.js:
-		$(COPY) $(srcdir)/vendor/$@ $@
-polyfill-intl-en.min.c: ./qjsc polyfill-intl-en.min.js
-		./qjsc $(POLYFILL_OPTS) -c -M polyfill/intl-en.so,intlen -m -o $@ polyfill-intl-en.min.js
 polyfill-file.min.js:
 		$(COPY) $(srcdir)/vendor/$@ $@
 polyfill-file.min.c: ./qjsc polyfill-file.min.js

data/ext/quickjsrb/quickjsrb.c

@@ -1077,15 +1077,8 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
         JS_NewCFunction(data->context, js_quickjsrb_set_timeout, "setTimeout", 2));
   }
 
-  if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillIntlId))))
-  {
-    const char *defineIntl = "Object.defineProperty(globalThis, 'Intl', { value:{} });\n";
-    JSValue j_defineIntl = JS_Eval(data->context, defineIntl, strlen(defineIntl), vmInternalFilename, JS_EVAL_TYPE_GLOBAL);
-    JS_FreeValue(data->context, j_defineIntl);
-
-    JSValue j_polyfillIntlResult = load_polyfill_bytecode(data->context, &qjsc_polyfill_intl_en_min, qjsc_polyfill_intl_en_min_size);
-    JS_FreeValue(data->context, j_polyfillIntlResult);
-  }
+  // POLYFILL_INTL is registered Ruby-side via Quickjs.register_polyfill and
+  // applied by the wrapper around VM#initialize in lib/quickjs/polyfills.rb.
 
   if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillFileId))))
   {
@@ -1317,6 +1310,36 @@ static VALUE vm_m_evalBytecode(VALUE r_self, VALUE r_bytecode)
   return to_rb_return_value(data->context, j_returnedValue);
 }
 
+// Loads pre-compiled polyfill bytecode without arming the eval timer.
+// The user's `timeout_msec` is a budget for *their* code; running our
+// own polyfill (~140 ms for FormatJS Intl) under that budget would
+// interrupt the load on tight defaults. Unlike load_polyfill_bytecode
+// above we hold the GVL through JS_ReadObject + JS_EvalFunction: the
+// bytecode buffer is a Ruby String, so releasing would let GC compact
+// the backing storage out from under us. The static-symbol path can
+// release safely; this path cannot.
+static VALUE vm_m_loadPolyfillBytecode(VALUE r_self, VALUE r_bytecode)
+{
+  VMData *data;
+  TypedData_Get_Struct(r_self, VMData, &vm_type, data);
+
+  check_disposed(data);
+  StringValue(r_bytecode);
+
+  JSValue j_func = JS_ReadObject(data->context,
+                                 (const uint8_t *)RSTRING_PTR(r_bytecode),
+                                 (size_t)RSTRING_LEN(r_bytecode),
+                                 JS_READ_OBJ_BYTECODE);
+  if (JS_IsException(j_func))
+    return to_rb_value(data->context, j_func); // raises
+
+  JSValue j_result = JS_EvalFunction(data->context, j_func); // frees j_func
+  if (JS_IsException(j_result))
+    return to_rb_value(data->context, j_result); // raises
+  JS_FreeValue(data->context, j_result);
+  return Qnil;
+}
+
 static VALUE vm_m_defineGlobalFunction(int argc, VALUE *argv, VALUE r_self)
 {
   rb_need_block();
@@ -1728,6 +1751,7 @@ RUBY_FUNC_EXPORTED void Init_quickjsrb(void)
   rb_define_method(r_class_vm, "eval_code", vm_m_evalCode, -1);
   rb_define_private_method(r_class_vm, "_compile_to_bytecode", vm_m_compile, -1);
   rb_define_private_method(r_class_vm, "_run_bytecode", vm_m_evalBytecode, 1);
+  rb_define_private_method(r_class_vm, "_load_polyfill_bytecode", vm_m_loadPolyfillBytecode, 1);
   rb_define_method(r_class_vm, "call", vm_m_callGlobalFunction, -1);
   rb_define_method(r_class_vm, "define_function", vm_m_defineGlobalFunction, -1);
   rb_define_method(r_class_vm, "import", vm_m_import, -1);

data/ext/quickjsrb/quickjsrb.h

@@ -14,8 +14,6 @@
 #include <string.h>
 #include <time.h>
 
-extern const uint32_t qjsc_polyfill_intl_en_min_size;
-extern const uint8_t qjsc_polyfill_intl_en_min;
 extern const uint32_t qjsc_polyfill_file_min_size;
 extern const uint8_t qjsc_polyfill_file_min;
 extern const uint32_t qjsc_polyfill_encoding_min_size;

data/lib/quickjs/polyfills/intl.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# FormatJS Intl polyfill (`en` locale only — getCanonicalLocales, Locale,
+# PluralRules, NumberFormat, DateTimeFormat). Compiled and cached on first
+# VM that enables the feature; the file is not read until then.
+
+Quickjs.register_polyfill(
+  Quickjs::POLYFILL_INTL,
+  source: -> { File.read(File.expand_path('intl-en.min.js', __dir__)) },
+  init: "Object.defineProperty(globalThis, 'Intl', { value:{} });"
+)

data/lib/quickjs/polyfills.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Quickjs
+  # Process-wide registry; entries are lazily compiled to bytecode on
+  # first use and the bytecode is reused across VMs.
+  @_polyfills = {}
+
+  # `source:` accepts either a `String` (eager) or a `Proc` returning one
+  # (lazy). The lazy form lets a companion gem call `register_polyfill`
+  # at require time without paying the file-read cost unless a VM
+  # actually opts into the feature.
+  def self.register_polyfill(name, source:, init: nil)
+    raise ::TypeError, "name must be a Symbol, got #{name.class}" unless name.is_a?(Symbol)
+    raise ::TypeError, "source: must be a String or Proc, got #{source.class}" unless source.is_a?(String) || source.is_a?(Proc)
+    raise ::TypeError, "init: must be a String or nil, got #{init.class}" unless init.nil? || init.is_a?(String)
+
+    @_polyfills[name] = {source: source, init: init&.freeze, bytecode: nil}
+    nil
+  end
+
+  def self._polyfill_for(name)
+    @_polyfills[name]
+  end
+
+  def self._unregister_polyfill(name)
+    @_polyfills.delete(name)
+    nil
+  end
+
+  def self._apply_registered_polyfills(vm, features)
+    features.each do |feature|
+      next unless (entry = @_polyfills[feature])
+      # `||=` isn't atomic — `_precompile_polyfill` releases the GVL inside
+      # `Quickjs.compile`, so two threads racing to construct VMs with the
+      # same polyfill can both see nil and both compile. The bytecode write
+      # is harmless because both threads produce identical bytes; the only
+      # observable cost is wasted compile work, and (for `source: Proc`) a
+      # second Proc invocation — so register Procs that are safe to call
+      # more than once.
+      entry[:bytecode] ||= _precompile_polyfill(entry, feature)
+      vm.send(:_load_polyfill_bytecode, entry[:bytecode])
+    end
+  end
+
+  # Compiled once per process per polyfill on a disposable VM whose
+  # generous timeout covers parsing multi-MB bundles (FormatJS Intl is
+  # ~2 MB). The user's per-VM `timeout_msec` is for their own JS — it
+  # would otherwise interrupt our infrastructure on tight defaults.
+  # `features: []` skips applying any registered polyfills to the temp
+  # VM (no recursion / no wasted polyfill loads).
+  def self._precompile_polyfill(entry, feature)
+    source = entry[:source]
+    source = source.call if source.is_a?(Proc)
+    combined = entry[:init] ? "#{entry[:init]}\n#{source}" : source
+    Quickjs.compile(combined, filename: feature.to_s, timeout_msec: 60_000, features: []).to_s
+  end
+
+  module PolyfillLoader
+    def initialize(features: [], **opts)
+      super
+      Quickjs._apply_registered_polyfills(self, features)
+    end
+  end
+
+  # Guard against double-prepend if this file is reloaded (e.g. Rails dev).
+  VM.prepend(PolyfillLoader) unless VM.ancestors.include?(PolyfillLoader)
+end

data/lib/quickjs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quickjs
-  VERSION = "0.18.0"
+  VERSION = "0.19.0.pre1"
 end

data/lib/quickjs.rb

@@ -8,6 +8,10 @@ require_relative "quickjs/crypto_key"
 require_relative "quickjs/function"
 require_relative "quickjs/quickjsrb"
 require_relative "quickjs/runnable"
+# Polyfills.rb defines Quickjs.register_polyfill; polyfills/intl.rb calls
+# it at load time, so the order matters.
+require_relative "quickjs/polyfills"
+require_relative "quickjs/polyfills/intl"
 
 module Quickjs
   class Blob

data/polyfills/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "quickjs-rb-polyfills",
-  "version": "0.18.0",
+  "version": "0.19.0.pre1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "quickjs-rb-polyfills",
-      "version": "0.18.0",
+      "version": "0.19.0.pre1",
       "dependencies": {
         "@formatjs/intl-datetimeformat": "^7.3.1",
         "@formatjs/intl-getcanonicallocales": "^3.2.2",

data/polyfills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickjs-rb-polyfills",
-  "version": "0.18.0",
+  "version": "0.19.0.pre1",
   "private": true,
   "scripts": {
     "build": "rolldown -c rolldown.config.mjs",

data/polyfills/rolldown.config.mjs

@@ -4,7 +4,10 @@ export default [
   defineConfig({
     input: "src/intl-en.js",
     output: {
-      file: "../ext/quickjsrb/vendor/polyfill-intl-en.min.js",
+      // Loaded at runtime by lib/quickjs/polyfills/intl.rb via
+      // Quickjs.register_polyfill; other entries are still embedded as
+      // pre-compiled bytecode in the .so until they go the same way.
+      file: "../lib/quickjs/polyfills/intl-en.min.js",
       format: "iife",
       minify: true,
     },

data/sig/quickjs.rbs

@@ -14,6 +14,8 @@ module Quickjs
   def self.eval_code: (String code, ?Hash[Symbol, untyped] overwrite_opts) -> untyped
   def self.compile: (String source, ?filename: String, **untyped) -> Quickjs::Runnable
 
+  def self.register_polyfill: (Symbol name, source: String | ^() -> String, ?init: String?) -> nil
+
   class Value
     UNDEFINED: Symbol
     NAN: Symbol

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quickjs
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0.pre1
 platform: ruby
 authors:
 - hmsk
@@ -86,11 +86,13 @@ files:
 - ext/quickjsrb/quickjsrb_file.h
 - ext/quickjsrb/vendor/polyfill-encoding.min.js
 - ext/quickjsrb/vendor/polyfill-file.min.js
-- ext/quickjsrb/vendor/polyfill-intl-en.min.js
 - ext/quickjsrb/vendor/polyfill-url.min.js
 - lib/quickjs.rb
 - lib/quickjs/crypto_key.rb
 - lib/quickjs/function.rb
+- lib/quickjs/polyfills.rb
+- lib/quickjs/polyfills/intl-en.min.js
+- lib/quickjs/polyfills/intl.rb
 - lib/quickjs/runnable.rb
 - lib/quickjs/subtle_crypto.rb
 - lib/quickjs/version.rb