qjs #

QuickJS bindings for Dart.

Quick Start #

import 'package:qjs/qjs.dart';

void main() {
  final rt = JSRuntime.create();

  // Evaluate expressions
  final result = rt.evaluateJavascript('2 + 2');
  print(result.asNumber); // 4.0

  // Pass variables via the global object
  rt.global['name'] = JSValue.string(rt, 'Dart');
  final greeting = rt.evaluateJavascript(r'`Hello, ${name}!`');
  print(greeting.asDartString); // Hello, Dart!

  // Call JavaScript functions
  final add = rt.evaluateJavascript('(a, b) => a + b').asObject.asFunction;
  final sum = add([JSValue.number(rt, 10), JSValue.number(rt, 25)]);
  print(sum.asNumber); // 35.0

  rt.release();
}

Runtime & Configuration #

JSRuntime #

JSRuntime manages an isolated JavaScript execution context and its native memory.

// Default configuration
final rt = JSRuntime.create();

// Custom configuration (e.g. sandbox memory limit of 64 MB and 512 KB stack)
final customRt = JSRuntime.create(const JSRuntimeConfig(
  memoryLimit: 64 * 1024 * 1024,
  maxStackSize: 512 * 1024,
  microtaskQueue: true,
));

// Hardened sandbox profile (disables eval/Proxy, limits memory to 64 MB)
final sandboxRt = JSRuntime.create(const JSRuntimeConfig.hardened());

customRt.release();
sandboxRt.release();

JSRuntimeConfig #

JSRuntimeConfig.hardened() disables eval and Proxy, and restricts memoryLimit to 64 MB and maxStackSize to 512 KB.

Code Evaluation #

evaluateJavascript #

Executes JavaScript source code. Provide sourceUrl to get meaningful stack traces when exceptions occur:

final result = rt.evaluateJavascript(
  '''
  function fib(n) {
    if (n <= 1) return n;
    return fib(n - 1) + fib(n - 2);
  }
  fib(10);
  ''',
  sourceUrl: 'math.js',
);

print(result.asNumber); // 55.0

Prepared JavaScript (Bytecode Preparation) #

Pre-compiles source code into bytecode to execute repeatedly without re-parsing overhead:

final script = rt.prepareJavaScript(
  'globalThis.counter = (globalThis.counter || 0) + 1;',
  sourceUrl: 'counter.js',
);

rt.evaluatePreparedJavaScript(script);
rt.evaluatePreparedJavaScript(script);

print(rt.global['counter'].asNumber); // 2.0

// Explicitly free compiled bytecode
script.release();

JavaScript Values #

JSValue is a handle to a native JavaScript value.

Type Checks and Conversions #

final numVal = JSValue.number(rt, 42);
final strVal = JSValue.string(rt, 'foo');
final boolVal = JSValue.boolean(rt, true);
final nullVal = JSValue.null_(rt);
final undefVal = JSValue.undefined(rt);

// Strict equality (===)
print(numVal.strictEquals(JSValue.number(rt, 42))); // true
print(numVal.strictEquals(strVal));                 // false

Objects & Properties #

JSObject #

Create and manipulate JavaScript objects:

final user = JSObject.create(rt);

// Index operator read/write
user['id'] = JSValue.number(rt, 1001);
user['name'] = JSValue.string(rt, 'Alice');

// Check properties
if (user.hasProperty('name')) {
  print(user['name'].asDartString); // Alice
}

// Enumerate property names
final names = user.getPropertyNames(); // JSArray
for (var i = 0; i < names.length; i++) {
  print(names[i].asDartString);
}

Property Descriptors & Accessors #

final obj = JSObject.create(rt);

// Read-only property
obj.defineProperty(
  'version',
  value: JSValue.string(rt, '1.0.0'),
  writable: false,
  enumerable: true,
  configurable: false,
);

