@thi.ng/wasm-api 0.5.0 → 0.8.0

package/codegen/typescript.js

@@ -0,0 +1,189 @@
+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 { isBigNumeric, isNumeric, isWasmPrim, isWasmString, prefixLines, } from "./utils.js";
+/**
+ * TypeScript code generator. Call with options and then pass to
+ * {@link generateTypes} (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates interface and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}. For structs it will also generate memory
+ * mapped wrappers with fully typed accessors.
+ *
+ * @param opts
+ */
+export const TYPESCRIPT = (opts) => {
+    const { indent, stringType, uppercaseEnums } = {
+        indent: "\t",
+        stringType: "slice",
+        uppercaseEnums: true,
+        ...opts,
+    };
+    const I = indent;
+    const I2 = I + I;
+    const I3 = I2 + I;
+    const gen = {
+        pre: `import type { WasmTypeBase, WasmTypeConstructor } from "${PKG_NAME}";`,
+        doc: (doc, indent, acc) => {
+            if (doc.indexOf("\n") !== -1) {
+                acc.push(indent + "/**", prefixLines(indent + " * ", doc), indent + " */");
+            }
+            else {
+                acc.push(`${indent}/** ${doc} */`);
+            }
+        },
+        enum: (type, _, acc) => {
+            const e = type;
+            acc.push(`export enum ${e.name} {`);
+            for (let v of e.values) {
+                let line = indent;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, indent, acc);
+                    line += uppercaseEnums ? v.name.toUpperCase() : v.name;
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line += uppercaseEnums ? v.toUpperCase() : v;
+                }
+                acc.push(line + ",");
+            }
+            acc.push("}\n");
+            return acc;
+        },
+        struct: (type, types, acc) => {
+            const struct = type;
+            const returnTypes = {};
+            // interface definition
+            acc.push(`export interface ${struct.name} extends WasmTypeBase {`);
+            for (let f of struct.fields) {
+                f.doc && gen.doc(f.doc, indent, acc);
+                let line = `${indent}${f.name}: `;
+                let rtype = "";
+                if (f.tag == "array" || f.tag == "slice" || f.tag === "vec") {
+                    rtype = isNumeric(f.type)
+                        ? TYPEDARRAY_CTORS[f.type].name
+                        : isBigNumeric(f.type)
+                            ? BIGINT_ARRAY_CTORS[f.type].name
+                            : f.type + "[]";
+                }
+                else if (!f.tag || f.tag === "scalar" || f.tag === "ptr") {
+                    rtype = isBigNumeric(f.type)
+                        ? "bigint"
+                        : isNumeric(f.type)
+                            ? "number"
+                            : f.type;
+                }
+                returnTypes[f.name] = rtype;
+                acc.push(line + rtype + ";");
+            }
+            acc.push("}\n");
+            // type implementation
+            acc.push(`export const $${struct.name}: WasmTypeConstructor<${struct.name}> = (mem) => ({`, `${I}get align() { return ${struct.__align}; },`, `${I}get size() { return ${struct.__size}; },`, `${I}instance: (base) => ({`, `${I2}get __base() { return base; },`, `${I2}get __bytes() { return mem.u8.subarray(base, base + ${struct.__size}); },`);
+            for (let f of struct.fields) {
+                const offset = f.__offset || 0;
+                acc.push(`${I2}get ${f.name}(): ${returnTypes[f.name]} {`);
+                const isPrim = isWasmPrim(f.type);
+                const isStr = isWasmString(f.type);
+                if (f.tag === "ptr") {
+                    if (isPrim) {
+                        acc.push(`${I3}return mem.${f.type}[${__ptrShift(offset, f.type)}];`);
+                    }
+                    else if (isStr) {
+                        acc.push(
+                        // double deref
+                        stringType === "slice"
+                            ? `${I3}return mem.getString(mem.${USIZE}[${__ptr(offset)} >>> ${USIZE_SIZE}])`
+                            : `${I3}return mem.getString(${__ptr(offset)})`);
+                    }
+                    else {
+                        acc.push(`${I3}return $${f.type}.instance(${__ptr(offset)});`);
+                    }
+                }
+                else if (f.tag === "slice") {
+                    acc.push(`${I3}const len = ${__ptr(offset + 4)};`);
+                    if (isPrim) {
+                        acc.push(`${I3}const addr = ${__ptrShift(offset, f.type)};`, `${I3}return mem.${f.type}.subarray(addr, addr + len);`);
+                    }
+                    else if (isStr) {
+                        acc.push(`${I3}const addr = ${__ptr(offset)};`, __mapStringArray(I3, stringType));
+                    }
+                    else {
+                        acc.push(`${I3}const addr = ${__ptr(offset)};`, __mapArray(f, I3));
+                    }
+                }
+                else if (f.tag === "array" || f.tag === "vec") {
+                    if (isPrim) {
+                        acc.push(`${I3}const addr = ${__addrShift(offset, f.type)};`, `${I3}return mem.${f.type}.subarray(addr, addr + ${f.len});`);
+                    }
+                    else if (isStr) {
+                        acc.push(`${I3}const addr = ${__addr(offset)};`, __mapStringArray(I3, stringType, f.len));
+                    }
+                    else {
+                        acc.push(`${I3}const addr = ${__addr(offset)};`, __mapArray(f, I3, f.len));
+                    }
+                }
+                else {
+                    let setter;
+                    if (isPrim) {
+                        const addr = __mem(f.type, f.__offset);
+                        acc.push(`${I3}return ${addr};`);
+                        setter = `${addr} = x`;
+                    }
+                    else if (isStr) {
+                        acc.push(`${I3}return mem.getString(${__ptr(offset)})`);
+                        setter =
+                            stringType === "slice"
+                                ? `mem.setString(x, ${__ptr(offset)}, ${__ptr(offset + 4)} + 1, true);`
+                                : `throw new Error("unsupported for raw string pointers")`;
+                    }
+                    else if (types[f.type].type === "enum") {
+                        const tag = types[f.type].tag;
+                        const addr = __mem(tag, f.__offset);
+                        acc.push(`${I3}return ${addr};`);
+                        setter = `${addr} = x`;
+                    }
+                    else {
+                        acc.push(`${I3}return $${f.type}(mem).instance(${__addr(offset)});`);
+                        setter = `mem.u8.set(x.__bytes, ${__addr(offset)})`;
+                    }
+                    // close getter
+                    acc.push(`${I2}},`);
+                    // setter
+                    acc.push(`${I2}set ${f.name}(x: ${returnTypes[f.name]}) {`, `${I3}${setter};`);
+                }
+                // close field accessor
+                acc.push(`${I2}},`);
+            }
+            acc.push(`${I}})\n});\n`);
+            return acc;
+        },
+    };
+    return gen;
+};
+/** @internal */
+const __shift = (type) => BIT_SHIFTS[type];
+/** @internal */
+const __addr = (offset) => (offset > 0 ? `(base + ${offset})` : "base");
+/** @internal */
+const __addrShift = (offset, shift) => {
+    const bits = __shift(shift);
+    return __addr(offset) + (bits ? " >>> " + bits : "");
+};
+/** @internal */
+const __ptr = (offset) => `mem.${USIZE}[${__addrShift(offset, USIZE)}]`;
+/** @internal */
+const __ptrShift = (offset, shift) => __ptr(offset) + " >>> " + __shift(shift);
+const __mem = (type, offset) => `mem.${type}[${__addrShift(offset, type)}]`;
+/** @internal */
+const __mapArray = (f, indent, len = "len") => prefixLines(indent, `const inst = $${f.type}(mem);
+const slice: ${f.type}[] = [];
+for(let i = 0; i < ${len}; i++) slice.push(inst.instance(addr + i * ${f.__size}));
+return slice;`);
+/** @internal */
+const __mapStringArray = (indent, type, len = "len") => prefixLines(indent, [
+    "const slice: string[] = [];",
+    `for(let i = 0; i < ${len}; i++) slice.push(mem.getString(mem.${USIZE}[(addr + i * ${USIZE_SIZE * (type === "slice" ? 2 : 1)}) >>> ${__shift(USIZE)}]));`,
+    "return slice;",
+]);

