Pass Ruby values into JS with VM#define_const / #define_let / #define_var

[hmsk]

Pass Ruby values into JS without interpolating them into source.

vm = Quickjs::VM.new
vm.define_const(:user, { name: 'Itadori', tags: ['strong', 'kind'] })

vm.eval_code("user.name + ': ' + user.tags.join(', ')") #=> "Itadori: strong, kind"

Why three methods

"Globals" is ambiguous in this VM: let / const declarations persist across eval_code calls but never appear on globalThis. Picking one destination silently diverges from user code:

vm.eval_code('globalThis.a = 1;')
vm.eval_code('let a = 2; a')   #=> 2
vm.eval_code('globalThis.a')   #=> 1

So the caller picks the binding form instead, and JS's own rules apply unchanged. Nothing new to learn, and nothing invented.

	JS can reassign it	Redeclaring it in JS	On globalThis
define_const	no, raises Quickjs::TypeError	Quickjs::SyntaxError	no
define_let	yes	Quickjs::SyntaxError	no
define_var	yes	allowed	yes

define_var is the one for JS you don't control, a bundle reading globalThis.APP_CONFIG. Because these are real declarations rather than property assignments, a colliding declaration in user code is a loud error instead of a silent shadow.

Notes

• Each declaration runs as its own eval, so caller source is never rewritten and backtrace line numbers keep pointing at the caller's code.
• Values are serialized to JS source here rather than through the C converter, which falls back to #inspect for unrecognized objects and would silently turn a Time into a string. Unsupported values raise TypeError. Circular structures raise ArgumentError.
• Names are validated against /\A[A-Za-z_$][A-Za-z0-9_$]*\z/, which is narrower than JS (it rejects Unicode identifiers like 値). Without validation, a name splices arbitrary JS into the source we evaluate.
• Redefining an existing let / var assigns to it. const and binding-form switches raise ArgumentError, tracked by a per-VM name -> kind registry that is only written after the eval succeeds.
• The value is a snapshot, not a live reference. define_function remains the way to have JS read the current Ruby value on every access.
• Pure Ruby, no C changes.

Open questions

• define_var on a name user code already declared as var silently overwrites, since var redeclaration is legal JS. Only const / let collisions are loud, so define_var is the least protected of the three.
• Bignum values are emitted as an integer literal and lose precision when JS parses them as a Number. Consistent with the existing C converter's Number(str) path, but silent.
• One-shot Quickjs.eval_code is not covered, since there is no VM handle to define on.

Re-review against current main

Rebased and re-read after #66, #72, #73, #74 and #75 landed. No defects found; two gaps closed.

Module interaction is now covered. Injecting configuration and then importing a module that reads it is the obvious pairing with compile_module, and it is not obvious from either feature alone that a declaration reaches module scope, since a module has its own scope and only var lands on globalThis. Verified and pinned down with tests: a const is readable from an imported module, a var through globalThis, a const defined after the import is readable at call time (the binding resolves when the function runs, not when the module body evaluates), and a Runnable run on the VM sees it too.

The identifier docs overstated what is accepted. The README said the name "must be a valid JavaScript identifier", but 値 is a valid JS identifier and this rejects it. The restriction is deliberate, so the docs now give the pattern and the reason.

Also checked, no action needed:

• const / let persist across evals even though eval_code defaults to async: true. Load-bearing and non-obvious, already covered by the first test.
• String values survive the JSON-to-JS-literal gap, including U+2028 / U+2029, which are legal in JSON strings and were illegal in JS string literals before ES2019.
• Bignum precision loss matches the C converter exactly: 2**70 yields 1.1805916207174113e+21 through both paths, so this path is not worse than the rest of the gem.
• define_var(:NaN, 1) silently no-ops, since NaN is a non-writable global and this is sloppy mode. That is JS behaviour, unchanged by us.

Validation

bundle exec rake — 597 runs, 946 assertions, 0 failures, 1 pre-existing skip. 36 new tests.

[hmsk]

Recording what the cold review turned up beyond the define_var problem already fixed in 89d573c, so it is attached to the code it describes rather than to issues about a file that is not on main yet. I verified each of these on this branch.

Nothing here blocks the merge as far as I can tell. Taking them in the PR or filing them once it lands both work; the split below is how I would divide them.

Worth deciding before this lands

