@thi.ng/wasm-api 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-23T22:46:54Z
+- **Last updated**: 2022-11-28T13:36:49Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.
 
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.1.0) (2022-11-28)
+
+#### 🚀 Features
+
+- update panic handler, add event support ([ab940d9](https://github.com/thi-ng/umbrella/commit/ab940d9))
+  - update panic handler to broadcast event w/ panic message
+  - only throw Panic error if no listeners could be notified
+  - add `EVENT_PANIC` constant
+
 # [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.0.0) (2022-11-23)
 
 #### 🛑 Breaking changes

package/README.md

@@ -10,11 +10,12 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
 
 - [About](#about)
-  - [Custom API modules](#custom-api-modules)
+- [Custom API modules](#custom-api-modules)
   - [Building Zig projects with these hybrid API modules](#building-zig-projects-with-these-hybrid-api-modules)
-  - [String handling](#string-handling)
-  - [Memory allocations](#memory-allocations)
-  - [Object indices & handles](#object-indices--handles)
+- [String handling](#string-handling)
+- [Memory allocations](#memory-allocations)
+  - [API module auto-initialization](#api-module-auto-initialization)
+- [Object indices & handles](#object-indices--handles)
 - [Status](#status)
 - [Support packages](#support-packages)
 - [Installation](#installation)
@@ -59,13 +60,12 @@ WebGL, WebGPU, WebAudio etc. is being actively worked on.
    for (currently) Zig & TypeScript and C11. For TS fully type checked and
 memory-mapped (zero-copy) accessors of WASM-side data are generated. In
 principle, all languages with a WASM target are supported, however currently
-only bindings for these mentioned langs are included. Other languages require
-custom bindings, e.g. based on the flexible primitives provided here.
+only bindings for these mentioned langs are included.
 8. [CLI
    frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
    for the code generator(s)
 
-### Custom API modules
+## Custom API modules
 
 The
 [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html)
@@ -83,40 +83,40 @@ following example provides a brief overview:
 import { IWasmAPI, WasmBridge } from "@thi.ng/wasm-api";
 
 export class CustomAPI implements IWasmAPI {
-	// Unique API module identifier to group WASM imports,
-	// must match ID used by native code (see further below).
-	readonly id = "custom";
-	// optionally list IDs of other API modules this module depends on
-	// these are used to infer the correct initialization order
-	readonly dependencies = [];
-
-	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 during instantiation. These imports are merged
-	 * into a larger imports object alongside the bridge's core API...
-	 */
-	getImports(): WebAssembly.Imports {
-		return {
-			/**
-			 * Writes `num` random float32 numbers from given address
-			 */
-			fillRandom: (addr: number, num: number) => {
-				addr >>>= 2;
-				while(num-- > 0) this.parent.f32[addr++] = Math.random();
-			}
-		};
-	}
+    // Unique API module identifier to group WASM imports,
+    // must match ID used by native code (see further below).
+    readonly id = "custom";
+    // optionally list IDs of other API modules this module depends on
+    // these are used to infer the correct initialization order
+    readonly dependencies = [];
+
+    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 during instantiation. These imports are merged
+     * into a larger imports object alongside the bridge's core API...
+     */
+    getImports(): WebAssembly.Imports {
+        return {
+            /**
+             * Writes `num` random float32 numbers from given address
+             */
+            fillRandom: (addr: number, num: number) => {
+                addr >>>= 2;
+                while(num-- > 0) this.parent.f32[addr++] = Math.random();
+            }
+        };
+    }
 }
 ```
 
@@ -127,7 +127,8 @@ export const bridge = new WasmBridge([new CustomAPI()]);
 ```
 
 In Zig (or any other language of your choice) we can then utilize this custom
-API like so (Please also see [example projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
+API like so (Please also see [example
+projects](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas/)
 & other example snippets in this readme):
 
 Bindings file / lib:
@@ -151,16 +152,16 @@ const js = @import("wasmapi");
 const custom = @import("custom.zig");
 
 export fn test_randomVec4() void {
-	var foo = [4]f32{ 1, 2, 3, 4 };
+    var foo = [4]f32{ 1, 2, 3, 4 };
 
-	// print original
-	js.printF32Array(foo[0..]);
+    // print original
+    js.printF32Array(foo[0..]);
 
-	// populate foo with random numbers
-	custom.fillRandom(&foo, foo.len);
+    // populate foo with random numbers
+    custom.fillRandom(&foo, foo.len);
 
-	// print result
-	js.printF32Array(foo[0..]);
+    // print result
+    js.printF32Array(foo[0..]);
 }
 ```
 
@@ -177,7 +178,7 @@ To avoid guesswork about the internals of these API modules, all of them are
 using an overall uniform structure, with the main Zig entry point in
 `/zig/lib.zig`...
 
-### String handling
+## String handling
 
 Most low-level languages deal with strings very differently and alas there's no
 general standard. Some have UTF-8/16 support, others don't. In some languages
@@ -190,7 +191,16 @@ and
 [`setString()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#setString)
 for details.
 
-### Memory allocations
+Furthermore, the package provides these string wrapper types:
+
+- [`WasmStringPtr`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmStringPtr.html)
+- [`WasmStringSlice`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmStringSlice.html)
+
+Finally, see more information in the
+[@thi.ng/wasm-api-bindgen](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#string-handling)
+package readme.
+
+## Memory allocations
 
 If explicitly enabled on the WASM side, the `WasmBridge` includes support for
 malloc/free-style allocations (within the linear WASM memory) from the JS side.
@@ -199,9 +209,9 @@ The actual allocator is implementation specific and suitable generic mechanisms
 are defined for both the included Zig & C bindings. Please see for further
 reference:
 
-- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig#L37-L71):
+- [`/zig/lib.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/lib.zig#L34-L68):
   comments about WASM-side allocator handling in Zig
-- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L20-L30):
+- [`/include/wasmapi.h`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/include/wasmapi.h#L18-L28):
   comments about WASM-side allocator handling in C/C++
 - [`WasmBridge.allocate()`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html#allocate):
   allocating memory from JS side
@@ -217,26 +227,37 @@ for more details...
 
 ```ts
 try {
-	// allocate 256 bytes of memory for passing a string to WASM side
-	// the function returns a tuple of `[address, len]`
-	const [addr, len] = bridge.allocate(256);
+    // allocate 256 bytes of memory for passing a string to WASM side
+    // the function returns a tuple of `[address, len]`
+    const [addr, len] = bridge.allocate(256);
 
-	// write zero terminated string to reserved memory (max. `len` bytes)
-	// function returns number of bytes written (excl. sentinel)
-	const num = bridge.setString("hello WASM world!", addr, len, true);
+    // write zero terminated string to reserved memory (max. `len` bytes)
+    // function returns number of bytes written (excl. sentinel)
+    const num = bridge.setString("hello WASM world!", addr, len, true);
 
-	// call WASM function doing something w/ the string
-	bridge.exports.doSomethingWithString(addr, num);
+    // call WASM function doing something w/ the string
+    bridge.exports.doSomethingWithString(addr, num);
 
-	// cleanup
-	bridge.free([addr, len]);
+    // cleanup
+    bridge.free([addr, len]);
 } catch(e) {
-	// deal with allocation error
-	// ...
+    // deal with allocation error
+    // ...
 }
 ```
 
-### Object indices & handles
+### API module auto-initialization
+
+The supplied child APIs
+([wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom),
+[wasm-api-schedule](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-schedule)
+etc.) use an auto-intialization hook related to the above `WASM_ALLOCATOR`
+mechanism: If that allocator is available, the WASM side of these modules will
+auto initialize and thus reduce boilerplate. However, if no such central
+allocator is defined and/or a custom allocator should be used, then these API
+modules will be have to be initialized manually.
+
+## 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
@@ -283,13 +304,14 @@ canvases.delete(0);
 // true
 ```
 
-Since v0.15.0, the supplied Zig core bindings lib also includes a
+The supplied Zig core library also includes a
 [`ManagedIndex`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/managed-index.zig)
-for similar dealings on the Zig side of the application. For example, in the
+for similar resource management on the Zig side of the application. For example,
+in the
 [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-dom/)
 &
-[@thi.ng/wasm-api-timer](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-timer/)
-modules this is used to manage Zig event listeners.
+[@thi.ng/wasm-api-schedule](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-schedule/)
+packages this is used to manage Zig-side event listeners.
 
 ## Status
 
@@ -326,7 +348,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.70 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.73 KB
 
 ## Dependencies
 
@@ -364,21 +386,21 @@ import { readFileSync } from "fs";
 
 // WASM exports from our dummy module (below)
 interface App extends WasmExports {
-	start: () => void;
+    start: () => void;
 }
 
 (async () => {
-	// new API bridge with defaults
-	// (i.e. no child API modules and using console logger)
-	const bridge = new WasmBridge<App>();
+    // new API bridge with defaults
+    // (i.e. no child API modules and using console logger)
+    const bridge = new WasmBridge<App>();
 
-	// instantiate WASM module using imports provided by the bridge
-	// this also initializes any bindings & bridge child APIs (if any)
-	// (also accepts a fetch() `Response` as input)
-	await bridge.instantiate(readFileSync("hello.wasm"));
+    // instantiate WASM module using imports provided by the bridge
+    // this also initializes any bindings & bridge child APIs (if any)
+    // (also accepts a fetch() `Response` as input)
+    await bridge.instantiate(readFileSync("hello.wasm"));
 
-	// call an exported WASM function
-	bridge.exports.start();
+    // call an exported WASM function
+    bridge.exports.start();
 })();
 ```
 
@@ -386,19 +408,15 @@ interface App extends WasmExports {
 
 Requires [Zig](https://ziglang.org) to be installed:
 
-```zig
+```zig tangle:export/hello.zig
 //! Example Zig application (hello.zig)
 
 /// import externals
 /// see build command for configuration
 const js = @import("wasmapi");
-const std = @import("std");
-
-// set custom memory allocator (here to disable)
-pub const WASM_ALLOCATOR: ?std.mem.Allocator = null;
 
 export fn start() void {
-	js.printStr("hello world!");
+    js.printStr("hello world!");
 }
 ```
 
@@ -409,10 +427,10 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-	--pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
-	-target wasm32-freestanding \
-	-O ReleaseSmall -dynamic --strip \
-	hello.zig
+    --pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
+    -target wasm32-freestanding \
+    -O ReleaseSmall -dynamic \
+    hello.zig
 
 # disassemble WASM
 wasm-dis -o hello.wast hello.wasm
@@ -451,11 +469,11 @@ The resulting WASM:
 
 Requires [Emscripten](https://emscripten.org/) to be installed:
 
-```c
+```c tangle:export/hello.c
 #include <wasmapi.h>
 
-void WASM_KEEP start() {
-	wasm_printStr0("hello world!");
+void WASMAPI_KEEP start() {
+    wasm_printStrZ("hello world!");
 }
 ```
 
@@ -467,73 +485,6 @@ emcc -Os -Inode_modules/@thi.ng/wasm-api/include \
   -o hello.wasm hello.c
 ```
 
-Resulting WASM:
-
-```wasm
-(module
- (type $i32_=>_none (func (param i32)))
- (type $none_=>_none (func))
- (type $i32_=>_i32 (func (param i32) (result i32)))
- (type $none_=>_i32 (func (result i32)))
- (type $i32_i32_=>_none (func (param i32 i32)))
- (import "wasmapi" "_printStr0" (func $fimport$0 (param i32)))
- (global $global$0 (mut i32) (i32.const 5243936))
- (memory $0 256 256)
- (data (i32.const 1024) "hello world!")
- (table $0 2 2 funcref)
- (elem (i32.const 1) $0)
- (export "memory" (memory $0))
- (export "_wasm_allocate" (func $1))
- (export "_wasm_free" (func $2))
- (export "start" (func $3))
- (export "__indirect_function_table" (table $0))
- (export "_initialize" (func $0))
- (export "__errno_location" (func $7))
- (export "stackSave" (func $4))
- (export "stackRestore" (func $5))
- (export "stackAlloc" (func $6))
- (func $0
-  (nop)
- )
- (func $1 (param $0 i32) (result i32)
-  (i32.const 0)
- )
- (func $2 (param $0 i32) (param $1 i32)
-  (nop)
- )
- (func $3
-  (call $fimport$0
-   (i32.const 1024)
-  )
- )
- (func $4 (result i32)
-  (global.get $global$0)
- )
- (func $5 (param $0 i32)
-  (global.set $global$0
-   (local.get $0)
-  )
- )
- (func $6 (param $0 i32) (result i32)
-  (global.set $global$0
-   (local.tee $0
-    (i32.and
-     (i32.sub
-      (global.get $global$0)
-      (local.get $0)
-     )
-     (i32.const -16)
-    )
-   )
-  )
-  (local.get $0)
- )
- (func $7 (result i32)
-  (i32.const 1040)
- )
-)
-```
-
 ## Authors
 
 Karsten Schmidt

package/api.d.ts

@@ -1,6 +1,7 @@
 import type { Fn, IDeref, ILength } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
+export declare const EVENT_PANIC = "panic";
 export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
 export declare type ReadonlyWasmString = IDeref<string> & ILength & {
     readonly addr: number;

package/api.js

@@ -1 +1,2 @@
 export const EVENT_MEMORY_CHANGED = "memory-changed";
+export const EVENT_PANIC = "panic";

package/bridge.d.ts

@@ -181,6 +181,6 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
     /** {@inheritDoc @thi.ng/api#INotify.removeListener} */
     removeListener(id: string, fn: Listener, scope?: any): boolean;
     /** {@inheritDoc @thi.ng/api#INotify.notify} */
-    notify(event: Event): void;
+    notify(event: Event): boolean;
 }
 //# sourceMappingURL=bridge.d.ts.map

package/bridge.js

@@ -5,7 +5,7 @@ import { assert } from "@thi.ng/errors/assert";
 import { defError } from "@thi.ng/errors/deferror";
 import { hexdumpLines, U16, U32, U64BIG, U8 } from "@thi.ng/hex";
 import { ConsoleLogger } from "@thi.ng/logger/console";
-import { EVENT_MEMORY_CHANGED, } from "./api.js";
+import { EVENT_MEMORY_CHANGED, EVENT_PANIC, } from "./api.js";
 export const Panic = defError(() => "Panic");
 export const OutOfMemoryError = defError(() => "Out of memory");
 /**
@@ -69,7 +69,10 @@ let WasmBridge = class WasmBridge {
                 debugger;
             },
             _panic: (addr, len) => {
-                throw new Panic(this.getString(addr, len));
+                const msg = this.getString(addr, len);
+                if (!this.notify({ id: EVENT_PANIC, value: msg })) {
+                    throw new Panic(msg);
+                }
             },
             timer: () => performance.now(),
             epoch: () => BigInt(Date.now()),

package/include/wasmapi.h

@@ -1,7 +1,5 @@
 #pragma once
 
-#include "wasmapi_types.h"
-
 #ifdef __cplusplus
 extern "C" {
 #endif

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -35,12 +35,12 @@
     "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi zig/lib.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.4.6",
-    "@thi.ng/arrays": "^2.4.2",
+    "@thi.ng/api": "^8.5.0",
+    "@thi.ng/arrays": "^2.4.3",
     "@thi.ng/checks": "^3.3.3",
     "@thi.ng/errors": "^2.2.4",
     "@thi.ng/hex": "^2.3.0",
-    "@thi.ng/idgen": "^2.1.18",
+    "@thi.ng/idgen": "^2.1.19",
     "@thi.ng/logger": "^1.4.3"
   },
   "devDependencies": {
@@ -110,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "044ee6a3895720fc78e115032d4d831b63510929\n"
+  "gitHead": "75ec32ff7f1b7b5e72e7a04ace24732cd5d6c774\n"
 }

package/zig/lib.zig

@@ -2,9 +2,6 @@
 
 const std = @import("std");
 const root = @import("root");
-const types = @import("types.zig");
-
-pub usingnamespace types;
 
 pub const ManagedIndex = @import("managed-index.zig").ManagedIndex;
 

package/include/wasmapi_types.h

@@ -1,35 +0,0 @@
-#pragma once
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-#include <stddef.h>
-
-typedef char* WASM_StringPtr;
-typedef const char* WASM_ConstStringPtr;
-
-typedef void* WASM_OpaquePtr;
-typedef const void* WASM_ConstOpaquePtr;
-
-// slice-based string
-typedef struct { WASM_StringPtr ptr; size_t len; } WASM_String;
-typedef struct { WASM_ConstStringPtr ptr; size_t len; } WASM_ConstString;
-
-// defines slice wrapper structs for given pointer types
-#define WASMAPI_SLICE(PREFIX, NAME, PTR, CONSTPTR) \
-  typedef struct { PTR* ptr; size_t len;  } PREFIX##NAME##Slice; \
-  typedef struct { CONSTPTR* ptr; size_t len; } PREFIX##Const##NAME##Slice;
-
-// slice of string slices
-WASMAPI_SLICE(WASM_, String, WASM_String, WASM_ConstString)
-
-// slice of string pointers
-WASMAPI_SLICE(WASM_, StringPtr, WASM_StringPtr, WASM_ConstStringPtr)
-
-// slice of opaque pointers
-WASMAPI_SLICE(WASM_, OpaquePtr, WASM_OpaquePtr, WASM_ConstOpaquePtr)
-
-#ifdef __cplusplus
-}
-#endif

package/zig/types.zig

@@ -1,52 +0,0 @@
-//! Common helper types used by the thi.ng/wasm-api code gen
-//! None of these type have any further dependencies on the main wasm-api package
-
-/// Higher-order generic slice wrapper for `extern struct` use cases
-/// S = slice type
-/// P = pointer type
-pub fn Slice(comptime S: type, comptime P: type) type {
-    return extern struct {
-        ptr: P = @as(S, &.{}).ptr,
-        len: usize = 0,
-
-        pub inline fn wrap(slice: S) @This() {
-            return .{
-                .ptr = @ptrCast(P, slice.ptr),
-                .len = slice.len,
-            };
-        }
-
-        pub inline fn toSlice(self: *@This()) S {
-            return @ptrCast(*S, self).*;
-        }
-    };
-}
-
-pub const StringPtr = [*:0]u8;
-pub const ConstStringPtr = [*:0]const u8;
-
-/// `[]u8` slice wrapper for `extern struct` use cases
-pub const String = Slice([]u8, StringPtr);
-/// `[]const u8` slice wrapper for `extern struct` use cases
-pub const ConstString = Slice([]const u8, ConstStringPtr);
-
-/// Slice of `String`s
-pub const StringSlice = Slice([]String, [*]String);
-pub const ConstStringSlice = Slice([]ConstString, [*]ConstString);
-
-/// Slice of `StringPtr`s
-pub const StringPtrSlice = Slice([]StringPtr, [*]StringPtr);
-pub const ConstStringPtrSlice = Slice([]ConstStringPtr, [*]ConstStringPtr);
-
-/// Alias for `*anyopaque`
-pub const OpaquePtr = *anyopaque;
-pub const ConstOpaquePtr = *const anyopaque;
-
-/// Slice of `OpaquePtr`s
-pub const OpaquePtrSlice = Slice([]OpaquePtr, [*]OpaquePtr);
-pub const ConstOpaquePtrSlice = Slice([]ConstOpaquePtr, [*]ConstOpaquePtr);
-
-/// Syntax sugar for `ConstString.wrap()`
-pub inline fn string(str: []const u8) ConstString {
-    return ConstString.wrap(str);
-}