quickjswasi

README

go-quickjs-wasi-reactor

A Go module that embeds the QuickJS-NG WASI WebAssembly runtime (reactor model).

Related Projects

• js-quickjs-wasi-reactor - JavaScript/TypeScript harness for browser environments
• go-quickjs-wasi - Standard WASI command model with blocking _start() entry point
• paralin/quickjs - Fork with QJS_WASI_REACTOR build target (see QJS_WASI_REACTOR.md for design docs)
• QuickJS-NG reactor PR - Upstream PR for reactor support

Variants

This repository provides the reactor model WASM binary for re-entrant execution. If you only need simple blocking execution where QuickJS runs to completion in _start(), see the command model variant above.

About QuickJS-NG

QuickJS is a small and embeddable JavaScript engine. It aims to support the latest ECMAScript specification.

This project uses QuickJS-NG which is a fork of the original QuickJS project by Fabrice Bellard and Charlie Gordon, after it went dormant, with the intent of reigniting its development.

Purpose

This module provides easy access to the QuickJS-NG JavaScript engine compiled to WebAssembly with WASI support using the reactor model. The WASM binary is embedded directly in the Go module, making it easy to use QuickJS in Go applications without external dependencies.

Reactor Model

Unlike the standard WASI "command" model that blocks in _start(), the reactor model exports functions that the host calls, enabling re-entrant execution in JavaScript host environments (browsers, Node.js, Deno, Go with wazero, etc.).

The reactor exports:

• qjs_init() - Initialize empty runtime
• qjs_init_argv(argc, argv) - Initialize with CLI args (e.g. ["qjs", "--std", "script.js"])
• qjs_eval(code, len, filename, is_module) - Evaluate JS code from WASM memory
• qjs_loop_once() - Run one iteration of the event loop (non-blocking)
• qjs_destroy() - Cleanup runtime
• malloc/free - For host to allocate memory for code strings

Features

• Embeds the QuickJS-NG WASI reactor WebAssembly binary
• Provides version information about the embedded QuickJS release
• High-level Go API via the wazero-quickjs subpackage
• Automatic update script to fetch the latest QuickJS-NG reactor release

Packages

Root Package (github.com/aperturerobotics/go-quickjs-wasi-reactor)

Provides the embedded WASM binary and version information:

package main

import (
    "fmt"
    quickjswasi "github.com/aperturerobotics/go-quickjs-wasi-reactor"
)

func main() {
    // Access the embedded WASM binary
    wasmBytes := quickjswasi.QuickJSWASM
    fmt.Printf("QuickJS WASM size: %d bytes\n", len(wasmBytes))

    // Get version information
    fmt.Printf("QuickJS version: %s\n", quickjswasi.Version)
    fmt.Printf("Download URL: %s\n", quickjswasi.DownloadURL)
}

Wazero QuickJS Library (github.com/aperturerobotics/go-quickjs-wasi-reactor/wazero-quickjs)

High-level Go API for running JavaScript with wazero:

package main

import (
    "context"
    "embed"
    "os"

    quickjs "github.com/aperturerobotics/go-quickjs-wasi-reactor/wazero-quickjs"
    "github.com/tetratelabs/wazero"
)

//go:embed scripts
var scriptsFS embed.FS

func main() {
    ctx := context.Background()
    r := wazero.NewRuntime(ctx)
    defer r.Close(ctx)

    config := wazero.NewModuleConfig().
        WithStdout(os.Stdout).
        WithStderr(os.Stderr).
        WithFS(scriptsFS)  // Mount embedded filesystem

    qjs, _ := quickjs.NewQuickJS(ctx, r, config)
    defer qjs.Close(ctx)

    // Option 1: Initialize with CLI args to load script via WASI filesystem
    qjs.InitArgv(ctx, []string{"qjs", "--std", "scripts/main.js"})

    // Option 2: Initialize with std module and eval code directly
    // qjs.InitStdModule(ctx)
    // qjs.Eval(ctx, `console.log("Hello from QuickJS!");`, false)

    // Run event loop until idle
    qjs.RunLoop(ctx)
}

See the wazero-quickjs README for more details.

Command-Line REPL

A command-line JavaScript runner with interactive REPL mode is provided:

# Install
go install github.com/aperturerobotics/go-quickjs-wasi-reactor/wazero-quickjs/repl@master

# Interactive REPL
repl

