@thi.ng/wasm-api 0.18.0 → 1.0.0

package/index.js

@@ -1,10 +1,5 @@
 export * from "./api.js";
 export * from "./bridge.js";
-export * from "./codegen.js";
-export * from "./codegen/c11.js";
-export * from "./codegen/typescript.js";
-export * from "./codegen/utils.js";
-export * from "./codegen/zig.js";
 export * from "./object-index.js";
 export * from "./pointer.js";
 export * from "./string.js";

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.18.0",
-  "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
+  "version": "1.0.0",
+  "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
-  "bin": "bin/wasm-api",
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -33,30 +32,23 @@
     "doc:stats": "tools:module-stats",
     "pub": "yarn npm publish --access public",
     "test": "testament test",
-    "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi zig/wasmapi.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm 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"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.4.4",
-    "@thi.ng/args": "^2.2.7",
-    "@thi.ng/arrays": "^2.4.0",
-    "@thi.ng/binary": "^3.3.8",
-    "@thi.ng/checks": "^3.3.2",
-    "@thi.ng/compare": "^2.1.14",
-    "@thi.ng/defmulti": "^2.1.19",
-    "@thi.ng/errors": "^2.2.3",
-    "@thi.ng/file-io": "^0.3.17",
-    "@thi.ng/hex": "^2.2.2",
-    "@thi.ng/idgen": "^2.1.16",
-    "@thi.ng/logger": "^1.4.2",
-    "@thi.ng/paths": "^5.1.20",
-    "@thi.ng/strings": "^3.3.15"
+    "@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"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/testament": "^0.3.4",
+    "@thi.ng/testament": "^0.3.5",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.18",
+    "typedoc": "^0.23.20",
     "typescript": "^4.8.4"
   },
   "keywords": [
@@ -65,16 +57,12 @@
     "bindings",
     "browser",
     "c",
-    "codegen",
-    "enum",
     "event",
     "interop",
     "logger",
     "memory",
     "modular",
-    "polyglot",
     "string",
-    "struct",
     "typedarray",
     "typescript",
     "utf8",
@@ -93,10 +81,8 @@
     "node": ">=14"
   },
   "files": [
-    "*.js",
-    "*.d.ts",
-    "bin",
-    "codegen",
+    "./*.js",
+    "./*.d.ts",
     "include",
     "zig"
   ],
@@ -110,24 +96,6 @@
     "./bridge": {
       "default": "./bridge.js"
     },
-    "./codegen/align": {
-      "default": "./codegen/align.js"
-    },
-    "./codegen/c11": {
-      "default": "./codegen/c11.js"
-    },
-    "./codegen/typescript": {
-      "default": "./codegen/typescript.js"
-    },
-    "./codegen/utils": {
-      "default": "./codegen/utils.js"
-    },
-    "./codegen/zig": {
-      "default": "./codegen/zig.js"
-    },
-    "./codegen": {
-      "default": "./codegen.js"
-    },
     "./object-index": {
       "default": "./object-index.js"
     },
@@ -142,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "7eff3051eb395f460421727b8cf5ef79f09faaa9\n"
+  "gitHead": "044ee6a3895720fc78e115032d4d831b63510929\n"
 }

package/pointer.d.ts

@@ -20,4 +20,24 @@ export declare class Pointer<T> implements IDeref<T> {
     set addr(addr: number);
     deref(): T;
 }
+/**
+ * Generic pointer facility for {@link WASM64} target, which on
+ * {@link Pointer64.deref()} calls wrapper function (provided as ctor arg) to
+ * realise the pointer's target value. The pointer's target address can be
+ * accessed via {@link Pointer.addr} (read/write).
+ *
+ * @remarks
+ * 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.
+ */
+export declare class Pointer64<T> implements IDeref<T> {
+    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;
+}
 //# sourceMappingURL=pointer.d.ts.map

package/pointer.js

@@ -25,3 +25,30 @@ export class Pointer {
         return this.fn(this.addr);
     }
 }
+/**
+ * Generic pointer facility for {@link WASM64} target, which on
+ * {@link Pointer64.deref()} calls wrapper function (provided as ctor arg) to
+ * realise the pointer's target value. The pointer's target address can be
+ * accessed via {@link Pointer.addr} (read/write).
+ *
+ * @remarks
+ * 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.
+ */
+export class Pointer64 {
+    constructor(mem, base, fn) {
+        this.mem = mem;
+        this.base = base;
+        this.fn = fn;
+    }
+    get addr() {
+        return this.mem.u64[Number(this.base >> BigInt(3))];
+    }
+    set addr(addr) {
+        this.mem.u64[Number(this.base >> BigInt(3))] = addr;
+    }
+    deref() {
+        return this.fn(this.addr);
+    }
+}