Shared substructures expand rather than share. seen.delete on the way out is what makes the same object twice as siblings legal, and it also means a DAG is written out in full:

structure	_js_literal output
x = {n: 1}; 10.times { x = [x, x] }	10,237 bytes
14 levels	163,837 bytes
18 levels	2,621,437 bytes
25 levels	~335 MB

Doubling per level. Reachable from a small Ruby structure with aliases, which YAML or Marshal produce without anyone intending it. A depth or output-size cap would bound it. Worth noting that #101 landed the opposite decision on the way out of the VM, for the same reason: a memo there was chosen partly so a guest could not turn a small graph into an enormous one.

A __proto__ key sets the prototype rather than becoming a property. Filed as #108, because the C converter does the same and this is gem-wide rather than yours. Mentioning it here only because this path is the deliberate input API, so it is a reasonable place to fix it first: ["__proto__"] as the emitted key rather than "__proto__".

Documentation, where the code and the README disagree

All verified on this branch:

• vm.define_const(:x, "\xff\xfe".b) raises JSON::GeneratorError, and vm.define_const("abc".encode("UTF-16LE"), 1) raises Encoding::CompatibilityError. The README says anything unsupported raises TypeError. The first also diverges from "converted the same way as elsewhere in the gem": the C converter takes those bytes without complaint.
• An ASCII-8BIT string whose bytes are valid UTF-8 is silently reinterpreted. "\xC3\xA9".b arrives as "é", length 1.
• 10**400 becomes Infinity, not a loss of precision.
• {"a" => 1, :a => 2} emits both keys and JS keeps the last, so the Hash silently loses an entry. Same for {1 => "x", "1" => "y"}.
• A File or an Exception raises TypeError here, while the C converter handles both.
• "A colliding declaration in your JS is a loud error instead of a silent shadow" holds at top-level script scope only. In a function body, and in module scope, the shadow is silent: a module declaring const injected shadows an injected const with no error.
• RESERVED_WORDS reads as protection against clobbering, and it is not: define_var(:eval, 1) makes typeof eval "number", and define_var(:Object, 1) breaks Object.keys. Same family as the define_var problem, and arguably now covered by the ordering advice, but the constant's name promises more than it delivers.

Robustness

_js_literal blows the Ruby stack at around depth 2619, with SystemStackError rather than anything worse. Circular structures already get a clean ArgumentError; merely deep ones do not. The C converter has no depth guard either, so this is a nit rather than a defect.

What the review could not break

No escape from a literal into executable JS, through string values, symbols, hash keys, floats, integers, or the variable name. NAME_PATTERN is anchored \A…\z so nothing gets past it with a newline, to_json escapes the full set that can terminate a JS string, and U+2028/U+2029 pass through raw where QuickJS accepts them. The disposed, owning-thread and OOM-poisoned guards are all inherited through eval_code rather than bypassed, and a failed declaration never writes the registry.

[hmsk]

Closing out the list above, since most of it has been dealt with since and the comment reads as if none of it had.

Fixed here

define_var onto a global that captures or discards the value	89d573c
Shared sub-structures expanding without a bound	b624590
A __proto__ key becoming the prototype	62fd78b
The documentation saying things the code does not do	the README commit

The three code fixes are separate commits and each reverts on its own. The __proto__ one could not be a separate pull request: lib/quickjs/variables.rb does not exist on main, so there would be nothing for it to change. The same key through the C converter is untouched and stays open as #108.

Left deliberately, and the one thing still worth doing

The exception classes. Two unsupported inputs report the layer that noticed them rather than the contract the API advertises:

vm.define_const(:x, "\xff\xfe".b)             #=> JSON::GeneratorError
vm.define_const("abc".encode("UTF-16LE"), 1)  #=> Encoding::CompatibilityError

Both are unsupported values, and the README says unsupported values raise TypeError. It now documents them as they are rather than as they should be, which is honest but not the end state.

Kept out of the documentation pass on purpose: changing what a method raises is a behaviour change, and burying one in a commit that claims to be correcting prose is how a behaviour change gets shipped without being reviewed as one. It also wants a decision rather than a patch, since JSON::GeneratorError is arguably useful information that a bare TypeError would throw away, so the answer may be a TypeError that carries the original as its cause rather than a plain replacement.

Worth an issue once this lands, for the same reason the __proto__ fix could not be its own pull request: there is nothing on main to file it against yet.