@thi.ng/wasm-api 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-08-15T15:40:55Z
+- **Last updated**: 2022-08-15T23:41:37Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.7.0) (2022-08-15)
+
+#### 🚀 Features
+
+- add CLI wrapper for codegens ([683a560](https://github.com/thi-ng/umbrella/commit/683a560))
+- update TSOpts & TS codegen ([4f6bbbf](https://github.com/thi-ng/umbrella/commit/4f6bbbf))
+  - add `uppercaseEnum` option to force UC enum IDs
+- update helper predicates ([65b23d4](https://github.com/thi-ng/umbrella/commit/65b23d4))
+
+#### 🩹 Bug fixes
+
+- allow signed ints for enum tags ([78d0822](https://github.com/thi-ng/umbrella/commit/78d0822))
+- correct TS __mapArray codegen ([289b137](https://github.com/thi-ng/umbrella/commit/289b137))
+
 ## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.6.0) (2022-08-15)
 
 #### 🚀 Features

package/README.md

@@ -13,8 +13,8 @@ This project is part of the
   - [Custom API modules](#custom-api-modules)
   - [Object indices & handles](#object-indices--handles)
   - [Data bindings & code generators](#data-bindings--code-generators)
+    - [CLI generator](#cli-generator)
     - [Data type definitions](#data-type-definitions)
-    - [Code generation](#code-generation)
     - [Example usage](#example-usage)
   - [Status](#status)
 - [Installation](#installation)
@@ -37,22 +37,26 @@ This package provides a the following:
 class as interop basis and much reduced boilerplate for hybrid JS/WebAssembly
 applications.
 2. A minimal core API for debug output, string, pointer, typed array accessors
-(8/16/32/64 bit (u)ints, 32/64 bit floats). In the future we aim to also supply
-support modules for DOM manipulation, WebGL, WebGPU, WebAudio etc.
-3. Extensible shared datatype code generators for (currently)
+for 8/16/32/64 bit (u)ints and 32/64 bit floats. In the future we aim to also
+supply support modules for DOM manipulation, WebGL, WebGPU, WebAudio etc.
+3. [Include files for C11/C++ and
+   Zig](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api/include),
+   defining WASM imports of the JS [core
+   API](https://docs.thi.ng/umbrella/wasm-api/interfaces/CoreAPI.html) defined
+   by this package
+4. Extensible shared datatype code generators for (currently)
    [Zig](https://ziglang.org) & TypeScript. The latter also generates fully type
    checked memory-mapped accessors of WASM-side data. In general, all languages
 with a WebAssembly target are supported, however currently only bindings for
 these few langs are included.
-4. Include files for C11 and Zig, defining imports for the JS core API defined
-   by this package
+5. [CLI frontend/utility](#cli-generator) to invoke the code generator(s)
 
 ### Custom API modules
 
-The WasmBridge is extensible via custom defined API modules. Such API extensions
+The [`WasmBridge`](https://docs.thi.ng/umbrella/wasm-api/classes/WasmBridge.html) is extensible via custom defined API modules. Such API extensions
 will consist of a collection of JS/TS functions & variables, their related
 counterparts (import definitions) for the WASM target and (optionally) some
-shared data types (bindings for which _can_ be generated by this package too).
+shared data types ([bindings for which _can_ be generated by this package too](#data-bindings--code-generators)).
 
 On the JS side, custom API modules can be easily integrated via the [`IWasmAPI`
 interface](https://docs.thi.ng/umbrella/wasm-api/interfaces/IWasmAPI.html). The
@@ -181,21 +185,249 @@ bilateral design & exchange of data structures shared between the WASM & JS host
 env. Currently, code generators for TypeScript & Zig are supplied (more are
 planned). A CLI wrapper is worked on too.
 
-#### Data type definitions
+#### CLI generator
+
+The package includes a [small CLI
+wrapper](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/src/cli.ts)
+to invoke the codegenerator(s) from JSON type definitions and to write the
+generated source code(s) to different files:
+
+```text
+$ npx run @thi.ng/wasm-api
+
+ █ █   █           │
+██ █               │
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.6.0
+ █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
+                 █ │
+               █ █ │
+
+usage: wasm-api [OPTS] JSON-INPUT-FILE(S) ...
+       wasm-api --help
+
+Flags:
+
+-d, --debug                     enable debug output
+--dry-run                       enable dry run (don't overwrite files)
+
+Main:
+
+-c FILE, --config FILE          JSON config file with codegen options
+-l ID[,..], --lang ID[,..]      [multiple] target language: "ts", "zig" (default: ["ts","zig"])
+-o FILE, --out FILE             [multiple] output file path
+```
+
+By default, the CLI generates sources for both TypeScript and Zig (in this
+order!). Order is important, since the output file paths must be given in the
+same order as the target languages. It's recommended to be more explicit. An
+example invocation looks like:
+
+```bash
+wasm-api --config codegen-opts.json \
+  --lang ts -o src/generated.ts \
+  --lang zig -o src.zig/generated.zig \
+  typedefs.json
+```
+
+The structure of the config file is as follows (all optional):
 
-TODO
+```text
+{
+	global: { ... },
+	ts: { ... },
+	zig: { ... },
+}
+```
 
-##### Struct
+More details about possible
+[`global`](https://docs.thi.ng/umbrella/wasm-api/interfaces/CodeGenOpts.html),
+[`ts`](https://docs.thi.ng/umbrella/wasm-api/interfaces/TSOpts.html) and
+[`zig`](https://docs.thi.ng/umbrella/wasm-api/interfaces/ZigOpts.html) config
+options & values.
 
-##### Enum
+#### Data type definitions
 
-#### Code generation
+Currently, the code generator supports structs and enums. See API docs for
+further details:
 
-TODO
+- [`Enum`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Enum.html)
+- [`EnumValue`](https://docs.thi.ng/umbrella/wasm-api/interfaces/EnumValue.html)
+- [`Struct`](https://docs.thi.ng/umbrella/wasm-api/interfaces/Struct.html)
+- [`StructField`](https://docs.thi.ng/umbrella/wasm-api/interfaces/StructField.html)
+- [`TopLevelType`](https://docs.thi.ng/umbrella/wasm-api/interfaces/TopLevelType.html)
 
 #### Example usage
 
-TODO
+Below is an example file with JSON type definitions and the resulting source
+codes:
+
+<details><summary>types.json (Type definitions, click to expand)</summary>
+
+```json
+[
+	{
+		"name": "Foo",
+		"type": "struct",
+		"doc": "Example struct",
+		"auto": true,
+		"fields": [
+			{ "name": "id", "type": "u8", "doc": "Unique ID" },
+			{ "name": "bars", "type": "Bar", "tag": "array", "len": 3 },
+			{ "name": "color", "type": "f32", "tag": "vec", "len": 4 }
+		]
+	},
+	{
+		"name": "Bar",
+		"type": "struct",
+		"fields": [
+			{ "name": "kind", "type": "Kind" },
+			{ "name": "flags", "type": "u32" }
+		]
+	},
+	{
+		"name": "Kind",
+		"type": "enum",
+		"tag": "u16",
+		"values": [
+			"unknown",
+			{ "name": "good", "value": 100 },
+			{ "name": "best", "value": 1000 }
+		]
+	}
+]
+```
+</details>
+
+<details><summary>generated.ts (generated TypeScript source, click to expand)</summary>
+
+```ts
+/** Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.189Z - DO NOT EDIT! */
+
+import type { WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
+
+/** Example struct */
+export interface Foo extends WasmTypeBase {
+	color: Float32Array;
+	bars: Bar[];
+	/** Unique ID */
+	id: number;
+}
+
+export const $Foo: WasmTypeConstructor<Foo> = (mem) => ({
+	get align() { return 16; },
+	get size() { return 48; },
+	instance: (base) => ({
+		get __base() { return base; },
+		get __bytes() { return mem.u8.subarray(base, base + 48); },
+		get color(): Float32Array {
+			const addr = base >>> 2;
+			return mem.f32.subarray(addr, addr + 4);
+		},
+		get bars(): Bar[] {
+			const addr = (base + 16);
+			const inst = $Bar(mem);
+			const slice: Bar[] = [];
+			for(let i = 0; i < 3; i++) slice.push(inst.instance(addr + i * 24));
+			return slice;
+		},
+		get id(): number {
+			return mem.u8[(base + 40)];
+		},
+		set id(x: number) {
+			mem.u8[(base + 40)] = x;
+		},
+	})
+});
+
+export interface Bar extends WasmTypeBase {
+	kind: Kind;
+	flags: number;
+}
+
+export const $Bar: WasmTypeConstructor<Bar> = (mem) => ({
+	get align() { return 4; },
+	get size() { return 8; },
+	instance: (base) => ({
+		get __base() { return base; },
+		get __bytes() { return mem.u8.subarray(base, base + 8); },
+		get kind(): Kind {
+			return mem.u16[base >>> 1];
+		},
+		set kind(x: Kind) {
+			mem.u16[base >>> 1] = x;
+		},
+		get flags(): number {
+			return mem.u32[(base + 4) >>> 2];
+		},
+		set flags(x: number) {
+			mem.u32[(base + 4) >>> 2] = x;
+		},
+	})
+});
+
+export enum Kind {
+	UNKNOWN,
+	GOOD = 100,
+	BEST = 1000,
+}
+```
+</details>
+
+<details><summary>generated.zig (generated Zig source, click to expand)</summary>
+
+```zig
+//! Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.191Z - DO NOT EDIT!
+
+/// Example struct
+pub const Foo = struct {
+    color: @Vector(4, f32),
+    bars: [3]Bar,
+    /// Unique ID
+    id: u8,
+};
+
+pub const Bar = struct {
+    kind: Kind,
+    flags: u32,
+};
+
+pub const Kind = enum(u16) {
+    unknown,
+    good = 100,
+    best = 1000,
+};
+```
+</details>
+
+On the TypeScript/JS side, the memory-mapped wrappers (e.g. `$Foo` and `$Bar`)
+can be used in combination with the `WasmBridge` to obtain fully typed views
+(according to the generated types) of the underlying WASM memory. Basic usage is
+like:
+
+```ts
+import { WasmBridge } from "@thi.ng/wasm-api";
+import { $Foo, Kind } from "./generated.ts";
+
+const bridge = new WasmBridge();
+// bridge initialization omitted here (see other examples below)
+// ...
+
+// Create an instance using the bridge's memory views
+// and mapping a `Foo` struct from given address
+// (e.g. obtained from an exported WASM function/value)
+const foo = $Foo(bridge).instance(0x10000);
+
+// then use like normal JS object
+foo.color
+// Float32Array(4) [0.1, 0.2, 0.3, 0.4]
+
+// this even applies to arrays using other types
+// (setters are currently only supported for scalar values, incl. enums)
+foo.bars[2].kind = Kind.BEST;
+
+// IMPORTANT: any modifications like this are directly
+// applied to the underlying WASM memory...
+```
 
 ### Status
 
@@ -226,7 +458,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 3.98 KB
+Package sizes (gzipped, pre-treeshake): ESM: 4.03 KB
 
 **IMPORTANT:** The package includes various code generators and supporting
 functions which are NOT required during runtime. Hence the actual package size
@@ -235,11 +467,13 @@ in production will be MUCH smaller!
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/args](https://github.com/thi-ng/umbrella/tree/develop/packages/args)
 - [@thi.ng/binary](https://github.com/thi-ng/umbrella/tree/develop/packages/binary)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
 - [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
+- [@thi.ng/file-io](https://github.com/thi-ng/umbrella/tree/develop/packages/file-io)
 - [@thi.ng/hex](https://github.com/thi-ng/umbrella/tree/develop/packages/hex)
 - [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { FloatType, Fn, Fn2 } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, Fn2 } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare type BigIntArray = bigint[] | BigInt64Array | BigUint64Array;
@@ -131,6 +131,7 @@ export declare type WasmInt = "i8" | "i16" | "i32" | "i64";
 export declare type WasmUint = "u8" | "u16" | "u32" | "u64";
 export declare type WasmFloat = FloatType;
 export declare type WasmPrim = WasmInt | WasmUint | WasmFloat;
+export declare type WasmPrim32 = Exclude<WasmPrim, BigType>;
 export declare type TypeColl = Record<string, TopLevelType>;
 export interface TypeInfo {
     /**
@@ -153,16 +154,30 @@ export interface TypeInfo {
     __align?: number;
 }
 export interface TopLevelType extends TypeInfo {
+    /**
+     * Type name
+     */
     name: string;
+    /**
+     * Optional (multi-line) docstring for this type
+     */
     doc?: string;
+    /**
+     * Type / kind
+     */
     type: "struct" | "enum";
 }
 export interface Struct extends TopLevelType {
     type: "struct";
+    /**
+     * List of struct fields (might be re-ordered if {@link Struct.auto} is
+     * enabled).
+     */
     fields: StructField[];
     /**
      * If true, struct fields will be re-ordered in descending order based on
-     * their {@link TypeInfo.__align} size.
+     * their {@link TypeInfo.__align} size. This might result in overall smaller
+     * structs due to minimizing inter-field padding.
      *
      * @defaultValue false
      */
@@ -178,8 +193,18 @@ export interface StructField extends TypeInfo {
      */
     doc?: string;
     /**
-     * Field type tag/qualifier (note: `slice` & `vec` are only supported by
-     * Zig & TS)
+     * Field type tag/qualifier (note: `slice` & `vec` are only supported by Zig
+     * & TS).
+     *
+     * @remarks
+     * - Array & vector fields are statically sized (using
+     *   {@link StructField.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
+     * - Zig slices are essentially a pointer w/ associated length
+     * - Zig vectors will be processed using SIMD (if enabled in WASM target)
+     *   and therefore will have stricter (larger) alignment requirements.
      *
      * @defaultValue "scalar"
      */
@@ -189,32 +214,46 @@ export interface StructField extends TypeInfo {
      * interpreted as another type name in the {@link TypeColl}.
      *
      * TODO `opaque` currently unsupported.
+     * TODO add string support (see {@link StructField.sentinel})
      */
     type: WasmPrim | "opaque" | string;
     /**
-     * TODO currently unsupported!
+     * TODO currently unsupported & ignored!
      */
     sentinel?: number;
     /**
-     * Array or vector length
+     * Array or vector length (see {@link StructField.tag})
      */
     len?: number;
     /**
-     * TODO currently unsupported!
+     * TODO currently unsupported & ignored!
      */
     default?: any;
 }
 export interface Enum extends TopLevelType {
     type: "enum";
     /**
-     * No u64 support, due to Typescript not supporting bigint enum values
+     * No i64/u64 support, due to Typescript not supporting bigint enum values
+     */
+    tag: Exclude<WasmPrim32, FloatType>;
+    /**
+     * List of possible values/IDs. Use {@link EnumValue}s for more detailed
+     * config.
      */
-    tag: Exclude<WasmUint, "u64">;
     values: (string | EnumValue)[];
 }
 export interface EnumValue {
+    /**
+     * Enum value name/ID
+     */
     name: string;
+    /**
+     * Optional associated numeric value
+     */
     value?: number;
+    /**
+     * Optional docstring for this value
+     */
     doc?: string;
 }
 export interface ICodeGen {
@@ -226,8 +265,17 @@ export interface ICodeGen {
      * Optional source code to be appended after any generated type defs.
      */
     post?: string;
+    /**
+     * Docstring codegen
+     */
     doc: (doc: string, indent: string, acc: string[], topLevel?: boolean) => void;
+    /**
+     * Codegen for enum types.
+     */
     enum: (type: Enum, types: TypeColl, acc: string[]) => void;
+    /**
+     * Codegen for struct types.
+     */
     struct: (type: Struct, types: TypeColl, acc: string[]) => void;
 }
 /**

package/bin/wasm-api

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# https://stackoverflow.com/a/246128/294515
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$( cd -P "$( dirname "$SOURCE" )" >/dev/null 2>&1 && pwd )"
+
+/usr/bin/env node "$DIR/../cli.js" "$DIR" "$@"

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 { isPrim } 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 (!(isPrim(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

@@ -6,6 +6,10 @@ export interface TSOpts {
      * @defaultValue "\t"
      */
     indent: string;
+    /**
+     * If true (default), forces uppercase enums
+     */
+    uppercaseEnums: boolean;
 }
 /**
  * TypeScript code generator. Call with options and then pass to

package/codegen/typescript.js

@@ -14,7 +14,11 @@ import { isBigNumeric, isNumeric, isPrim, prefixLines } from "./utils.js";
  * @param opts
  */
 export const TYPESCRIPT = (opts) => {
-    const { indent } = { indent: "\t", ...opts };
+    const { indent, uppercaseEnums } = {
+        indent: "\t",
+        uppercaseEnums: true,
+        ...opts,
+    };
     const I = indent;
     const I2 = I + I;
     const I3 = I2 + I;
@@ -35,12 +39,12 @@ export const TYPESCRIPT = (opts) => {
                 var 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 + ",");
             }
@@ -89,13 +93,13 @@ export const TYPESCRIPT = (opts) => {
                     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)}`);
+                        : `${I3}const addr = ${__ptr(offset)};\n${__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)}`);
+                        : `${I3}const addr = ${__addr(offset)};\n${__mapArray(f, I3, f.len)}`);
                 }
                 else {
                     let setter;
@@ -133,14 +137,17 @@ 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;`);

package/codegen/utils.d.ts

@@ -1,5 +1,29 @@
-export declare const isNumeric: (x: string) => boolean;
-export declare const isBigNumeric: (x: string) => boolean;
-export declare const isPrim: (x: string) => boolean;
+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 isPrim: (x: string) => x is WasmPrim;
+/**
+ * Splits given string into lines, prefixes each with given `prefix` and then
+ * returns rejoined result.
+ *
+ * @param prefix
+ * @param str
+ */
 export declare const prefixLines: (prefix: string, str: string) => string;
 //# sourceMappingURL=utils.d.ts.map

package/codegen/utils.js

@@ -1,6 +1,28 @@
-export const isNumeric = (x) => /^([iu](8|16|32))|(f(32|64))$/.test(x);
+/**
+ * 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 isPrim = (x) => isNumeric(x) || isBigNumeric(x);
+/**
+ * Splits given string into lines, prefixes each with given `prefix` and then
+ * returns rejoined result.
+ *
+ * @param prefix
+ * @param str
+ */
 export const prefixLines = (prefix, str) => str
     .split("\n")
     .map((line) => prefix + line)

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Generic, modular, extensible API bridge, glue code and bindings code generator for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
+  "bin": "bin/wasm-api",
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -36,11 +37,13 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.4.0",
+    "@thi.ng/args": "^2.2.0",
     "@thi.ng/binary": "^3.3.3",
     "@thi.ng/checks": "^3.2.4",
     "@thi.ng/compare": "^2.1.10",
     "@thi.ng/defmulti": "^2.1.12",
     "@thi.ng/errors": "^2.1.10",
+    "@thi.ng/file-io": "^0.3.9",
     "@thi.ng/hex": "^2.1.9",
     "@thi.ng/idgen": "^2.1.11",
     "@thi.ng/logger": "^1.2.0"
@@ -80,8 +83,9 @@
   "files": [
     "*.js",
     "*.d.ts",
-    "codegen",
-    "include"
+    "bin",
+    "include",
+    "codegen"
   ],
   "exports": {
     ".": {
@@ -113,5 +117,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "295e76c6f68ef34ba2117ff77612848e09f5c587\n"
+  "gitHead": "78193cdd838d9d09114352b117b6c5e92631e3cd\n"
 }