icemic / quickjspp-rs

A rusty QuickJS (QuickJS-NG) Javascript engine wrapper, and more.

QuickJS is a small and embeddable Javascript engine by Fabrice Bellard and Charlie Gordon. It supports the ES2023 specification including modules, asynchronous generators, proxies and BigInt.
Quickjs-NG is one of the most active forks of QuickJS, and it is maintained by the community focused on reigniting the project.

This crate allows you to easily access and use all the features of QuickJS from Rust. It also provides robust Rust-JS type conversion and interoperability capabilities.

Quickstart

[dependencies]
quickjs-rusty = "0.6.0"

use quickjs_rusty::{Context, JsValue};

let context = Context::new().unwrap();

// Eval.

let value = context.eval("1 + 2").unwrap();
assert_eq!(value, JsValue::Int(3));

let value = context.eval_as::<String>(" var x = 100 + 250; x.toString() ").unwrap();
assert_eq!(&value, "350");

// Callbacks.

context.add_callback("myCallback", |a: i32, b: i32| a + b).unwrap();

context.eval(r#"
    // x will equal 30
    var x = myCallback(10, 20);
"#).unwrap();

Note: This project is derived from quickjs-rs, but it has undergone significant restructuring. It features a completely different code structure and functional design compared to the original project.

Optional Features

The crate supports the following features:

• serde: (default enabled). enable serde method from_js and to_js to transform between Rust types and js value in quickjs context. It should compatible with serde_json but not tested yet. See more on the example.
• chrono: (default enabled). chrono integration
  • adds a JsValue::Date variant that can be (de)serialized to/from a JS Date
• bigint: (default enabled). arbitrary precision integer support via num-bigint

Installation

By default, quickjs is bundled with the libquickjs-sys crate and automatically compiled, assuming you have the appropriate dependencies.

Windows Support

quickjspp-rs can be used under target x86_64-pc-windows-msvc,

System installation

To use the system installation, without the bundled feature, first install the required dependencies, and then compile and install quickjspp.

You then need to disable the bundled feature in the libquickjs-sys crate to force using the system version.

quickjspp-rs's Issues

Catch up the latest quickjs, or quickjs-ng?

Currently, we're utilizing a forked version of QuickJS, aka quickjspp, as opposed to the original QuickJS. The original version has received numerous updates that significantly enhance its compatibility with ES2023 recently.

Our choice to use quickjspp is primarily due to its support for MSVC compilation. However, there's a concern that if quickjspp doesn't keep up with the latest updates from the original repository, we might fall behind as well. It raises the question of whether it's time to consider other options.

To be frank, the current ecosystem is somewhat perplexing, with multiple versions of quickjs in existence, including Bellard's original and several forks:

• Bellard's original version https://github.com/bellard/quickjs, tons of updates recently. Let's simply refer to it as quickjs.
• The version we are currently utilizing, c-smile's fork, also known as quickjspp https://github.com/c-smile/quickjspp, the one we are using
• quickjs-ng, termed the next generation https://github.com/quickjs-ng/quickjs
• some other forks, but not not widely used

It seems that quickjs-ng is the one we shall choose and txiki.js has chosen it. This fork version came up just before Bellard committed the recent updates, so now, it seems a little awkward.
I can not figure out the future of quickjs-ng or quickjs, will they merge together or develop separately?

The most important, both of them have not supported MSVC yet, though there are some discussion on quickjs-ng

I will keep monitoring their progress and update accordingly.