package/codegen/utils.d.ts

@@ -0,0 +1,30 @@
+import type { BigType } from "@thi.ng/api";
+import type { WasmPrim, WasmPrim32 } from "../api.js";
+/**
+ * Returns true iff `x` is a {@link WasmPrim32}.
+ *
+ * @param x
+ */
+export declare const isNumeric: (x: string) => x is WasmPrim32;
+/**
+ * Returns true iff `x` is a `i64` or `u64`.
+ *
+ * @param x
+ */
+export declare const isBigNumeric: (x: string) => x is BigType;
+/**
+ * Returns true iff `x` is a {@link WasmPrim}.
+ *
+ * @param x
+ */
+export declare const isWasmPrim: (x: string) => x is WasmPrim;
+export declare const isWasmString: (x: string) => x is "string";
+/**
+ * Takes an array of strings or splits given string into lines, prefixes each
+ * line with given `prefix` and then returns rejoined result.
+ *
+ * @param prefix
+ * @param str
+ */
+export declare const prefixLines: (prefix: string, str: string | string[]) => string;
+//# sourceMappingURL=utils.d.ts.map

package/codegen/utils.js

@@ -0,0 +1,30 @@
+import { isString } from "@thi.ng/checks/is-string";
+/**
+ * Returns true iff `x` is a {@link WasmPrim32}.
+ *
+ * @param x
+ */
+export const isNumeric = (x) => /^(([iu](8|16|32))|(f(32|64)))$/.test(x);
+/**
+ * Returns true iff `x` is a `i64` or `u64`.
+ *
+ * @param x
+ */
+export const isBigNumeric = (x) => /^[iu]64$/.test(x);
+/**
+ * Returns true iff `x` is a {@link WasmPrim}.
+ *
+ * @param x
+ */
+export const isWasmPrim = (x) => isNumeric(x) || isBigNumeric(x);
+export const isWasmString = (x) => x === "string";
+/**
+ * Takes an array of strings or splits given string into lines, prefixes each
+ * line with given `prefix` and then returns rejoined result.
+ *
+ * @param prefix
+ * @param str
+ */
+export const prefixLines = (prefix, str) => (isString(str) ? str.split("\n") : str)
+    .map((line) => prefix + line)
+    .join("\n");