package/string.d.ts

@@ -1,8 +1,9 @@
-import type { IWasmMemoryAccess, ReadonlyWasmString } from "./api.js";
+import type { IWasmMemoryAccess, MemorySlice, ReadonlyWasmString } from "./api.js";
 /**
  * Memory mapped string wrapper for Zig-style UTF-8 encoded byte slices (aka
  * pointer & length pair). The actual JS string can be obtained via
- * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ * {@link WasmStringSlice.deref} and possibly mutated via
+ * {@link WasmStringSlice.set}.
  *
  * @remarks
  * Currently only supports wasm32 target, need alt. solution for 64bit (possibly
@@ -11,9 +12,10 @@ import type { IWasmMemoryAccess, ReadonlyWasmString } from "./api.js";
 export declare class WasmStringSlice implements ReadonlyWasmString {
     readonly mem: IWasmMemoryAccess;
     readonly base: number;
-    readonly isConst: boolean;
-    readonly max: number;
-    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean);
+    protected isConst: boolean;
+    protected terminated: boolean;
+    protected maxLen: number;
+    constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean, terminated?: boolean);
     /**
      * Returns string start address (deref'd pointer).
      */
@@ -48,23 +50,42 @@ export declare class WasmStringSlice implements ReadonlyWasmString {
     /**
      * Sets the slice itself to the new values provided.
      *
-     * @param addr
-     * @param len
+     * @param slice
+     * @param terminated
+     */
+    setSlice(slice: MemorySlice, terminated: boolean): MemorySlice;
+    setSlice(addr: number, len: number, terminated: boolean): MemorySlice;
+    /**
+     * Encodes given string to UTF-8 (by default zero terminated), allocates
+     * memory for it, updates this slice and returns a {@link MemorySlice} of
+     * the allocated region.
+     *
+     * @remarks
+     * If `terminated` is true, the stored slice length will **NOT** include the
+     * sentinel! E.g. the slice length of zero-terminated string `"abc"` is 3,
+     * but the number of allocated bytes is 4. This is done for compatibility
+     * with Zig's sentinel-terminated slice handling (e.g. `[:0]u8` slices).
+     *
+     * Regardless of `terminated` setting, the returned `MemorySlice` **always**
+     * covers the entire allocated region!
+     *
+     * @param str
+     * @param terminate
      */
-    setSlice(addr: number, len: number): void;
+    setAlloc(str: string, terminate?: boolean): MemorySlice;
     toJSON(): string;
     toString(): string;
     valueOf(): string;
 }
 /**
- * Memory mapped string wrapper for C-style UTF-8 encoded and zero-terminated
- * char pointers. The actual JS string can be obtained via
+ * 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}.
  */
 export declare class WasmStringPtr implements ReadonlyWasmString {
     readonly mem: IWasmMemoryAccess;
     readonly base: number;
-    readonly isConst: boolean;
+    protected isConst: boolean;
     constructor(mem: IWasmMemoryAccess, base: number, isConst?: boolean);
     /**
      * Returns string start address (deref'd pointer).
@@ -81,10 +102,11 @@ export declare class WasmStringPtr implements ReadonlyWasmString {
      */
     deref(): string;
     /**
-     * If given a JS string as arg (and if not a const pointer), attempts to
-     * overwrite this wrapped string's memory with bytes from given string. If
-     * given another {@link WasmStringPtr}, it merely overrides the pointer to
-     * the new one (always succeeds).
+     * If given a JS string as arg (and if this `WasmStringPtr` instance itself
+     * is not a `const` pointer), attempts to overwrite this wrapped string's
+     * memory with bytes from given string. If given another
+     * {@link WasmStringPtr}, it merely overrides the pointer to the new one
+     * (always succeeds).
      *
      * @remarks
      * Unlike with {@link WasmStringSlice.set} this implementation which
@@ -100,6 +122,17 @@ export declare class WasmStringPtr implements ReadonlyWasmString {
      * @param str
      */
     set(str: string | WasmStringPtr): void;
+    /**
+     * Encodes given string to UTF-8 (by default zero terminated), allocates
+     * memory for it, updates this pointer to new address and returns allocated
+     * {@link MemorySlice}.
+     *
+     * @remarks
+     * See {@link WasmStringSlice.setAlloc} for important details.
+     *
+     * @param str
+     */
+    setAlloc(str: string): MemorySlice;
     toJSON(): string;
     toString(): string;
     valueOf(): string;

package/string.js

@@ -1,19 +1,22 @@
+import { isNumber } from "@thi.ng/checks/is-number";
 import { unsupported } from "@thi.ng/errors/unsupported";
 /**
  * Memory mapped string wrapper for Zig-style UTF-8 encoded byte slices (aka
  * pointer & length pair). The actual JS string can be obtained via
- * {@link WasmStringSlice.deref} and mutated via {@link WasmStringSlice.set}.
+ * {@link WasmStringSlice.deref} and possibly mutated via
+ * {@link WasmStringSlice.set}.
  *
  * @remarks
  * Currently only supports wasm32 target, need alt. solution for 64bit (possibly
  * diff implementation) using bigint addresses (TODO)
  */
 export class WasmStringSlice {
-    constructor(mem, base, isConst = true) {
+    constructor(mem, base, isConst = true, terminated = true) {
         this.mem = mem;
         this.base = base;
         this.isConst = isConst;
-        this.max = this.length;
+        this.terminated = terminated;
+        this.maxLen = this.length;
     }
     /**
      * Returns string start address (deref'd pointer).
@@ -58,23 +61,44 @@ export class WasmStringSlice {
         if (typeof str === "string") {
             if (this.isConst)
                 unsupported("can't mutate const string");
-            this.mem.u32[(this.base + 4) >>> 2] = this.mem.setString(str, this.addr, this.max + 1, true);
+            this.mem.u32[(this.base + 4) >>> 2] = this.mem.setString(str, this.addr, this.maxLen + ~~this.terminated, this.terminated);
         }
         else {
             this.mem.u32[this.base >>> 2] = str.addr;
             this.mem.u32[(this.base + 4) >>> 2] = str.length;
         }
     }
+    setSlice(...args) {
+        this.mem.ensureMemory();
+        const [slice, terminated] = ((isNumber(args[0])
+            ? [[args[0], args[1]], args[2]]
+            : [args[0], args[1]]));
+        this.mem.u32[this.base >>> 2] = slice[0];
+        this.mem.u32[(this.base + 4) >>> 2] = slice[1];
+        this.terminated = terminated;
+        return slice;
+    }
     /**
-     * Sets the slice itself to the new values provided.
+     * Encodes given string to UTF-8 (by default zero terminated), allocates
+     * memory for it, updates this slice and returns a {@link MemorySlice} of
+     * the allocated region.
      *
-     * @param addr
-     * @param len
+     * @remarks
+     * If `terminated` is true, the stored slice length will **NOT** include the
+     * sentinel! E.g. the slice length of zero-terminated string `"abc"` is 3,
+     * but the number of allocated bytes is 4. This is done for compatibility
+     * with Zig's sentinel-terminated slice handling (e.g. `[:0]u8` slices).
+     *
+     * Regardless of `terminated` setting, the returned `MemorySlice` **always**
+     * covers the entire allocated region!
+     *
+     * @param str
+     * @param terminate
      */
-    setSlice(addr, len) {
-        this.mem.ensureMemory();
-        this.mem.u32[this.base >>> 2] = addr;
-        this.mem.u32[(this.base + 4) >>> 2] = len;
+    setAlloc(str, terminate = true) {
+        const slice = __alloc(this.mem, str, terminate);
+        this.setSlice(terminate ? [slice[0], slice[1] - 1] : slice, terminate);
+        return slice;
     }
     toJSON() {
         return this.deref();
@@ -87,8 +111,8 @@ export class WasmStringSlice {
     }
 }
 /**
- * Memory mapped string wrapper for C-style UTF-8 encoded and zero-terminated
- * char pointers. The actual JS string can be obtained via
+ * 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}.
  */
 export class WasmStringPtr {
@@ -124,10 +148,11 @@ export class WasmStringPtr {
         return this.mem.getString(this.addr, this.length);
     }
     /**
-     * If given a JS string as arg (and if not a const pointer), attempts to
-     * overwrite this wrapped string's memory with bytes from given string. If
-     * given another {@link WasmStringPtr}, it merely overrides the pointer to
-     * the new one (always succeeds).
+     * If given a JS string as arg (and if this `WasmStringPtr` instance itself
+     * is not a `const` pointer), attempts to overwrite this wrapped string's
+     * memory with bytes from given string. If given another
+     * {@link WasmStringPtr}, it merely overrides the pointer to the new one
+     * (always succeeds).
      *
      * @remarks
      * Unlike with {@link WasmStringSlice.set} this implementation which
@@ -152,8 +177,24 @@ export class WasmStringPtr {
         }
         else {
             this.addr = str.addr;
+            this.isConst = str.isConst;
         }
     }
+    /**
+     * Encodes given string to UTF-8 (by default zero terminated), allocates
+     * memory for it, updates this pointer to new address and returns allocated
+     * {@link MemorySlice}.
+     *
+     * @remarks
+     * See {@link WasmStringSlice.setAlloc} for important details.
+     *
+     * @param str
+     */
+    setAlloc(str) {
+        const slice = __alloc(this.mem, str, true);
+        this.mem.u32[this.base >>> 2] = slice[0];
+        return slice;
+    }
     toJSON() {
         return this.deref();
     }
@@ -164,3 +205,12 @@ export class WasmStringPtr {
         return this.deref();
     }
 }
+const __alloc = (mem, str, terminate) => {
+    const buf = new TextEncoder().encode(str);
+    const slice = mem.allocate(buf.length + ~~terminate);
+    if (slice[1] > 0) {
+        mem.u8.set(buf, slice[0]);
+        terminate && (mem.u8[slice[0] + buf.length] = 0);
+    }
+    return slice;
+};

package/zig/lib.zig

@@ -2,38 +2,11 @@
 
 const std = @import("std");
 const root = @import("root");
+const types = @import("types.zig");
 
-pub const ManagedIndex = @import("managed-index.zig").ManagedIndex;
-
-/// 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).*;
-        }
-    };
-}
+pub usingnamespace types;
 
-/// []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);
-}
+pub const ManagedIndex = @import("managed-index.zig").ManagedIndex;
 
 /// Similar to @ptrCast intrinsic. Helper function to cast & re-align an
 /// optional `anyopaque` pointer to another given pointer type.
