@thi.ng/wasm-api 0.13.1 → 0.15.0

package/codegen/zig.js

@@ -2,7 +2,7 @@ import { isNumber } from "@thi.ng/checks/is-number";
 import { isString } from "@thi.ng/checks/is-string";
 import { unsupported } from "@thi.ng/errors/unsupported";
 import { split } from "@thi.ng/strings/split";
-import { enumName, isPadding, isStringSlice, prefixLines, withIndentation, } from "./utils.js";
+import { enumName, isPadding, isStringSlice, isWasmString, prefixLines, withIndentation, } from "./utils.js";
 /**
  * Zig code generator. Call with options and then pass to {@link generateTypes}
  * (see its docs for further usage).
@@ -45,75 +45,99 @@ export const ZIG = (opts = {}) => {
             acc.push(...withIndentation(lines, INDENT, ...SCOPES));
         },
         struct: (struct, _, acc, opts) => {
-            const name = struct.name;
-            const res = [];
-            res.push(`pub const ${name} = ${struct.tag ? struct.tag + " " : ""}struct {`);
-            const ftypes = {};
-            let padID = 0;
-            for (let f of struct.fields) {
-                // autolabel explicit padding fields
-                if (isPadding(f)) {
-                    res.push(`__pad${padID++}: [${f.pad}]u8,`);
-                    continue;
-                }
-                f.doc && gen.doc(f.doc, res, opts);
-                let ftype = f.type === "string"
-                    ? isStringSlice(opts.stringType)
-                        ? f.const !== false
-                            ? "[]const u8"
-                            : "[]u8"
-                        : f.const !== false
-                            ? "[*:0]const u8"
-                            : "[*:0]u8"
-                    : f.type;
-                let defaultVal = "";
-                switch (f.tag) {
-                    case "array":
-                        ftype =
-                            f.sentinel !== undefined
-                                ? `[${f.len}:${f.sentinel}]${ftype}`
-                                : `[${f.len}]${ftype}`;
-                        break;
-                    case "slice":
-                        ftype = `[${f.sentinel !== undefined ? ":" + f.sentinel : ""}]${f.const ? "const " : ""}${ftype}`;
-                        break;
-                    case "vec":
-                        ftype = `@Vector(${f.len}, ${ftype})`;
-                        break;
-                    case "ptr":
-                        ftype = `*${f.const ? "const " : ""}${f.len ? `[${f.len}]` : ""}${ftype}`;
-                        break;
-                    case "scalar":
-                    default:
-                        if (f.default != undefined) {
-                            if (!(isString(f.default) || isNumber(f.default))) {
-                                unsupported(`wrong default value for ${name}.${f.name} (${f.default})`);
-                            }
-                            defaultVal = ` = ${JSON.stringify(f.default)}`;
-                        }
-                }
-                ftypes[f.name] = ftype;
-                res.push(`${f.name}: ${ftype}${defaultVal},`);
-            }
-            if (struct.body?.zig) {
-                res.push("", ...split(struct.body.zig), "");
-            }
-            res.push("};");
-            if (opts.debug) {
-                const fn = (fname, body) => res.push("", `export fn ${name}_${fname}() usize {`, `return ${body};`, `}`);
-                fn("align", `@alignOf(${name})`);
-                fn("size", `@sizeOf(${name})`);
-                for (let f of struct.fields) {
-                    if (isPadding(f))
-                        continue;
-                    fn(f.name + "_align", `@alignOf(${ftypes[f.name]})`);
-                    fn(f.name + "_offset", `@offsetOf(${name}, "${f.name}")`);
-                    fn(f.name + "_size", `@sizeOf(${ftypes[f.name]})`);
-                }
-            }
-            res.push("");
-            acc.push(...withIndentation(res, INDENT, ...SCOPES));
+            acc.push(...withIndentation([
+                `pub const ${struct.name} = ${struct.tag ? struct.tag + " " : ""}struct {`,
+                ...__generateFields(gen, struct, opts),
+            ], INDENT, ...SCOPES));
+        },
+        union: (union, _, acc, opts) => {
+            acc.push(...withIndentation([
+                `pub const ${union.name} = ${union.tag ? union.tag + " " : ""}union {`,
+                ...__generateFields(gen, union, opts),
+            ], INDENT, ...SCOPES));
         },
     };
     return gen;
 };
+const __generateFields = (gen, parent, opts) => {
+    const res = [];
+    const ftypes = {};
+    const isUnion = parent.type === "union";
+    const name = parent.name;
+    let padID = 0;
+    for (let f of parent.fields) {
+        // autolabel explicit padding fields
+        if (isPadding(f)) {
+            parent.tag === "packed"
+                ? __packedPadding(padID, f.pad, res)
+                : res.push(`__pad${padID}: [${f.pad}]u8,`);
+            padID++;
+            continue;
+        }
+        f.doc && gen.doc(f.doc, res, opts);
+        let ftype = isWasmString(f.type)
+            ? isStringSlice(opts.stringType)
+                ? f.const !== false
+                    ? "[]const u8"
+                    : "[]u8"
+                : f.const !== false
+                    ? "[*:0]const u8"
+                    : "[*:0]u8"
+            : f.type;
+        let defaultVal = "";
+        switch (f.tag) {
+            case "array":
+                ftype =
+                    f.sentinel !== undefined
+                        ? `[${f.len}:${f.sentinel}]${ftype}`
+                        : `[${f.len}]${ftype}`;
+                break;
+            case "slice":
+                ftype = `[${f.sentinel !== undefined ? ":" + f.sentinel : ""}]${f.const ? "const " : ""}${ftype}`;
+                break;
+            case "vec":
+                ftype = `@Vector(${f.len}, ${ftype})`;
+                break;
+            case "ptr":
+                ftype = `*${f.const ? "const " : ""}${f.len ? `[${f.len}]` : ""}${ftype}`;
+                break;
+            case "scalar":
+            default:
+                if (f.default != undefined) {
+                    if (!(isString(f.default) || isNumber(f.default))) {
+                        unsupported(`wrong default value for ${name}.${f.name} (${f.default})`);
+                    }
+                    defaultVal = ` = ${JSON.stringify(f.default)}`;
+                }
+        }
+        ftypes[f.name] = ftype;
+        res.push(`${f.name}: ${ftype}${defaultVal},`);
+    }
+    if (parent.body?.zig) {
+        res.push("", ...split(parent.body.zig), "");
+    }
+    res.push("};");
+    if (opts.debug) {
+        const fn = (fname, body) => res.push("", `export fn ${name}_${fname}() usize {`, `return ${body};`, `}`);
+        fn("align", `@alignOf(${name})`);
+        fn("size", `@sizeOf(${name})`);
+        for (let f of parent.fields) {
+            if (isPadding(f))
+                continue;
+            fn(f.name + "_align", `@alignOf(${ftypes[f.name]})`);
+            !isUnion &&
+                fn(f.name + "_offset", `@offsetOf(${name}, "${f.name}")`);
+            fn(f.name + "_size", `@sizeOf(${ftypes[f.name]})`);
+        }
+    }
+    res.push("");
+    return res;
+};
+const __packedPadding = (id, n, res) => {
+    let i = 0;
+    n <<= 3;
+    for (; n >= 128; n -= 128, i++) {
+        res.push(`__pad${id}_${i}: u128,`);
+    }
+    res.push(`__pad${id}_${i}: u${n},`);
+};

package/codegen.d.ts

@@ -1,4 +1,5 @@
 import { CodeGenOpts, ICodeGen, TypeColl } from "./api.js";
+export declare const DEFAULT_CODEGEN_OPTS: CodeGenOpts;
 /**
  * Takes a type collection and analyzes each analyzed to compute individual
  * alignments and sizes.
@@ -11,7 +12,7 @@ import { CodeGenOpts, ICodeGen, TypeColl } from "./api.js";
  *
  * @internal
  */
