@thi.ng/wasm-api

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

• About
  • Custom API modules
  • Object indices & handles
  • Data bindings & code generators
    • Data type definitions
    • Code generation
    • Example usage
  • Status
• Installation
• Dependencies
• API
• Basic usage example
  • Zig version
  • C11 version
• Authors
• License

About

Generic, modular, extensible API bridge, glue code and bindings code generator for hybrid JS & WebAssembly projects.

This package provides a the following:

1. A small, generic and modular WasmBridge class as interop basis and much reduced boilerplate for hybrid JS/WebAssembly applications.
2. A minimal core API for debug output, string, pointer, typed array accessors (8/16/32/64 bit (u)ints, 32/64 bit floats). In the future we aim to also supply support modules for DOM manipulation, WebGL, WebGPU, WebAudio etc.
3. Extensible shared datatype code generators for (currently) Zig & TypeScript. The latter also generates fully type checked memory-mapped accessors of WASM-side data. In general, all languages with a WebAssembly target are supported, however currently only bindings for these few langs are included.
4. Include files for C11 and Zig, defining imports for the JS core API defined by this package

Custom API modules

The WasmBridge is extensible via custom defined API modules. Such API extensions will consist of a collection of JS/TS functions & variables, their related counterparts (import definitions) for the WASM target and (optionally) some shared data types (bindings for which can be generated by this package too).

On the JS side, custom API modules can be easily integrated via the IWasmAPI interface. The following example provides a brief overview:

import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";

export class CustomAPI implements IWasmAPI {
	parent!: WasmBridge;

	async init(parent: WasmBridge) {
		this.parent = parent;
		this.parent.logger.debug("initializing custom API");

		// any other tasks you might need to do...

		return true;
	}

	/**
	 * Returns object of functions to import as externals into
	 * the WASM module. These imports are merged into a larger
	 * imports object alongside the bridge's core API...
	 */
	getImports(): WebAssembly.Imports {
		return {
			/**
			 * Writes 2 random float32 numbers to given address
			 */
			randomVec2: (addr: number) => {
				this.parent.f32.set(
					[Math.random(), Math.random()],
					addr >> 2
				);
			}
		};
	}
}

Now we can supply this custom API when creating the main WASM bridge:

export const bridge = new WasmBridge({ custom: new CustomAPI() });

