@thi.ng/wasm-api 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-01T22:09:32Z
+- **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,23 @@ 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

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
@@ -82,25 +83,26 @@ 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 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 };
+	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));
+	custom_randomVec2(@ptrToInt(&foo));
 
 	// print result
-    js.printF32Array(foo[0..]);
+	js.printF32Array(foo[0..]);
 }
 ```
 
@@ -180,7 +182,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.63 KB
 
 ## Dependencies
 
@@ -195,34 +197,25 @@ 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)
+	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 +231,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

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,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,90 @@ export declare class WasmBridge {
     u16: Uint16Array;
     i32: Int32Array;
     u32: Uint32Array;
+    i64: BigInt64Array;
+    u64: BigUint64Array;
     f32: Float32Array;
     f64: Float64Array;
     utf8Decoder: TextDecoder;
     utf8Encoder: TextEncoder;
     core: CoreAPI;
-    constructor(modules?: Record<string, IWasmAPI>, logger?: ILogger);
-    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: (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 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;
-    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