@thi.ng/wasm-api 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-01T14:53:59Z
+- **Last updated**: 2022-08-04T21:21:08Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,34 @@ 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.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
+
+- major update ObjectIndex ([4547f1f](https://github.com/thi-ng/umbrella/commit/4547f1f))
+  - add ObjectIndexOpts ctor options
+  - add IDGen for internal ID generation/recycling
+  - add iterators
+  - rename existing methods
+- fix zig slice pointer handling, use named child modules ([bd7905a](https://github.com/thi-ng/umbrella/commit/bd7905a))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.1.0) (2022-08-01)
 
 #### 🚀 Features

package/README.md

@@ -10,6 +10,8 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
+  - [Custom API modules](#custom-api-modules)
+  - [Object indices & handles](#object-indices--handles)
   - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -23,14 +25,134 @@ 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
 currently only bindings for [Zig](https://ziglang.org) are included.
 
+### Custom API modules
+
+On the JS side, custom API modules can be easily integrated via the [`IWasmAPI`
+interface](https://docs.thi.ng/umbrella/wasm-api/interfaces/IWasmAPI.html). The
+following example provides a brief overview:
+
+```ts
+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 with the bridge's
+	 * core API and hence should use naming prefixes...
+	 */
+	getImports(): WebAssembly.Imports {
+		return {
+			/**
+			 * Writes 2 random float32 numbers to given address
+			 */
+			custom_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:
+
+```ts
+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 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;
+
+export fn test_randomVec2() void {
+	var foo = [2]f32{ 0, 0 };
+
+	// print original
+	js.printF32Array(foo[0..]);
+
+	// populate foo with random numbers
+	custom_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 in JS. For this purpose the [`ObjectIndex`
+class](https://docs.thi.ng/umbrella/wasm-api/classes/ObjectIndex.html) can be
+used by API modules to handle ID generation (incl. recycling, using
+[@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen))
+& indexing of different types of JS objects/values. Only the numeric IDs will
+then need to be exchanged with the WASM module...
+
+```ts
+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
+```
+
 ### Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -60,13 +182,14 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.08 KB
+Package sizes (gzipped, pre-treeshake): ESM: 1.63 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/hex](https://github.com/thi-ng/umbrella/tree/develop/packages/hex)
+- [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 
 ## API
@@ -74,29 +197,25 @@ Package sizes (gzipped, pre-treeshake): ESM: 1.08 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 () => {
-	const bridge = new WasmBridge();
+	// 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
-	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();
+	// this also initializes any bindings & bridge child APIs (if any)
+	await bridge.instantiate(readFileSync("hello.wasm"));
+
+	// call an exported WASM function
+	bridge.exports.start();
 })();
 ```
 
@@ -112,15 +231,17 @@ export fn start() void {
 }
 ```
 
-The WASM binary can be built via:
+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
@@ -135,12 +256,12 @@ The resulting WASM:
  (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")
+ (data (i32.const 65536) "hello world!\00")
  (export "memory" (memory $0))
  (export "start" (func $0))
  (func $0
   (call $fimport$0
-   (i32.const 65552)
+   (i32.const 65536)
    (i32.const 12)
   )
  )

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,6 +25,29 @@ export interface IWasmAPI {
      */
     getImports(): WebAssembly.ModuleImports;
 }
+/**
+ * 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 {
     printI8: Fn<number, void>;
     printU8: Fn<number, void>;
@@ -30,17 +58,22 @@ 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: (ptr: number, len: number) => void;
-    _printU8Array: (ptr: number, len: number) => void;
-    _printI16Array: (ptr: number, len: number) => void;
-    _printU16Array: (ptr: number, len: number) => void;
-    _printI32Array: (ptr: number, len: number) => void;
-    _printU32Array: (ptr: number, len: number) => void;
-    _printF32Array: (ptr: number, len: number) => void;
-    _printF64Array: (ptr: number, len: number) => void;
-    _printStr0: (ptr: number) => void;
-    _printStr: (ptr: number, len: 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;
+    _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;
+    _printStr: (addr: number, len: number) => void;
 }
 //# sourceMappingURL=api.d.ts.map

package/bridge.d.ts

@@ -1,68 +1,115 @@
+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 {
+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;
-    protected children: IWasmAPI[];
     i8: Int8Array;
     u8: Uint8Array;
     i16: Int16Array;
     u16: Uint16Array;
     i32: Int32Array;
     u32: Uint32Array;
+    i64: BigInt64Array;
+    u64: BigUint64Array;
     f32: Float32Array;
     f64: Float64Array;
     utf8Decoder: TextDecoder;
     utf8Encoder: TextEncoder;
     core: CoreAPI;
-    constructor(logger?: ILogger, children?: IWasmAPI[]);
-    init(mem: WebAssembly.Memory): Promise<boolean>;
+    exports: T;
+    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: (ptr: number, len: number) => void;
-            _printU8Array: (ptr: number, len: number) => void;
-            _printI16Array: (ptr: number, len: number) => void;
-            _printU16Array: (ptr: number, len: number) => void;
-            _printI32Array: (ptr: number, len: number) => void;
-            _printU32Array: (ptr: number, len: number) => void;
-            _printF32Array: (ptr: number, len: number) => void;
-            _printF64Array: (ptr: number, len: number) => void;
-            _printStr0: (ptr: number) => void;
-            _printStr: (ptr: 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;
-    getString(ptr: number, len?: number): string;
-    getElementById(ptr: number, len?: number): HTMLElement | null;
-    setString(str: string, ptr: number, maxBytes: number, terminate?: boolean): 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 all declared imports will be merged into a single flat namespace,
+     * it's recommended to use per-module naming prefixes to avoid clashes. If
+     * there're any naming clashes, this function will throw an error.
+     */
+    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;
+    setString(str: string, addr: number, maxBytes: number, terminate?: boolean): number;
+    getElementById(addr: number, len?: number): HTMLElement;
 }
 //# sourceMappingURL=bridge.d.ts.map