package/codegen/zig.d.ts

@@ -0,0 +1,25 @@
+import type { ICodeGen } from "../api.js";
+/**
+ * Zig code generator options.
+ */
+export interface ZigOpts {
+    /**
+     * If true, generates various struct & struct field analysis functions
+     * (sizes, alignment, offsets etc.).
+     *
+     * @defaultValue false
+     */
+    debug: boolean;
+}
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export declare const ZIG: (opts?: Partial<ZigOpts>) => ICodeGen;
+//# sourceMappingURL=zig.d.ts.map

package/codegen/zig.js

@@ -0,0 +1,75 @@
+import { isString } from "@thi.ng/checks/is-string";
+import { prefixLines } from "./utils.js";
+/**
+ * Zig code generator. Call with options and then pass to {@link generateTypes}
+ * (see its docs for further usage).
+ *
+ * @remarks
+ * This codegen generates struct and enum definitions for a {@link TypeColl}
+ * given to {@link generateTypes}.
+ *
+ * @param opts
+ */
+export const ZIG = (opts) => {
+    const { debug } = { debug: false, ...opts };
+    const gen = {
+        doc: (doc, indent, acc, topLevel = false) => {
+            acc.push(prefixLines(topLevel ? "//! " : indent + "/// ", doc));
+        },
+        enum: (e, _, acc) => {
+            acc.push(`pub const ${e.name} = enum(${e.tag}) {`);
+            for (let v of e.values) {
+                let line = `    `;
+                if (!isString(v)) {
+                    v.doc && gen.doc(v.doc, "    ", acc);
+                    line += v.name;
+                    if (v.value != null)
+                        line += ` = ${v.value}`;
+                }
+                else {
+                    line += v;
+                }
+                acc.push(line + ",");
+            }
+            acc.push("};\n");
+        },
+        struct: (struct, _, acc) => {
+            const name = struct.name;
+            acc.push(`pub const ${name} = struct {`);
+            const ftypes = {};
+            for (let f of struct.fields) {
+                f.doc && gen.doc(f.doc, "    ", acc);
+                let ftype = f.type === "string" ? "[]const u8" : f.type;
+                switch (f.tag) {
+                    case "array":
+                        ftype = `[${f.len}]${ftype}`;
+                        break;
+                    case "slice":
+                        // ftype = `[]${f.const ? "const" : ""}${ftype}`; // TODO
+                        ftype = `[]${ftype}`;
+                        break;
+                    case "vec":
+                        ftype = `@Vector(${f.len}, ${ftype})`;
+                        break;
+                    case "ptr":
+                        ftype = `*${f.len ? `[${f.len}]` : ""}${ftype}`;
+                        break;
+                    case "scalar":
+                    default:
+                }
+                ftypes[f.name] = ftype;
+                acc.push(`    ${f.name}: ${ftype},`);
+            }
+            acc.push("};\n");
+            if (!debug)
+                return;
+            const fn = (fname, body) => `export fn ${name}_${fname}() usize { return ${body}; }`;
+            acc.push(fn("align", `@alignOf(${name})`), fn("size", `@sizeOf(${name})`));
+            for (let f of struct.fields) {
+                acc.push(fn(f.name + "_align", `@alignOf(${ftypes[f.name]})`), fn(f.name + "_offset", `@offsetOf(${name}, "${f.name}")`), fn(f.name + "_size", `@sizeOf(${ftypes[f.name]})`));
+            }
+            acc.push("");
+        },
+    };
+    return gen;
+};

