@thi.ng/wasm-api 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-09-21T21:37:59Z
+- **Last updated**: 2022-10-03T16:07:55Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,35 @@ 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.12.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.12.0) (2022-10-03)
+
+#### 🚀 Features
+
+- update CLI ([98d2414](https://github.com/thi-ng/umbrella/commit/98d2414))
+  - add optional type analytics JSON output
+  - add support for including user code via `@`-file references
+  - update config `@`-file refs to resolve relative to config file
+- add support for sentinels & user type body injection ([d240046](https://github.com/thi-ng/umbrella/commit/d240046))
+  - update sizeOf() to include sentinels
+  - add TopLevelType.body for extra user code
+  - update Zig codegen to:
+    - support array/slice sentinels
+    - add optional user code injection
+    - add `std` import header
+- add ReadonlyWasmString, update impls ([240a148](https://github.com/thi-ng/umbrella/commit/240a148))
+- add default value support for Zig codegen ([3c37ae7](https://github.com/thi-ng/umbrella/commit/3c37ae7))
+- add doc string word wrapping ([c0b8e15](https://github.com/thi-ng/umbrella/commit/c0b8e15))
+  - update prefixLines(), add target line width arg
+  - update ICodeGen & CodeGenOpts
+  - update all codegens
+  - update deps
+
+#### 🩹 Bug fixes
+
+- update zig panic handler sig for latest zig master version ([cb51bf6](https://github.com/thi-ng/umbrella/commit/cb51bf6))
+  - see https://github.com/ziglang/zig/commit/694fab484805088030fa36efe3e6b6e7ee385852
+- minor fix word wrap line width ([053ba0f](https://github.com/thi-ng/umbrella/commit/053ba0f))
+
 ## [0.11.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@0.11.0) (2022-09-21)
 
 #### 🚀 Features

package/README.md

@@ -1,6 +1,6 @@
 <!-- This file is generated - DO NOT EDIT! -->
 
-# ![wasm-api](https://media.thi.ng/umbrella/banners-20220914/thing-wasm-api.svg?eb6dbc93)
+# ![wasm-api](https://media.thi.ng/umbrella/banners-20220914/thing-wasm-api.svg?be328da7)
 
 [![npm version](https://img.shields.io/npm/v/@thi.ng/wasm-api.svg)](https://www.npmjs.com/package/@thi.ng/wasm-api)
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/wasm-api.svg)
@@ -19,8 +19,10 @@ This project is part of the
   - [Custom API modules](#custom-api-modules)
   - [Object indices & handles](#object-indices--handles)
 - [Status](#status)
+- [Support packages](#support-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
 - [Basic usage example](#basic-usage-example)
   - [Zig version](#zig-version)
@@ -39,9 +41,10 @@ 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/typedarray accessors for
-8/16/32/64 bit (u)ints and 32/64 bit floats, memory allocation (optional). In
-the future we aim to also supply support modules for DOM manipulation, WebGL,
-WebGPU, WebAudio etc.
+8/16/32/64 bit (u)ints and 32/64 bit floats, memory allocation (optional).
+Additionally, a number of support modules for [DOM
+manipulation](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom/),
+WebGL, WebGPU, WebAudio etc. is being actively worked on.
 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 extern JS [core
@@ -51,7 +54,7 @@ WebGPU, WebAudio etc.
    [Zig](https://ziglang.org). The latter also generates fully type checked
    memory-mapped (zero-copy) 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.
+bindings for these mentioned langs are included.
 5. [CLI frontend/utility](#cli-generator) to invoke the code generator(s)
 
 ### Data bindings & code generators
@@ -59,7 +62,9 @@ bindings for these few langs are included.
 The package provides an extensible codegeneration framework to simplify the
 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 available too.
+planned). A CLI wrapper is available too. See the
+[@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom/)
+support package for a more thorough realworld example...
 
 #### CLI generator
 
@@ -73,7 +78,7 @@ $ npx @thi.ng/wasm-api
 
  █ █   █           │
 ██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.11.0
+ █ █ █ █   █ █ █ █ │ @thi.ng/wasm-api 0.12.0
  █ █ █ █ █ █ █ █ █ │ Multi-language data bindings code generator
                  █ │
                █ █ │
@@ -88,6 +93,7 @@ Flags:
 
 Main:
 
+-a FILE, --analytics FILE       output file path for raw codegen analytics
 -c FILE, --config FILE          JSON config file with codegen options
 -l ID[,..], --lang ID[,..]      [multiple] target language: "c11", "ts", "zig" (default: ["ts","zig"])
 -o FILE, --out FILE             [multiple] output file path
@@ -195,42 +201,59 @@ codes:
 <details><summary>generated.ts (generated TypeScript source)</summary>
 
 ```ts
-/** Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.189Z - DO NOT EDIT! */
+/**
+ * Generated by @thi.ng/wasm-api at 2022-10-03T15:32:12.339Z - DO NOT EDIT!
+ */
 
-import type { WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
+// @ts-ignore possibly includes unused imports
+import { Pointer, WasmStringSlice, WasmTypeBase, WasmTypeConstructor } from "@thi.ng/wasm-api";
 
-/** Example struct */
+/**
+ * Example struct
+ */
 export interface Foo extends WasmTypeBase {
 	color: Float32Array;
 	bars: Bar[];
-	/** Unique ID */
+	/**
+	 * 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;
-		},
-	})
+	get align() {
+		return 16;
+	},
+	get size() {
+		return 48;
+	},
+	instance: (base) => {
+		return {
+			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 {
@@ -239,24 +262,34 @@ export interface Bar extends WasmTypeBase {
 }
 
 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;
-		},
-	})
+	get align() {
+		return 4;
+	},
+	get size() {
+		return 8;
+	},
+	instance: (base) => {
+		return {
+			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 {
@@ -270,7 +303,9 @@ export enum Kind {
 <details><summary>generated.zig (generated Zig source)</summary>
 
 ```zig
-//! Generated by @thi.ng/wasm-api at 2022-08-15T22:32:21.191Z - DO NOT EDIT!
+//! Generated by @thi.ng/wasm-api at 2022-10-03T15:32:12.341Z - DO NOT EDIT!
+
+const std = @import("std");
 
 /// Example struct
 pub const Foo = struct {
@@ -286,9 +321,9 @@ pub const Bar = struct {
 };
 
 pub const Kind = enum(u16) {
-    unknown,
-    good = 100,
-    best = 1000,
+    UNKNOWN,
+    GOOD = 100,
+    BEST = 1000,
 };
 ```
 </details>
@@ -538,6 +573,10 @@ canvases.delete(0);
 
 [Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bwasm-api%5D+in%3Atitle)
 
+## Support packages
+
+- [@thi.ng/wasm-api-dom](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-dom) - Browser DOM bridge API for hybrid TypeScript & Zig applications
+
 ## Installation
 
 ```bash
@@ -561,7 +600,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 6.05 KB
+Package sizes (gzipped, pre-treeshake): ESM: 6.29 KB
 
 **IMPORTANT:** The package includes code generators for various languages which
 are **not** required for just using the API bridge. Hence, the usual package
@@ -581,6 +620,19 @@ size in production will be MUCH smaller than what's stated here!
 - [@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)
 - [@thi.ng/paths](https://github.com/thi-ng/umbrella/tree/develop/packages/paths)
+- [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
+
+## Usage examples
+
+Several demos in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory are using this package.
+
+A selection:
+
+| Screenshot                                                                                                        | Description                                 | Live demo                                        | Source                                                                        |
+|:------------------------------------------------------------------------------------------------------------------|:--------------------------------------------|:-------------------------------------------------|:------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/> | Zig-based DOM creation & canvas drawing app | [Demo](https://demo.thi.ng/umbrella/zig-canvas/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas) |
 
 ## API
 

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { BigType, FloatType, Fn } from "@thi.ng/api";
+import type { BigType, FloatType, Fn, IDeref, ILength, IObjectOf } from "@thi.ng/api";
 import type { WasmBridge } from "./bridge.js";
 export declare const PKG_NAME = "@thi.ng/wasm-api";
 export declare const EVENT_MEMORY_CHANGED = "memory-changed";
@@ -175,6 +175,9 @@ 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 ReadonlyWasmString = IDeref<string> & ILength & {
+    readonly addr: number;
+};
 export declare type TypeColl = Record<string, TopLevelType>;
 export interface TypeInfo {
     /**
@@ -209,6 +212,14 @@ export interface TopLevelType extends TypeInfo {
      * Type / kind
      */
     type: "struct" | "enum";
+    /**
+     * Optional object of user provided source codes to be injected into the
+     * generated type. Keys are language IDs (same name as respective codegen).
+     *
+     * @remarks
+     * Currently only supported by the {@link ZIG} codegen, ignored otherwise.
+     */
+    body?: IObjectOf<string>;
 }
 export interface Struct extends TopLevelType {
     type: "struct";
@@ -276,7 +287,8 @@ export interface StructField extends TypeInfo {
      */
     const?: boolean;
     /**
-     * TODO currently unsupported & ignored!
+     * Currently only supported for {@link ZIG} arrays & slices, otherwise
+     * ignored!
      */
     sentinel?: number;
     /**
@@ -284,9 +296,10 @@ export interface StructField extends TypeInfo {
      */
     len?: number;
     /**
-     * TODO currently unsupported & ignored!
+     * Currently only supported for {@link ZIG} scalar & string values,
+     * otherwise ignored!
      */
-    default?: any;
+    default?: number;
     /**
      * If defined and > 0, the field will be considered for padding purposes only and
      * the value provided is the number of bytes used.
@@ -363,6 +376,12 @@ export interface CodeGenOpts extends CodeGenOptsBase {
      * @defaultValue false
      */
     debug: boolean;
+    /**
+     * Target line width for word wrapping doc strings
+     *
+     * @defaultValue 80
+     */
+    lineWidth: number;
 }
 export interface ICodeGen {
     /**
@@ -376,7 +395,7 @@ export interface ICodeGen {
     /**
      * Docstring codegen
      */
-    doc: (doc: string, acc: string[], topLevel?: boolean) => void;
+    doc: (doc: string, acc: string[], opts: CodeGenOpts, topLevel?: boolean) => void;
     /**
      * Codegen for enum types.
      */

package/bin/wasm-api.mjs_

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { spawn } from "child_process";
+import { realpathSync } from "fs";
+import { join } from "path";
+const [node, toolsDir, ...args] = process.argv;
+
+const cli = join(realpathSync(toolsDir), "..", "..", "cli.js");
+
+const child = spawn(node, ["--loader", "ts-node/esm", cli, ...args]);
+
+child.stderr.on("data", (d) => {
+	const dStr = d.toString().trim();
+	!dStr.includes("ExperimentalWarning") ? console.log(dStr) : "";
+});
+child.on("exit", (err) => process.exit(err));
+child.stdout.pipe(process.stdout);

package/bridge.js

@@ -215,7 +215,7 @@ let WasmBridge = class WasmBridge {
         const addr = this.exports._wasm_allocate(numBytes);
         if (!addr)
             throw new OutOfMemoryError(`unable to allocate: ${numBytes}`);
-        this.logger.debug(`allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.logger.fine(`allocated ${numBytes} bytes @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.ensureMemory();
         clear && this.u8.fill(0, addr, addr + numBytes);
         return addr;
@@ -234,7 +234,7 @@ let WasmBridge = class WasmBridge {
      * @param numBytes
      */
     free(addr, numBytes) {
-        this.logger.debug(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
+        this.logger.fine(`freeing memory @ 0x${U32(addr)} .. 0x${U32(addr + numBytes - 1)}`);
         this.exports._wasm_free(addr, numBytes);
     }
     getI8(addr) {

package/cli.js

@@ -1,10 +1,10 @@
 import { flag, oneOf, oneOfMulti, parse, ParseError, string, strings, usage, } from "@thi.ng/args";
 import { isArray, isPlainObject } from "@thi.ng/checks";
 import { illegalArgs } from "@thi.ng/errors";
-import { mutIn } from "@thi.ng/paths/mut-in";
-import { readJSON, readText, writeText } from "@thi.ng/file-io";
+import { readJSON, readText, writeJSON, writeText } from "@thi.ng/file-io";
 import { ConsoleLogger } from "@thi.ng/logger";
-import { resolve } from "path";
+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";
@@ -12,6 +12,11 @@ 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",
@@ -70,6 +75,16 @@ const addTypeSpec = (ctx, path, coll, spec) => {
         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 (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;
@@ -141,20 +156,26 @@ try {
         opts,
     };
     if (opts.config) {
-        ctx.config = readJSON(resolve(opts.config), ctx.logger);
+        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(conf.pre.substring(1), ctx.logger);
+                conf.pre = readText(resolve(dirname(opts.config), conf.pre.substring(1)), ctx.logger);
             }
             if (conf.post && conf.post[0] === "@") {
-                conf.post = readText(conf.post.substring(1), ctx.logger);
+                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);
-    generateOutputs(ctx, parseTypeSpecs(ctx, rest));
+    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))

package/codegen/c11.js

@@ -36,8 +36,8 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
 #include <stddef.h>
 #include <stdint.h>${opts.pre ? `\n${opts.pre}` : ""}`,
         post: () => opts.post || "",
-        doc: (doc, acc) => {
-            acc.push(prefixLines("// ", doc));
+        doc: (doc, acc, opts) => {
+            acc.push(...prefixLines("// ", doc, opts.lineWidth));
         },
         enum: (e, _, acc, opts) => {
             if (!(e.tag === "i32" || e.tag === "u32")) {
@@ -49,7 +49,7 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
             for (let v of e.values) {
                 let line;
                 if (!isString(v)) {
-                    v.doc && gen.doc(v.doc, lines);
+                    v.doc && gen.doc(v.doc, lines, opts);
                     line = enumName(opts, v.name);
                     if (v.value != null)
                         line += ` = ${v.value}`;
@@ -74,7 +74,7 @@ ${opts.debug ? "\n#include <stdalign.h>" : ""}
                     res.push(`uint8_t __pad${padID++}[${f.pad}];`);
                     continue;
                 }
-                f.doc && gen.doc(f.doc, res);
+                f.doc && gen.doc(f.doc, res, opts);
                 const fconst = f.const ? "const " : "";
                 let ftype = f.type === "string"
                     ? isStringSlice(opts.stringType)

package/codegen/typescript.js

@@ -24,13 +24,8 @@ export const TYPESCRIPT = (opts = {}) => {
         pre: (opts) => `// @ts-ignore possibly includes unused imports
 import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } from "${PKG_NAME}";${opts.pre ? `\n${opts.pre}` : ""}`,
         post: () => opts.post || "",
-        doc: (doc, acc) => {
-            if (doc.indexOf("\n") !== -1) {
-                acc.push("/**", prefixLines(indent + " * ", doc), " */");
-            }
-            else {
-                acc.push(`/** ${doc} */`);
-            }
+        doc: (doc, acc, opts) => {
+            acc.push("/**", ...prefixLines(" * ", doc, opts.lineWidth), " */");
         },
         enum: (e, _, acc, opts) => {
             const res = [];
@@ -38,7 +33,7 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
             for (let v of e.values) {
                 let line;
                 if (!isString(v)) {
-                    v.doc && gen.doc(v.doc, res);
+                    v.doc && gen.doc(v.doc, res, opts);
                     line = enumName(opts, v.name);
                     if (v.value != null)
                         line += ` = ${v.value}`;
@@ -60,7 +55,7 @@ import { Pointer, ${__stringImpl(opts)}, WasmTypeBase, WasmTypeConstructor } fro
             for (let f of struct.fields) {
                 if (isPadding(f))
                     continue;
-                f.doc && gen.doc(f.doc, lines);
+                f.doc && gen.doc(f.doc, lines, opts);
                 const ftype = __fieldType(f, opts);
                 fieldTypes[f.name] = ftype;
                 lines.push(`${f.name}: ${ftype};`);

package/codegen/utils.d.ts

@@ -21,13 +21,15 @@ export declare const isWasmPrim: (x: string) => x is WasmPrim;
 export declare const isWasmString: (x: string) => x is "string";
 export declare const isPadding: (f: StructField) => boolean;
 /**
- * Takes an array of strings or splits given string into lines, prefixes each
- * line with given `prefix` and then returns rejoined result.
+ * Takes an array of strings or splits given string into lines, word wraps and
+ * then prefixes each line with given `width` and `prefix`. Returns array of new
+ * lines.
  *
  * @param prefix
  * @param str
+ * @param width
  */
-export declare const prefixLines: (prefix: string, str: string | string[]) => string;
+export declare const prefixLines: (prefix: string, str: string | string[], width: number) => string[];
 /**
  * Returns true if `type` is "slice".
  *

package/codegen/utils.js

@@ -1,4 +1,5 @@
 import { isString } from "@thi.ng/checks/is-string";
+import { wordWrapLine, wordWrapLines } from "@thi.ng/strings/word-wrap";
 /**
  * Returns true iff `x` is a {@link WasmPrim32}.
  *
@@ -20,15 +21,17 @@ export const isWasmPrim = (x) => isNumeric(x) || isBigNumeric(x);
 export const isWasmString = (x) => x === "string";
 export const isPadding = (f) => f.pad != null && f.pad > 0;
 /**
- * Takes an array of strings or splits given string into lines, prefixes each
- * line with given `prefix` and then returns rejoined result.
+ * Takes an array of strings or splits given string into lines, word wraps and
+ * then prefixes each line with given `width` and `prefix`. Returns array of new
+ * lines.
  *
  * @param prefix
  * @param str
+ * @param width
  */
-export const prefixLines = (prefix, str) => (isString(str) ? str.split("\n") : str)
-    .map((line) => prefix + line)
-    .join("\n");
+export const prefixLines = (prefix, str, width) => (isString(str)
+    ? wordWrapLines(str, { width: width - prefix.length })
+    : str.flatMap((x) => wordWrapLine(x, { width: width - prefix.length }))).map((line) => prefix + line);
 /**
  * Returns true if `type` is "slice".
  *