@thi.ng/wasm-api 0.6.0 → 0.9.0

package/bridge.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import type { NumericArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
-import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports, WasmMemViews } from "./api.js";
+import type { BigIntArray, CoreAPI, IWasmAPI, WasmExports, IWasmMemoryAccess } from "./api.js";
 export declare const OutOfMemoryError: {
     new (msg?: string | undefined): {
         name: string;
@@ -28,7 +28,7 @@ export declare const OutOfMemoryError: {
  * 64bit integers are handled via JS `BigInt` and hence require the host env to
  * support it. No polyfill is provided.
  */
-export declare class WasmBridge<T extends WasmExports = WasmExports> implements WasmMemViews {
+export declare class WasmBridge<T extends WasmExports = WasmExports> implements IWasmMemoryAccess {
     modules: Record<string, IWasmAPI<T>>;
     logger: ILogger;
     i8: Int8Array;
@@ -193,7 +193,8 @@ export declare class WasmBridge<T extends WasmExports = WasmExports> implements
     /**
      * Encodes given string as UTF-8 and writes it to WASM memory starting at
      * `addr`. By default the string will be zero-terminated and only `maxBytes`
-     * will be written. Returns the number of bytes written.
+     * will be written. Returns the number of bytes written (excluding final
+     * sentinel, if any).
      *
      * @remarks
      * An error will be thrown if the encoded string doesn't fully fit into the

package/bridge.js

@@ -55,6 +55,9 @@ export class WasmBridge {
             _printF64Array: logA(this.getF64Array.bind(this)),
             _printStr0: (addr) => this.logger.debug(this.getString(addr, 0)),
             _printStr: (addr, len) => this.logger.debug(this.getString(addr, len)),
+            debug: () => {
+                debugger;
+            },
         };
     }
     /**
@@ -370,7 +373,8 @@ export class WasmBridge {
     /**
      * Encodes given string as UTF-8 and writes it to WASM memory starting at
      * `addr`. By default the string will be zero-terminated and only `maxBytes`
-     * will be written. Returns the number of bytes written.
+     * will be written. Returns the number of bytes written (excluding final
+     * sentinel, if any).
      *
      * @remarks
      * An error will be thrown if the encoded string doesn't fully fit into the
@@ -386,11 +390,10 @@ export class WasmBridge {
         maxBytes = Math.min(maxBytes, this.u8.length - addr);
         const len = this.utf8Encoder.encodeInto(str, this.u8.subarray(addr, addr + maxBytes)).written;
         if (len == null || len >= maxBytes + (terminate ? 0 : 1)) {
-            illegalArgs(`error writing string to 0x${U32(addr)}`);
+            illegalArgs(`error writing string to 0x${U32(addr)} (max. ${maxBytes} bytes, got at least ${str.length})`);
         }
         if (terminate) {
             this.u8[addr + len] = 0;
-            return len + 1;
         }
         return len;
     }

package/cli.d.ts

@@ -0,0 +1,5 @@
+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

package/cli.js

@@ -0,0 +1,142 @@
+import { flag, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
+import { isArray, isPlainObject } from "@thi.ng/checks";
+import { illegalArgs } from "@thi.ng/errors";
+import { readJSON, writeText } from "@thi.ng/file-io";
+import { ConsoleLogger } from "@thi.ng/logger";
+import { resolve } from "path";
+import { generateTypes } from "./codegen.js";
+import { TYPESCRIPT } from "./codegen/typescript.js";
+import { isWasmPrim, isWasmString } from "./codegen/utils.js";
+import { ZIG } from "./codegen/zig.js";
+const GENERATORS = { ts: TYPESCRIPT, zig: ZIG };
+const argOpts = {
+    config: string({
+        alias: "c",
+        hint: "FILE",
+        desc: "JSON config file with codegen options",
+    }),
+    debug: flag({ alias: "d", default: false, desc: "enable debug output" }),
+    dryRun: flag({
+        default: false,
+        desc: "enable dry run (don't overwrite files)",
+    }),
+    lang: oneOfMulti(Object.keys(GENERATORS), {
+        alias: "l",
+        desc: "target language",
+        default: ["ts", "zig"],
+        delim: ",",
+    }),
+    out: strings({ alias: "o", hint: "FILE", desc: "output file path" }),
+};
+export const INSTALL_DIR = resolve(`${process.argv[2]}/..`);
+export const PKG = readJSON(`${INSTALL_DIR}/package.json`);
+export const APP_NAME = PKG.name.split("/")[1];
+export const HEADER = `
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ ${PKG.name} ${PKG.version}
+ █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
+                 █ │
+               █ █ │
+`;
+const usageOpts = {
+    lineWidth: process.stdout.columns,
+    prefix: `${HEADER}
+usage: ${APP_NAME} [OPTS] JSON-INPUT-FILE(S) ...
+       ${APP_NAME} --help
+
+`,
+    showGroupNames: true,
+    paramWidth: 32,
+};
+const showUsage = () => {
+    process.stderr.write(usage(argOpts, usageOpts));
+    process.exit(1);
+};
+const invalidSpec = (path, msg) => {
+    throw new Error(`invalid typedef: ${path}${msg ? ` (${msg})` : ""}`);
+};
+const addTypeSpec = (ctx, path, coll, spec) => {
+    if (!(spec.name && spec.type))
+        invalidSpec(path);
+    if (!(spec.type === "enum" || spec.type === "struct"))
+        invalidSpec(path, `${spec.name} type: ${spec.type}`);
+    if (coll[spec.name])
+        invalidSpec(path, `duplicate name: ${spec.name}`);
+    ctx.logger.debug(`registering ${spec.type}: ${spec.name}`);
+    coll[spec.name] = spec;
+    spec.__path = path;
+};
+const validateTypeRefs = (coll) => {
+    for (let spec of Object.values(coll)) {
+        if (spec.type !== "struct")
+            continue;
+        for (let f of spec.fields) {
+            if (!(isWasmPrim(f.type) || isWasmString(f.type) || coll[f.type])) {
+                invalidSpec(spec.__path, `structfield ${spec.name}.${f.name} of unknown type: ${f.type}`);
+            }
+        }
+    }
+};
+const parseTypeSpecs = (ctx, inputs) => {
+    const coll = {};
+    for (let path of inputs) {
+        try {
+            const spec = readJSON(resolve(path), ctx.logger);
+            if (isArray(spec)) {
+                for (let s of spec)
+                    addTypeSpec(ctx, path, coll, s);
+            }
+            else if (isPlainObject(spec)) {
+                addTypeSpec(ctx, path, coll, spec);
+            }
+            else {
+                invalidSpec(path);
+            }
+        }
+        catch (e) {
+            process.stderr.write(e.message);
+            process.exit(1);
+        }
+    }
+    validateTypeRefs(coll);
+    return coll;
+};
+const generateOutputs = ({ config, logger, opts }, coll) => {
+    for (let i = 0; i < opts.lang.length; i++) {
+        const lang = opts.lang[i];
+        logger.debug(`generating ${lang.toUpperCase()} output...`);
+        const src = generateTypes(coll, GENERATORS[lang](config[lang]), config.global);
+        if (opts.out) {
+            writeText(resolve(opts.out[i]), src, logger, opts.dryRun);
+        }
+        else {
+            process.stdout.write(src + "\n");
+        }
+    }
+};
+try {
+    const result = parse(argOpts, process.argv, { start: 3, usageOpts });
+    if (!result)
+        process.exit(1);
+    const { result: opts, rest } = result;
+    if (!rest.length)
+        showUsage();
+    if (opts.out && opts.lang.length != opts.out.length) {
+        illegalArgs(`expected ${opts.lang.length} outputs, but got ${opts.out.length}`);
+    }
+    const ctx = {
+        logger: new ConsoleLogger("wasm-api", opts.debug ? "DEBUG" : "INFO"),
+        config: {},
+        opts,
+    };
+    if (opts.config) {
+        ctx.config = readJSON(resolve(opts.config), ctx.logger);
+    }
+    generateOutputs(ctx, parseTypeSpecs(ctx, rest));
+}
+catch (e) {
+    if (!(e instanceof ParseError))
+        process.stderr.write(e.message);
+    process.exit(1);
+}

package/codegen/typescript.d.ts

@@ -1,4 +1,7 @@
 import { ICodeGen } from "../api.js";
+/**
+ * TypeScript code generator options.
+ */
 export interface TSOpts {
     /**
      * Indentation string
@@ -6,6 +9,16 @@ export interface TSOpts {
      * @defaultValue "\t"
      */
     indent: string;
+    /**
+     * If true (default), forces uppercase enums
+     *
+     * @defaultValue true
+     */
+    uppercaseEnums: boolean;
+    /**
+     * Same as {@link CodeGenOpts.stringType}.
+     */
+    stringType: "slice" | "ptr";
 }
 /**
  * TypeScript code generator. Call with options and then pass to

package/codegen/typescript.js

@@ -1,7 +1,7 @@
 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, } from "../api.js";
-import { isBigNumeric, isNumeric, isPrim, prefixLines } from "./utils.js";
+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).
@@ -14,7 +14,12 @@ import { isBigNumeric, isNumeric, isPrim, prefixLines } from "./utils.js";
  * @param opts
  */
 export const TYPESCRIPT = (opts) => {
-    const { indent } = { indent: "\t", ...opts };
+    const { indent, stringType, uppercaseEnums } = {
+        indent: "\t",
+        stringType: "slice",
+        uppercaseEnums: true,
+        ...opts,
+    };
     const I = indent;
     const I2 = I + I;
     const I3 = I2 + I;
@@ -32,15 +37,15 @@ export const TYPESCRIPT = (opts) => {
             const e = type;
             acc.push(`export enum ${e.name} {`);
             for (let v of e.values) {
-                var line = indent;
+                let line = indent;
                 if (!isString(v)) {
                     v.doc && gen.doc(v.doc, indent, acc);
-                    line += v.name;
+                    line += uppercaseEnums ? v.name.toUpperCase() : v.name;
                     if (v.value != null)
                         line += ` = ${v.value}`;
                 }
                 else {
-                    line += v;
+                    line += uppercaseEnums ? v.toUpperCase() : v;
                 }
                 acc.push(line + ",");
             }
@@ -79,31 +84,60 @@ export const TYPESCRIPT = (opts) => {
             for (let f of struct.fields) {
                 const offset = f.__offset || 0;
                 acc.push(`${I2}get ${f.name}(): ${returnTypes[f.name]} {`);
-                const prim = isPrim(f.type);
+                const isPrim = isWasmPrim(f.type);
+                const isStr = isWasmString(f.type);
                 if (f.tag === "ptr") {
-                    acc.push(prim
-                        ? `${I3}return mem.${f.type}[${__ptrShift(offset, f.type)}];`
-                        : `${I3}return $${f.type}.instance(${__ptr(offset)});`);
+                    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)};`, prim
-                        ? `${I3}const addr = ${__ptrShift(offset, f.type)};
-${I3}return mem.${f.type}.subarray(addr, addr + len);`
-                        : `${I3}const addr = ${__ptr(offset)};\n${__mapArray(struct, f, I3)}`);
+                    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") {
-                    acc.push(prim
-                        ? `${I3}const addr = ${__addrShift(offset, f.type)};
-${I3}return mem.${f.type}.subarray(addr, addr + ${f.len});`
-                        : `${I3}const addr = ${__addr(offset)};\n${__mapArray(struct, f, I3, f.len)}`);
+                    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 (prim) {
+                    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);
@@ -133,14 +167,23 @@ const __shift = (type) => BIT_SHIFTS[type];
 /** @internal */
 const __addr = (offset) => (offset > 0 ? `(base + ${offset})` : "base");
 /** @internal */
-const __addrShift = (offset, shift) => __addr(offset) + " >>> " + __shift(shift);
+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 = (struct, f, indent, len = "len") => prefixLines(indent, `const inst = $${f.type}(mem);
+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 * ${struct.__size}));
+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

@@ -1,5 +1,30 @@
-export declare const isNumeric: (x: string) => boolean;
-export declare const isBigNumeric: (x: string) => boolean;
-export declare const isPrim: (x: string) => boolean;
-export declare const prefixLines: (prefix: string, str: string) => string;
+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

@@ -1,7 +1,30 @@
-export const isNumeric = (x) => /^([iu](8|16|32))|(f(32|64))$/.test(x);
+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);
-export const isPrim = (x) => isNumeric(x) || isBigNumeric(x);
-export const prefixLines = (prefix, str) => str
-    .split("\n")
+/**
+ * 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

@@ -1,4 +1,7 @@
 import type { ICodeGen } from "../api.js";
+/**
+ * Zig code generator options.
+ */
 export interface ZigOpts {
     /**
      * If true, generates various struct & struct field analysis functions

package/codegen/zig.js

@@ -39,23 +39,22 @@ export const ZIG = (opts) => {
             const ftypes = {};
             for (let f of struct.fields) {
                 f.doc && gen.doc(f.doc, "    ", acc);
-                var ftype;
+                let ftype = f.type === "string" ? "[]const u8" : f.type;
                 switch (f.tag) {
                     case "array":
-                        ftype = `[${f.len}]${f.type}`;
+                        ftype = `[${f.len}]${ftype}`;
                         break;
                     case "slice":
-                        ftype = `[]${f.type}`;
+                        ftype = `[]${ftype}`;
                         break;
                     case "vec":
-                        ftype = `@Vector(${f.len}, ${f.type})`;
+                        ftype = `@Vector(${f.len}, ${ftype})`;
                         break;
                     case "ptr":
-                        ftype = `*${f.len ? `[${f.len}]` : ""}${f.type}`;
+                        ftype = `*${f.len ? `[${f.len}]` : ""}${ftype}`;
                         break;
                     case "scalar":
                     default:
-                        ftype = f.type;
                 }
                 ftypes[f.name] = ftype;
                 acc.push(`    ${f.name}: ${ftype},`);

package/codegen.d.ts

@@ -1,4 +1,7 @@
 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
@@ -10,7 +13,41 @@ export interface CodeGenOpts {
      * 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";
 }
-export declare const prepareTypes: (types: TypeColl) => void;
+/**
+ * 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

@@ -5,9 +5,9 @@ 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 } from "./codegen/utils.js";
+import { isNumeric, isWasmString } from "./codegen/utils.js";
 const sizeOf = defmulti((x) => x.type, {}, {
-    [DEFAULT]: (field, types) => {
+    [DEFAULT]: (field, types, opts) => {
         if (field.__size)
             return field.__size;
         let size = 0;
@@ -20,7 +20,9 @@ const sizeOf = defmulti((x) => x.type, {}, {
         else {
             size = isNumeric(field.type)
                 ? SIZEOF[field.type]
-                : sizeOf(types[field.type], types);
+                : 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;
             }
@@ -32,7 +34,7 @@ const sizeOf = defmulti((x) => x.type, {}, {
             return type.__size;
         return (type.__size = SIZEOF[type.tag]);
     },
-    struct: (type, types) => {
+    struct: (type, types, opts) => {
         if (type.__size)
             return type.__size;
         const struct = type;
@@ -40,7 +42,7 @@ const sizeOf = defmulti((x) => x.type, {}, {
         for (let f of struct.fields) {
             size = align(size, f.__align);
             f.__offset = size;
-            size += sizeOf(f, types);
+            size += sizeOf(f, types, opts);
         }
         return (type.__size = align(size, type.__align));
     },
@@ -51,7 +53,9 @@ const alignOf = defmulti((x) => x.type, {}, {
             return field.__align;
         let align = isNumeric(field.type)
             ? SIZEOF[field.type]
-            : alignOf(types[field.type], types);
+            : isWasmString(field.type)
+                ? USIZE_SIZE
+                : alignOf(types[field.type], types);
         if (field.tag === "vec") {
             align *= ceilPow2(field.len);
         }
@@ -71,13 +75,13 @@ const alignOf = defmulti((x) => x.type, {}, {
     },
 });
 const prepareType = defmulti((x) => x.type, {}, {
-    [DEFAULT]: (x, types) => {
+    [DEFAULT]: (x, types, opts) => {
         if (x.__align && x.__size)
             return;
         alignOf(x, types);
-        sizeOf(x, types);
+        sizeOf(x, types, opts);
     },
-    struct: (x, types) => {
+    struct: (x, types, opts) => {
         if (x.__align && x.__size)
             return;
         const struct = x;
@@ -87,30 +91,58 @@ const prepareType = defmulti((x) => x.type, {}, {
         }
         for (let f of struct.fields) {
             if (types[f.type]) {
-                prepareType(types[f.type], types);
+                prepareType(types[f.type], types, opts);
             }
         }
-        sizeOf(struct, types);
+        sizeOf(struct, types, opts);
     },
 });
-export const prepareTypes = (types) => {
+/**
+ * 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);
+        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 = {}) => {
-    prepareTypes(types);
+    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, "");
+    $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);
+    $opts.post && res.push("", $opts.post);
     codegen.post && res.push("", codegen.post);
     return res.join("\n");
 };