package/codegen.d.ts

@@ -0,0 +1,53 @@
+import { ICodeGen, TypeColl } from "./api.js";
+/**
+ * Global/shared code generator options.
+ */
+export interface CodeGenOpts {
+    /**
+     * Optional string to be injected before generated type defs (but after
+     * codegen's own prelude, if any)
+     */
+    pre: string;
+    /**
+     * Optional string to be injected after generated type defs (but before
+     * codegen's own epilogue, if any)
+     */
+    post: string;
+    /**
+     * 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).
+     *
+     * @defaultValue "slice"
+     */
+    stringType: "slice" | "ptr";
+}
+/**
+ * Takes a type collection and analyzes each analyzed to compute individual
+ * alignments and sizes.
+ *
+ * @remarks
+ * This function is idempotent and called automatically by
+ * {@link generateTypes}. Only exported for dev/debug purposes.
+ *
+ * @param types
+ *
+ * @internal
+ */
+export declare const prepareTypes: (types: TypeColl, opts: CodeGenOpts) => void;
+/**
+ * Code generator main entry point. Takes an object of {@link TopLevelType}
+ * definitions, an actual code generator implementation for a single target
+ * language and (optional) global codegen options. Returns generated source code
+ * for all given types as a single string.
+ *
+ * @remarks
+ * Before actual code generation the types are first analyzed to compute their
+ * alignments and sizes. This is only ever done once (idempotent), even if
+ * `generateTypes()` is called multiple times for different target langs.
+ *
+ * @param types
+ * @param codegen
+ * @param opts
+ */
+export declare const generateTypes: (types: TypeColl, codegen: ICodeGen, opts?: Partial<CodeGenOpts>) => string;
+//# sourceMappingURL=codegen.d.ts.map

