@thi.ng/wasm-api 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-04T17:35:45Z
+- **Last updated**: 2022-10-17T12:08:09Z
 - **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.
 
+## [0.14.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.14.0) (2022-10-17)
+
+#### 🚀 Features
+
+- add ptrCast() zig helper ([72a9406](https://github.com/thi-ng/umbrella/commit/72a9406))
+- add Zig Slice & String wrappers ([28d057e](https://github.com/thi-ng/umbrella/commit/28d057e))
+  - allows expressing & converting slices for `extern struct`s
+- ensure memory in WasmStringSlice/Ptr ([c55c6f0](https://github.com/thi-ng/umbrella/commit/c55c6f0))
+- update IWasmMemoryAccess ([28bfff6](https://github.com/thi-ng/umbrella/commit/28bfff6))
+  - add IWasmMemoryAccess.ensureMemory()
+  - update WasmBridge.setString() to ensure memory
+
 ## [0.13.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.13.0) (2022-10-04)
 
 #### 🚀 Features

package/api.d.ts

@@ -91,6 +91,11 @@ export interface IWasmMemoryAccess {
     u64: BigUint64Array;
     f32: Float32Array;
     f64: Float64Array;
+    /**
+     * Initializes and/or updates the various typed WASM memory views (e.g.
+     * after growing the WASM memory and the previous buffer becoming detached).
+     */
+    ensureMemory(): void;
     /**
      * Reads UTF-8 encoded string from given address and optional byte length.
      * The default length is 0, which will be interpreted as a zero-terminated

package/bridge.js

@@ -414,6 +414,7 @@ let WasmBridge = class WasmBridge {
      * @param terminate
      */
     setString(str, addr, maxBytes, terminate = true) {
+        this.ensureMemory();
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
         if (len == null || len >= maxBytes + (terminate ? 0 : 1)) {

package/include/wasmapi.zig

@@ -3,6 +3,47 @@
 const std = @import("std");
 const root = @import("root");
 
+/// Higher-order slice wrapper for extern struct use cases
+/// S = slice type
+/// P = pointer type
+/// default = point default value
+pub fn Slice(comptime S: type, comptime P: type, comptime default: P) type {
+    return extern struct {
+        ptr: P = default,
+        len: usize = 0,
+
+        pub fn wrap(slice: S) @This() {
+            return .{
+                .ptr = @ptrCast(P, slice.ptr),
+                .len = slice.len,
+            };
+        }
+
+        pub fn toSlice(self: *@This()) S {
+            return @ptrCast(*S, self).*;
+        }
+    };
+}
+
+/// []const u8 wrapper for extern struct use cases
+const String = Slice([]const u8, [*:0]const u8, "");
+
+/// Syntax sugar for `String.wrap()`
+pub fn string(str: []const u8) String {
+    return String.wrap(str);
+}
+
+/// Similar to @ptrCast intrinsic. Helper function to cast & re-align an
+/// optional `anyopaque` pointer to another given pointer type.
+/// E.g. useful for retrieving user context data from an opaque extra arg
+/// given to a event listner callback...
+pub fn ptrCast(comptime T: type, ptr: ?*anyopaque) ?T {
+    if (ptr == null) return null;
+    const info = @typeInfo(T);
+    if (info != .Pointer) @compileError("require pointer type");
+    return @ptrCast(T, @alignCast(@alignOf(info.Pointer.child), ptr));
+}
+
 /// JS external part of the custom panic handler
 /// Prints message using configured JS logger and then throws JS error
 pub extern "wasmapi" fn _panic(addr: [*]const u8, len: usize) noreturn;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -37,22 +37,22 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.4.3",
-    "@thi.ng/args": "^2.2.4",
+    "@thi.ng/args": "^2.2.5",
     "@thi.ng/binary": "^3.3.6",
-    "@thi.ng/checks": "^3.2.6",
+    "@thi.ng/checks": "^3.3.0",
     "@thi.ng/compare": "^2.1.13",
-    "@thi.ng/defmulti": "^2.1.17",
+    "@thi.ng/defmulti": "^2.1.18",
     "@thi.ng/errors": "^2.2.2",
-    "@thi.ng/file-io": "^0.3.14",
+    "@thi.ng/file-io": "^0.3.15",
     "@thi.ng/hex": "^2.2.1",
     "@thi.ng/idgen": "^2.1.15",
-    "@thi.ng/logger": "^1.4.0",
-    "@thi.ng/paths": "^5.1.17",
+    "@thi.ng/logger": "^1.4.1",
+    "@thi.ng/paths": "^5.1.18",
     "@thi.ng/strings": "^3.3.14"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.31.1",
-    "@thi.ng/testament": "^0.3.2",
+    "@thi.ng/testament": "^0.3.3",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.22.17",
@@ -62,13 +62,15 @@
     "allocator",
     "api",
     "bindings",
+    "browser",
     "c",
     "codegen",
     "enum",
     "event",
-    "id",
+    "interop",
     "logger",
     "memory",
+    "modular",
     "polyglot",
     "string",
     "struct",
@@ -77,7 +79,6 @@
     "utf8",
     "wasm",
     "webassembly",
-    "wrapper",
     "ziglang"
   ],
   "publishConfig": {
@@ -94,8 +95,8 @@
     "*.js",
     "*.d.ts",
     "bin",
-    "include",
-    "codegen"
+    "codegen",
+    "include"
   ],
   "exports": {
     ".": {
@@ -136,5 +137,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "c3f7d6598c7d7d0c61ba87150a56deac12649d7b\n"
+  "gitHead": "612b1b0bdf442473f04c2edac3012975a6ca28bb\n"
 }

package/string.js

@@ -15,12 +15,14 @@ export class WasmStringSlice {
      * Returns string start address (deref'd pointer).
      */
     get addr() {
+        this.mem.ensureMemory();
         return this.mem.u32[this.base >>> 2];
     }
     /**
      * Returns string length (read from memory)
      */
     get length() {
+        this.mem.ensureMemory();
         return this.mem.u32[(this.base + 4) >>> 2];
     }
     /**
@@ -48,6 +50,7 @@ export class WasmStringSlice {
      * @param str
      */
     set(str) {
+        this.mem.ensureMemory();
         if (typeof str === "string") {
             if (this.isConst)
                 unsupported("can't mutate const string");
@@ -65,6 +68,7 @@ export class WasmStringSlice {
      * @param len
      */
     setSlice(addr, len) {
+        this.mem.ensureMemory();
         this.mem.u32[this.base >>> 2] = addr;
         this.mem.u32[(this.base + 4) >>> 2] = len;
     }
@@ -93,18 +97,20 @@ export class WasmStringPtr {
      * Returns string start address (deref'd pointer).
      */
     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;
     }
     /**
      * Returns computed string length (scanning memory for zero sentinel)
      */
     get length() {
-        const addr = this.addr;
-        const idx = this.mem.u8.indexOf(0, addr);
-        return idx >= 0 ? idx - addr : 0;
+        this.mem.ensureMemory();
+        const idx = this.mem.u8.indexOf(0, this.addr);
+        return idx >= 0 ? idx - this.addr : 0;
     }
     /**
      * Returns memory as JS string (aka wrapper for
@@ -137,6 +143,7 @@ export class WasmStringPtr {
         if (typeof str === "string") {
             if (this.isConst)
                 unsupported("can't mutate const string");
+            this.mem.ensureMemory();
             this.mem.setString(str, addr, this.mem.u8.byteLength - addr, true);
         }
         else {