@thi.ng/wasm-api 0.18.0 → 1.0.0

package/cli.js

@@ -1,188 +0,0 @@
-import { flag, oneOf, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
-import { isArray, isPlainObject, isString } from "@thi.ng/checks";
-import { illegalArgs } from "@thi.ng/errors";
-import { readJSON, readText, writeJSON, writeText } from "@thi.ng/file-io";
-import { ConsoleLogger } from "@thi.ng/logger";
-import { mutIn } from "@thi.ng/paths";
-import { dirname, resolve } from "path";
-import { generateTypes } from "./codegen.js";
-import { C11 } from "./codegen/c11.js";
-import { TYPESCRIPT } from "./codegen/typescript.js";
-import { isPadding, isWasmPrim, isWasmString } from "./codegen/utils.js";
-import { ZIG } from "./codegen/zig.js";
-const GENERATORS = { c11: C11, ts: TYPESCRIPT, zig: ZIG };
-const argOpts = {
-    analytics: string({
-        alias: "a",
-        hint: "FILE",
-        desc: "output file path for raw codegen analytics",
-    }),
-    config: string({
-        alias: "c",
-        hint: "FILE",
-        desc: "JSON config file with codegen options",
-    }),
-    debug: flag({
-        alias: "d",
-        default: false,
-        desc: "enable debug output & functions",
-    }),
-    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" }),
-    string: oneOf(["slice", "ptr"], {
-        alias: "s",
-        hint: "TYPE",
-        desc: "Force string type implementation",
-    }),
-};
-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 (!["enum", "struct", "union"].includes(spec.type))
-        invalidSpec(path, `${spec.name} type: ${spec.type}`);
-    if (coll[spec.name])
-        invalidSpec(path, `duplicate name: ${spec.name}`);
-    if (spec.body) {
-        if (!isPlainObject(spec.body))
-            invalidSpec(path, `${spec.name}.body must be an object`);
-        for (let lang in spec.body) {
-            const src = spec.body[lang];
-            if (isString(src) && src[0] === "@") {
-                spec.body[lang] = readText(src.substring(1), ctx.logger);
-            }
-        }
-    }
-    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 (!(isPadding(f) ||
-                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: { global: {} },
-        opts,
-    };
-    if (opts.config) {
-        opts.config = resolve(opts.config);
-        ctx.config = readJSON(opts.config, ctx.logger);
-        for (let id in ctx.config) {
-            const conf = ctx.config[id];
-            if (conf.pre && conf.pre[0] === "@") {
-                conf.pre = readText(resolve(dirname(opts.config), conf.pre.substring(1)), ctx.logger);
-            }
-            if (conf.post && conf.post[0] === "@") {
-                conf.post = readText(resolve(dirname(opts.config), conf.post.substring(1)), ctx.logger);
-            }
-        }
-    }
-    opts.debug && mutIn(ctx, ["config", "global", "debug"], true);
-    opts.string && mutIn(ctx, ["config", "global", "stringType"], opts.string);
-    const types = parseTypeSpecs(ctx, rest);
-    generateOutputs(ctx, types);
-    if (ctx.opts.analytics) {
-        // always write analytics, even if dry run
-        writeJSON(resolve(ctx.opts.analytics), types, undefined, "\t", ctx.logger);
-    }
-}
-catch (e) {
-    if (!(e instanceof ParseError))
-        process.stderr.write(e.message);
-    process.exit(1);
-}

package/codegen/align.d.ts

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

@@ -1,35 +0,0 @@
-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/c.d.ts

@@ -1,33 +0,0 @@
-import type { ICodeGen } from "../api.js";
-/**
- * Zig code generator options.
- */
-export interface COpts {
-    /**
-     * If true, generates various struct & struct field analysis functions
-     * (sizes, alignment, offsets etc.).
-     *
-     * @defaultValue false
-     */
-    debug: boolean;
-    /**
-     * Optional prelude
-     */
-    pre: string;
-    /**
-     * Optional postfix (inserted after the generated code)
-     */
-    post: string;
-}
-/**
- * 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 C11: (opts?: Partial<COpts>) => ICodeGen;
-//# sourceMappingURL=c.d.ts.map

package/codegen/c.js

@@ -1,100 +0,0 @@
-import { isString } from "@thi.ng/checks/is-string";
-import { isPadding, isStringSlice, prefixLines, withIndentation, } 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 C11 = (opts = {}) => {
-    const { debug } = { debug: false, ...opts };
-    const INDENT = "    ";
-    const SCOPES = [/\{$/, /\}\)?[;,]?$/];
-    const gen = {
-        pre: (opts) => `#pragma once
-#include <stddef.h>
-#include <stdint.h>${opts.pre ? `\n${opts.pre}` : ""}`,
-        post: () => opts.post || "",
-        doc: (doc, acc) => {
-            acc.push(prefixLines("// ", doc));
-        },
-        enum: (e, _, acc) => {
-            const lines = [];
-            lines.push(`enum {`);
-            for (let v of e.values) {
-                let line;
-                if (!isString(v)) {
-                    v.doc && gen.doc(v.doc, lines);
-                    line = `${e.name}_${v.name}`;
-                    if (v.value != null)
-                        line += ` = ${v.value}`;
-                }
-                else {
-                    line = v;
-                }
-                lines.push(line + ",");
-            }
-            lines.push("};", "");
-            acc.push(...withIndentation(lines, INDENT, ...SCOPES));
-        },
-        struct: (struct, _, acc, opts) => {
-            const name = 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(`__pad${padID++}: [${f.pad}]u8,`);
-                    continue;
-                }
-                f.doc && gen.doc(f.doc, res);
-                let ftype = f.type === "string"
-                    ? isStringSlice(opts.stringType)
-                        ? f.const !== false
-                            ? "[]const u8"
-                            : "[]u8"
-                        : f.const !== false
-                            ? "[*:0]const u8"
-                            : "[*:0]u8"
-                    : f.type;
-                switch (f.tag) {
-                    case "array":
-                    case "vec":
-                        ftype = `[${f.len}]${ftype}`;
-                        break;
-                    case "slice":
-                        ftype = `[]${f.const ? "const " : ""}${ftype}`;
-                        break;
-                    case "ptr":
-                        ftype = `*${f.const ? "const " : ""}${f.len ? `[${f.len}]` : ""}${ftype}`;
-                        break;
-                    case "scalar":
-                    default:
-                }
-                ftypes[f.name] = ftype;
-                res.push(`${f.name}: ${ftype},`);
-            }
-            res.push("};");
-            if (debug) {
-                res.push("");
-                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) {
-                    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));
-        },
-    };
-    return gen;
-};

package/codegen/c11.d.ts

@@ -1,22 +0,0 @@
-import type { CodeGenOptsBase, ICodeGen } from "../api.js";
-/**
- * Zig code generator options.
- */
-export interface C11Opts extends CodeGenOptsBase {
-    /**
-     * Optional name prefix for generated types, e.g. `WASM_`.
-     */
-    typePrefix: string;
-}
-/**
- * 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 C11: (opts?: Partial<C11Opts>) => ICodeGen;
-//# sourceMappingURL=c11.d.ts.map

package/codegen/c11.js

@@ -1,145 +0,0 @@
-import { isString } from "@thi.ng/checks/is-string";
-import { unsupported } from "@thi.ng/errors/unsupported";
-import { enumName, isPadding, isStringSlice, isWasmString, prefixLines, withIndentation, } from "./utils.js";
-const PRIM_ALIASES = {
-    i8: "int8_t",
-    u8: "uint8_t",
-    i16: "int16_t",
-    u16: "uint16_t",
-    i32: "int32_t",
-    u32: "uint32_t",
-    i64: "int64_t",
-    u64: "uint64_t",
-    f32: "float",
-    f64: "double",
-};
-/**
- * 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 C11 = (opts = {}) => {
-    const { typePrefix } = {
-        typePrefix: "",
-        ...opts,
-    };
-    const INDENT = "    ";
-    const SCOPES = [/\{$/, /^\}[ A-Za-z0-9_]*[;,]?$/];
-    const gen = {
-        pre: (opts) => `#pragma once
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-${opts.debug ? "\n#include <stdalign.h>" : ""}
-#include <stddef.h>
-#include <stdint.h>${opts.pre ? `\n${opts.pre}` : ""}`,
-        post: () => `${opts.post ? `${opts.post}\n` : ""}#ifdef __cplusplus\n}\n#endif\n`,
-        doc: (doc, acc, opts) => {
-            acc.push(...prefixLines("// ", doc, opts.lineWidth));
-        },
-        enum: (e, _, acc, opts) => {
-            if (!(e.tag === "i32" || e.tag === "u32")) {
-                unsupported(`enum ${e.name} must be a i32/u32 in C, but got '${e.tag}'`);
-            }
-            const name = typePrefix + e.name;
-            const lines = [];
-            lines.push(`typedef enum {`);
-            for (let v of e.values) {
-                let line;
-                if (!isString(v)) {
-                    v.doc && gen.doc(v.doc, lines, opts);
-                    line = enumName(opts, v.name);
-                    if (v.value != null)
-                        line += ` = ${v.value}`;
-                }
-                else {
-                    line = enumName(opts, v);
-                }
-                lines.push(line + ",");
-            }
-            lines.push(`} ${name};`, "");
-            acc.push(...withIndentation(lines, INDENT, ...SCOPES));
-        },
-        struct: (struct, coll, acc, opts) => {
-            const name = typePrefix + struct.name;
-            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.d.ts

@@ -1,25 +0,0 @@
-import { CodeGenOptsBase, ICodeGen } from "../api.js";
-/**
- * TypeScript code generator options.
- */
-export interface TSOpts extends CodeGenOptsBase {
-    /**
-     * Indentation string
-     *
-     * @defaultValue "\t"
-     */
-    indent: string;
-}
-/**
- * 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 declare const TYPESCRIPT: (opts?: Partial<TSOpts>) => ICodeGen;
-//# sourceMappingURL=typescript.d.ts.map