flutter_qjs

This plugin is a simple js engine for flutter using the quickjs project with dart:ffi. Plugin currently supports all the platforms except web!

Getting Started

Basic usage

Firstly, create a FlutterQjs object, then call dispatch to dispatch event loop:

final engine = FlutterQjs(
  stackSize: 1024 * 1024, // change stack size here.
);
engine.dispatch();

Use evaluate method to run js script, now you can use it synchronously, or use await to resolve Promise:

try {
  print(engine.evaluate(code ?? ''));
} catch (e) {
  print(e.toString());
}

Method close can destroy quickjs runtime that can be recreated again if you call evaluate. Parameter port should be close to stop dispatch loop when you do not need it.

engine.port.close(); // stop dispatch loop
engine.close();      // close engine
engine = null;

Data conversion between dart and js are implemented as follow:

dart	js
Bool	boolean
Int	number
Double	number
String	string
Uint8List	ArrayBuffer
List	Array
Map	Object
Function	function(....args)
Future	Promise
Object	DartObject

notice: Dart function parameter thisVal is used to store this in js.

Set into global object

Method setToGlobalObject is presented to set dart object into global object. For example, you can pass a function implement http in JavaScript with Dio:

engine.setToGlobalObject("http", (String url) {
  return Dio().get(url).then((response) => response.data);
});

then, in java script you can use http function to invoke dart function:

http("http://example.com/");

Use modules

ES6 module with import function is supported and can be managed in dart with moduleHandler:

final engine = FlutterQjs(
  moduleHandler: (String module) {
    if(module == "hello")
      return "export default (name) => `hello \${name}!`;";
    throw Exception("Module Not found");
  },
);

then in JavaScript, import function is used to get modules:

import("hello").then(({default: greet}) => greet("world"));

notice: Module handler should be called only once for each module name. To reset the module cache, call FlutterQjs.close then evaluate again.

To use async function in module handler, try Run on isolate thread

Run on isolate thread

Create a IsolateQjs object, pass handlers to resolving modules. Async function such as rootBundle.loadString can be used now to get modules:

The methodHandler is used in isolate, so the handler function must be a top-level function or a static method.

dynamic methodHandler(String method, List arg) {
  switch (method) {
    case "http":
      return Dio().get(arg[0]).then((response) => response.data);
    default:
      throw Exception("No such method");
  }
}
final engine = IsolateQjs(
  methodHandler: methodHandler,
  moduleHandler: (String module) async {
    return await rootBundle.loadString(
        "js/" + module.replaceFirst(new RegExp(r".js$"), "") + ".js");
  },
);
// not need engine.dispatch();

Method setToGlobalObject is still here to set dart object into global object. Use await to make sure it is finished. Make sure the object that can pass through isolate, For example, a top level function:

dynamic http(String url) {
  return Dio().get(url).then((response) => response.data);
}
await engine.setToGlobalObject("http", http);

Same as run on main thread, use evaluate to run js script. In this way, Promise return by evaluate will be automatically tracked and return the resolved data:

try {
  print(await engine.evaluate(code ?? '', "<eval>"));
} catch (e) {
  print(e.toString());
}

Method close can destroy quickjs runtime that can be recreated again if you call evaluate.

This example contains a complete demonstration on how to use this plugin.

4.4 KiB Raw Blame History