# Run a JavaScript file
repl script.js

# Run as ES module
repl script.mjs --module

Updating

To update to the latest QuickJS-NG reactor release:

./update-quickjs.bash

This script will:

1. Fetch the latest release information from the paralin/quickjs GitHub repository
2. Download the qjs-wasi-reactor.wasm file
3. Generate version information constants

Testing

go test ./...
cd wazero-quickjs && go test ./...

License

This module is released under the same license as the embedded QuickJS-NG project.

MIT

Documentation

Index

• Constants
• Variables

Constants

const (
	// ExportInit is the function to initialize an empty QuickJS runtime.
	// Signature: qjs_init() -> i32 (0 on success)
	ExportInit = "qjs_init"

	// ExportInitArgv is the function to initialize QuickJS with CLI arguments.
	// This can be used to pass flags like --std or load scripts via WASI filesystem.
	// Signature: qjs_init_argv(argc: i32, argv: i32) -> i32 (0 on success)
	ExportInitArgv = "qjs_init_argv"

	// ExportEval is the function to evaluate JavaScript code.
	// Signature: qjs_eval(code: i32, len: i32, filename: i32, is_module: i32) -> i32
	// The filename parameter is a pointer to a null-terminated string (or 0 for default).
	ExportEval = "qjs_eval"

	// ExportLoopOnce runs one iteration of the event loop.
	// Signature: qjs_loop_once() -> i32
	// Returns:
	//   >0: next timer fires in N ms
	//    0: more microtasks pending, call again immediately
	//   -1: idle, no pending work
	//   -2: error occurred
	ExportLoopOnce = "qjs_loop_once"

	// ExportPollIO polls for I/O events and invokes registered read/write handlers.
	// This must be called when the host knows stdin (or other fds) have data available.
	// Signature: qjs_poll_io(timeout_ms: i32) -> i32
	// Parameters:
	//   timeout_ms: Poll timeout in milliseconds
	//     0 = non-blocking (check and return immediately)
	//     >0 = wait up to timeout_ms for I/O events
	//     -1 = block indefinitely (not recommended)
	// Returns:
	//   0: success (handler invoked or no handlers registered)
	//   -1: error or no I/O handlers
	//   -2: not initialized or exception in handler
	ExportPollIO = "qjs_poll_io"

	// ExportDestroy cleans up the QuickJS runtime.
	// Signature: qjs_destroy() -> void
	ExportDestroy = "qjs_destroy"

	// ExportMalloc allocates memory in WASM linear memory.
	// Signature: malloc(size: i32) -> i32 (pointer)
	ExportMalloc = "malloc"

	// ExportFree frees memory in WASM linear memory.
	// Signature: free(ptr: i32) -> void
	ExportFree = "free"
)

Reactor export function names

const (
	// LoopResultIdle indicates no pending work (-1)
	LoopResultIdle = -1
	// LoopResultError indicates an error occurred (-2)
	LoopResultError = -2
)

Loop result constants from qjs_loop_once()

const (
	// Version is the QuickJS-NG reactor version
	Version = "v0.11.0-wasi29-reactor-r3"
	// DownloadURL is the URL where this WASM file was downloaded from
	DownloadURL = "https://github.com/paralin/quickjs/releases/download/v0.11.0-wasi29-reactor-r3/qjs-wasi-reactor.wasm"
)

QuickJS-NG WASI Reactor version information

const QuickJSWASMFilename = "qjs-wasi.wasm"

QuickJSWASMFilename is the filename for QuickJSWASM.

Variables

var QuickJSWASM []byte

QuickJSWASM contains the binary contents of the QuickJS WASI reactor build.

This is a reactor-model WASM that exports functions for re-entrant execution in host environments. Unlike the command model which blocks in _start(), the reactor model allows the host to control execution flow.

Exported functions:

• qjs_init() - Initialize empty runtime
• qjs_init_argv(argc, argv) - Initialize with CLI args (e.g. ["qjs", "--std", "script.js"])
• qjs_eval(code, len, filename, is_module) - Evaluate JS code from WASM memory
• qjs_loop_once() - Run one iteration of the event loop (non-blocking)
• qjs_poll_io(timeout_ms) - Poll for I/O and invoke read/write handlers
• qjs_destroy() - Cleanup runtime
• malloc/free - For host to allocate memory for code strings

See: https://github.com/paralin/quickjs/tree/wasi-reactor