quickjs-rust

A Rust-native ECMAScript engine and embeddable bytecode runtime.

quickjs-rust is a Rust implementation of the ECMAScript language runtime. It includes a span-preserving lexer and parser, bytecode compiler, virtual machine, module linker, standard-library builtins, and a command-line host for local execution.

The current normative target is ECMA-262 16th edition, June 2025 (ECMAScript 2025 / ES2025), corresponding to the tc39/ecma262@es2025 specification tag. TC39 living-draft features are tracked separately from the default conformance baseline. Test262 does not publish edition-specific stable tags; this repository therefore pins a concrete Test262 commit and evaluates it against the ES2025 target and a pinned QuickJS-NG comparison baseline.

ECMAScript Conformance

Conformance is tracked with pinned Test262 inputs and differential checks against QuickJS-NG. CI runs Rust checks, QuickJS-NG comparison smoke tests, curated Test262 subsets, and a sharded full Test262 coverage workflow.

Full-scan snapshots are recorded under docs/conformance/burndown.jsonl, including the current pass counts and comparison details.

Active work is focused on production engineering, performance, broader specification coverage, Temporal, and TC39 draft features beyond ES2025.

Runtime Surface

The runtime supports:

• Script and module execution, including dynamic import() and top-level await.
• Lexical bindings, closures, classes, private names, generators, async functions, promises, regular expressions, destructuring, and Annex B behavior.
• Typed arrays, ArrayBuffer and SharedArrayBuffer behavior, and Atomics.
• Core standard-library objects including Object, Function, Array, Map, Set, WeakMap, WeakSet, String, Number, BigInt, Math, JSON, Date, RegExp, Promise, Reflect, Proxy, symbols, iterator helpers, and resource-management builtins.
• Structured lexer, parser, compile, and runtime errors. Tokens and syntax nodes preserve byte-offset spans for diagnostics.

Getting Started

Prebuilt qjs-rust CLI binaries are attached to GitHub Releases for macOS and Linux on x86_64 and arm64. Install the latest release with:

curl -fsSL https://raw.githubusercontent.com/Lewin671/quickjs-rust/main/install.sh | sh

Run the installer again to update an existing installation; use sh -s -- --help for version and destination options.

Then run:

qjs-rust --version
qjs-rust --raw -e 'JSON.stringify([1, 2, 3].toReversed())'
# [3,2,1]
qjs-rust

For source builds, install Rust with rustup, then:

git clone --recurse-submodules https://github.com/Lewin671/quickjs-rust.git
cd quickjs-rust
./scripts/bootstrap.sh   # initializes submodules if you forgot --recurse-submodules

Use the CLI for scripts, modules, or direct evaluation:

cargo run -p qjs-cli -- --raw -e 'JSON.stringify([1, 2, 3].toReversed())'
# [3,2,1]
cargo run -p qjs-cli -- --help
cargo run -p qjs-cli -- --interactive
cargo run -p qjs-cli -- --module path/to/module.mjs
cargo run -p qjs-cli -- path/to/script.js

The runtime crate exposes direct evaluation and bytecode entry points for embedding layers:

use qjs_runtime::{Value, eval};

fn main() -> Result<(), qjs_runtime::RuntimeError> {
    let value = eval("const x = 20 + 22; x")?;
    assert_eq!(value, Value::Number(42.0));
    Ok(())
}

Development

Run the standard local verification gate before submitting changes:

./scripts/check.sh

Additional harness commands are available for targeted conformance work:

./scripts/compare-qjs.sh                 # differential fixtures vs. pinned QuickJS-NG
./scripts/find-qjsng-gaps.sh             # discover comparison gaps against QuickJS-NG
./scripts/test262-subset.sh              # curated, deterministic Test262-derived cases
./scripts/test262-burndown.sh --help     # record full-scan conformance trend entries

See scripts/README.md for the full catalog and docs/harness.md for harness flags and behavior.

For deeper context, see docs/architecture.md for the runtime architecture.

License

This project is licensed under the MIT license.