@thi.ng/wasm-api 2.0.4 → 2.1.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-10-08T20:41:04Z
+- **Last updated**: 2024-11-09T15:34:31Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ 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.
 
+## [2.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.1.0) (2024-11-09)
+
+#### 🚀 Features
+
+- add null handling in WasmStringPtr ([e8a094d](https://github.com/thi-ng/umbrella/commit/e8a094d))
+  - update logic to interpret as null pointer if addr=0
+  - update doc strings
+- add null pointer checks, update tests ([247cbbf](https://github.com/thi-ng/umbrella/commit/247cbbf))
+  - update Pointer/Pointer64 deref logic to return undefined for null pointers
+  - add `.isNull` getter for all pointer types (incl. `WasmStringPtr`)
+  - update tests
+
 # [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@2.0.0) (2024-08-18)
 
 #### 🛑 Breaking changes

package/README.md

@@ -460,7 +460,7 @@ Browser ESM import:
 
 [JSDelivr documentation](https://www.jsdelivr.com/)
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.00 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.05 KB
 
 ## Dependencies
 
@@ -520,7 +520,7 @@ interface App extends WasmExports {
 
 ### Zig version
 
-Requires [Zig](https://ziglang.org) to be installed:
+Requires [Zig](https://ziglang.org) (v0.13.x) to be installed:
 
 ```zig tangle:export/hello.zig
 //! Example Zig application (hello.zig)
@@ -539,7 +539,7 @@ scenarios add the supplied .zig file(s) to your `build.zig` and/or source
 folder):
 
 ```bash
-# compile WASM binary (zig v0.12)
+# compile WASM binary (zig v0.13)
 zig build-exe \
     -fno-entry -fstrip -OReleaseSmall -target wasm32-freestanding \
     --name hello -rdynamic --import-symbols \
@@ -555,24 +555,29 @@ The resulting WASM:
 
 ```wasm
 (module
-  (type $t0 (func (param i32 i32)))
-  (type $t1 (func))
-  (type $t2 (func (param i32) (result i32)))
-  (import "wasmapi" "_printStr" (func $wasmapi._printStr (type $t0)))
-  (func $start (type $t1)
-    (call $wasmapi._printStr
-      (i32.const 1048576)
-      (i32.const 12)))
-  (func $_wasm_allocate (type $t2) (param $p0 i32) (result i32)
-    (i32.const 0))
-  (func $_wasm_free (type $t0) (param $p0 i32) (param $p1 i32))
-  (memory $memory 17)
-  (global $g0 (mut i32) (i32.const 1048576))
-  (export "memory" (memory $memory))
-  (export "start" (func $start))
-  (export "_wasm_allocate" (func $_wasm_allocate))
-  (export "_wasm_free" (func $_wasm_free))
-  (data $d0 (i32.const 1048576) "hello world!\00"))
+ (type $0 (func (param i32 i32)))
+ (type $1 (func))
+ (type $2 (func (param i32) (result i32)))
+ (import "wasmapi" "_printStr" (func $fimport$0 (param i32 i32)))
+ (global $global$0 (mut i32) (i32.const 1048576))
+ (memory $0 17)
+ (data $0 (i32.const 1048576) "hello world!\00")
+ (export "memory" (memory $0))
+ (export "start" (func $0))
+ (export "_wasm_allocate" (func $1))
+ (export "_wasm_free" (func $2))
+ (func $0
+  (call $fimport$0
+   (i32.const 1048576)
+   (i32.const 12)
+  )
+ )
+ (func $1 (param $0 i32) (result i32)
+  (i32.const 0)
+ )
+ (func $2 (param $0 i32) (param $1 i32)
+ )
+)
 ```
 
 ### C version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -33,12 +33,14 @@
     "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
     "pub": "yarn npm publish --access public",
     "test": "zig test zig/tests.zig && bun test",
-    "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",
+    "test:build-zig-allocators": "zig build-exe -fno-entry -fstrip --stack 4096 -OReleaseSmall -target wasm32-freestanding --dep wasmapi -Mroot=test/allocators.zig -Mwasmapi=zig/lib.zig --name allocators -rdynamic --import-symbols && wasm-dis -o allocators.wast allocators.wasm && mv allocators.wasm test",
+    "test:build-zig-custom": "zig build-exe -fno-entry -fstrip --stack 4096 -OReleaseSmall -target wasm32-freestanding --dep wasmapi -Mroot=test/custom.zig -Mwasmapi=zig/lib.zig --name custom -rdynamic --import-symbols && wasm-dis -o custom.wast custom.wasm && mv custom.wasm test",
+    "test:build-zig": "yarn test:build-zig-allocators && yarn test:build-zig-custom",
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.11",
-    "@thi.ng/arrays": "^2.10.3",
+    "@thi.ng/arrays": "^2.10.4",
     "@thi.ng/checks": "^3.6.13",
     "@thi.ng/errors": "^2.5.17",
     "@thi.ng/hex": "^2.3.55",
@@ -119,5 +121,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "9219c4c1d5fff4869d8afce6c06531e3b08a1527\n"
+  "gitHead": "c2c371069911fdae138149fdcf937c4ad7a8c71e\n"
 }

package/pointer.d.ts

@@ -10,15 +10,19 @@ import type { IWasmMemoryAccess } from "./api.js";
  * The pointer always behaves like `volatile`, i.e. memoization of target values
  * is purposfully avoided and the wrapper function is executed anew _each_ time
  * the pointer is deref'd.
+ *
+ * Pointers with addr=0 are interpreted as null/optional pointers and
+ * {@link Pointer.deref} will return `undefined` in these cases.
  */
-export declare class Pointer<T> implements IDeref<T> {
+export declare class Pointer<T> implements IDeref<T | undefined> {
     readonly mem: IWasmMemoryAccess;
     readonly base: number;
     readonly fn: Fn<number, T>;
     constructor(mem: IWasmMemoryAccess, base: number, fn: Fn<number, T>);
     get addr(): number;
     set addr(addr: number);
-    deref(): T;
+    get isNull(): boolean;
+    deref(): T | undefined;
 }
 /**
  * Generic pointer facility for
@@ -31,14 +35,18 @@ export declare class Pointer<T> implements IDeref<T> {
  * The pointer always behaves like `volatile`, i.e. memoization of target values
  * is purposefully avoided and the wrapper function is executed anew _each_ time
  * the pointer is deref'd.
+ *
+ * Pointers with addr=0 are interpreted as null/optional pointers and
+ * {@link Pointer64.deref} will return `undefined` in these cases.
  */
-export declare class Pointer64<T> implements IDeref<T> {
+export declare class Pointer64<T> implements IDeref<T | undefined> {
     readonly mem: IWasmMemoryAccess;
     readonly base: bigint;
     readonly fn: Fn<bigint, T>;
     constructor(mem: IWasmMemoryAccess, base: bigint, fn: Fn<bigint, T>);
     get addr(): bigint;
     set addr(addr: bigint);
-    deref(): T;
+    get isNull(): boolean;
+    deref(): T | undefined;
 }
 //# sourceMappingURL=pointer.d.ts.map

package/pointer.js

@@ -5,13 +5,19 @@ class Pointer {
     this.fn = fn;
   }
   get addr() {
+    this.mem.ensureMemory();
     return this.mem.u32[this.base >>> 2];
   }
   set addr(addr) {
+    this.mem.ensureMemory();
     this.mem.u32[this.base >>> 2] = addr;
   }
+  get isNull() {
+    return this.addr === 0;
+  }
   deref() {
-    return this.fn(this.addr);
+    const addr = this.addr;
+    return addr ? this.fn(addr) : void 0;
   }
 }
 class Pointer64 {
@@ -21,13 +27,19 @@ class Pointer64 {
     this.fn = fn;
   }
   get addr() {
+    this.mem.ensureMemory();
     return this.mem.u64[Number(this.base >> BigInt(3))];
   }
   set addr(addr) {
+    this.mem.ensureMemory();
     this.mem.u64[Number(this.base >> BigInt(3))] = addr;
   }
+  get isNull() {
+    return this.addr === 0n;
+  }
   deref() {
-    return this.fn(this.addr);
+    const addr = this.addr;
+    return addr ? this.fn(addr) : void 0;
   }
 }
 export {

package/string.d.ts

@@ -80,7 +80,11 @@ export declare class WasmStringSlice implements ReadonlyWasmString {
 /**
  * Memory mapped string wrapper for C-style UTF-8 encoded and **always**
  * zero-terminated char pointers. The actual JS string can be obtained via
- * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ * {@link WasmStringPtr.deref} and mutated via {@link WasmStringPtr.set}.
+ *
+ * @remarks
+ * Pointers with addr=0 are interpreted as null/optional pointers. See
+ * {@link WasmStringPtr.length} and {@link WasmStringPtr.deref} for details.
  */
 export declare class WasmStringPtr implements ReadonlyWasmString {
     readonly mem: IWasmMemoryAccess;
@@ -92,13 +96,19 @@ export declare class WasmStringPtr implements ReadonlyWasmString {
      */
     get addr(): number;
     set addr(addr: number);
+    get isNull(): boolean;
     /**
      * Returns computed string length (scanning memory for zero sentinel)
+     *
+     * @remarks
+     * Always returns 0 if null pointer (i.e. if {@link WasmStringPtr.addr} is
+     * zero).
      */
     get length(): number;
     /**
-     * Returns memory as JS string (aka wrapper for
-     * {@link WasmBridge.getString}).
+     * Returns memory as JS string (via {@link WasmBridge.getString}). Returns
+     * empty string if null pointer (i.e. if {@link WasmStringPtr.addr} is
+     * zero).
      */
     deref(): string;
     /**

package/string.js

@@ -119,20 +119,30 @@ class WasmStringPtr {
     this.mem.ensureMemory();
     this.mem.u32[this.base >>> 2] = addr;
   }
+  get isNull() {
+    return this.addr === 0;
+  }
   /**
    * Returns computed string length (scanning memory for zero sentinel)
+   *
+   * @remarks
+   * Always returns 0 if null pointer (i.e. if {@link WasmStringPtr.addr} is
+   * zero).
    */
   get length() {
-    this.mem.ensureMemory();
-    const idx = this.mem.u8.indexOf(0, this.addr);
-    return idx >= 0 ? idx - this.addr : 0;
+    const addr = this.addr;
+    if (!addr) return 0;
+    const idx = this.mem.u8.indexOf(0, addr);
+    return idx >= 0 ? idx - addr : 0;
   }
   /**
-   * Returns memory as JS string (aka wrapper for
-   * {@link WasmBridge.getString}).
+   * Returns memory as JS string (via {@link WasmBridge.getString}). Returns
+   * empty string if null pointer (i.e. if {@link WasmStringPtr.addr} is
+   * zero).
    */
   deref() {
-    return this.mem.getString(this.addr, this.length);
+    const addr = this.addr;
+    return addr ? this.mem.getString(addr, this.length) : "";
   }
   /**
    * If given a JS string as arg (and if this `WasmStringPtr` instance itself
@@ -156,6 +166,7 @@ class WasmStringPtr {
    */
   set(str) {
     const addr = this.addr;
+    if (!addr) unsupported("can't mutate null pointer");
     if (typeof str === "string") {
       if (this.isConst) unsupported("can't mutate const string");
       this.mem.ensureMemory();