@@ -197,8 +170,10 @@ pub fn printF64Array(buf: []const f64) void {
     _printF64Array(buf.ptr, buf.len);
 }
 
+pub extern "wasmapi" fn printHexdump(addr: *const anyopaque, len: usize) void;
+
 /// Prints a zero-terminated string using configured JS logger
-pub extern "wasmapi" fn _printStr0(addr: [*]const u8) void;
+pub extern "wasmapi" fn printStrZ(addr: [*:0]const u8) void;
 /// Prints a string of given length using configured JS logger
 pub extern "wasmapi" fn _printStr(addr: [*]const u8, len: usize) void;
 /// Convenience wrapper for _printStr, accepting a slice as arg

package/zig/types.zig

@@ -0,0 +1,52 @@
+//! 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);
+}

package/bin/wasm-api

@@ -1,12 +0,0 @@
-#!/usr/bin/env bash
-
-# https://stackoverflow.com/a/246128/294515
-SOURCE="${BASH_SOURCE[0]}"
-while [ -h "$SOURCE" ]; do
-  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
-  SOURCE="$(readlink "$SOURCE")"
-  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
-done
-DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
-
-/usr/bin/env node "$DIR/../cli.js" "$DIR" "$@"

package/bin/wasm-api.mjs_

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-
-import { spawn } from "child_process";
-import { realpathSync } from "fs";
-import { join } from "path";
-const [node, toolsDir, ...args] = process.argv;
-
-const cli = join(realpathSync(toolsDir), "..", "..", "cli.js");
-
-const child = spawn(node, ["--loader", "ts-node/esm", cli, ...args]);
-
-child.stderr.on("data", (d) => {
-	const dStr = d.toString().trim();
-	!dStr.includes("ExperimentalWarning") ? console.log(dStr) : "";
-});
-child.on("exit", (err) => process.exit(err));
-child.stdout.pipe(process.stdout);

package/cli.d.ts

@@ -1,5 +0,0 @@
-export declare const INSTALL_DIR: string;
-export declare const PKG: any;
-export declare const APP_NAME: any;
-export declare const HEADER: string;
-//# sourceMappingURL=cli.d.ts.map