@thi.ng/wasm-api 2.4.32 → 2.5.0

package/README.md

@@ -20,6 +20,7 @@
 - [About](#about)
 - [Polyglot bindings generator](#polyglot-bindings-generator)
 - [Custom API modules](#custom-api-modules)
+- [Async handling](#async-handling)
 - [String handling](#string-handling)
 - [Memory allocations](#memory-allocations)
   - [API module auto-initialization](#api-module-auto-initialization)
@@ -123,6 +124,13 @@ export const CustomModule: WasmModuleSpec = {
     // only happens at a later point via WasmBridge.instantiate() or
     // WasmBridge.init() and each module's own init() method...
     factory: () => new CustomAPI(),
+    opts: {
+        // List of exported symbols which should be auto-wrapped using
+        // `WebAssembly.promising`. The counterpart, async function WASM imports,
+        // are also auto-wrapped using `WebAssembly.Suspend`.
+        // Also see section "Async handling" in readme
+        asyncExports: [/* ... */]
+    }
 };
 
 // Optional declarations for JS-side functions which can be used from the WASM side.
@@ -172,6 +180,9 @@ export class CustomAPI implements IWasmAPI<CustomWasmExports> {
      *
      * Each module's imports will be grouped by its declared module ID, which
      * also needs to be used to declare extern functions on the WASM side.
+     *
+     * Async functions given as WASM imports are will be auto-wrapped using
+     * `WebAssembly.Suspend`.
      */
     getImports(): CustomImports {
         return {
@@ -230,6 +241,25 @@ export fn test_randomVec4() void {
 }
 ```
 
+## Async handling
+
+If the targeted WASM runtime supports
+[`WebAssembly.promising`](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/promising_static)
+and
+[`WebAssembly.Suspending`](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/Suspending),
+then async functions will be automatically wrapped as follows:
+
+- Async functions declared in a module's WASM imports will be auto-wrapped using
+  `WebAssembly.Suspending`
+- WASM exports declared via
+  [`WasmModuleOpts.asyncExports`](https://docs.thi.ng/umbrella/wasm-api/interfaces/WasmModuleOpts.html#asyncexports)
+  will be auto-wrapped using `WebAssembly.promising`
+
+(Also see above code examples...)
+
+If either of these are present, but the WASM runtime doesn't support these
+features, an error will be thrown during instantiation/init.
+
 ## String handling
 
 Most low-level languages deal with strings very differently and alas there's no
@@ -469,7 +499,7 @@ Browser ESM import:
 
 [JSDelivr documentation](https://www.jsdelivr.com/)
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.37 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -96,6 +96,26 @@ export interface WasmModuleSpec<T extends WasmExports = WasmExports> {
      * modules own {@link IWasmAPI.init} method.
      */
     factory: Fn<WasmBridge<T>, IWasmAPI<T>>;
+    /**
+     * Module options to configure advanced WASM features
+     */
+    opts?: WasmModuleOpts;
+}
+export interface WasmModuleOpts {
+    /**
+     * List of export symbol names which should be automatically wrapped
+     * using `WebAssembly.promising()`.
+     *
+     * @remarks
+     * Note: Async functions provided as module imports are automatically
+     * wrapped via `WebAssembly.Suspending()`, however for exports no
+     * auto-detection is possible and hence needs to be provided here.
+     *
+     * Reference:
+     * - https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/promising_static
+     * - https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/JavaScript_interface/Suspending
+     */
+    asyncExports?: string[];
 }
 /**
  * Base interface of exports declared by the WASM module. At the very least, a

package/bridge.d.ts

@@ -59,6 +59,7 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
     imports: WebAssembly.Imports;
     exports: T;
     api: CoreAPI;
+    moduleSpecs: IObjectOf<WasmModuleSpec<T>>;
     modules: IObjectOf<IWasmAPI<T>>;
     order: string[];
     constructor(modules?: WasmModuleSpec<T>[], logger?: ILogger);
@@ -85,10 +86,17 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * will be instantiated via `WebAssembly.instantiateStreaming()`, otherwise
      * the non-streaming version will be used.
      *
+     * Any async functions defined in given `imports` will be automatically
+     * wrapped using `WebAssembly.Suspend`. An error will be thrown if async
+     * function imports are provided, but if the suspend feature is not
+     * supported by the WASM runtime. See
+     * {@link WasmModuleSpec.opts} for more details and counterparts.
+     *
      * @param src
      * @param imports
      */
     instantiate(src: Response | BufferSource | PromiseLike<Response | BufferSource>, imports?: WebAssembly.Imports): Promise<boolean>;
+    protected _prepareImports(imports: WebAssembly.Imports): WebAssembly.Imports;
     /**
      * Receives the WASM module's combined exports, stores them for future
      * reference and then initializes all declared bridge child API modules in
@@ -102,6 +110,7 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
      * @param exports
      */
     init(exports: T): Promise<boolean>;
+    protected _prepareExports(exports: T): T;
     /**
      * Called automatically during initialization and from other memory
      * accessors. Initializes and/or updates the various typed WASM memory views

package/bridge.js

@@ -10,8 +10,10 @@ var __decorateClass = (decorators, target, key, kind) => {
 };
 import { INotifyMixin } from "@thi.ng/api/mixins/inotify";
 import { topoSort } from "@thi.ng/arrays/topo-sort";
+import { isAsyncFunction } from "@thi.ng/checks/is-async-function";
 import { assert } from "@thi.ng/errors/assert";
 import { defError } from "@thi.ng/errors/deferror";
+import { unsupportedFeature } from "@thi.ng/errors/unsupported";
 import { U16, U32, U64BIG, U8, hexdumpLines } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
 import {
@@ -89,6 +91,7 @@ let WasmBridge = class {
   imports;
   exports;
   api;
+  moduleSpecs;
   modules;
   order;
   /**
@@ -126,6 +129,13 @@ let WasmBridge = class {
       {}
     );
     this.order = topoSort(graph, (mod) => mod.deps?.map((x) => x.id));
+    this.moduleSpecs = this.order.reduce(
+      (acc, id) => {
+        acc[id] = graph[id];
+        return acc;
+      },
+      {}
+    );
     this.modules = this.order.reduce(
       (acc, id) => {
         acc[id] = graph[id].factory(this);
@@ -144,15 +154,41 @@ let WasmBridge = class {
    * will be instantiated via `WebAssembly.instantiateStreaming()`, otherwise
    * the non-streaming version will be used.
    *
+   * Any async functions defined in given `imports` will be automatically
+   * wrapped using `WebAssembly.Suspend`. An error will be thrown if async
+   * function imports are provided, but if the suspend feature is not
+   * supported by the WASM runtime. See
+   * {@link WasmModuleSpec.opts} for more details and counterparts.
+   *
    * @param src
    * @param imports
    */
   async instantiate(src, imports) {
     const $src = await src;
-    const $imports = { ...this.getImports(), ...imports };
+    const $imports = this._prepareImports({
+      ...this.getImports(),
+      ...imports
+    });
     const wasm = await ($src instanceof Response ? WebAssembly.instantiateStreaming($src, $imports) : WebAssembly.instantiate($src, $imports));
     return this.init(wasm.instance.exports);
   }
+  _prepareImports(imports) {
+    for (let modID in imports) {
+      const moduleImports = imports[modID];
+      for (let id in moduleImports) {
+        if (isAsyncFunction(moduleImports[id])) {
+          if (!("Suspending" in WebAssembly))
+            unsupportedFeature(
+              "async function in WASM module imports"
+            );
+          moduleImports[id] = new WebAssembly["Suspending"](
+            moduleImports[id]
+          );
+        }
+      }
+    }
+    return imports;
+  }
   /**
    * Receives the WASM module's combined exports, stores them for future
    * reference and then initializes all declared bridge child API modules in
@@ -166,7 +202,7 @@ let WasmBridge = class {
    * @param exports
    */
   async init(exports) {
-    this.exports = exports;
+    this.exports = this._prepareExports(exports);
     this.ensureMemory(false);
     for (const id of this.order) {
       this.logger.debug(`initializing API module: ${id}`);
@@ -176,6 +212,30 @@ let WasmBridge = class {
     this.notify({ id: EVENT_MEMORY_CHANGED, value: this.exports.memory });
     return true;
   }
+  _prepareExports(exports) {
+    for (let modID in this.modules) {
+      const opts = this.moduleSpecs[modID].opts;
+      if (!opts?.asyncExports) continue;
+      for (let id of opts.asyncExports) {
+        const item = exports[id];
+        if (item != null) {
+          if (!("promising" in WebAssembly))
+            unsupportedFeature(
+              "async function in WASM module exports"
+            );
+          exports = {
+            ...exports,
+            [id]: WebAssembly.promising(item)
+          };
+        } else {
+          this.logger.warn(
+            `WASM export ${id} declared as async, but missing...`
+          );
+        }
+      }
+    }
+    return exports;
+  }
   /**
    * Called automatically during initialization and from other memory
    * accessors. Initializes and/or updates the various typed WASM memory views

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@thi.ng/wasm-api",
-	"version": "2.4.32",
+	"version": "2.5.0",
 	"description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
 	"type": "module",
 	"module": "./index.js",
@@ -43,22 +43,23 @@
 		"tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
 	},
 	"dependencies": {
-		"@thi.ng/api": "^8.12.26",
-		"@thi.ng/arrays": "^2.14.23",
-		"@thi.ng/checks": "^3.10.0",
-		"@thi.ng/errors": "^2.6.15",
-		"@thi.ng/hex": "^2.4.18",
-		"@thi.ng/idgen": "^2.2.100",
-		"@thi.ng/logger": "^3.3.9"
+		"@thi.ng/api": "^8.12.27",
+		"@thi.ng/arrays": "^2.14.25",
+		"@thi.ng/checks": "^3.11.0",
+		"@thi.ng/errors": "^2.6.16",
+		"@thi.ng/hex": "^2.4.19",
+		"@thi.ng/idgen": "^2.2.101",
+		"@thi.ng/logger": "^3.3.10"
 	},
 	"devDependencies": {
-		"esbuild": "^0.28.0",
+		"esbuild": "^0.28.1",
 		"typedoc": "^0.28.19",
 		"typescript": "^6.0.3"
 	},
 	"keywords": [
 		"allocator",
 		"api",
+		"async",
 		"bigint",
 		"bindings",
 		"browser",
@@ -127,5 +128,5 @@
 		"tag": "wasm",
 		"year": 2022
 	},
-	"gitHead": "c47c56420bcae2e0477d252a497be44f08ca185a"
+	"gitHead": "6a4e7c564ebc476770d213d98a2aa6257a41ac15"
 }