@thi.ng/wasm-api 0.14.0 → 0.15.0

package/api.d.ts

@@ -1,4 +1,5 @@
-import type { BigType, FloatType, Fn, IDeref, ILength, IObjectOf } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, Fn2, IDeref, ILength, IObjectOf } from "@thi.ng/api";
+import type { Pow2 } from "@thi.ng/binary";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
@@ -124,8 +125,12 @@ export interface IWasmMemoryAccess {
 }
 /**
  * Core API of WASM imports defined by the {@link WasmBridge}. The same
- * functions are declared as bindings in `/zig/core.zig`. Also see this file for
- * documentation of each function...
+ * functions are declared as bindings in `/zig/wasmapi.zig`. **Also see this
+ * file for documentation of each function...**
+ *
+ * @remarks
+ * Zig API:
+ * https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/wasmapi.zig
  */
 export interface CoreAPI extends WebAssembly.ModuleImports {
     printI8: Fn<number, void>;
@@ -192,17 +197,17 @@ export interface TypeInfo {
      */
     __size?: number;
     /**
-     * Auto-computed offset (in bytes) in parent struct
+     * Auto-computed offset (in bytes) in parent struct.
      *
      * @internal
      */
     __offset?: number;
     /**
-     * Auto-computed alignment (in bytes)
+     * Auto-computed alignment (in bytes) actually used.
      *
      * @internal
      */
-    __align?: number;
+    __align?: Pow2;
 }
 export interface TopLevelType extends TypeInfo {
     /**
@@ -216,7 +221,7 @@ export interface TopLevelType extends TypeInfo {
     /**
      * Type / kind
      */
-    type: "struct" | "enum";
+    type: "enum" | "struct" | "union";
     /**
      * Optional object of user provided source codes to be injected into the
      * generated type. Keys are language IDs (same name as respective codegen).
@@ -229,10 +234,10 @@ export interface TopLevelType extends TypeInfo {
 export interface Struct extends TopLevelType {
     type: "struct";
     /**
-     * List of struct fields (might be re-ordered if {@link Struct.auto} is
+     * Array of struct fields (might be re-ordered if {@link Struct.auto} is
      * enabled).
      */
-    fields: StructField[];
+    fields: Field[];
     /**
      * If true, struct fields will be re-ordered in descending order based on
      * their {@link TypeInfo.__align} size. This might result in overall smaller
@@ -248,8 +253,14 @@ export interface Struct extends TopLevelType {
      * interpretation, currently only used by {@link ZIG}).
      */
     tag?: "extern" | "packed";
+    /**
+     * Optional user supplied {@link AlignStrategy}. By default uses
+     * {@link ALIGN_C} or {@link ALIGN_PACKED} (if using "packed" structs).
+     */
+    align?: AlignStrategy;
 }
-export interface StructField extends TypeInfo {
+export declare type FieldTag = "scalar" | "array" | "ptr" | "slice" | "vec";
+export interface Field extends TypeInfo {
     /**
      * Field name (prefix: "__" is reserved)
      */
@@ -264,7 +275,7 @@ export interface StructField extends TypeInfo {
      *
      * @remarks
      * - Array & vector fields are statically sized (using
-     *   {@link StructField.len})
+     *   {@link Field.len})
      * - Pointers are emitted as single-value pointers (where this distinction
      *   exist), i.e. even if they're pointing to multiple values, there's no
      *   explicit length encoded/available
@@ -274,7 +285,7 @@ export interface StructField extends TypeInfo {
      *
      * @defaultValue "scalar"
      */
-    tag?: "scalar" | "array" | "ptr" | "slice" | "vec";
+    tag?: FieldTag;
     /**
      * Field base type. If not a {@link WasmPrim}, `string` or `opaque`, the
      * value is interpreted as another type name in the {@link TypeColl}.
@@ -297,7 +308,7 @@ export interface StructField extends TypeInfo {
      */
     sentinel?: number;
     /**
-     * Array or vector length (see {@link StructField.tag})
+     * Array or vector length (see {@link Field.tag})
      */
     len?: number;
     /**
@@ -306,11 +317,29 @@ export interface StructField extends TypeInfo {
      */
     default?: number;
     /**
-     * If defined and > 0, the field will be considered for padding purposes only and
-     * the value provided is the number of bytes used.
+     * If defined and > 0, the field will be considered for padding purposes
+     * only and the value provided is the number of bytes used. All other config
+     * for this field will be ignored!
      */
     pad?: number;
 }
+export interface Union extends TopLevelType {
+    type: "union";
+    /**
+     * Array of union fields.
+     */
+    fields: Field[];
+    /**
+     * Optional qualifier for the kind of struct to be emitted (codegen specific
+     * interpretation, currently only used by {@link ZIG}).
+     */
+    tag?: "extern" | "packed";
+    /**
+     * Optional user supplied {@link AlignStrategy}. By default uses
+     * {@link ALIGN_C} or {@link ALIGN_PACKED} (if using "packed" union).
+     */
+    align?: AlignStrategy;
+}
 export interface Enum extends TopLevelType {
     type: "enum";
     /**
@@ -340,22 +369,42 @@ export interface EnumValue {
      */
     doc?: string;
 }
+export interface AlignStrategy {
+    /**
+     * Returns implementation specific alignment for given struct field.
+     */
+    align: Fn<Field, Pow2>;
+    /**
+     * Returns possibly rounded value for given base size & alignment.
+     */
+    size: Fn2<number, Pow2, number>;
+    /**
+     * Returns possibly rounded value for given base offset & alignment.
+     */
+    offset: Fn2<number, Pow2, number>;
+}
 export interface CodeGenOptsBase {
     /**
      * Optional string to be injected before generated type defs (but after
      * codegen's own prelude, if any)
      */
-    pre: string;
+    pre?: string;
     /**
      * Optional string to be injected after generated type defs (but before
      * codegen's own epilogue, if any)
      */
-    post: string;
+    post?: string;
 }
 /**
  * Global/shared code generator options.
  */
 export interface CodeGenOpts extends CodeGenOptsBase {
+    /**
+     * WASM target specification.
+     *
+     * @defaultValue {@link WASM32}
+     */
+    target: WasmTarget;
     /**
      * Identifier how strings are stored on WASM side, e.g. in Zig string
      * literals are slices (8 bytes), in C just plain pointers (4 bytes).
@@ -409,13 +458,21 @@ export interface ICodeGen {
      * Codegen for struct types.
      */
     struct: (type: Struct, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
+    /**
+     * Codegen for union types.
+     */
+    union: (type: Union, types: TypeColl, acc: string[], opts: CodeGenOpts) => void;
+}
+export interface WasmTarget {
+    usize: "u32" | "u64";
+    usizeBytes: number;
 }
 /**
- * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ * WASM32 target spec
  */
-export declare const USIZE = "u32";
+export declare const WASM32: WasmTarget;
 /**
- * Byte size of {@link USIZE}.
+ * WASM64 target spec
  */
-export declare const USIZE_SIZE = 4;
+export declare const WASM64: WasmTarget;
 //# sourceMappingURL=api.d.ts.map

package/api.js

@@ -1,10 +1,16 @@
 export const PKG_NAME = "@thi.ng/wasm-api";
 export const EVENT_MEMORY_CHANGED = "memory-changed";
 /**
- * WASM usize type. Assuming wasm32 until wasm64 surfaces, then need an option.
+ * WASM32 target spec
  */
-export const USIZE = "u32";
+export const WASM32 = {
+    usize: "u32",
+    usizeBytes: 4,
+};
 /**
- * Byte size of {@link USIZE}.
+ * WASM64 target spec
  */
-export const USIZE_SIZE = 4;
+export const WASM64 = {
+    usize: "u64",
+    usizeBytes: 8,
+};

package/cli.js

@@ -22,7 +22,11 @@ const argOpts = {
         hint: "FILE",
         desc: "JSON config file with codegen options",
     }),
-    debug: flag({ alias: "d", default: false, desc: "enable debug output" }),
+    debug: flag({
+        alias: "d",
+        default: false,
+        desc: "enable debug output & functions",
+    }),
     dryRun: flag({
         default: false,
         desc: "enable dry run (don't overwrite files)",
@@ -71,7 +75,7 @@ const invalidSpec = (path, msg) => {
 const addTypeSpec = (ctx, path, coll, spec) => {
     if (!(spec.name && spec.type))
         invalidSpec(path);
-    if (!(spec.type === "enum" || spec.type === "struct"))
+    if (!["enum", "struct", "union"].includes(spec.type))
         invalidSpec(path, `${spec.name} type: ${spec.type}`);
     if (coll[spec.name])
         invalidSpec(path, `duplicate name: ${spec.name}`);

package/codegen/align.d.ts

@@ -0,0 +1,14 @@
+import type { AlignStrategy, TopLevelType } from "../api.js";
+/**
+ * C ABI compatible alignment
+ */
+export declare const ALIGN_C: AlignStrategy;
+export declare const ALIGN_PACKED: AlignStrategy;
+/**
+ * Returns a suitable alignment strategy for given type, either via user
+ * supplied impl defined for the type or derived via a struct's tag.
+ *
+ * @param type
+ */
+export declare const selectAlignment: (type: TopLevelType) => AlignStrategy;
+//# sourceMappingURL=align.d.ts.map

package/codegen/align.js

@@ -0,0 +1,35 @@
+import { SIZEOF } from "@thi.ng/api/typedarray";
+import { align as $align } from "@thi.ng/binary/align";
+import { ceilPow2 } from "@thi.ng/binary/pow";
+/**
+ * C ABI compatible alignment
+ */
+export const ALIGN_C = {
+    align: (field) => {
+        let align = SIZEOF[field.type];
+        if (field.tag === "vec") {
+            align *= ceilPow2(field.len);
+        }
+        return align;
+    },
+    size: (size, align) => $align(size, align),
+    offset: (offset, align) => $align(offset, align),
+};
+export const ALIGN_PACKED = {
+    align: () => 1,
+    size: (size) => size,
+    offset: (offset) => offset,
+};
+/**
+ * Returns a suitable alignment strategy for given type, either via user
+ * supplied impl defined for the type or derived via a struct's tag.
+ *
+ * @param type
+ */
+export const selectAlignment = (type) => {
+    if (type.type === "struct" || type.type === "union") {
+        let $type = type;
+        return $type.align || ($type.tag === "packed" ? ALIGN_PACKED : ALIGN_C);
+    }
+    return ALIGN_C;
+};

package/codegen/c11.js

@@ -1,6 +1,6 @@
 import { isString } from "@thi.ng/checks/is-string";
 import { unsupported } from "@thi.ng/errors/unsupported";
-import { enumName, isPadding, isStringSlice, prefixLines, withIndentation, } from "./utils.js";
+import { enumName, isPadding, isStringSlice, isWasmString, prefixLines, withIndentation, } from "./utils.js";
 const PRIM_ALIASES = {
     i8: "int8_t",
     u8: "uint8_t",
@@ -68,62 +68,78 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
         },
         struct: (struct, coll, acc, opts) => {
             const name = typePrefix + struct.name;
-            const res = [];
-            res.push(`typedef struct ${name} ${name};`, `struct ${name} {`);
-            const ftypes = {};
-            let padID = 0;
-            for (let f of struct.fields) {
-                // autolabel explicit padding fields
-                if (isPadding(f)) {
-                    res.push(`uint8_t __pad${padID++}[${f.pad}];`);
-                    continue;
-                }
-                f.doc && gen.doc(f.doc, res, opts);
-                const fconst = f.const ? "const " : "";
-                let ftype = f.type === "string"
-                    ? isStringSlice(opts.stringType)
-                        ? __slice("char", fconst)
-                        : `${f.const !== false ? "const " : ""}char*`
-                    : PRIM_ALIASES[f.type] || f.type;
-                if (coll[ftype])
-                    ftype = typePrefix + ftype;
-                switch (f.tag) {
-                    case "array":
-                    case "vec":
-                        res.push(`${fconst}${ftype} ${f.name}[${f.len}];`);
-                        ftype = `${ftype}[${f.len}]`;
-                        break;
-                    case "slice":
-                        ftype = __slice(ftype, fconst);
-                        res.push(`${ftype} ${f.name};`);
-                        break;
-                    case "ptr":
-                        ftype = `${fconst}${ftype}*`;
-                        res.push(`${ftype} ${f.name};`);
-                        break;
-                    case "scalar":
-                    default:
-                        res.push(`${ftype} ${f.name};`);
-                }
-                ftypes[f.name] = ftype;
-            }
-            res.push("};");
-            if (opts.debug) {
-                const fn = (fname, body) => res.push("", `size_t __attribute__((used)) ${name}_${fname}() {`, `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([
+                `typedef struct ${name} ${name};`,
+                `struct ${name} {`,
+                ...__generateFields(gen, struct, coll, opts, typePrefix),
+            ], INDENT, ...SCOPES));
+        },
+        union: (union, coll, acc, opts) => {
+            const name = typePrefix + union.name;
+            acc.push(...withIndentation([
+                `typedef union ${name} ${name};`,
+                `union ${name} {`,
+                ...__generateFields(gen, union, coll, opts, typePrefix),
+            ], INDENT, ...SCOPES));
         },
     };
     return gen;
 };
+const __generateFields = (gen, parent, coll, opts, typePrefix) => {
+    const res = [];
+    const ftypes = {};
+    const isUnion = parent.type === "union";
+    const name = typePrefix + parent.name;
+    let padID = 0;
+    for (let f of parent.fields) {
+        // autolabel explicit padding fields
+        if (isPadding(f)) {
+            res.push(`uint8_t __pad${padID++}[${f.pad}];`);
+            continue;
+        }
+        f.doc && gen.doc(f.doc, res, opts);
+        const fconst = f.const ? "const " : "";
+        let ftype = isWasmString(f.type)
+            ? isStringSlice(opts.stringType)
+                ? __slice("char", fconst)
+                : `${f.const !== false ? "const " : ""}char*`
+            : PRIM_ALIASES[f.type] || f.type;
+        if (coll[ftype])
+            ftype = typePrefix + ftype;
+        switch (f.tag) {
+            case "array":
+            case "vec":
+                res.push(`${fconst}${ftype} ${f.name}[${f.len}];`);
+                ftype = `${ftype}[${f.len}]`;
+                break;
+            case "slice":
+                ftype = __slice(ftype, fconst);
+                res.push(`${ftype} ${f.name};`);
+                break;
+            case "ptr":
+                ftype = `${fconst}${ftype}*`;
+                res.push(`${ftype} ${f.name};`);
+                break;
+            case "scalar":
+            default:
+                res.push(`${ftype} ${f.name};`);
+        }
+        ftypes[f.name] = ftype;
+    }
+    res.push("};");
+    if (opts.debug) {
+        const fn = (fname, body) => res.push("", `size_t __attribute__((used)) ${name}_${fname}() {`, `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 __slice = (type, $const) => `struct { ${$const}${type} *ptr; size_t len; }`;

package/codegen/typescript.js

@@ -1,6 +1,6 @@
 import { BIGINT_ARRAY_CTORS, BIT_SHIFTS, TYPEDARRAY_CTORS, } from "@thi.ng/api/typedarray";
 import { isString } from "@thi.ng/checks/is-string";
-import { PKG_NAME, USIZE, USIZE_SIZE, } from "../api.js";
+import { PKG_NAME, } from "../api.js";
 import { enumName, isBigNumeric, isNumeric, isPadding, isStringSlice, isWasmPrim, isWasmString, pointerFields, prefixLines, stringFields, withIndentation, } from "./utils.js";
 /**
  * TypeScript code generator. Call with options and then pass to
@@ -91,7 +91,7 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
                         const fn = f.len
                             ? [
                                 `(addr) => {`,
-                                ...__mapStringArray("buf", $stringImpl, f.len, isConst, true),
+                                ...__mapStringArray(opts.target, "buf", $stringImpl, f.len, isConst, true),
                                 `}`,
                             ]
                             : [
@@ -107,15 +107,15 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
                     }
                 }
                 else if (f.tag === "slice") {
-                    lines.push(`const len = ${__ptr(offset + 4)};`);
+                    lines.push(`const len = ${__ptr(opts.target, offset + 4)};`);
                     if (isPrim) {
-                        lines.push(`const addr = ${__ptrShift(offset, f.type)};`, `return mem.${f.type}.subarray(addr, addr + len);`);
+                        lines.push(`const addr = ${__ptrShift(opts.target, offset, f.type)};`, `return mem.${f.type}.subarray(addr, addr + len);`);
                     }
                     else if (isStr) {
-                        lines.push(`const addr = ${__ptr(offset)};`, ...__mapStringArray("buf", $stringImpl, "len", isConst));
+                        lines.push(`const addr = ${__ptr(opts.target, offset)};`, ...__mapStringArray(opts.target, "buf", $stringImpl, "len", isConst));
                     }
                     else {
-                        lines.push(`const addr = ${__ptr(offset)};`, ...__mapArray(f));
+                        lines.push(`const addr = ${__ptr(opts.target, offset)};`, ...__mapArray(f));
                     }
                 }
                 else if (f.tag === "array" || f.tag === "vec") {
@@ -123,7 +123,7 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
                         lines.push(`const addr = ${__addrShift(offset, f.type)};`, `return mem.${f.type}.subarray(addr, addr + ${f.len});`);
                     }
                     else if (isStr) {
-                        lines.push(`if ($${f.name}) return $${f.name};`, `const addr = ${__addr(offset)};`, ...__mapStringArray(f.name, $stringImpl, f.len, isConst));
+                        lines.push(`if ($${f.name}) return $${f.name};`, `const addr = ${__addr(offset)};`, ...__mapStringArray(opts.target, f.name, $stringImpl, f.len, isConst));
                     }
                     else {
                         lines.push(`const addr = ${__addr(offset)};`, ...__mapArray(f, f.len));
@@ -162,6 +162,9 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
             lines.push("};", "}", "});", "");
             acc.push(...withIndentation(lines, indent, ...SCOPES));
         },
+        union: (type, coll, acc, opts) => {
+            gen.struct(type, coll, acc, opts);
+        },
     };
     return gen;
 };
@@ -201,9 +204,9 @@ const __addrShift = (offset, shift) => {
     return __addr(offset) + (bits ? " >>> " + bits : "");
 };
 /** @internal */
-const __ptr = (offset) => `mem.${USIZE}[${__addrShift(offset, USIZE)}]`;
+const __ptr = (target, offset) => `mem.${target.usize}[${__addrShift(offset, target.usize)}]`;
 /** @internal */
-const __ptrShift = (offset, shift) => __ptr(offset) + " >>> " + __shift(shift);
+const __ptrShift = (target, offset, shift) => __ptr(target, offset) + " >>> " + __shift(shift);
 const __mem = (type, offset) => `mem.${type}[${__addrShift(offset, type)}]`;
 /** @internal */
 const __mapArray = (f, len = "len") => [
@@ -213,8 +216,8 @@ const __mapArray = (f, len = "len") => [
     `return slice;`,
 ];
 /** @internal */
-const __mapStringArray = (name, type, len, isConst, isLocal = false) => [
+const __mapStringArray = (target, name, type, len, isConst, isLocal = false) => [
     isLocal ? `const $${name}: ${type}[] = [];` : `$${name} = [];`,
-    `for(let i = 0; i < ${len}; i++) $${name}.push(new ${type}(mem, addr + i * ${USIZE_SIZE * (type === "WasmStringSlice" ? 2 : 1)}, ${isConst}));`,
+    `for(let i = 0; i < ${len}; i++) $${name}.push(new ${type}(mem, addr + i * ${target.usizeBytes * (type === "WasmStringSlice" ? 2 : 1)}, ${isConst}));`,
     `return $${name};`,
 ];

package/codegen/utils.d.ts

@@ -1,5 +1,5 @@
 import type { BigType } from "@thi.ng/api";
-import type { CodeGenOpts, StructField, WasmPrim, WasmPrim32 } from "../api.js";
+import type { CodeGenOpts, Field, WasmPrim, WasmPrim32 } from "../api.js";
 /**
  * Returns true iff `x` is a {@link WasmPrim32}.
  *
@@ -19,7 +19,15 @@ export declare const isBigNumeric: (x: string) => x is BigType;
  */
 export declare const isWasmPrim: (x: string) => x is WasmPrim;
 export declare const isWasmString: (x: string) => x is "string";
-export declare const isPadding: (f: StructField) => boolean;
+export declare const isPadding: (f: Field) => boolean;
+export declare const isPointer: (f: Field) => boolean;
+export declare const isSlice: (f: Field) => boolean;
+/**
+ * Returns true iff the struct field is a pointer, slice or "string" type
+ *
+ * @param f
+ */
+export declare const isPointerLike: (f: Field) => boolean;
 /**
  * Takes an array of strings or splits given string into lines, word wraps and
  * then prefixes each line with given `width` and `prefix`. Returns array of new
@@ -43,7 +51,7 @@ export declare const isStringSlice: (type: CodeGenOpts["stringType"]) => type is
  *
  * @internal
  */
-export declare const pointerFields: (fields: StructField[]) => StructField[];
+export declare const pointerFields: (fields: Field[]) => Field[];
 /**
  * Returns filtered array of struct fields of only "string" fields.
  *
@@ -51,7 +59,7 @@ export declare const pointerFields: (fields: StructField[]) => StructField[];
  *
  * @internal
  */
-export declare const stringFields: (fields: StructField[]) => StructField[];
+export declare const stringFields: (fields: Field[]) => Field[];
 /**
  * Returns enum identifier formatted according to given opts.
  *

package/codegen/utils.js

@@ -20,6 +20,14 @@ export const isBigNumeric = (x) => /^[iu]64$/.test(x);
 export const isWasmPrim = (x) => isNumeric(x) || isBigNumeric(x);
 export const isWasmString = (x) => x === "string";
 export const isPadding = (f) => f.pad != null && f.pad > 0;
+export const isPointer = (f) => f.tag === "ptr";
+export const isSlice = (f) => f.tag === "slice";
+/**
+ * Returns true iff the struct field is a pointer, slice or "string" type
+ *
+ * @param f
+ */
+export const isPointerLike = (f) => isPointer(f) || isSlice(f) || isWasmString(f.type);
 /**
  * Takes an array of strings or splits given string into lines, word wraps and
  * then prefixes each line with given `width` and `prefix`. Returns array of new