package/codegen.js

@@ -0,0 +1,148 @@
+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 { PKG_NAME, USIZE_SIZE, } from "./api.js";
+import { isNumeric, isWasmString } from "./codegen/utils.js";
+const sizeOf = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (field, types, opts) => {
+        if (field.__size)
+            return field.__size;
+        let size = 0;
+        if (field.tag === "ptr") {
+            size = USIZE_SIZE;
+        }
+        else if (field.tag === "slice") {
+            size = USIZE_SIZE * 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);
+            if (field.tag == "array" || field.tag === "vec") {
+                size *= field.len;
+            }
+        }
+        return (field.__size = align(size, field.__align));
+    },
+    enum: (type) => {
+        if (type.__size)
+            return type.__size;
+        return (type.__size = SIZEOF[type.tag]);
+    },
+    struct: (type, types, 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);
+        }
+        return (type.__size = align(size, type.__align));
+    },
+});
+const alignOf = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (field, types) => {
+        if (field.__align)
+            return field.__align;
+        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;
+    },
+    enum: (e) => {
+        return (e.__align = SIZEOF[e.tag]);
+    },
+    struct: (type, types) => {
+        const struct = type;
+        let maxAlign = 0;
+        for (let f of struct.fields) {
+            maxAlign = Math.max(maxAlign, alignOf(f, types));
+        }
+        return (type.__align = maxAlign);
+    },
+});
+const prepareType = defmulti((x) => x.type, {}, {
+    [DEFAULT]: (x, types, opts) => {
+        if (x.__align && x.__size)
+            return;
+        alignOf(x, types);
+        sizeOf(x, types, opts);
+    },
+    struct: (x, types, opts) => {
+        if (x.__align && x.__size)
+            return;
+        const struct = x;
+        alignOf(struct, types);
+        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);
+            }
+        }
+        sizeOf(struct, types, opts);
+    },
+});
+/**
+ * Takes a type collection and analyzes each analyzed to compute individual
+ * alignments and sizes.
+ *
+ * @remarks
+ * This function is idempotent and called automatically by
+ * {@link generateTypes}. Only exported for dev/debug purposes.
+ *
+ * @param types
+ *
+ * @internal
+ */
+export const prepareTypes = (types, opts) => {
+    for (let id in types) {
+        prepareType(types[id], types, opts);
+    }
+};
+/**
+ * Code generator main entry point. Takes an object of {@link TopLevelType}
+ * definitions, an actual code generator implementation for a single target
+ * language and (optional) global codegen options. Returns generated source code
+ * for all given types as a single string.
+ *
+ * @remarks
+ * Before actual code generation the types are first analyzed to compute their
+ * alignments and sizes. This is only ever done once (idempotent), even if
+ * `generateTypes()` is called multiple times for different target langs.
+ *
+ * @param types
+ * @param codegen
+ * @param opts
+ */
+export const generateTypes = (types, codegen, opts = {}) => {
+    const $opts = { stringType: "slice", ...opts };
+    prepareTypes(types, $opts);
+    const res = [];
+    codegen.doc(`Generated by ${PKG_NAME} at ${new Date().toISOString()} - DO NOT EDIT!`, "", res, true);
+    res.push("");
+    codegen.pre && res.push(codegen.pre, "");
+    $opts.pre && res.push($opts.pre, "");
+    for (let id in types) {
+        const type = types[id];
+        type.doc && codegen.doc(type.doc, "", res);
+        codegen[type.type](type, types, res);
+    }
+    $opts.post && res.push("", $opts.post);
+    codegen.post && res.push("", codegen.post);
+    return res.join("\n");
+};