@thi.ng/wasm-api 0.14.0 → 0.16.0

package/codegen/typescript.js

@@ -1,7 +1,8 @@
 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 { enumName, isBigNumeric, isNumeric, isPadding, isStringSlice, isWasmPrim, isWasmString, pointerFields, prefixLines, stringFields, withIndentation, } from "./utils.js";
+import { PKG_NAME, } from "../api.js";
+import { ensureLines, enumName, isBigNumeric, isNumeric, isPadding, isStringSlice, isWasmPrim, isWasmString, pointerFields, prefixLines, stringFields, withIndentation, } from "./utils.js";
+import { fieldType as zigFieldType } from "./zig.js";
 /**
  * TypeScript code generator. Call with options and then pass to
  * {@link generateTypes} (see its docs for further usage).
@@ -22,7 +23,7 @@ export const TYPESCRIPT = (opts = {}) => {
     const SCOPES = [/\{$/, /\}\)?[;,]?$/];
     const gen = {
         pre: (opts) => `// @ts-ignore possibly includes unused imports
-import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } from "${PKG_NAME}";${opts.pre ? `\n${opts.pre}` : ""}`,
+import { MemorySlice, Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } from "${PKG_NAME}";${opts.pre ? `\n${opts.pre}` : ""}`,
         post: () => opts.post || "",
         doc: (doc, acc, opts) => {
             acc.push("/**", ...prefixLines(" * ", doc, opts.lineWidth), " */");
@@ -55,11 +56,15 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
             for (let f of struct.fields) {
                 if (isPadding(f))
                     continue;
-                f.doc && gen.doc(f.doc, lines, opts);
+                const doc = __docType(struct, f, opts);
+                doc && gen.doc(doc, lines, opts);
                 const ftype = __fieldType(f, opts);
                 fieldTypes[f.name] = ftype;
                 lines.push(`${f.name}: ${ftype};`);
             }
+            if (struct.body?.ts) {
+                lines.push("", ...ensureLines(struct.body.ts, "decl"));
+            }
             lines.push("}", "");
             const pointerDecls = pointerFields(struct.fields).map((x) => {
                 return `let $${x.name}: ${fieldTypes[x.name]} | null = null;`;
@@ -91,7 +96,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 +112,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 +128,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));
@@ -159,9 +164,15 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
                 // close field accessor
                 lines.push(`},`);
             }
+            if (struct.body?.ts) {
+                lines.push("", ...ensureLines(struct.body.ts, "impl"), "");
+            }
             lines.push("};", "}", "});", "");
             acc.push(...withIndentation(lines, indent, ...SCOPES));
         },
+        union: (type, coll, acc, opts) => {
+            gen.struct(type, coll, acc, opts);
+        },
     };
     return gen;
 };