In Zig (or any other language of your choice) we can then utilize this custom API like so (Please also see /test/index.ts` & the example further below in this readme):

// Import JS core API
const js = @import("wasmapi");

/// JS external to fill vec2 w/ random values
/// Note: Each API module uses a separate import object to avoid naming clashes
/// Here we declare an external binding belonging to the "custom" import group
extern "custom" fn randomVec2(addr: usize) void;

export fn test_randomVec2() void {
	var foo = [2]f32{ 0, 0 };

	// print original
	js.printF32Array(foo[0..]);

	// populate foo with random numbers
	randomVec2(@ptrToInt(&foo));

	// print result
	js.printF32Array(foo[0..]);
}

Object indices & handles

Since only numeric values can be exchanged between the WASM module and the JS host, any JS native objects the WASM side might want to be working with must be managed manually in JS. For this purpose the ObjectIndex class can be used by API modules to handle ID generation (incl. recycling, using @thi.ng/idgen) and the indexing of different types of JS objects/values. Only the numeric IDs (handles) will then need to be exchanged with the WASM module...

import { ObjectIndex } from "@thi.ng/wasm-api";

const canvases = new ObjectIndex<HTMLCanvasElement>({ name: "canvas" });

// index item and assign new ID
canvases.add(document.createElement("canvas"));
// 0

// look up item by ID
canvases.get(0);
// <canvas ...>

// work w/ retrieved item
canvases.get(0).id = "foo";

// check if item for ID exists (O(1))
canvases.has(1)
// false

// by default invalid IDs throw error
canvases.get(1)
// Uncaught Error: Assertion failed: missing canvas for ID: 2

// error can be disabled via 2nd arg
canvases.get(1, false)
// undefined

// find ID using custom predicate (same failure behavior as .get())
canvases.find((x) => x.id == "bar")
// Uncaught Error: Assertion failed: given predicate matched no canvas

canvases.delete(0);
// true

Data bindings & code generators

The package provides an extensible codegeneration framework to simplify the bilateral design & exchange of data structures shared between the WASM & JS host env. Currently, code generators for TypeScript & Zig are supplied (more are planned). A CLI wrapper is worked on too.

Data type definitions

TODO

Struct

Enum

Code generation

TODO

Example usage

TODO

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: 3.98 KB

IMPORTANT: The package includes various code generators and supporting functions which are NOT required during runtime. Hence the actual package size in production will be MUCH smaller!

Dependencies

• @thi.ng/api
• @thi.ng/binary
• @thi.ng/checks
• @thi.ng/compare
• @thi.ng/defmulti
• @thi.ng/errors
• @thi.ng/hex
• @thi.ng/idgen
• @thi.ng/logger

API

Generated API docs

Basic usage example

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

// WASM exports from our dummy module (below)
interface App extends WasmExports {
	start: () => void;
}

(async () => {
	// new API bridge with defaults
	// (i.e. no child API modules and using console logger)
	const bridge = new WasmBridge<App>();

	// instantiate WASM module using imports provided by the bridge
	// this also initializes any bindings & bridge child APIs (if any)
	// (also accepts a fetch() `Response` as input)
	await bridge.instantiate(readFileSync("hello.wasm"));

	// call an exported WASM function
	bridge.exports.start();
})();

Zig version

Requires Zig to be installed:

//! Example Zig application (hello.zig)

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

// set custom memory allocator (here to disable)
pub const WASM_ALLOCATOR: ?std.mem.Allocator = null;

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

The WASM binary can be built using the following command (or for more complex scenarios add the supplied .zig file(s) to your build.zig and/or source folder):

# compile WASM binary
zig build-lib \
	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/include/wasmapi.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))
 (type $i32_=>_i32 (func (param i32) (result i32)))
 (import "wasmapi" "_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")
 (export "memory" (memory $0))
 (export "start" (func $0))
 (export "_wasm_allocate" (func $1))
 (export "_wasm_free" (func $2))
 (func $0
  (call $fimport$0
   (i32.const 65536)
   (i32.const 12)
  )
 )
 (func $1 (param $0 i32) (result i32)
  (i32.const 0)
 )
 (func $2 (param $0 i32) (param $1 i32)
 )
)

C11 version

Requires Emscripten to be installed:

#include <wasmapi.h>

void WASM_KEEP start() {
	wasm_printStr0("hello world!");
}

Building the WASM module:

emcc -Os -Inode_modules/@thi.ng/wasm-api/include -DWASMAPI_NO_MALLOC \
  -sERROR_ON_UNDEFINED_SYMBOLS=0 --no-entry \
  -o hello.wasm hello.c

Resulting WASM:

(module
 (type $i32_=>_none (func (param i32)))
 (type $none_=>_none (func))
 (type $i32_=>_i32 (func (param i32) (result i32)))
 (type $none_=>_i32 (func (result i32)))
 (import "wasmapi" "_printStr0" (func $fimport$0 (param i32)))
 (global $global$0 (mut i32) (i32.const 5243936))
 (memory $0 256 256)
 (data (i32.const 1024) "hello world!")
 (table $0 2 2 funcref)
 (elem (i32.const 1) $0)
 (export "memory" (memory $0))
 (export "_wasm_allocate" (func $1))
 (export "_wasm_free" (func $2))
 (export "start" (func $3))
 (export "__indirect_function_table" (table $0))
 (export "_initialize" (func $0))
 (export "__errno_location" (func $7))
 (export "stackSave" (func $4))
 (export "stackRestore" (func $5))
 (export "stackAlloc" (func $6))
 (func $0
  (nop)
 )
 (func $1 (param $0 i32) (result i32)
  (i32.const 0)
 )
 (func $2 (param $0 i32)
  (nop)
 )
 (func $3
  (call $fimport$0
   (i32.const 1024)
  )
 )
 (func $4 (result i32)
  (global.get $global$0)
 )
 (func $5 (param $0 i32)
  (global.set $global$0
   (local.get $0)
  )
 )
 (func $6 (param $0 i32) (result i32)
  (global.set $global$0
   (local.tee $0
    (i32.and
     (i32.sub
      (global.get $global$0)
      (local.get $0)
     )
     (i32.const -16)
    )
   )
  )
  (local.get $0)
 )
 (func $7 (result i32)
  (i32.const 1040)
 )
)

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