quickjs 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb155f6499b100170fefe4f9e8d3a24eb221bf5cd3363adaae7c1dda6d157f12
-  data.tar.gz: 7b51767a21b911a62eab5f561aaebc14461fa9078874491db8163fd92bdced5a
+  metadata.gz: 64bdf2de37fc8ac24b7acec74dd724226f732a4acbef401d579b9b46e12c86f1
+  data.tar.gz: 4d76617466a380a038de3684495dc38eacb29be11002b3d6b1536c2c6caf0d80
 SHA512:
-  metadata.gz: f45ea57fcb653f3f886443fef85ebd9138cdfd0ddff0322ac628a25d18033f6eb23fc81f578951d04af23dff604fe7196efca663cf46d74d1820ef3f346bd7ce
-  data.tar.gz: 4e721e1621759230776b78194657de9199e9fc7af61d6b091e31a379b010cd2f7a76ce825d6e693595a2cb12bc7b12d76d9fa9ef683b1b726ef1a8e03851ec06
+  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',
 ]
 
@@ -37,7 +38,8 @@ else
 end
 
 append_cflags('-fwrapv')
-$CFLAGS << ' ' << '-D_GNU_SOURCE -DCONFIG_VERSION=\"2024-02-14\"'
+# NDEBUG: suppress QuickJS debug assertions that conflict with Ruby 4.0 GC
+$CFLAGS << ' ' << '-D_GNU_SOURCE -DCONFIG_VERSION=\"2024-02-14\" -DNDEBUG'
 
 abort('could not find quickjs.h') unless find_header('quickjs.h')
 abort('could not find cutils.h') unless find_header('cutils.h')
@@ -60,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

@@ -8,6 +8,10 @@ JSValue j_error_from_ruby_error(JSContext *ctx, VALUE r_error)
   int objectId = NUM2INT(r_object_id);
   JS_SetPropertyStr(ctx, j_error, "rb_object_id", JS_NewInt32(ctx, objectId));
 
+  // Keep the error alive in VMData to prevent GC before find_ruby_error retrieves it
+  VMData *data = JS_GetContextOpaque(ctx);
+  rb_hash_aset(data->alive_errors, r_object_id, r_error);
+
   VALUE r_exception_message = rb_funcall(r_error, rb_intern("message"), 0);
   const char *errorMessage = StringValueCStr(r_exception_message);
   JS_SetPropertyStr(ctx, j_error, "message", JS_NewString(ctx, errorMessage));
@@ -89,8 +93,11 @@ VALUE find_ruby_error(JSContext *ctx, JSValue j_error)
     JS_FreeValue(ctx, j_errorOriginalRubyObjectId);
     if (errorOriginalRubyObjectId > 0)
     {
-      // may be nice if cover the case of object is missing
-      return rb_funcall(rb_const_get(rb_cClass, rb_intern("ObjectSpace")), rb_intern("_id2ref"), 1, INT2NUM(errorOriginalRubyObjectId));
+      VMData *data = JS_GetContextOpaque(ctx);
+      VALUE r_key = INT2NUM(errorOriginalRubyObjectId);
+      VALUE r_error = rb_hash_aref(data->alive_errors, r_key);
+      rb_hash_delete(data->alive_errors, r_key);
+      return r_error;
     }
   }
   else
@@ -329,7 +336,7 @@ static JSValue js_quickjsrb_call_global(JSContext *ctx, JSValueConst _this, int
     JS_FreeValue(ctx, j_v);
   }
   rb_ary_push(r_call_args, r_argv);
-  rb_ary_push(r_call_args, ULONG2NUM(data->eval_time->limit * 1000 / CLOCKS_PER_SEC));
+  rb_ary_push(r_call_args, ULONG2NUM(data->eval_time->limit_ms));
 
   int sadnessHappened;
 
@@ -507,7 +514,7 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
   VMData *data;
   TypedData_Get_Struct(r_self, VMData, &vm_type, data);
 
