@thi.ng/wasm-api

This project is part of the @thi.ng/umbrella monorepo.

• About
  • Status
• Installation
• Dependencies
• API
• Authors
• License

About

Modular, extensible API bridge and generic glue code between JS & WebAssembly.

This package provides a small, generic and modular WasmBridge class as interop basis for hybrid JS/WebAssembly applications. At the moment only a basic core API is provided (i.e. for debug output, string & pointer handling), but in the future we aim to also supply support modules for DOM manipulation, WebGL, WebGPU, WebAudio etc.

In general, all languages with a WebAssembly target are supported, however currently only bindings for Zig are included.

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Installation

yarn add @thi.ng/wasm-api

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/wasm-api"></script>

Skypack documentation

For Node.js REPL:

# with flag only for < v16
node --experimental-repl-await

> const wasmApi = await import("@thi.ng/wasm-api");

Package sizes (gzipped, pre-treeshake): ESM: 1.08 KB

Dependencies

• @thi.ng/api
• @thi.ng/errors
• @thi.ng/hex
• @thi.ng/logger

API

Generated API docs

import { WasmBridge } from "@thi.ng/wasm-api";
import { readFileSync } from "fs";

// WASM exports from our dummy module (below)
interface App {
	memory: WebAssembly.Memory;
	start: () => void;
}

(async () => {
	const bridge = new WasmBridge();
	// instantiate WASM module using imports provided by the bridge
	const wasm = await WebAssembly.instantiate(
		readFileSync("hello.wasm"),
		bridge.getImports()
	);
	// cast WASM exports to our defined interface
	const app: App = <any>wasm.instance.exports;
	// init bindings & child APIs (if any)
	await bridge.init(app.memory);

	// call WASM function
	app.start();
})();

//! Example Zig application (hello.zig)

/// import externals
/// see build command for configuration
const js = @import("wasmapi");

export fn start() void {
	js.printStr("hello world!");
}

The WASM binary can be built via:

# compile WASM binary
zig build-lib \
  --pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/core.zig --pkg-end \
  -target wasm32-freestanding \
  -O ReleaseSmall -dynamic --strip \
  hello.zig

# disassemble WASM
wasm-dis -o hello.wast hello.wasm

The resulting WASM:

(module
 (type $i32_i32_=>_none (func (param i32 i32)))
 (type $none_=>_none (func))
 (import "env" "_printStr" (func $fimport$0 (param i32 i32)))
 (global $global$0 (mut i32) (i32.const 65536))
 (memory $0 2)
 (data (i32.const 65536) "hello world!\00\00\00\00\00\00\01\00\0c\00\00\00")
 (export "memory" (memory $0))
 (export "start" (func $0))
 (func $0
  (call $fimport$0
   (i32.const 65552)
   (i32.const 12)
  )
 )
)

Authors

Karsten Schmidt

If this project contributes to an academic publication, please cite it as:

@misc{thing-wasm-api,
  title = "@thi.ng/wasm-api",
  author = "Karsten Schmidt",
  note = "https://thi.ng/wasm-api",
  year = 2022
}

License

© 2022 Karsten Schmidt // Apache Software License 2.0