@@ -201,9 +212,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 +224,17 @@ 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};`,
 ];
+const __docType = (parent, f, opts) => {
+    const doc = [...ensureLines(f.doc || [])];
+    if (isWasmPrim(f.type)) {
+        if (doc.length)
+            doc.push("");
+        doc.push(`WASM type: ${zigFieldType(parent, f, opts).type}`);
+    }
+    return doc.length ? doc : undefined;
+};

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, InjectedBody, WasmPrim, WasmPrim32 } from "../api.js";
 /**
  * Returns true iff `x` is a {@link WasmPrim32}.
  *
@@ -19,17 +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;
 /**
- * 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
- * lines.
+ * Returns true iff the struct field is a pointer, slice or "string" type
  *
- * @param prefix
- * @param str
- * @param width
+ * @param f
  */
-export declare const prefixLines: (prefix: string, str: string | string[], width: number) => string[];
+export declare const isPointerLike: (f: Field) => boolean;
 /**
  * Returns true if `type` is "slice".
  *
@@ -43,7 +41,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 +49,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.
  *
@@ -61,6 +59,17 @@ export declare const stringFields: (fields: StructField[]) => StructField[];
  * @internal
  */
 export declare const enumName: (opts: CodeGenOpts, name: string) => string;
+/**
+ * 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
+ * lines.
+ *
+ * @param prefix
+ * @param str
+ * @param width
+ */
+export declare const prefixLines: (prefix: string, str: string | string[], width: number) => string[];
+export declare const ensureLines: (src: string | string[] | InjectedBody, key?: keyof InjectedBody) => Iterable<string>;
 /**
  * Yields iterator of given lines, each with applied indentation based on given
  * scope regexp's which are applied to each line to increase or decrease

package/codegen/utils.js

@@ -1,4 +1,6 @@
+import { isArray } from "@thi.ng/checks/is-array";
 import { isString } from "@thi.ng/checks/is-string";
+import { split } from "@thi.ng/strings/split";
 import { wordWrapLine, wordWrapLines } from "@thi.ng/strings/word-wrap";
 /**
  * Returns true iff `x` is a {@link WasmPrim32}.
@@ -20,18 +22,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";
 /**
- * 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
- * lines.
+ * Returns true iff the struct field is a pointer, slice or "string" type
  *
- * @param prefix
- * @param str
- * @param width
+ * @param f
  */
-export const prefixLines = (prefix, str, width) => (isString(str)
-    ? wordWrapLines(str, { width: width - prefix.length })
-    : str.flatMap((x) => wordWrapLine(x, { width: width - prefix.length }))).map((line) => prefix + line);
+export const isPointerLike = (f) => isPointer(f) || isSlice(f) || isWasmString(f.type);
 /**
  * Returns true if `type` is "slice".
  *
@@ -63,6 +61,27 @@ export const stringFields = (fields) => fields.filter((f) => isWasmString(f.type
  * @internal
  */
 export const enumName = (opts, name) => opts.uppercaseEnums ? name.toUpperCase() : name;
+/**
+ * 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
+ * lines.
+ *
+ * @param prefix
+ * @param str
+ * @param width
+ */
+export const prefixLines = (prefix, str, width) => (isString(str)
+    ? wordWrapLines(str, { width: width - prefix.length })
+    : str.flatMap((x) => wordWrapLine(x, { width: width - prefix.length }))).map((line) => prefix + line);
+export const ensureLines = (src, key) => isString(src)
+    ? split(src)
+    : isArray(src)
+        ? src
+        : key
+            ? src[key]
+                ? ensureLines(src[key], key)
+                : []
+            : [];
 /**
  * Yields iterator of given lines, each with applied indentation based on given
  * scope regexp's which are applied to each line to increase or decrease

package/codegen/zig.d.ts

@@ -1,4 +1,4 @@
-import type { CodeGenOptsBase, ICodeGen } from "../api.js";
+import type { CodeGenOpts, CodeGenOptsBase, Field, ICodeGen, Struct, Union } from "../api.js";
 /**
  * Zig code generator options.
  */
@@ -15,4 +15,9 @@ export interface ZigOpts extends CodeGenOptsBase {
  * @param opts
  */
 export declare const ZIG: (opts?: Partial<ZigOpts>) => ICodeGen;
+/** @internal */
+export declare const fieldType: (parent: Struct | Union, f: Field, opts: CodeGenOpts) => {
+    type: string;
+    defaultVal: string;
+};
 //# sourceMappingURL=zig.d.ts.map

package/codegen/zig.js

@@ -1,8 +1,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 { ensureLines, 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).
@@ -39,81 +38,110 @@ export const ZIG = (opts = {}) => {
                 lines.push(line + ",");
             }
             if (e.body?.zig) {
-                lines.push("", ...split(e.body.zig), "");
+                lines.push("", ...ensureLines(e.body.zig, "impl"), "");
             }
             lines.push("};", "");
             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);
+        const { type, defaultVal } = fieldType(parent, f, opts);
+        ftypes[f.name] = type;
+        res.push(`${f.name}: ${type}${defaultVal},`);
+    }
+    if (parent.body?.zig) {
+        res.push("", ...ensureLines(parent.body.zig, "impl"), "");
+    }
+    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;
+};
+/** @internal */
+export const fieldType = (parent, f, opts) => {
+    let type = 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":
+            type =
+                f.sentinel !== undefined
+                    ? `[${f.len}:${f.sentinel}]${type}`
+                    : `[${f.len}]${type}`;
+            break;
+        case "slice":
+            type = `[${f.sentinel !== undefined ? ":" + f.sentinel : ""}]${f.const ? "const " : ""}${type}`;
+            break;
+        case "vec":
+            type = `@Vector(${f.len}, ${type})`;
+            break;
+        case "ptr":
+            type = `*${f.const ? "const " : ""}${f.len ? `[${f.len}]` : ""}${type}`;
+            break;
+        case "scalar":
+        default:
+            if (f.default != undefined) {
+                if (!(isString(f.default) || isNumber(f.default))) {
+                    unsupported(`wrong default value for ${parent.name}.${f.name} (${f.default})`);
+                }
+                defaultVal = ` = ${JSON.stringify(f.default)}`;
+            }
+    }
+    return { type, defaultVal };
+};
+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