// Getter & Setter backed by Dart
var internalState = 0;
obj.defineProperty(
  'count',
  get: JSFunction.createFromHostFunction(rt, (rt, thisValue, args) {
    return JSValue.number(rt, internalState.toDouble());
  }),
  set: JSFunction.createFromHostFunction(rt, (rt, thisValue, args) {
    internalState = args[0].asNumber.toInt();
    return JSValue.undefined(rt);
  }),
);

Object Freezing & Integrity #

final config = JSObject.create(rt)..['env'] = JSValue.string(rt, 'production');

config.preventExtensions(); // Disallow adding new properties
config.seal();              // Disallow adding/deleting properties
config.freeze();            // Make completely immutable

Custom Host Objects #

Implement JSHostObject to handle property accesses dynamically in Dart:

class StorageHostObject extends JSHostObject {
  final Map<String, JSValue> _storage = {};

  @override
  JSValue get(JSRuntime rt, JSPropNameId name) {
    return _storage[name.string] ?? JSValue.undefined(rt);
  }

  @override
  void set(JSRuntime rt, JSPropNameId name, JSValue value) {
    _storage[name.string] = value.retain();
  }

  @override
  List<JSPropNameId> getPropertyNames(JSRuntime rt) {
    return _storage.keys.map((k) => JSPropNameId.fromString(rt, k)).toList();
  }
}

final hostObj = JSObject.createFromHostObject(rt, StorageHostObject());
rt.global['storage'] = hostObj.asValue;

Arrays & Buffers #

JSArray #

final array = JSArray.create(rt)
  ..add(JSValue.number(rt, 10))
  ..add(JSValue.number(rt, 20));

print(array.length); // 2
print(array[0].asNumber); // 10.0

// Zero-copy live Dart List view (modifications sync both ways)
final List<JSValue> list = array.asList;
list.add(JSValue.number(rt, 30));
print(array.length); // 3

JSArrayBuffer #

JSArrayBuffer provides direct, zero-copy access to binary memory via Uint8List:

// Create a new 1 KB buffer
final buffer = JSArrayBuffer.create(rt, 1024);
buffer.data[0] = 0xAA;
buffer.data[1] = 0xBB;

// Create from existing Uint8List
final data = Uint8List.fromList([1, 2, 3, 4]);
final fromBytes = JSArrayBuffer.fromBytes(rt, data);

// Zero-copy read/write from JavaScript
rt.global['buf'] = buffer.asValue;
rt.evaluateJavascript('''
  const view = new Uint8Array(buf);
  view[2] = 0xCC;
''');

print(buffer.data[2]); // 204 (0xCC)

Functions & Host Interop #

Calling JavaScript Functions from Dart #

final multiply = rt.evaluateJavascript('(a, b) => a * b').asObject.asFunction;

// Direct invocation
final product = multiply([
  JSValue.number(rt, 6),
  JSValue.number(rt, 7),
]);
print(product.asNumber); // 42.0

// Constructor invocation (new Point(x, y))
final pointCtor = rt.evaluateJavascript(
  'function Point(x, y) { this.x = x; this.y = y; } Point;'
).asObject.asFunction;

final point = pointCtor.callAsConstructor([
  JSValue.number(rt, 5),
  JSValue.number(rt, 10),
]).asObject;

print(point['x'].asNumber); // 5.0

Registering Dart Functions in JavaScript #

final hostLog = JSFunction.createFromHostFunction(
  rt,
  (rt, thisValue, args) {
    final message = args.map((a) => a.isString ? a.asDartString : a.asNumber).join(' ');
    print('[Host] $message');
    return JSValue.undefined(rt);
  },
  name: 'nativeLog',
  length: 1,
);

rt.global['nativeLog'] = hostLog.asValue;
rt.evaluateJavascript('nativeLog("Item count:", 42);'); // [Host] Item count: 42

Async & Promises #

JSPromise.fromAsyncFunction #

