quickjs 0.11.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29ad9419055f853b82d642f0c5404d24d476dcc3d0d8e7da4364f06a819b10a3
-  data.tar.gz: 77b07d4c214663c8fd716ab2c9dda3d88c327f3f77b0d350f2987d506a70677e
+  metadata.gz: 64bdf2de37fc8ac24b7acec74dd724226f732a4acbef401d579b9b46e12c86f1
+  data.tar.gz: 4d76617466a380a038de3684495dc38eacb29be11002b3d6b1536c2c6caf0d80
 SHA512:
-  metadata.gz: 75ba55882ce0d5371e3ba3d584849d012c06a955d230e7b9975266852753dae3db45244fc8b9bf967f86ba25fff52d7c6d8118bab131f9e8b61bb421356597c0
-  data.tar.gz: 97964de7f1ef9f20c548cc8e69da09fe058112193593bb433e8b93e3e42424582f111a306df13df78dd583442dd712bc71e6da8ff0ce17116f19618f8aa803d2
+  metadata.gz: 0fcf3bde7047e39038983326a6d867430e4e5fc63ac65bc6823c44df4222904a8bef385abd12bcadcca5213c9610198a08cdf4f12bc949dc2f7613509a8e46fc
+  data.tar.gz: af03f93832d2400cbb1418c764fbdaca5b1a51fd232462731b404a897851ff60cb3437c745ab2c03e36a7a5219c3618751075649b1cdc2e9935689b4e218ccf7

data/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+quickjs.rb is a Ruby gem wrapping QuickJS (a lightweight JavaScript interpreter) via a C extension. It lets Ruby programs evaluate JavaScript code without a full Node.js runtime.
+
+## Build & Test Commands
+
+```bash
+bundle exec rake              # Full cycle: clobber → compile → test
+bundle exec rake compile      # Compile C extension only
+bundle exec rake test         # Run all tests
+bundle exec ruby -Itest:lib test/quickjs_test.rb              # Run single test file
+bundle exec ruby -Itest:lib test/quickjs_test.rb -n test_name # Run single test
+rake polyfills:build          # Rebuild Intl polyfill bundle (requires npm)
+```
+
+QuickJS source lives as a git submodule under `ext/quickjsrb/quickjs/` — clone with `--recurse-submodules`.
+
+## Design Principles
+
+- **Never modify QuickJS core** — the engine is a git submodule; all customization is implemented externally in our C extension or Ruby layer
+- **Prefer Ruby over C** — don't rush to write C code; use Ruby where it provides better extendability and maintainability
+- **Security-conscious C layer** — avoid adding flexible C-level features that introduce security risks; expose QuickJS's own options as-is rather than inventing new attack surface
+- **Keep the default footprint small** — don't increase bundle size or add JavaScript overhead (e.g. polyfills) by default; additional capabilities should be opt-in via feature flags
+
+## Architecture
+
+**C Extension** (`ext/quickjsrb/`):
+- `quickjsrb.c` / `quickjsrb.h` — Core extension: creates QuickJS runtime/context, handles Ruby↔JS value conversion, timeout interrupts, and Ruby function bridging into JS
+- Value conversion uses JSON serialization for complex types (objects/arrays); direct conversion for primitives
+- `VMData` struct holds the JS context, defined Ruby functions, timeout state, console logs, and error references
+- Ruby GC integration via `vm_mark`, `vm_free`, `vm_compact` callbacks
+
+**Ruby layer** (`lib/quickjs/`):
+- `Quickjs::VM` — Persistent JS runtime with `eval_code`, `import`, `define_function`
+- `Quickjs.eval_code` — Convenience method for one-shot evaluation
+- Exception hierarchy maps JS error types (SyntaxError, TypeError, etc.) to Ruby classes under `Quickjs::`
+- Special values: `Quickjs::Value::UNDEFINED` and `Quickjs::Value::NAN` represent JS undefined/NaN
+
+**Feature flags** (passed to `VM.new` via `features:` array):
+- `:feature_std`, `:feature_os` — QuickJS std/os modules
+- `:feature_timeout` — setTimeout/setInterval via CRuby threads
+- `:feature_polyfill_intl` — Intl API polyfill (DateTimeFormat, NumberFormat, PluralRules, Locale)
+
+**Polyfills** (`polyfills/`):
+- Built from FormatJS packages via rolldown, output minified JS embedded as C source
+- Polyfill version must match gem version (enforced during `rake release`)
+
+## Testing
+
+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
+
+## Build Notes
+
+- `extconf.rb` compiles with `-DNDEBUG` to avoid conflicts with Ruby 4.0 GC assertions
+- Symbol visibility is hidden by default (`-fvisibility=hidden`)
+- CI matrix: Ruby 3.2/3.3/3.4/4.0 × Ubuntu/macOS

data/README.md

@@ -63,6 +63,9 @@ vm = Quickjs.eval_code(features: [::Quickjs::FEATURE_TIMEOUT])
 
 # Inject the polyfill of Intl
 vm = Quickjs.eval_code(features: [::Quickjs::POLYFILL_INTL])
