@thi.ng/wasm-api 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-24T12:23:48Z
+- **Last updated**: 2022-11-30T22:27:37Z
 - **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)
@@ -64,7 +65,7 @@ only bindings for these mentioned langs are included.
    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)
@@ -126,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:
@@ -146,7 +148,7 @@ Main Zig file:
 
 ```zig
 // Import JS core API
-const js = @import("wasmapi");
+const js = @import("wasm-api");
 const custom = @import("custom.zig");
 
 export fn test_randomVec4() void {
@@ -176,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
@@ -198,7 +200,7 @@ 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
+## 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.
@@ -244,7 +246,18 @@ try {
 }
 ```
 
-### 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
@@ -291,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-schedule](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-schedule/)
-packages this is used to manage Zig event listeners.
+packages this is used to manage Zig-side event listeners.
 
 ## Status
 
@@ -334,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 (brotli'd, pre-treeshake): ESM: 2.47 KB
 
 ## Dependencies
 
@@ -357,6 +371,7 @@ A selection:
 | Screenshot                                                                                                           | Description                                                        | Live demo                                           | Source                                                                           |
 |:---------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------|:----------------------------------------------------|:---------------------------------------------------------------------------------|
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/>    | Zig-based DOM creation & canvas drawing app                        | [Demo](https://demo.thi.ng/umbrella/zig-canvas/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-cellular.jpg" width="240"/>  | Zig-based 2D multi-behavior cellular automata                      | [Demo](https://demo.thi.ng/umbrella/zig-cellular/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-cellular)  |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-counter.png" width="240"/>   | Simple Zig/WASM click counter DOM component                        | [Demo](https://demo.thi.ng/umbrella/zig-counter/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-counter)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-todo-list.png" width="240"/> | Zig-based To-Do list, DOM creation, local storage task persistence | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-todo-list) |
 
@@ -399,7 +414,7 @@ Requires [Zig](https://ziglang.org) to be installed:
 
 /// import externals
 /// see build command for configuration
-const js = @import("wasmapi");
+const js = @import("wasm-api");
 
 export fn start() void {
     js.printStr("hello world!");
@@ -413,7 +428,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-    --pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
+    --pkg-begin wasm-api node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
     -target wasm32-freestanding \
     -O ReleaseSmall -dynamic \
     hello.zig

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -35,17 +35,17 @@
     "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/checks": "^3.3.3",
-    "@thi.ng/errors": "^2.2.4",
-    "@thi.ng/hex": "^2.3.0",
-    "@thi.ng/idgen": "^2.1.18",
-    "@thi.ng/logger": "^1.4.3"
+    "@thi.ng/api": "^8.5.1",
+    "@thi.ng/arrays": "^2.4.4",
+    "@thi.ng/checks": "^3.3.4",
+    "@thi.ng/errors": "^2.2.5",
+    "@thi.ng/hex": "^2.3.1",
+    "@thi.ng/idgen": "^2.1.20",
+    "@thi.ng/logger": "^1.4.4"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/testament": "^0.3.5",
+    "@thi.ng/testament": "^0.3.6",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.20",
@@ -110,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "8d59e559a576ecb3d2c2d13edf5c3146df95d6ac\n"
+  "gitHead": "1fe40da507070653f420156d91e6b27cf682004f\n"
 }