-  data->eval_time->limit = (clock_t)(CLOCKS_PER_SEC * NUM2UINT(r_timeout_msec) / 1000);
+  data->eval_time->limit_ms = (int64_t)NUM2UINT(r_timeout_msec);
   JS_SetContextOpaque(data->context, data);
   JSRuntime *runtime = JS_GetRuntime(data->context);
 
@@ -554,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",
@@ -580,7 +594,11 @@ static VALUE vm_m_initialize(int argc, VALUE *argv, VALUE r_self)
 static int interrupt_handler(JSRuntime *runtime, void *opaque)
 {
   EvalTime *eval_time = opaque;
-  return clock() >= eval_time->started_at + eval_time->limit ? 1 : 0;
+  struct timespec now;
+  clock_gettime(CLOCK_MONOTONIC, &now);
+  int64_t elapsed_ms = (int64_t)(now.tv_sec - eval_time->started_at.tv_sec) * 1000
+                     + (now.tv_nsec - eval_time->started_at.tv_nsec) / 1000000;
+  return elapsed_ms >= eval_time->limit_ms ? 1 : 0;
 }
 
 static VALUE vm_m_evalCode(VALUE r_self, VALUE r_code)
@@ -594,7 +612,7 @@ static VALUE vm_m_evalCode(VALUE r_self, VALUE r_code)
     rb_raise(rb_eTypeError, "JavaScript code must be a String, got %s", StringValueCStr(r_code_class));
   }
 
-  data->eval_time->started_at = clock();
+  clock_gettime(CLOCK_MONOTONIC, &data->eval_time->started_at);
   JS_SetInterruptHandler(JS_GetRuntime(data->context), interrupt_handler, data->eval_time);
 
   char *code = StringValueCStr(r_code);
@@ -612,9 +630,12 @@ static VALUE vm_m_evalCode(VALUE r_self, VALUE r_code)
   }
   else
   {
+    // Free j_awaitedResult before to_rb_value because to_rb_value may
+    // raise (longjmp) for JS exceptions, which would skip any cleanup
+    // after it and leak JS GC objects.
+    JS_FreeValue(data->context, j_awaitedResult);
     VALUE result = to_rb_value(data->context, j_returnedValue);
     JS_FreeValue(data->context, j_returnedValue);
-    JS_FreeValue(data->context, j_awaitedResult);
     return result;
   }
 }

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";
@@ -39,8 +42,8 @@ const char *native_errors[] = {
 
 typedef struct EvalTime
 {
-  clock_t limit;
-  clock_t started_at;
+  int64_t limit_ms;
+  struct timespec started_at;
 } EvalTime;
 
 typedef struct VMData
@@ -49,6 +52,7 @@ typedef struct VMData
   VALUE defined_functions;
   struct EvalTime *eval_time;
   VALUE logs;
+  VALUE alive_errors;
 } VMData;
 
 static void vm_free(void *ptr)
@@ -75,6 +79,15 @@ static void vm_mark(void *ptr)
   VMData *data = (VMData *)ptr;
   rb_gc_mark_movable(data->defined_functions);
   rb_gc_mark_movable(data->logs);
+  rb_gc_mark_movable(data->alive_errors);
+}
+
+static void vm_compact(void *ptr)
+{
+  VMData *data = (VMData *)ptr;
+  data->defined_functions = rb_gc_location(data->defined_functions);
+  data->logs = rb_gc_location(data->logs);
+  data->alive_errors = rb_gc_location(data->alive_errors);
 }
 
 static const rb_data_type_t vm_type = {
@@ -83,6 +96,7 @@ static const rb_data_type_t vm_type = {
         .dmark = vm_mark,
         .dfree = vm_free,
         .dsize = vm_size,
+        .dcompact = vm_compact,
     },
     .flags = RUBY_TYPED_FREE_IMMEDIATELY,
 };
@@ -93,6 +107,7 @@ static VALUE vm_alloc(VALUE r_self)
   VALUE obj = TypedData_Make_Struct(r_self, VMData, &vm_type, data);
   data->defined_functions = rb_hash_new();
   data->logs = rb_ary_new();
+  data->alive_errors = rb_hash_new();
 
   EvalTime *eval_time = malloc(sizeof(EvalTime));
   data->eval_time = eval_time;
@@ -138,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})();