-export declare const prepareTypes: (types: TypeColl, opts: CodeGenOpts) => void;
+export declare const prepareTypes: (types: TypeColl, opts: CodeGenOpts) => TypeColl;
 /**
  * Code generator main entry point. Takes an object of {@link TopLevelType}
  * definitions, an actual code generator implementation for a single target

package/codegen.js

@@ -1,14 +1,21 @@
 import { SIZEOF } from "@thi.ng/api/typedarray";
-import { align } from "@thi.ng/binary/align";
-import { ceilPow2 } from "@thi.ng/binary/pow";
 import { compareByKey } from "@thi.ng/compare/keys";
 import { compareNumDesc } from "@thi.ng/compare/numeric";
 import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
 import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
-import { PKG_NAME, USIZE_SIZE, } from "./api.js";
-import { isNumeric, isWasmString } from "./codegen/utils.js";
+import { PKG_NAME, WASM32, } from "./api.js";
+import { selectAlignment } from "./codegen/align.js";
+import { isBigNumeric, isNumeric, isPointer, isPointerLike, isSlice, isStringSlice, isWasmString, } from "./codegen/utils.js";
+export const DEFAULT_CODEGEN_OPTS = {
+    debug: false,
+    header: true,
+    lineWidth: 80,
+    stringType: "slice",
+    target: WASM32,
+    uppercaseEnums: true,
+};
 const sizeOf = defmulti((x) => x.type, {}, {
-    [DEFAULT]: (field, types, opts) => {
+    [DEFAULT]: (field, types, align, opts) => {
         if (field.__size)
             return field.__size;
         if (field.pad != null) {
@@ -16,18 +23,20 @@ const sizeOf = defmulti((x) => x.type, {}, {
             return (field.__size = field.pad);
         }
         let size = 0;
-        if (field.tag === "ptr") {
-            size = USIZE_SIZE;
+        if (isPointer(field)) {
+            size = opts.target.usizeBytes;
         }
-        else if (field.tag === "slice") {
-            size = USIZE_SIZE * 2;
+        else if (isSlice(field)) {
+            size = opts.target.usizeBytes * 2;
         }
         else {
-            size = isNumeric(field.type)
-                ? SIZEOF[field.type]
-                : isWasmString(field.type)
-                    ? USIZE_SIZE * (opts.stringType === "slice" ? 2 : 1)
-                    : sizeOf(types[field.type], types, opts);
+            size =
+                isNumeric(field.type) || isBigNumeric(field.type)
+                    ? SIZEOF[field.type]
+                    : isWasmString(field.type)
+                        ? opts.target.usizeBytes *
+                            (isStringSlice(opts.stringType) ? 2 : 1)
+                        : sizeOf(types[field.type], types, align, opts);
             if (field.tag == "array" || field.tag === "vec") {
                 size *= field.len;
                 if (field.sentinel !== undefined && field.tag === "array") {
@@ -35,79 +44,95 @@ const sizeOf = defmulti((x) => x.type, {}, {
                 }
             }
         }
-        return (field.__size = align(size, field.__align));
+        return (field.__size = align.size(size, field.__align));
     },
     enum: (type) => {
         if (type.__size)
             return type.__size;
         return (type.__size = SIZEOF[type.tag]);
     },
-    struct: (type, types, opts) => {
+    struct: (type, types, align, opts) => {
         if (type.__size)
             return type.__size;
-        const struct = type;
-        let size = 0;
-        for (let f of struct.fields) {
-            size = align(size, f.__align);
-            f.__offset = size;
-            size += sizeOf(f, types, opts);
+        let offset = 0;
+        for (let f of type.fields) {
+            offset = align.offset(offset, f.__align);
+            f.__offset = offset;
+            offset += sizeOf(f, types, align, opts);
+        }
+        return (type.__size = align.size(offset, type.__align));
+    },
+    union: (type, types, align, opts) => {
+        if (type.__size)
+            return type.__size;
+        let maxSize = 0;
+        for (let f of type.fields) {
+            f.__offset = 0;
+            maxSize = Math.max(maxSize, sizeOf(f, types, align, opts));
         }
-        return (type.__size = align(size, type.__align));
+        return (type.__size = align.size(maxSize, type.__align));
     },
 });
 const alignOf = defmulti((x) => x.type, {}, {
-    [DEFAULT]: (field, types) => {
+    [DEFAULT]: (field, types, align, opts) => {
         if (field.__align)
             return field.__align;
+        if (field.type === "usize") {
+            field.type = opts.target.usize;
+        }
         if (field.pad)
             return (field.__align = 1);
-        let align = isNumeric(field.type)
-            ? SIZEOF[field.type]
-            : isWasmString(field.type)
-                ? USIZE_SIZE
-                : alignOf(types[field.type], types);
-        if (field.tag === "vec") {
-            align *= ceilPow2(field.len);
-        }
-        field.__align = align;
-        return align;
+        return (field.__align = isPointerLike(field)
+            ? align.align({ type: opts.target.usize })
+            : isNumeric(field.type) || isBigNumeric(field.type)
+                ? align.align(field)
+                : alignOf(types[field.type], types, selectAlignment(types[field.type]), opts));
     },
-    enum: (type) => {
+    enum: (type, _, align) => {
         const e = type;
         if (!e.tag)
             e.tag = "i32";
-        return (e.__align = SIZEOF[e.tag]);
+        return (e.__align = align.align({
+            type: e.tag,
+        }));
     },
-    struct: (type, types) => {
-        const struct = type;
-        let maxAlign = 0;
-        for (let f of struct.fields) {
-            maxAlign = Math.max(maxAlign, alignOf(f, types));
+    struct: (type, types, align, opts) => {
+        let maxAlign = 1;
+        for (let f of type.fields) {
+            maxAlign = Math.max(maxAlign, alignOf(f, types, align, opts));
+        }
+        return (type.__align = maxAlign);
+    },
+    union: (type, types, align, opts) => {
+        let maxAlign = 1;
+        for (let f of type.fields) {
+            maxAlign = Math.max(maxAlign, alignOf(f, types, align, opts));
         }
         return (type.__align = maxAlign);
     },
 });
 const prepareType = defmulti((x) => x.type, {}, {
-    [DEFAULT]: (x, types, opts) => {
+    [DEFAULT]: (x, types, alignImpl, opts) => {
         if (x.__align && x.__size)
             return;
-        alignOf(x, types);
-        sizeOf(x, types, opts);
+        alignOf(x, types, alignImpl, opts);
+        sizeOf(x, types, alignImpl, opts);
     },
-    struct: (x, types, opts) => {
+    struct: (x, types, align, opts) => {
         if (x.__align && x.__size)
             return;
         const struct = x;
-        alignOf(struct, types);
+        alignOf(struct, types, align, opts);
         if (struct.auto) {
             struct.fields.sort(compareByKey("__align", compareNumDesc));
         }
         for (let f of struct.fields) {
-            if (types[f.type]) {
-                prepareType(types[f.type], types, opts);
+            const type = types[f.type];
+            if (type) {
+                prepareType(type, types, selectAlignment(type), opts);
             }
         }
-        sizeOf(struct, types, opts);
+        sizeOf(struct, types, align, opts);
     },
 });
 /**
@@ -124,8 +149,9 @@ const prepareType = defmulti((x) => x.type, {}, {
  */
 export const prepareTypes = (types, opts) => {
     for (let id in types) {
-        prepareType(types[id], types, opts);
+        prepareType(types[id], types, selectAlignment(types[id]), opts);
     }
+    return types;
 };
 /**
  * Code generator main entry point. Takes an object of {@link TopLevelType}
@@ -144,10 +170,7 @@ export const prepareTypes = (types, opts) => {
  */
 export const generateTypes = (types, codegen, opts = {}) => {
     const $opts = {
-        header: true,
-        stringType: "slice",
-        uppercaseEnums: true,
-        lineWidth: 80,
+        ...DEFAULT_CODEGEN_OPTS,
         ...opts,
     };
     prepareTypes(types, $opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Generic, modular, extensible API bridge, polyglot glue code and bindings code generators for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -33,26 +33,26 @@
     "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 include/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/wasmapi.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test"
   },
   "dependencies": {
     "@thi.ng/api": "^8.4.3",
-    "@thi.ng/args": "^2.2.4",
-    "@thi.ng/binary": "^3.3.6",
-    "@thi.ng/checks": "^3.2.6",
+    "@thi.ng/args": "^2.2.6",
+    "@thi.ng/binary": "^3.3.7",
+    "@thi.ng/checks": "^3.3.1",
     "@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.16",
     "@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.19",
     "@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,9 @@
     "*.js",
     "*.d.ts",
     "bin",
+    "codegen",
     "include",
-    "codegen"
+    "zig"
   ],
   "exports": {
     ".": {
@@ -107,6 +109,9 @@
     "./bridge": {
       "default": "./bridge.js"
     },
+    "./codegen/align": {
+      "default": "./codegen/align.js"
+    },
     "./codegen/c11": {
       "default": "./codegen/c11.js"
     },
@@ -136,5 +141,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "c3f7d6598c7d7d0c61ba87150a56deac12649d7b\n"
+  "gitHead": "cc61bc0a890288bea00b8df81ffd73bc4851ffd3\n"
 }

package/string.d.ts

@@ -3,6 +3,10 @@ import type { IWasmMemoryAccess, 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}.
+ *
+ * @remarks
+ * Currently only supports wasm32 target, need alt. solution for 64bit (possibly
+ * diff implementation) using bigint addresses (TODO)
  */
 export declare class WasmStringSlice implements ReadonlyWasmString {
     readonly mem: IWasmMemoryAccess;

package/string.js

@@ -3,6 +3,10 @@ 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}.
+ *
+ * @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) {
@@ -15,12 +19,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 +54,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 +72,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 +101,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 +147,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 {