Bridge Dart Future calls directly into JavaScript Promise:

final fetchData = JSFunction.createFromHostFunction(rt, (rt, thisValue, args) {
  return JSPromise.fromAsyncFunction(rt, () async {
    // Perform async Dart operation
    await Future<void>.delayed(const Duration(milliseconds: 100));
    return JSValue.string(rt, 'Response payload');
  });
});

rt.global['fetchData'] = fetchData.asValue;

rt.evaluateJavascript('''
  async function run() {
    const data = await fetchData();
    globalThis.result = data;
  }
  run();
''');

JSPromise.withResolvers #

Creates a promise along with separate resolve and reject functions (Promise.withResolvers()):

final (promise, resolve, reject) = JSPromise.withResolvers(rt);

rt.global['pendingPromise'] = promise;

// Resolve manually from Dart
resolve([JSValue.string(rt, 'Resolved from Dart!')]);

Microtask Queue #

When microtaskQueue: true is configured, drain pending promises explicitly:

final rt = JSRuntime.create(const JSRuntimeConfig(microtaskQueue: true));

rt.evaluateJavascript('''
  Promise.resolve().then(() => { globalThis.resolved = true; });
''');

// Process pending microtasks
rt.drainMicrotasks();
print(rt.global['resolved'].asBoolean); // true

rt.release();

Extensions #

Console Logging (JSConsole) #

Bridges JavaScript console.log, info, warn, error, and debug to package:logging:

import 'package:logging/logging.dart';
import 'package:qjs/qjs.dart';

final logger = Logger('QuickJS');
logger.onRecord.listen((rec) => print('[${rec.level.name}] ${rec.message}'));

final rt = JSRuntime.create();
JSConsole.install(rt, logger: logger);

rt.evaluateJavascript('console.warn("Watch out:", 404);');
// Output: [WARNING] Watch out: 404

Timers (JSTimers) #

Installs standard timer APIs (setTimeout, setInterval, clearTimeout, clearInterval, setImmediate):

final rt = JSRuntime.create();
final timers = JSTimers.install(rt);

rt.evaluateJavascript('''
  setTimeout(() => {
    globalThis.executed = true;
  }, 50);
''');

// Await until all scheduled timers resolve
await timers.resolved;
print(rt.global['executed'].asBoolean); // true

timers.release();
rt.release();

Error Handling #

Catching Errors from JavaScript #

When JavaScript code throws, Dart receives a JSException:

try {
  rt.evaluateJavascript('throw new TypeError("Invalid configuration");');
} on JSException catch (e) {
  print('Caught JS error: ${e.message}');
  print('Stack trace:\n${e.stack}');
  print('Error value: ${e.value}');
} on JSNativeException catch (e) {
  print('Engine internal exception: ${e.message}');
}

Creating Standard Errors in Dart #

final typeError = JSError.typeError(rt, 'Expected a string');
final rangeError = JSError.rangeError(rt, 'Index out of bounds');
final syntaxError = JSError.syntaxError(rt, 'Unexpected token');

// Throw into JS from host functions
throw JSException(typeError);

Memory Management #

Finalizers & Reference Counting #

• Automatic Cleanup: Every JSValue, JSObject, JSArray, and JSPreparedJavaScript registers with Dart's NativeFinalizer. When a Dart handle is garbage collected, the underlying native reference count is decremented automatically.
• Explicit Release: Call rt.release() when finished with a runtime to free all associated memory, global objects, and native contexts deterministically.
• Retaining Handles: Use value.retain() to increment the native reference count when sharing handles across asynchronous boundaries.

Weak References (JSWeakObject) #

Hold references to JavaScript objects without preventing garbage collection:

final obj = JSObject.create(rt);
final weakRef = JSWeakObject.create(rt, obj);

// Lock weak reference to obtain strong handle
final strongVal = weakRef.lock();
if (!strongVal.isUndefined) {
  print('Object is still alive');
}