+
+# Inject the polyfill of Blob and File (W3C File API)
+vm = Quickjs.eval_code(features: [::Quickjs::POLYFILL_FILE])
 ```
 
 </details>
@@ -103,6 +106,9 @@ vm = Quickjs::VM.new(features: [::Quickjs::FEATURE_TIMEOUT])
 
 # Inject the polyfill of Intl
 vm = Quickjs::VM.new(features: [::Quickjs::POLYFILL_INTL])
+
+# Inject the polyfill of Blob and File (W3C File API)
+vm = Quickjs::VM.new(features: [::Quickjs::POLYFILL_FILE])
 ```
 
 #### VM timeout
@@ -163,7 +169,7 @@ vm.logs.last.raw #=> ['log me', nil]
 
 - `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)
+- `ext/quickjsrb/vendor/polyfill-intl-en.min.js` ([bundled and minified from `polyfills/`](https://github.com/hmsk/quickjs.rb/tree/main/polyfills))
   - MIT License Copyright (c) 2023 FormatJS
     - [@formatjs/intl-getcanonicallocales](https://github.com/formatjs/formatjs/blob/main/packages/intl-getcanonicallocales/LICENSE.md)
     - [@formatjs/intl-locale](https://github.com/formatjs/formatjs/blob/main/packages/intl-locale/LICENSE.md)

data/Rakefile

@@ -11,7 +11,7 @@ end
 
 require 'rake/extensiontask'
 
-task build: :compile
+task build: [:compile, 'polyfills:version:warn']
 
 GEMSPEC = Gem::Specification.load('quickjs.gemspec')
 
@@ -19,4 +19,56 @@ Rake::ExtensionTask.new('quickjsrb', GEMSPEC) do |ext|
   ext.lib_dir = 'lib/quickjs'
 end
 
+def check_polyfill_version!
+  require 'json'
+  require_relative 'lib/quickjs/version'
+
+  package = JSON.parse(File.read(File.expand_path('polyfills/package.json', __dir__)))
+  return if package['version'] == Quickjs::VERSION
+
+  yield package['version'], Quickjs::VERSION
+end
+
+namespace :polyfills do
+  desc 'Build polyfill bundles with rolldown and recompile'
+  task build: :clobber do
+    require 'json'
+    require_relative 'lib/quickjs/version'
+
+    polyfills_dir = File.expand_path('polyfills', __dir__)
+    package_json_path = File.join(polyfills_dir, 'package.json')
+    package = JSON.parse(File.read(package_json_path))
+    old_version = package['version']
+    package['version'] = Quickjs::VERSION
+    File.write(package_json_path, "#{JSON.pretty_generate(package)}\n")
+    if old_version != Quickjs::VERSION
+      warn "\n⚠️  polyfills/package.json version was #{old_version}, updated to #{Quickjs::VERSION}\n\n"
+    end
+
+    Dir.chdir(polyfills_dir) do
+      sh 'npm install' unless File.exist?('node_modules/.package-lock.json') &&
+        File.mtime('node_modules/.package-lock.json') >= File.mtime('package.json')
+      sh 'npx rolldown -c rolldown.config.mjs'
+    end
+
+    Rake::Task[:compile].invoke
+  end
+
+  namespace :version do
+    task :check do
+      check_polyfill_version! do |pkg_v, gem_v|
+        abort "polyfills/package.json version (#{pkg_v}) does not match gem version (#{gem_v}). Run `rake polyfills:build` first."
+      end
+    end
+
+    task :warn do
+      check_polyfill_version! do |pkg_v, gem_v|
+        warn "⚠️  polyfills/package.json version (#{pkg_v}) does not match gem version (#{gem_v}). Run `rake polyfills:build` to sync."
+      end
+    end
+  end
+end
+
+task 'release:guard_clean' => 'polyfills:version:check'
+
 task default: %i[clobber compile test]

data/ext/quickjsrb/extconf.rb

@@ -12,6 +12,7 @@ $srcs = [
   'quickjs.c',
   'quickjs-libc.c',
   'polyfill-intl-en.min.c',
+  'polyfill-file.min.c',
   'quickjsrb.c',
 ]
 
@@ -61,6 +62,10 @@ 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
+		./qjsc -fno-string-normalize -fno-eval -fno-proxy -fno-module-loader -c -M polyfill/file.so,file -m -o $@ polyfill-file.min.js
 COMPILE_POLYFILL
   conf
 end

data/ext/quickjsrb/quickjsrb.c

@@ -561,6 +561,13 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
     JS_FreeValue(data->context, j_polyfillIntlResult);
   }
 
+  if (RTEST(rb_funcall(r_features, rb_intern("include?"), 1, QUICKJSRB_SYM(featurePolyfillFileId))))
+  {
+    JSValue j_polyfillFileObject = JS_ReadObject(data->context, &qjsc_polyfill_file_min, qjsc_polyfill_file_min_size, JS_READ_OBJ_BYTECODE);
+    JSValue j_polyfillFileResult = JS_EvalFunction(data->context, j_polyfillFileObject);
+    JS_FreeValue(data->context, j_polyfillFileResult);
+  }
+
   JSValue j_console = JS_NewObject(data->context);
   JS_SetPropertyStr(
       data->context, j_console, "log",

data/ext/quickjsrb/quickjsrb.h

@@ -14,11 +14,14 @@
 
 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;
 
 const char *featureStdId = "feature_std";
 const char *featureOsId = "feature_os";
 const char *featureTimeoutId = "feature_timeout";
 const char *featurePolyfillIntlId = "feature_polyfill_intl";
+const char *featurePolyfillFileId = "feature_polyfill_file";
 
 const char *undefinedId = "undefined";
 const char *nanId = "NaN";
@@ -150,6 +153,7 @@ static void r_define_constants(VALUE r_parent_class)
   rb_define_const(r_parent_class, "MODULE_OS", QUICKJSRB_SYM(featureOsId));
   rb_define_const(r_parent_class, "FEATURE_TIMEOUT", QUICKJSRB_SYM(featureTimeoutId));
   rb_define_const(r_parent_class, "POLYFILL_INTL", QUICKJSRB_SYM(featurePolyfillIntlId));
+  rb_define_const(r_parent_class, "POLYFILL_FILE", QUICKJSRB_SYM(featurePolyfillFileId));
 
   VALUE rb_cQuickjsValue = rb_define_class_under(r_parent_class, "Value", rb_cObject);
   rb_define_const(rb_cQuickjsValue, "UNDEFINED", QUICKJSRB_SYM(undefinedId));

data/ext/quickjsrb/vendor/polyfill-file.min.js

@@ -0,0 +1 @@
+(function(){var e=class e{#e;#t;constructor(n,i){if(this.#t=t(i?.type??``),!n){this.#e=new Uint8Array;return}if(!Array.isArray(n))throw TypeError(`Failed to construct 'Blob': The provided value cannot be converted to a sequence.`);let a=[],o=0;for(let t of n){let n;n=typeof t==`string`?r(t):t instanceof ArrayBuffer?new Uint8Array(t):ArrayBuffer.isView(t)?new Uint8Array(t.buffer,t.byteOffset,t.byteLength):t instanceof e?t.#e:r(String(t)),a.push(n),o+=n.byteLength}let s=new Uint8Array(o),c=0;for(let e of a)s.set(e,c),c+=e.byteLength;this.#e=s}get size(){return this.#e.byteLength}get type(){return this.#t}slice(r,i,a){let o=this.size,s=r===void 0?0:n(r,o),c=i===void 0?o:n(i,o),l=Math.max(c-s,0),u=new e;return u.#e=this.#e.slice(s,s+l),u.#t=t(a??``),u}text(){return Promise.resolve(i(this.#e))}arrayBuffer(){return Promise.resolve(this.#e.buffer.slice(this.#e.byteOffset,this.#e.byteOffset+this.#e.byteLength))}toString(){return`[object Blob]`}get[Symbol.toStringTag](){return`Blob`}};function t(e){return/[^\x20-\x7E]/.test(e)?``:e.toLowerCase()}function n(e,t){return e<0?Math.max(t+e,0):Math.min(e,t)}function r(e){let t=[];for(let n=0;n<e.length;n++){let r=e.charCodeAt(n);if(r>=55296&&r<=56319&&n+1<e.length){let t=e.charCodeAt(n+1);t>=56320&&t<=57343&&(r=(r-55296)*1024+(t-56320)+65536,n++)}r<=127?t.push(r):r<=2047?t.push(192|r>>6,128|r&63):r<=65535?t.push(224|r>>12,128|r>>6&63,128|r&63):t.push(240|r>>18,128|r>>12&63,128|r>>6&63,128|r&63)}return new Uint8Array(t)}function i(e){let t=``,n=0;for(;n<e.length;){let r,i=e[n];i<=127?(r=i,n++):(i&224)==192?(r=(i&31)<<6|e[n+1]&63,n+=2):(i&240)==224?(r=(i&15)<<12|(e[n+1]&63)<<6|e[n+2]&63,n+=3):(r=(i&7)<<18|(e[n+1]&63)<<12|(e[n+2]&63)<<6|e[n+3]&63,n+=4),r<=65535?t+=String.fromCharCode(r):(r-=65536,t+=String.fromCharCode(55296+(r>>10),56320+(r&1023)))}return t}var a=class extends e{#e;#t;constructor(e,t,n){if(arguments.length<2)throw TypeError(`Failed to construct 'File': 2 arguments required, but only `+arguments.length+` present.`);super(e,n),this.#e=String(t),this.#t=n?.lastModified===void 0?Date.now():Number(n.lastModified)}get name(){return this.#e}get lastModified(){return this.#t}toString(){return`[object File]`}get[Symbol.toStringTag](){return`File`}};globalThis.Blob=e,globalThis.File=a})();