@thi.ng/wasm-api 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-01T22:09:32Z
+- **Last updated**: 2022-08-07T15:28:01Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,32 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.4.0) (2022-08-07)
+
+#### 🚀 Features
+
+- use named import objects ([4965f20](https://github.com/thi-ng/umbrella/commit/4965f20))
+  - switch to name import objects to avoid merging into flat namespace
+  - update externs in core.zig
+  - update docstrings
+
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.3.0) (2022-08-04)
+
+#### 🚀 Features
+
+- add i64/u64 support/accessors ([768c8bd](https://github.com/thi-ng/umbrella/commit/768c8bd))
+- add WasmBridge.instantiate, add/update accessors ([0698bae](https://github.com/thi-ng/umbrella/commit/0698bae))
+  - add WasmBridge.instantiate() boilerplate
+  - add setters for typed scalars & arrays
+  - rename derefXX() => getXX() getters
+  - update tests
+- major update WasmBridge, add types ([47aa222](https://github.com/thi-ng/umbrella/commit/47aa222))
+  - add WasmExports base interface
+  - add generics for WasmBridge & IWasmAPI
+  - update WasmBridge.init() arg (full WASM exports, not just mem)
+  - add WasmBridge.exports field to store WASM module exports
+  - add naming conflict check in WasmBridge.getImports()
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.2.0) (2022-08-01)
 
 #### 🚀 Features

package/README.md

@@ -25,9 +25,10 @@ Modular, extensible API bridge and generic glue code between JS & WebAssembly.
 
 This package provides a small, generic and modular
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
-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
+class as interop basis and a much reduced boilerplate for hybrid JS/WebAssembly
+applications. At the moment only a minimal core API is provided (i.e. for debug
+output, string, pointer, typed array accessors [8/16/32/64 bit (u)ints, 32/64
+bit floats]), 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
@@ -56,15 +57,15 @@ export class CustomAPI implements IWasmAPI {
 
 	/**
 	 * Returns object of functions to import as externals into
-	 * the WASM module. These imports are merged with the bridge's
-	 * core API and hence should use naming prefixes...
+	 * 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
 			 */
-			custom_randomVec2: (addr: number) => {
+			randomVec2: (addr: number) => {
 				this.parent.f32.set(
 					[Math.random(), Math.random()],
 					addr >> 2
@@ -82,25 +83,29 @@ 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 (also see example further below in this readme):
+API like so (Please also see /test/index.ts` & the example further below in this
+readme):
 
 ```zig
+// Import JS core API
 const js = @import("wasmapi");
 
 /// JS external to fill vec2 w/ random values
-extern fn custom_randomVec2(addr: usize) void;
+/// 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 };
+	var foo = [2]f32{ 0, 0 };
 
 	// print original
-    js.printF32Array(foo[0..]);
+	js.printF32Array(foo[0..]);
 
 	// populate foo with random numbers
-    custom_randomVec2(@ptrToInt(&foo));
+	randomVec2(@ptrToInt(&foo));
 
 	// print result
-    js.printF32Array(foo[0..]);
+	js.printF32Array(foo[0..]);
 }
 ```
 
@@ -180,7 +185,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.21 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.61 KB
 
 ## Dependencies
 
@@ -195,34 +200,26 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.21 KB
 [Generated API docs](https://docs.thi.ng/umbrella/wasm-api/)
 
 ```ts
-import { WasmBridge } from "@thi.ng/wasm-api";
+import { WasmBridge, WasmExports } from "@thi.ng/wasm-api";
 import { readFileSync } from "fs";
 
 // WASM exports from our dummy module (below)
-interface App {
-	memory: WebAssembly.Memory;
+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();
+	const bridge = new WasmBridge<App>();
 
 	// instantiate WASM module using imports provided by the bridge
-	const wasm = await WebAssembly.instantiate(
-		readFileSync("hello.wasm"),
-		bridge.getImports()
-	);
+	// this also initializes any bindings & bridge child APIs (if any)
+	// (also accepts a fetch() `Response` as input)
+	await bridge.instantiate(readFileSync("hello.wasm"));
 
-	// 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 a WASM function
-	app.start();
+	// call an exported WASM function
+	bridge.exports.start();
 })();
 ```
 
@@ -238,16 +235,17 @@ export fn start() void {
 }
 ```
 
-The WASM binary can be built via (for more complex scenarios add the supplied
-.zig file(s) to your `build.zig` and/or source folder):
+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):
 
 ```bash
 # 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
+	--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
@@ -259,7 +257,7 @@ 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)))
+ (import "core" "_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")

package/api.d.ts

@@ -1,10 +1,15 @@
-import type { Fn } from "@thi.ng/api";
+import type { Fn, Fn2 } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
+export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
 /**
  * Common interface for WASM/JS child APIs which will be used in combination
  * with a parent {@link WasmBridge}.
+ *
+ * @remarks
+ * The generic type param is optional and only used if the API is requiring
+ * certain exports declared by WASM module.
  */
-export interface IWasmAPI {
+export interface IWasmAPI<T extends WasmExports = WasmExports> {
     /**
      * Called by {@link WasmBridge.init} to initialize all child APIs (async)
      * after the WASM module has been instantiated. If the method returns false
@@ -12,7 +17,7 @@ export interface IWasmAPI {
      *
      * @param parent
      */
-    init(parent: WasmBridge): Promise<boolean>;
+    init(parent: WasmBridge<T>): Promise<boolean>;
     /**
      * Returns an object of this child API's declared WASM imports. Be aware
      * imports from all child APIs will be merged into a single flat namespace,
@@ -20,7 +25,30 @@ export interface IWasmAPI {
      */
     getImports(): WebAssembly.ModuleImports;
 }
-export interface CoreAPI {
+/**
+ * Base interface of exports declared by the WASM module. At the very least, the
+ * module needs to export its memory.
+ *
+ * @remarks
+ * This interface is supposed to be extended with the concrete exports defined
+ * by your WASM module and is used as generic type param for {@link WasmBridge}
+ * and any {@link IWasmAPI} bridge modules. These exports can obtained via
+ * {@link WasmBridge.exports} where they will be stored during the execution of
+ * {@link WasmBridge.init}.
+ */
+export interface WasmExports {
+    /**
+     * The WASM module's linear memory buffer. The `WasmBridge` automatically
+     * creates various typed views of that memory.
+     */
+    memory: WebAssembly.Memory;
+}
+/**
+ * Core API of WASM imports defined by the {@link WasmBridge}. The same
+ * functions are declared as bindings in `/zig/core.zig`. Also see this file for
+ * documentation of each function...
+ */
+export interface CoreAPI extends WebAssembly.ModuleImports {
     printI8: Fn<number, void>;
     printU8: Fn<number, void>;
     printU8Hex: Fn<number, void>;
@@ -30,6 +58,9 @@ export interface CoreAPI {
     printI32: Fn<number, void>;
     printU32: Fn<number, void>;
     printU32Hex: Fn<number, void>;
+    _printI64: Fn2<number, number, void>;
+    _printU64: Fn2<number, number, void>;
+    _printU64Hex: Fn2<number, number, void>;
     printF32: Fn<number, void>;
     printF64: Fn<number, void>;
     _printI8Array: (addr: number, len: number) => void;
@@ -38,6 +69,8 @@ export interface CoreAPI {
     _printU16Array: (addr: number, len: number) => void;
     _printI32Array: (addr: number, len: number) => void;
     _printU32Array: (addr: number, len: number) => void;
+    _printI64Array: (addr: number, len: number) => void;
+    _printU64Array: (addr: number, len: number) => void;
     _printF32Array: (addr: number, len: number) => void;
     _printF64Array: (addr: number, len: number) => void;
     _printStr0: (addr: number) => void;

package/bridge.d.ts

@@ -1,7 +1,24 @@
+import type { NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import type { CoreAPI, IWasmAPI } from "./api.js";
-export declare class WasmBridge {
-    modules: Record<string, IWasmAPI>;
+import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports } from "./api.js";
+/**
+ * The main interop API bridge between the JS host environment and a WebAssembly
+ * module. This class provides a small core API with various typed accessors and
+ * utils to exchange data (scalars, arrays, strings etc.) via the WASM module's
+ * memory.
+ *
+ * @remarks
+ * All typed memory accessors are assuming the given lookup addresses are
+ * properly aligned to the corresponding primitive types (e.g. f32 values are
+ * aligned to 4 byte boundaries, f64 to 8 bytes etc.) Unaligned access is
+ * explicitly **not supported**! If you need such, please refer to other
+ * mechanisms like JS `DataView`...
+ *
+ * 64bit integers are handled via JS `BigInt` and hence require the host env to
+ * support it. No polyfill is provided.
+ */
+export declare class WasmBridge<T extends WasmExports = WasmExports> {
+    modules: Record<string, IWasmAPI<T>>;
     logger: ILogger;
     i8: Int8Array;
     u8: Uint8Array;
@@ -9,60 +26,114 @@ export declare class WasmBridge {
     u16: Uint16Array;
     i32: Int32Array;
     u32: Uint32Array;
+    i64: BigInt64Array;
+    u64: BigUint64Array;
     f32: Float32Array;
     f64: Float64Array;
     utf8Decoder: TextDecoder;
     utf8Encoder: TextEncoder;
+    imports: WebAssembly.Imports;
+    exports: T;
     core: CoreAPI;
-    constructor(modules?: Record<string, IWasmAPI>, logger?: ILogger);
-    init(mem: WebAssembly.Memory): Promise<boolean>;
+    constructor(modules?: Record<string, IWasmAPI<T>>, logger?: ILogger);
     /**
-     * Returns object of all WASM imports declared in the bridge core API and
-     * any provided child APIs.
+     * Instantiates WASM module from given `src` (and optional provided extra
+     * imports), then automatically calls {@link WasmBridge.init} with the
+     * modules exports.
+     *
+     * @remarks
+     * If the given `src` is a `Response` or `Promise<Response>`, the module
+     * will be instantiated via `WebAssembly.instantiateStreaming()`, otherwise
+     * the non-streaming version will be used.
+     *
+     * @param src
+     * @param imports
      */
-    getImports(): {
-        env: {
-            printI8: import("@thi.ng/api").Fn<number, void>;
-            printU8: import("@thi.ng/api").Fn<number, void>;
-            printU8Hex: import("@thi.ng/api").Fn<number, void>;
-            printI16: import("@thi.ng/api").Fn<number, void>;
-            printU16: import("@thi.ng/api").Fn<number, void>;
-            printU16Hex: import("@thi.ng/api").Fn<number, void>;
-            printI32: import("@thi.ng/api").Fn<number, void>;
-            printU32: import("@thi.ng/api").Fn<number, void>;
-            printU32Hex: import("@thi.ng/api").Fn<number, void>;
-            printF32: import("@thi.ng/api").Fn<number, void>;
-            printF64: import("@thi.ng/api").Fn<number, void>;
-            _printI8Array: (addr: number, len: number) => void;
-            _printU8Array: (addr: number, len: number) => void;
-            _printI16Array: (addr: number, len: number) => void;
-            _printU16Array: (addr: number, len: number) => void;
-            _printI32Array: (addr: number, len: number) => void;
-            _printU32Array: (addr: number, len: number) => void;
-            _printF32Array: (addr: number, len: number) => void;
-            _printF64Array: (addr: number, len: number) => void;
-            _printStr0: (addr: number) => void;
-            _printStr: (addr: number, len: number) => void;
-        };
-    };
-    getI8Array(ptr: number, len: number): Int8Array;
-    getU8Array(ptr: number, len: number): Uint8Array;
-    getI16Array(ptr: number, len: number): Int16Array;
-    getU16Array(ptr: number, len: number): Uint16Array;
-    getI32Array(ptr: number, len: number): Int32Array;
-    getU32Array(ptr: number, len: number): Uint32Array;
-    getF32Array(ptr: number, len: number): Float32Array;
-    getF64Array(ptr: number, len: number): Float64Array;
-    derefI8(ptr: number): number;
-    derefU8(ptr: number): number;
-    derefI16(ptr: number): number;
-    derefU16(ptr: number): number;
-    derefI32(ptr: number): number;
-    derefU32(ptr: number): number;
-    derefF32(ptr: number): number;
-    derefF64(ptr: number): number;
+    instantiate(src: Response | BufferSource | PromiseLike<Response | BufferSource>, imports?: WebAssembly.Imports): Promise<boolean>;
+    /**
+     * Receives the WASM module's exports, stores the for future reference and
+     * then initializes all declared bridge child API modules. Returns false if
+     * any of the module initializations failed.
+     *
+     * @param exports
+     */
+    init(exports: T): Promise<boolean>;
+    /**
+     * Required use for WASM module instantiation to provide JS imports to the
+     * module. Returns an object of all WASM imports declared by the bridge core
+     * API and any provided bridge API modules.
+     *
+     * @remarks
+     * Since v0.4.0 each API module's imports will be in their own WASM import
+     * table, named using the same key which was assigned to the module when
+     * creating the WASM bridge.
+     *
+     * @example
+     * The following creates a bridge with a fictional `custom` API module:
+     *
+     * ```ts
+     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     *
+     * // get combined imports object
+     * bridge.getImports();
+     * {
+     *   // imports defined by the core API of the bridge itself
+     *   core: { ... },
+     *   // imports defined by the CustomAPI module
+     *   custom: { ... }
+     * }
+     * ```
+     *
+     * Any related API bindings on the WASM (Zig) side then also need to refer
+     * to these custom import sections (also see `/zig/core.zig`):
+     *
+     * ```zig
+     * pub export "custom" fn foo(x: u32) void;
+     * ```
+     */
+    getImports(): WebAssembly.Imports;
+    getI8(addr: number): number;
+    getU8(addr: number): number;
+    getI16(addr: number): number;
+    getU16(addr: number): number;
+    getI32(addr: number): number;
+    getU32(addr: number): number;
+    getI64(addr: number): bigint;
+    getU64(addr: number): bigint;
+    getF32(addr: number): number;
+    getF64(addr: number): number;
+    setI8(addr: number, x: number): this;
+    setU8(addr: number, x: number): this;
+    setI16(addr: number, x: number): this;
+    setU16(addr: number, x: number): this;
+    setI32(addr: number, x: number): this;
+    setU32(addr: number, x: number): this;
+    setI64(addr: number, x: bigint): this;
+    setU64(addr: number, x: bigint): this;
+    setF32(addr: number, x: number): this;
+    setF64(addr: number, x: number): this;
+    getI8Array(addr: number, len: number): Int8Array;
+    getU8Array(addr: number, len: number): Uint8Array;
+    getI16Array(addr: number, len: number): Int16Array;
+    getU16Array(addr: number, len: number): Uint16Array;
+    getI32Array(addr: number, len: number): Int32Array;
+    getU32Array(addr: number, len: number): Uint32Array;
+    getI64Array(addr: number, len: number): BigInt64Array;
+    getU64Array(addr: number, len: number): BigUint64Array;
+    getF32Array(addr: number, len: number): Float32Array;
+    getF64Array(addr: number, len: number): Float64Array;
+    setI8Array(addr: number, buf: NumericArray): this;
+    setU8Array(addr: number, buf: NumericArray): this;
+    setI16Array(addr: number, buf: NumericArray): this;
+    setU16Array(addr: number, buf: NumericArray): this;
+    setI32Array(addr: number, buf: NumericArray): this;
+    setU32Array(addr: number, buf: NumericArray): this;
+    setI64Array(addr: number, buf: BigIntArray): this;
+    setU64Array(addr: number, buf: BigIntArray): this;
+    setF32Array(addr: number, buf: NumericArray): this;
+    setF64Array(addr: number, buf: NumericArray): this;
     getString(addr: number, len?: number): string;
-    getElementById(addr: number, len?: number): HTMLElement | null;
     setString(str: string, addr: number, maxBytes: number, terminate?: boolean): number;
+    getElementById(addr: number, len?: number): HTMLElement;
 }
 //# sourceMappingURL=bridge.d.ts.map

package/bridge.js

@@ -1,6 +1,23 @@
-import { assert } from "@thi.ng/errors/assert";
-import { U16, U32, U8 } from "@thi.ng/hex";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { U16, U32, U64HL, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
+const B32 = BigInt(32);
+/**
+ * The main interop API bridge between the JS host environment and a WebAssembly
+ * module. This class provides a small core API with various typed accessors and
+ * utils to exchange data (scalars, arrays, strings etc.) via the WASM module's
+ * memory.
+ *
+ * @remarks
+ * All typed memory accessors are assuming the given lookup addresses are
+ * properly aligned to the corresponding primitive types (e.g. f32 values are
+ * aligned to 4 byte boundaries, f64 to 8 bytes etc.) Unaligned access is
+ * explicitly **not supported**! If you need such, please refer to other
+ * mechanisms like JS `DataView`...
+ *
+ * 64bit integers are handled via JS `BigInt` and hence require the host env to
+ * support it. No polyfill is provided.
+ */
 export class WasmBridge {
     constructor(modules = {}, logger = new ConsoleLogger("wasm")) {
         this.modules = modules;
@@ -17,8 +34,11 @@ export class WasmBridge {
             printU16: logN,
             printU16Hex: (x) => this.logger.debug(`0x${U16(x)}`),
             printI32: logN,
-            printU32: logN,
+            printU32: (x) => this.logger.debug(x >>> 0),
             printU32Hex: (x) => this.logger.debug(`0x${U32(x)}`),
+            _printI64: (hi, lo) => this.logger.debug((BigInt(hi) << B32) | BigInt(lo)),
+            _printU64: (hi, lo) => this.logger.debug((BigInt(hi >>> 0) << B32) | BigInt(lo >>> 0)),
+            _printU64Hex: (hi, lo) => this.logger.debug(`0x${U64HL(hi, lo)}`),
             printF32: logN,
             printF64: logN,
             _printI8Array: logA(this.getI8Array.bind(this)),
@@ -27,21 +47,55 @@ export class WasmBridge {
             _printU16Array: logA(this.getU16Array.bind(this)),
             _printI32Array: logA(this.getI32Array.bind(this)),
             _printU32Array: logA(this.getU32Array.bind(this)),
+            _printI64Array: logA(this.getI64Array.bind(this)),
+            _printU64Array: logA(this.getU64Array.bind(this)),
             _printF32Array: logA(this.getF32Array.bind(this)),
             _printF64Array: logA(this.getF64Array.bind(this)),
             _printStr0: (addr) => this.logger.debug(this.getString(addr, 0)),
             _printStr: (addr, len) => this.logger.debug(this.getString(addr, len)),
         };
     }
-    async init(mem) {
-        this.i8 = new Int8Array(mem.buffer);
-        this.u8 = new Uint8Array(mem.buffer);
-        this.i16 = new Int16Array(mem.buffer);
-        this.u16 = new Uint16Array(mem.buffer);
-        this.i32 = new Int32Array(mem.buffer);
-        this.u32 = new Uint32Array(mem.buffer);
-        this.f32 = new Float32Array(mem.buffer);
-        this.f64 = new Float64Array(mem.buffer);
+    /**
+     * Instantiates WASM module from given `src` (and optional provided extra
+     * imports), then automatically calls {@link WasmBridge.init} with the
+     * modules exports.
+     *
+     * @remarks
+     * If the given `src` is a `Response` or `Promise<Response>`, the module
+     * will be instantiated via `WebAssembly.instantiateStreaming()`, otherwise
+     * the non-streaming version will be used.
+     *
+     * @param src
+     * @param imports
+     */
+    async instantiate(src, imports) {
+        const $src = await src;
+        const $imports = { ...this.getImports(), ...imports };
+        const wasm = await ($src instanceof Response
+            ? WebAssembly.instantiateStreaming($src, $imports)
+            : WebAssembly.instantiate($src, $imports));
+        return this.init(wasm.instance.exports);
+    }
+    /**
+     * Receives the WASM module's exports, stores the for future reference and
+     * then initializes all declared bridge child API modules. Returns false if
+     * any of the module initializations failed.
+     *
+     * @param exports
+     */
+    async init(exports) {
+        this.exports = exports;
+        const buf = exports.memory.buffer;
+        this.i8 = new Int8Array(buf);
+        this.u8 = new Uint8Array(buf);
+        this.i16 = new Int16Array(buf);
+        this.u16 = new Uint16Array(buf);
+        this.i32 = new Int32Array(buf);
+        this.u32 = new Uint32Array(buf);
+        this.i64 = new BigInt64Array(buf);
+        this.u64 = new BigUint64Array(buf);
+        this.f32 = new Float32Array(buf);
+        this.f64 = new Float64Array(buf);
         for (let id in this.modules) {
             this.logger.debug(`initializing API module: ${id}`);
             const status = await this.modules[id].init(this);
@@ -51,87 +105,217 @@ export class WasmBridge {
         return true;
     }
     /**
-     * Returns object of all WASM imports declared in the bridge core API and
-     * any provided child APIs.
+     * Required use for WASM module instantiation to provide JS imports to the
+     * module. Returns an object of all WASM imports declared by the bridge core
+     * API and any provided bridge API modules.
+     *
+     * @remarks
+     * Since v0.4.0 each API module's imports will be in their own WASM import
+     * table, named using the same key which was assigned to the module when
+     * creating the WASM bridge.
+     *
+     * @example
+     * The following creates a bridge with a fictional `custom` API module:
+     *
+     * ```ts
+     * const bridge = new WasmBridge({ custom: new CustomAPI() });
+     *
+     * // get combined imports object
+     * bridge.getImports();
+     * {
+     *   // imports defined by the core API of the bridge itself
+     *   core: { ... },
+     *   // imports defined by the CustomAPI module
+     *   custom: { ... }
+     * }
+     * ```
+     *
+     * Any related API bindings on the WASM (Zig) side then also need to refer
+     * to these custom import sections (also see `/zig/core.zig`):
+     *
+     * ```zig
+     * pub export "custom" fn foo(x: u32) void;
+     * ```
      */
     getImports() {
-        const env = { ...this.core };
-        for (let id in this.modules) {
-            Object.assign(env, this.modules[id].getImports());
+        if (!this.imports) {
+            this.imports = { core: this.core };
+            for (let id in this.modules) {
+                if (this.imports[id] !== undefined) {
+                    illegalArgs(`attempt to redeclare API module ${id}`);
+                }
+                this.imports[id] = this.modules[id].getImports();
+            }
         }
-        return { env };
+        return this.imports;
+    }
+    getI8(addr) {
+        return this.i8[addr];
+    }
+    getU8(addr) {
+        return this.u8[addr];
+    }
+    getI16(addr) {
+        return this.i16[addr >> 1];
+    }
+    getU16(addr) {
+        return this.u16[addr >> 1];
+    }
+    getI32(addr) {
+        return this.i32[addr >> 2];
+    }
+    getU32(addr) {
+        return this.u32[addr >> 2];
+    }
+    getI64(addr) {
+        return this.i64[addr >> 3];
+    }
+    getU64(addr) {
+        return this.u64[addr >> 3];
+    }
+    getF32(addr) {
+        return this.f32[addr >> 2];
+    }
+    getF64(addr) {
+        return this.f64[addr >> 3];
+    }
+    setI8(addr, x) {
+        this.i8[addr] = x;
+        return this;
+    }
+    setU8(addr, x) {
+        this.u8[addr] = x;
+        return this;
+    }
+    setI16(addr, x) {
+        this.i16[addr >> 1] = x;
+        return this;
+    }
+    setU16(addr, x) {
+        this.u16[addr >> 1] = x;
+        return this;
+    }
+    setI32(addr, x) {
+        this.i32[addr >> 2] = x;
+        return this;
     }
-    getI8Array(ptr, len) {
-        return this.i8.subarray(ptr, ptr + len);
+    setU32(addr, x) {
+        this.u32[addr >> 2] = x;
+        return this;
     }
-    getU8Array(ptr, len) {
-        return this.u8.subarray(ptr, ptr + len);
+    setI64(addr, x) {
+        this.i64[addr >> 3] = x;
+        return this;
     }
-    getI16Array(ptr, len) {
-        ptr >>= 1;
-        return this.i16.subarray(ptr, ptr + len);
+    setU64(addr, x) {
+        this.u64[addr >> 3] = x;
+        return this;
     }
-    getU16Array(ptr, len) {
-        ptr >>= 1;
-        return this.u16.subarray(ptr, ptr + len);
+    setF32(addr, x) {
+        this.f32[addr >> 2] = x;
+        return this;
     }
-    getI32Array(ptr, len) {
-        ptr >>= 2;
-        return this.i32.subarray(ptr, ptr + len);
+    setF64(addr, x) {
+        this.f64[addr >> 3] = x;
+        return this;
     }
-    getU32Array(ptr, len) {
-        ptr >>= 2;
-        return this.u32.subarray(ptr, ptr + len);
+    getI8Array(addr, len) {
+        return this.i8.subarray(addr, addr + len);
     }
-    getF32Array(ptr, len) {
-        ptr >>= 2;
-        return this.f32.subarray(ptr, ptr + len);
+    getU8Array(addr, len) {
+        return this.u8.subarray(addr, addr + len);
     }
-    getF64Array(ptr, len) {
-        ptr >>= 3;
-        return this.f64.subarray(ptr, ptr + len);
+    getI16Array(addr, len) {
+        addr >>= 1;
+        return this.i16.subarray(addr, addr + len);
     }
-    derefI8(ptr) {
-        return this.i8[ptr];
+    getU16Array(addr, len) {
+        addr >>= 1;
+        return this.u16.subarray(addr, addr + len);
     }
-    derefU8(ptr) {
-        return this.u8[ptr];
+    getI32Array(addr, len) {
+        addr >>= 2;
+        return this.i32.subarray(addr, addr + len);
     }
-    derefI16(ptr) {
-        return this.i16[ptr >> 1];
+    getU32Array(addr, len) {
+        addr >>= 2;
+        return this.u32.subarray(addr, addr + len);
     }
-    derefU16(ptr) {
-        return this.u16[ptr >> 1];
+    getI64Array(addr, len) {
+        addr >>= 3;
+        return this.i64.subarray(addr, addr + len);
     }
-    derefI32(ptr) {
-        return this.i32[ptr >> 2];
+    getU64Array(addr, len) {
+        addr >>= 3;
+        return this.u64.subarray(addr, addr + len);
     }
-    derefU32(ptr) {
-        return this.u32[ptr >> 2];
+    getF32Array(addr, len) {
+        addr >>= 2;
+        return this.f32.subarray(addr, addr + len);
     }
-    derefF32(ptr) {
-        return this.f32[ptr >> 2];
+    getF64Array(addr, len) {
+        addr >>= 3;
+        return this.f64.subarray(addr, addr + len);
     }
-    derefF64(ptr) {
-        return this.f64[ptr >> 3];
+    setI8Array(addr, buf) {
+        this.i8.set(buf, addr);
+        return this;
+    }
+    setU8Array(addr, buf) {
+        this.u8.set(buf, addr);
+        return this;
+    }
+    setI16Array(addr, buf) {
+        this.i16.set(buf, addr >> 1);
+        return this;
+    }
+    setU16Array(addr, buf) {
+        this.u16.set(buf, addr >> 1);
+        return this;
+    }
+    setI32Array(addr, buf) {
+        this.i32.set(buf, addr >> 2);
+        return this;
+    }
+    setU32Array(addr, buf) {
+        this.u32.set(buf, addr >> 2);
+        return this;
+    }
+    setI64Array(addr, buf) {
+        this.i64.set(buf, addr >> 3);
+        return this;
+    }
+    setU64Array(addr, buf) {
+        this.u64.set(buf, addr >> 3);
+        return this;
+    }
+    setF32Array(addr, buf) {
+        this.f32.set(buf, addr >> 2);
+        return this;
+    }
+    setF64Array(addr, buf) {
+        this.f64.set(buf, addr >> 3);
+        return this;
     }
     getString(addr, len = 0) {
         return this.utf8Decoder.decode(this.u8.subarray(addr, len > 0 ? addr + len : this.u8.indexOf(0, addr)));
     }
-    getElementById(addr, len = 0) {
-        const id = this.getString(addr, len);
-        const el = document.getElementById(id);
-        assert(!!el, `missing DOM element #${id}`);
-        return el;
-    }
     setString(str, addr, maxBytes, terminate = true) {
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
-        assert(len != null && len < maxBytes + (terminate ? 0 : 1), `error writing string to 0x${U32(addr)}`);
+        if (len != null && len < maxBytes + (terminate ? 0 : 1)) {
+            illegalArgs(`error writing string to 0x${U32(addr)}`);
+        }
         if (terminate) {
             this.u8[addr + len] = 0;
             return len + 1;
         }
         return len;
     }
+    getElementById(addr, len = 0) {
+        const id = this.getString(addr, len);
+        const el = document.getElementById(id);
+        el == null && illegalArgs(`missing DOM element #${id}`);
+        return el;
+    }
 }

package/dev/custom.zig

@@ -1,3 +1,4 @@
+// Import JS core API
 const js = @import("wasmapi");
 
 /// Fill vec2 with random values

package/dev/fieldinfo.zig

@@ -0,0 +1,135 @@
+const js = @import("wasmapi");
+const std = @import("std");
+
+const Foo = struct {
+    pos: [2]f32,
+    col: [3]f32,
+    speed: u8,
+    acc: u16,
+};
+
+fn writeU32(buf: [*]u8, i: u32, x: u32) void {
+    buf[i] = @intCast(u8, x & 0xff);
+    buf[i + 1] = @intCast(u8, x >> 8 & 0xff);
+    buf[i + 2] = @intCast(u8, x >> 16 & 0xff);
+    buf[i + 3] = @intCast(u8, x >> 24);
+}
+
+const FieldType = enum(u8) {
+    I8,
+    U8,
+    I16,
+    U16,
+    I32,
+    U32,
+    F32,
+    F64,
+
+    pub fn fromTypeInfo(comptime info: std.builtin.TypeInfo) FieldType {
+        if (info == .Int) {
+            const bits = info.Int.bits;
+            if (!(bits == 8 or bits == 16 or bits == 32)) {
+                @compileError("unsupported int type (only 8, 16, 32)");
+            }
+            if (info.Int.signedness == .signed) {
+                return switch (bits) {
+                    8 => .I8,
+                    16 => .I16,
+                    32 => .I32,
+                    else => unreachable,
+                };
+            } else {
+                return switch (bits) {
+                    8 => .U8,
+                    16 => .U16,
+                    32 => .U32,
+                    else => unreachable,
+                };
+            }
+        } else if (info == .Float) {
+            return switch (info.Float.bits) {
+                32 => .F32,
+                64 => .F64,
+                else => @compileError("unsupported float type (only f32, f64)"),
+            };
+        }
+        @compileError("unsupported field type");
+    }
+};
+
+// int
+// float
+// ptr
+// array
+// slice
+
+// 8
+// 16
+// 32
+// 64
+
+const Field = packed struct {
+    name: [15]u8 = [_]u8{0} ** 15,
+    tag: FieldType = .U8,
+    offset: u32,
+    len: u32 = 0,
+
+    pub fn fromTypeInfo(comptime T: type, comptime field: std.builtin.TypeInfo.StructField) Field {
+        const finfo = @typeInfo(field.field_type);
+        var ftype: FieldType = .U8;
+        var flen = 0;
+        if (!(finfo == .Int or finfo == .Float or finfo == .Array)) {
+            @compileError("unsupported field type: " ++ @typeName(field.field_type));
+        }
+        if (finfo == .Array) {
+            const cinfo = @typeInfo(finfo.Array.child);
+            if (!(cinfo == .Int or cinfo == .Float)) {
+                @compileError("unsupported field array type: " ++ @typeName(field.field_type));
+            }
+            ftype = FieldType.fromTypeInfo(cinfo);
+            flen = finfo.Array.len;
+        } else {
+            ftype = FieldType.fromTypeInfo(finfo);
+        }
+        var res: Field = .{
+            .tag = ftype,
+            .offset = @offsetOf(T, field.name),
+            .len = flen,
+        };
+        const len = @minimum(14, field.name.len);
+        std.mem.copy(u8, res.name[0..len], field.name[0..len]);
+        return res;
+    }
+};
+
+fn writeTypeInfo(comptime T: type) []u8 {
+    const fields = @typeInfo(T).Struct.fields;
+    const fsize = @sizeOf(Field);
+    var buf: [fields.len * fsize + 4]u8 = undefined;
+    var i = 4;
+    writeU32(&buf, 0, fields.len);
+    for (fields) |field| {
+        var f = Field.fromTypeInfo(T, field);
+        std.mem.copy(
+            u8,
+            buf[i .. i + fsize],
+            @ptrCast(*[fsize]u8, &f)[0..],
+        );
+        i += fsize;
+    }
+    return buf[0..];
+}
+
+export var Foo__info = writeTypeInfo(Foo);
+export var Bar__info = writeTypeInfo(struct { x: i16, y: i16 });
+
+export var U64: u64 = 0xdecafbadcafebabe;
+export var I64: i64 = -0x8000000000000000;
+
+export fn foo() void {
+    js.printI64(I64);
+    js.printU64(U64);
+    js.printI64Array(&[_]i64{ I64, I64 });
+    js.printU32(@truncate(u32, U64 >> 32));
+    js.printU32Hex(@truncate(u32, U64 >> 32));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Modular, extensible API bridge and generic glue code between JS & WebAssembly",
   "type": "module",
   "module": "./index.js",
@@ -35,14 +35,14 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.3.9",
-    "@thi.ng/errors": "^2.1.9",
+    "@thi.ng/errors": "^2.1.10",
     "@thi.ng/hex": "^2.1.9",
-    "@thi.ng/idgen": "^2.1.9",
-    "@thi.ng/logger": "^1.1.9"
+    "@thi.ng/idgen": "^2.1.10",
+    "@thi.ng/logger": "^1.2.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.25.0",
-    "@thi.ng/testament": "^0.2.10",
+    "@thi.ng/testament": "^0.2.11",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
@@ -92,5 +92,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "24ec2749982f4193e6bc50173a238f336854bb1c\n"
+  "gitHead": "0eeb5054111cea51f4714b013dda8700ade3cd54\n"
 }

package/test/custom.zig

@@ -0,0 +1,12 @@
+// Import JS core API
+const js = @import("wasmapi");
+
+/// Fill vec2 with random values
+extern "custom" fn setVec2(addr: usize) void;
+
+export fn test_setVec2() void {
+    var foo = [2]f32{ 0, 0 };
+    js.printF32Array(foo[0..]);
+    setVec2(@ptrToInt(&foo));
+    js.printF32Array(foo[0..]);
+}

package/zig/core.zig

@@ -1,27 +1,51 @@
 //! JavaScript externals for https://thi.ng/wasm-api
 
 /// Prints number using configured JS logger
-pub extern fn printI8(x: i8) void;
+pub extern "core" fn printI8(x: i8) void;
 /// Prints number using configured JS logger
-pub extern fn printU8(x: u8) void;
+pub extern "core" fn printU8(x: u8) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU8Hex(x: u8) void;
+pub extern "core" fn printU8Hex(x: u8) void;
+
 /// Prints number using configured JS logger
-pub extern fn printI16(x: i16) void;
+pub extern "core" fn printI16(x: i16) void;
 /// Prints number using configured JS logger
-pub extern fn printU16(x: u16) void;
+pub extern "core" fn printU16(x: u16) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU16Hex(x: u16) void;
+pub extern "core" fn printU16Hex(x: u16) void;
+
 /// Prints number using configured JS logger
-pub extern fn printI32(x: i32) void;
+pub extern "core" fn printI32(x: i32) void;
 /// Prints number using configured JS logger
-pub extern fn printU32(x: u32) void;
+pub extern "core" fn printU32(x: u32) void;
 /// Prints hex number using configured JS logger
-pub extern fn printU32Hex(x: u32) void;
+pub extern "core" fn printU32Hex(x: u32) void;
+
+/// Prints decomposed i64 number using configured JS logger
+pub extern "core" fn _printI64(hi: i32, lo: i32) void;
+/// Convenience wrapper for _printI64(), accepting an i64
+pub fn printI64(x: i64) void {
+    _printI64(@truncate(i32, x >> 32), @truncate(i32, x));
+}
+
+/// Prints decomposed u64 number using configured JS logger
+pub extern "core" fn _printU64(hi: u32, lo: u32) void;
+/// Convenience wrapper for _printU64(), accepting an u64
+pub fn printU64(x: u64) void {
+    _printU64(@truncate(u32, x >> 32), @truncate(u32, x));
+}
+
+/// Prints decomposed u64 hex number using configured JS logger
+pub extern "core" fn _printU64Hex(hi: u32, lo: u32) void;
+/// Convenience wrapper for _printU64Hex(), accepting an u64
+pub fn printU64Hex(x: u64) void {
+    _printU64Hex(@truncate(u32, x >> 32), @truncate(u32, x));
+}
+
 /// Prints number using configured JS logger
-pub extern fn printF32(x: f32) void;
+pub extern "core" fn printF32(x: f32) void;
 /// Prints number using configured JS logger
-pub extern fn printF64(x: f64) void;
+pub extern "core" fn printF64(x: f64) void;
 
 /// Prints pointer as hex number using configured JS logger
 pub fn printPtr(ptr: *const anyopaque) void {
@@ -29,21 +53,25 @@ pub fn printPtr(ptr: *const anyopaque) void {
 }
 
 /// Prints number array using configured JS logger
-pub extern fn _printI8Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI8Array(addr: usize, len: usize) void;
+/// Prints number array using configured JS logger
+pub extern "core" fn _printU8Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU8Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI16Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printI16Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU16Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU16Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI32Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printI32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU32Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printU32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printI64Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printF32Array(addr: usize, len: usize) void;
+pub extern "core" fn _printU64Array(addr: usize, len: usize) void;
 /// Prints number array using configured JS logger
-pub extern fn _printF64Array(addr: usize, len: usize) void;
+pub extern "core" fn _printF32Array(addr: usize, len: usize) void;
+/// Prints number array using configured JS logger
+pub extern "core" fn _printF64Array(addr: usize, len: usize) void;
 
 /// Prints number array using configured JS logger
 pub fn printI8Array(buf: []const i8) void {
@@ -70,6 +98,14 @@ pub fn printU32Array(buf: []const u32) void {
     _printU32Array(@ptrToInt(buf.ptr), buf.len);
 }
 /// Prints number array using configured JS logger
+pub fn printI64Array(buf: []const i64) void {
+    _printI64Array(@ptrToInt(buf.ptr), buf.len);
+}
+/// Prints number array using configured JS logger
+pub fn printU64Array(buf: []const u64) void {
+    _printU64Array(@ptrToInt(buf.ptr), buf.len);
+}
+/// Prints number array using configured JS logger
 pub fn printF32Array(buf: []const f32) void {
     _printF32Array(@ptrToInt(buf.ptr), buf.len);
 }
@@ -79,10 +115,10 @@ pub fn printF64Array(buf: []const f64) void {
 }
 
 /// Prints a zero-terminated string using configured JS logger
-extern fn _printStr0(addr: usize) void;
+pub extern "core" fn _printStr0(addr: usize) void;
 /// Prints a string of given length using configured JS logger
-extern fn _printStr(addr: usize, len: usize) void;
-
+pub extern "core" fn _printStr(addr: usize, len: usize) void;
+/// Convenience wrapper for _printStr, accepting a slice as arg
 pub fn printStr(msg: []const u8) void {
     _printStr(@ptrToInt(msg.ptr), msg.len);
 }

package/dev/zig-cache/o/9e1187e9310422c9c2330ebceeaecce7/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;

package/dev/zig-cache/o/f647d1186cb589536c92b809f6e25f75/builtin.zig

@@ -1,39 +0,0 @@
-const std = @import("std");
-/// Zig version. When writing code that supports multiple versions of Zig, prefer
-/// feature detection (i.e. with `@hasDecl` or `@hasField`) over version checks.
-pub const zig_version = std.SemanticVersion.parse("0.10.0-dev.3034+6fab6c3e4") catch unreachable;
-pub const zig_backend = std.builtin.CompilerBackend.stage1;
-/// Temporary until self-hosted supports the `cpu.arch` value.
-pub const stage2_arch: std.Target.Cpu.Arch = .wasm32;
-
-pub const output_mode = std.builtin.OutputMode.Lib;
-pub const link_mode = std.builtin.LinkMode.Dynamic;
-pub const is_test = false;
-pub const single_threaded = true;
-pub const abi = std.Target.Abi.musl;
-pub const cpu: std.Target.Cpu = .{
-    .arch = .wasm32,
-    .model = &std.Target.wasm.cpu.generic,
-    .features = std.Target.wasm.featureSet(&[_]std.Target.wasm.Feature{
-    }),
-};
-pub const os = std.Target.Os{
-    .tag = .freestanding,
-    .version_range = .{ .none = {} },
-};
-pub const target = std.Target{
-    .cpu = cpu,
-    .os = os,
-    .abi = abi,
-};
-pub const object_format = std.Target.ObjectFormat.wasm;
-pub const mode = std.builtin.Mode.ReleaseSmall;
-pub const link_libc = false;
-pub const link_libcpp = false;
-pub const have_error_return_tracing = false;
-pub const valgrind_support = false;
-pub const sanitize_thread = false;
-pub const position_independent_code = true;
-pub const position_independent_executable = false;
-pub const strip_debug_info = true;
-pub const code_model = std.builtin.CodeModel.default;