quickjs_runtime library

A pure-Dart QuickJS JavaScript runtime on dart:ffi.

Wraps the vendored QuickJS 2024-01-13 sources and a C bridge with JSON-based marshaling: JS arguments are stringified to JSON in C, passed to a synchronous Dart callback, and the JSON result string is parsed back into a JS value.

Build the native library first:

tool/build_quickjs.sh   # produces native/quickjs/libquickjs_bridge.so

VM-only (dart:ffi); never import from a web-reachable path.

Classes

AsyncEnginePool
Pool of engine-worker isolates serving dispatched functions.
AsyncJobEnvelope
Completion envelope for one dispatched job.
AsyncJobRequest
One dispatched job as seen by the worker side.
The worker's view of the pool's mailbox protocol.
NodeCompatConfig
Consumer hooks and values for installNodeCompat.
NodeCompatHandle
Returned by installNodeCompat so the embedding can adjust per-script state after install (and tear the surface down with dispose).
QuickjsFfi
Low-level QuickJS FFI bindings.
QuickjsRuntime
A QuickJS JavaScript runtime with synchronous host callbacks.
TimerDrainStats
Stats from a NodeCompatHandle.drainTimers run.

Enums

TimerDrainMode
Timer draining strategy — see NodeCompatConfig.timerDrain.

Constants

asyncJobPrelude → const String
Main-engine bootstrap: runAsync / AsyncJob / runAsync.all.
asyncWorkerBootstrap → const String
Worker-engine bootstrap: materializes and runs one dispatched function.
nodeCompatBufferPrelude → const String
The Node.js Buffer surface for the compat layer, as one JS bootstrap.
nodeCompatFetchPrelude → const String
The sync fetch / Headers / Response surface for the compat layer, evaluated only when NodeCompatConfig.httpFetch is set.
nodeCompatPrelude → const String
The compat surface, as one JS bootstrap evaluated by installNodeCompat.
nodeCompatUrlPrelude → const String
The WHATWG URL / URLSearchParams subset for the compat layer.

Functions

installNodeCompat(QuickjsRuntime runtime, [NodeCompatConfig? config]) → NodeCompatHandle
Installs the compat layer onto runtime. Idempotent per runtime (reinstalling replaces the previous surface).
installNodeCompatModule(QuickjsRuntime runtime, String name, String? factory(String name)) → void
Registers (or replaces) one consumer-provided builtin module visible to the compat require (e.g. 'fs' mapped onto file tools).
runAsyncJobOnRuntime(QuickjsRuntime runtime, {required int jobId, required String fnSource, required String argsJson, String bootstrapFilename = '<jsr_worker_bootstrap>', String jobFilename = '<jsr_job>'}) → Map<String, dynamic>
Runs one dispatched function on runtime using the pool's calling convention and returns its completion envelope.

Typedefs

AsyncDispatchContext = Map<String, dynamic> Function()
Called synchronously at dispatch time on the submitting (main) isolate; its return value travels to the worker as AsyncJobRequest.context.
AsyncJobExecutor = Map<String, dynamic> Function(AsyncJobRequest request)
Worker-side job runner: runs one dispatched function on this worker's engines and returns the completion envelope.
AsyncWorkerMain = Future<void> Function(AsyncWorkerLink link)
Entry point of one worker isolate.