@venn-lang/fmt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinicius Borges
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @venn-lang/fmt
+
+> The `fmt` namespace: a value in, formatted text out. JSON, tables, YAML, CSV and XML.
+
+Formatting is kept separate from printing on purpose. Every verb here returns a `string`, which is a
+value you can print, assert against, send in a request or write to a file, not something that only
+ever reaches a terminal. The plugin is pure: it needs no host capability and touches nothing.
+
+## Install
+
+`@venn-lang/fmt` is part of the stdlib the `venn` CLI and the language server load, so there is nothing
+to install. A file that formats says so:
+
+```ruby
+use "venn/fmt"
+```
+
+## Usage
+
+```ruby
+# report.vn, run with `venn run report.vn`
+use "venn/fmt"
+
+const people = [
+  { name: "Ada",   age: 36 },
+  { name: "Linus", age: 54 }
+]
+
+print fmt.table(people)
+print fmt.csv(people)
+print fmt.json({ count: people.len }, 0)
+```
+
+```
+name  │ age
+──────┼────
+Ada   │ 36
+Linus │ 54
+name,age
+Ada,36
+Linus,54
+{"count":2}
+```
+
+`print` is in the prelude, so that file imports nothing but `fmt`.
+
+## Verbs
+
+| Verb | Signature | What it does |
+| --- | --- | --- |
+| `fmt.json` | `(dynamic, number?) -> string` | JSON text. Indents by 2 by default; `fmt.json(x, 0)` puts it on one line. A value that contains itself degrades instead of throwing. |
+| `fmt.table` | `(list<dynamic>) -> string` | An aligned ASCII table of a list of records. |
+| `fmt.yaml` | `(dynamic) -> string` | YAML for a map, a list or a scalar. |
+| `fmt.csv` | `(list<dynamic>, string?) -> string` | CSV with a header row. `fmt.csv(rows, ";")` changes the separator. |
+| `fmt.xml` | `(dynamic, string?) -> string` | XML text. `fmt.xml(x, "user")` names the root element, which is `root` otherwise. |
+
+Every knob is positional, and every verb ends in a `string`. None of them reads an options map, so
+none declares one: an options map in the editor's hover that the verb never looks at would quietly
+strip the keys a caller wrote there.
+
+### What each renderer decides
+
+- **`table`** takes the columns from the union of every row's keys, in first-seen order, so a row
+  missing a field still lines up. Each column is padded to its widest cell. An empty list renders as
+  `(no rows)`.
+- **`yaml`** puts a scalar on its key's line and opens an indented block for a map or a list. A
+  string that would not read back as plain YAML is quoted, and so is the empty string. An empty list
+  is `[]` and an empty map is `{}`.
+- **`csv`** follows RFC 4180: a field is quoted only when it holds a separator, a quote or a
+  newline, and inner quotes are doubled. A list with no records renders as the empty string.
+- **`xml`** turns keys into elements and repeats a tag for each item of a list. Text is escaped
+  (`&`, `<`, `>`, `"`), and a map with nothing in it becomes a self-closing element.
+
+## API
+
+| Export | What it is |
+| --- | --- |
+| `fmtPlugin` (also the default export) | The `PluginDefinition`: namespace `fmt`, five actions, no required capability, no types of its own. |
+| `fmtActions` | The five `ActionDefinition`s. |
+| `toJson(value, spaces?)` | The renderer behind `fmt.json`. Defaults to 2 spaces. |
+| `toTable(rows)` | The renderer behind `fmt.table`. |
+| `toYaml(value, indent?)` | The renderer behind `fmt.yaml`. |
+| `toCsv(rows, separator?)` | The renderer behind `fmt.csv`. Defaults to a comma. |
+| `toXml(value, tag?, indent?)` | The renderer behind `fmt.xml`. Defaults to the tag `root`. |
+
+The renderers are plain functions with no context and no ports, so they are usable on their own:
+
+```ts
+import { toCsv, toYaml } from "@venn-lang/fmt";
+
+toCsv([{ text: 'say "hi", now', plain: "ok" }]);
+// 'text,plain\n"say ""hi"", now",ok'
+
+toYaml({ name: "Ada", tags: ["a", "b"], nested: { n: 1 } });
+// "name: Ada\ntags:\n  - a\n  - b\nnested:\n  n: 1"
+```
+
+## See also
+
+- [`@venn-lang/io`](../std-io) for writing the resulting text to standard output or standard error.
+- [`@venn-lang/assert`](../std-assert) for asserting on it once it is a string.
+- [`@venn-lang/sdk`](../sdk) for `defineAction` and the typed argument helpers used here.

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { ActionDefinition, PluginDefinition } from "@venn-lang/sdk";
+//#region src/actions/fmt-actions.d.ts
+/**
+ * The verbs of the `fmt` namespace: a value in, a string out.
+ *
+ * Formatting is kept apart from printing on purpose. The string is a value you
+ * can compare in a test, send in a request or write to a file, not something
+ * that only ever reaches a terminal.
+ *
+ * Every verb is positional and none reads an options map, so none declares a
+ * params schema: one would put a `{ … }` in the editor's hover that the verb
+ * never looks at, and would quietly strip the keys a caller wrote there.
+ */
+declare const fmtActions: ActionDefinition[];
+//#endregion
+//#region src/plugin.d.ts
+/**
+ * The `fmt` plugin: a value to text, as JSON, a table, YAML, CSV or XML.
+ *
+ * Every verb is pure, so the plugin needs no host capability and runs anywhere,
+ * the LSP included. What comes back is a string, yours to print, compare or send.
+ */
+declare const fmtPlugin: PluginDefinition;
+//#endregion
+//#region src/render/csv.d.ts
+/**
+ * Renders a list of records as CSV with a header row.
+ *
+ * Columns are the union of every record's keys, in first-seen order, so a
+ * record missing a field still lines up. A field is quoted only when it holds a
+ * separator, a quote or a newline, and inner quotes are doubled (RFC 4180).
+ *
+ * @param rows The records to render. Anything that is not a record is skipped.
+ * @param separator What goes between fields. A comma by default.
+ * @returns The CSV text, or an empty string when no record survives the filter.
+ */
+declare function toCsv(rows: readonly unknown[], separator?: string): string;
+//#endregion
+//#region src/render/json.d.ts
+/**
+ * Renders a value as JSON text.
+ *
+ * A value JSON cannot express (a cycle, a BigInt) falls back to `String(value)`
+ * instead of throwing: formatting is not where a run should die.
+ *
+ * @param value What to render.
+ * @param spaces Spaces per level of nesting. 0 puts it all on one line.
+ * @returns The JSON text.
+ */
+declare function toJson(value: unknown, spaces?: number): string;
+//#endregion
+//#region src/render/table.d.ts
+/**
+ * Renders a list of records as an aligned table, for reading in a terminal.
+ *
+ * Columns are the union of every row's keys, in first-seen order, so a row
+ * missing a field still lines up. Each column is as wide as its widest cell.
+ *
+ * @param rows The records to render. Anything that is not a record is skipped.
+ * @returns The table text, or `(no rows)` when there is nothing to show.
+ */
+declare function toTable(rows: readonly unknown[]): string;
+//#endregion
+//#region src/render/xml.d.ts
+/**
+ * Renders a value as indented XML.
+ *
+ * A map's keys become tags; a list repeats the tag it was given, once per item.
+ * Text is escaped. Attributes are never produced, so a round trip through this
+ * and back is not the identity.
+ *
+ * @param value What to render.
+ * @param tag The name of the outermost element.
+ * @param indent Depth to start at, two spaces per level. The recursion sets it.
+ * @returns The XML text, with no declaration or prologue.
+ */
+declare function toXml(value: unknown, tag?: string, indent?: number): string;
+//#endregion
+//#region src/render/yaml.d.ts
+/**
+ * Renders a value as YAML: maps, lists and scalars, two spaces per level.
+ *
+ * A string is quoted only where plain style would change what it means. Empty
+ * maps and lists print as `{}` and `[]`, since a block with nothing under it
+ * would read as an absent value.
+ *
+ * @param value What to render.
+ * @param indent Depth to start at. The recursion sets it.
+ * @returns The YAML text, with no document marker.
+ */
+declare function toYaml(value: unknown, indent?: number): string;
+//#endregion
+export { fmtPlugin as default, fmtPlugin, fmtActions, toCsv, toJson, toTable, toXml, toYaml };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/actions/fmt-actions.ts","../src/plugin.ts","../src/render/csv.ts","../src/render/json.ts","../src/render/table.ts","../src/render/xml.ts","../src/render/yaml.ts"],"mappings":";;;;;;;;;;;;;cA4Ba,YAAY;;;;;;;;;cCnBZ,WAAW;;;;;;;;;;;;;;iBCIR,MAAM,0BAA0B;;;;;;;;;;;;;iBCHhC,OAAO,gBAAgB;;;;;;;;;;;;iBCCvB,QAAQ;;;;;;;;;;;;;;;iBCCR,MAAM,gBAAgB,cAAc;;;;;;;;;;;;;;iBCDpC,OAAO,gBAAgB"}

package/dist/index.js

@@ -0,0 +1,271 @@
+import { arg, defineAction, definePlugin, optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+//#region src/render/csv.ts
+/**
+* Renders a list of records as CSV with a header row.
+*
+* Columns are the union of every record's keys, in first-seen order, so a
+* record missing a field still lines up. A field is quoted only when it holds a
+* separator, a quote or a newline, and inner quotes are doubled (RFC 4180).
+*
+* @param rows The records to render. Anything that is not a record is skipped.
+* @param separator What goes between fields. A comma by default.
+* @returns The CSV text, or an empty string when no record survives the filter.
+*/
+function toCsv(rows, separator = ",") {
+	const records = rows.filter(isRow$1);
+	if (records.length === 0) return "";
+	const columns = columnsOf$1(records);
+	return [columns.map(quote).join(separator), ...records.map((row) => columns.map((c) => quote(cell$1(row[c]))).join(separator))].join("\n");
+}
+function isRow$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function columnsOf$1(rows) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const row of rows) for (const key of Object.keys(row)) seen.add(key);
+	return [...seen];
+}
+function cell$1(value) {
+	if (value === null || value === void 0) return "";
+	return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+/** Quote when the field holds a separator, a quote or a newline; double inner quotes. */
+function quote(field) {
+	if (!/[",;\t\n\r]/.test(field)) return field;
+	return `"${field.replace(/"/g, "\"\"")}"`;
+}
+//#endregion
+//#region src/render/json.ts
+/**
+* Renders a value as JSON text.
+*
+* A value JSON cannot express (a cycle, a BigInt) falls back to `String(value)`
+* instead of throwing: formatting is not where a run should die.
+*
+* @param value What to render.
+* @param spaces Spaces per level of nesting. 0 puts it all on one line.
+* @returns The JSON text.
+*/
+function toJson(value, spaces = 2) {
+	try {
+		return JSON.stringify(value, null, spaces) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+//#endregion
+//#region src/render/table.ts
+/**
+* Renders a list of records as an aligned table, for reading in a terminal.
+*
+* Columns are the union of every row's keys, in first-seen order, so a row
+* missing a field still lines up. Each column is as wide as its widest cell.
+*
+* @param rows The records to render. Anything that is not a record is skipped.
+* @returns The table text, or `(no rows)` when there is nothing to show.
+*/
+function toTable(rows) {
+	const records = rows.filter(isRow);
+	if (records.length === 0) return "(no rows)";
+	const columns = columnsOf(records);
+	const widths = columns.map((column) => widthOf(column, records));
+	return [
+		line(columns, widths),
+		widths.map((width) => "─".repeat(width)).join("─┼─"),
+		...records.map((row) => line(columns.map((column) => cell(row[column])), widths))
+	].join("\n");
+}
+function isRow(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function columnsOf(rows) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const row of rows) for (const key of Object.keys(row)) seen.add(key);
+	return [...seen];
+}
+function widthOf(column, rows) {
+	return rows.reduce((width, row) => Math.max(width, cell(row[column]).length), column.length);
+}
+function line(values, widths) {
+	return values.map((value, index) => value.padEnd(widths[index] ?? 0)).join(" │ ");
+}
+function cell(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+}
+//#endregion
+//#region src/render/xml.ts
+/**
+* Renders a value as indented XML.
+*
+* A map's keys become tags; a list repeats the tag it was given, once per item.
+* Text is escaped. Attributes are never produced, so a round trip through this
+* and back is not the identity.
+*
+* @param value What to render.
+* @param tag The name of the outermost element.
+* @param indent Depth to start at, two spaces per level. The recursion sets it.
+* @returns The XML text, with no declaration or prologue.
+*/
+function toXml(value, tag = "root", indent = 0) {
+	const pad = "  ".repeat(indent);
+	if (Array.isArray(value)) return value.map((item) => toXml(item, tag, indent)).join("\n");
+	if (isMap$1(value)) return element({
+		tag,
+		body: children(value, indent),
+		pad,
+		block: true
+	});
+	return element({
+		tag,
+		body: escaped(text(value)),
+		pad,
+		block: false
+	});
+}
+function children(map, indent) {
+	return Object.entries(map).map(([key, item]) => toXml(item, key, indent + 1)).join("\n");
+}
+function element(args) {
+	const { tag, body, pad } = args;
+	if (!args.block) return `${pad}<${tag}>${body}</${tag}>`;
+	return body === "" ? `${pad}<${tag}/>` : `${pad}<${tag}>\n${body}\n${pad}</${tag}>`;
+}
+function isMap$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+	return value === null || value === void 0 ? "" : String(value);
+}
+function escaped(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+//#endregion
+//#region src/render/yaml.ts
+/**
+* Renders a value as YAML: maps, lists and scalars, two spaces per level.
+*
+* A string is quoted only where plain style would change what it means. Empty
+* maps and lists print as `{}` and `[]`, since a block with nothing under it
+* would read as an absent value.
+*
+* @param value What to render.
+* @param indent Depth to start at. The recursion sets it.
+* @returns The YAML text, with no document marker.
+*/
+function toYaml(value, indent = 0) {
+	const pad = "  ".repeat(indent);
+	if (Array.isArray(value)) return listYaml(value, indent, pad);
+	if (isMap(value)) return mapYaml(value, indent, pad);
+	return `${pad}${scalar(value)}`;
+}
+function listYaml(items, indent, pad) {
+	if (items.length === 0) return `${pad}[]`;
+	return items.map((item) => `${pad}- ${nested(item, indent)}`).join("\n");
+}
+function mapYaml(map, indent, pad) {
+	const entries = Object.entries(map);
+	if (entries.length === 0) return `${pad}{}`;
+	return entries.map(([key, item]) => `${pad}${key}:${suffix(item, indent)}`).join("\n");
+}
+/** A scalar sits on the key's line; a map or list opens a block below it. */
+function suffix(value, indent) {
+	if (isEmpty(value)) return ` ${Array.isArray(value) ? "[]" : "{}"}`;
+	if (Array.isArray(value) || isMap(value)) return `\n${toYaml(value, indent + 1)}`;
+	return ` ${scalar(value)}`;
+}
+/** A nested value under `- `, with its first line already positioned. */
+function nested(value, indent) {
+	if (isEmpty(value) || !Array.isArray(value) && !isMap(value)) return scalar(value);
+	return toYaml(value, indent + 1).trimStart();
+}
+function isEmpty(value) {
+	if (Array.isArray(value)) return value.length === 0;
+	return isMap(value) && Object.keys(value).length === 0;
+}
+function isMap(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const PLAIN = /^[A-Za-z_][\w .-]*$/;
+function scalar(value) {
+	if (value === null || value === void 0) return "null";
+	if (typeof value !== "string") return String(value);
+	return value === "" || !PLAIN.test(value) ? JSON.stringify(value) : value;
+}
+//#endregion
+//#region src/actions/fmt-actions.ts
+function list(value) {
+	return Array.isArray(value) ? value : [value];
+}
+function number(value, fallback) {
+	const parsed = Number(value);
+	return value === void 0 || Number.isNaN(parsed) ? fallback : parsed;
+}
+/**
+* The verbs of the `fmt` namespace: a value in, a string out.
+*
+* Formatting is kept apart from printing on purpose. The string is a value you
+* can compare in a test, send in a request or write to a file, not something
+* that only ever reaches a terminal.
+*
+* Every verb is positional and none reads an options map, so none declares a
+* params schema: one would put a `{ … }` in the editor's hover that the verb
+* never looks at, and would quietly strip the keys a caller wrote there.
+*/
+const fmtActions = [
+	defineAction({
+		name: "json",
+		doc: "JSON text. `fmt.json(x, 0)` puts it on one line; the default indents by 2.",
+		args: [arg("value", t.dynamic, "What to render."), optionalArg("indent", t.number, "Spaces per level. 0 puts it on one line.")],
+		result: t.string,
+		run: (_ctx, input) => toJson(input.args[0], number(input.args[1], 2))
+	}),
+	defineAction({
+		name: "table",
+		doc: "An aligned ASCII table of a list of records.",
+		args: [arg("rows", t.list(t.dynamic), "A list of records. Their keys become the columns.")],
+		result: t.string,
+		run: (_ctx, input) => toTable(list(input.args[0]))
+	}),
+	defineAction({
+		name: "yaml",
+		doc: "YAML text, for a map, a list or a scalar.",
+		args: [arg("value", t.dynamic, "What to render.")],
+		result: t.string,
+		run: (_ctx, input) => toYaml(input.args[0])
+	}),
+	defineAction({
+		name: "csv",
+		doc: "CSV with a header row. `fmt.csv(rows, ';')` changes the separator.",
+		args: [arg("rows", t.list(t.dynamic), "A list of records. Their keys become the header row."), optionalArg("separator", t.string, "What goes between fields. A comma by default.")],
+		result: t.string,
+		run: (_ctx, input) => toCsv(list(input.args[0]), String(input.args[1] ?? ","))
+	}),
+	defineAction({
+		name: "xml",
+		doc: "XML text. `fmt.xml(x, 'user')` names the root element.",
+		args: [arg("value", t.dynamic, "What to render."), optionalArg("root", t.string, "What to call the outermost element.")],
+		result: t.string,
+		run: (_ctx, input) => toXml(input.args[0], String(input.args[1] ?? "root"))
+	})
+];
+//#endregion
+//#region src/plugin.ts
+/**
+* The `fmt` plugin: a value to text, as JSON, a table, YAML, CSV or XML.
+*
+* Every verb is pure, so the plugin needs no host capability and runs anywhere,
+* the LSP included. What comes back is a string, yours to print, compare or send.
+*/
+const fmtPlugin = definePlugin({
+	name: "venn/fmt",
+	version: "0.0.0",
+	namespace: "fmt",
+	actions: fmtActions
+});
+//#endregion
+export { fmtPlugin as default, fmtPlugin, fmtActions, toCsv, toJson, toTable, toXml, toYaml };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["isRow","columnsOf","cell","isMap"],"sources":["../src/render/csv.ts","../src/render/json.ts","../src/render/table.ts","../src/render/xml.ts","../src/render/yaml.ts","../src/actions/fmt-actions.ts","../src/plugin.ts"],"sourcesContent":["type Row = Record<string, unknown>;\n\n/**\n * Renders a list of records as CSV with a header row.\n *\n * Columns are the union of every record's keys, in first-seen order, so a\n * record missing a field still lines up. A field is quoted only when it holds a\n * separator, a quote or a newline, and inner quotes are doubled (RFC 4180).\n *\n * @param rows The records to render. Anything that is not a record is skipped.\n * @param separator What goes between fields. A comma by default.\n * @returns The CSV text, or an empty string when no record survives the filter.\n */\nexport function toCsv(rows: readonly unknown[], separator = \",\"): string {\n  const records = rows.filter(isRow);\n  if (records.length === 0) return \"\";\n  const columns = columnsOf(records);\n  const header = columns.map(quote).join(separator);\n  const body = records.map((row) => columns.map((c) => quote(cell(row[c]))).join(separator));\n  return [header, ...body].join(\"\\n\");\n}\n\nfunction isRow(value: unknown): value is Row {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction columnsOf(rows: readonly Row[]): string[] {\n  const seen = new Set<string>();\n  for (const row of rows) for (const key of Object.keys(row)) seen.add(key);\n  return [...seen];\n}\n\nfunction cell(value: unknown): string {\n  if (value === null || value === undefined) return \"\";\n  return typeof value === \"object\" ? JSON.stringify(value) : String(value);\n}\n\n/** Quote when the field holds a separator, a quote or a newline; double inner quotes. */\nfunction quote(field: string): string {\n  if (!/[\",;\\t\\n\\r]/.test(field)) return field;\n  return `\"${field.replace(/\"/g, '\"\"')}\"`;\n}\n","/**\n * Renders a value as JSON text.\n *\n * A value JSON cannot express (a cycle, a BigInt) falls back to `String(value)`\n * instead of throwing: formatting is not where a run should die.\n *\n * @param value What to render.\n * @param spaces Spaces per level of nesting. 0 puts it all on one line.\n * @returns The JSON text.\n */\nexport function toJson(value: unknown, spaces = 2): string {\n  try {\n    return JSON.stringify(value, null, spaces) ?? String(value);\n  } catch {\n    return String(value);\n  }\n}\n","type Row = Record<string, unknown>;\n\n/**\n * Renders a list of records as an aligned table, for reading in a terminal.\n *\n * Columns are the union of every row's keys, in first-seen order, so a row\n * missing a field still lines up. Each column is as wide as its widest cell.\n *\n * @param rows The records to render. Anything that is not a record is skipped.\n * @returns The table text, or `(no rows)` when there is nothing to show.\n */\nexport function toTable(rows: readonly unknown[]): string {\n  const records = rows.filter(isRow);\n  if (records.length === 0) return \"(no rows)\";\n  const columns = columnsOf(records);\n  const widths = columns.map((column) => widthOf(column, records));\n  return [\n    line(columns, widths),\n    widths.map((width) => \"─\".repeat(width)).join(\"─┼─\"),\n    ...records.map((row) =>\n      line(\n        columns.map((column) => cell(row[column])),\n        widths,\n      ),\n    ),\n  ].join(\"\\n\");\n}\n\nfunction isRow(value: unknown): value is Row {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction columnsOf(rows: readonly Row[]): string[] {\n  const seen = new Set<string>();\n  for (const row of rows) for (const key of Object.keys(row)) seen.add(key);\n  return [...seen];\n}\n\nfunction widthOf(column: string, rows: readonly Row[]): number {\n  return rows.reduce((width, row) => Math.max(width, cell(row[column]).length), column.length);\n}\n\nfunction line(values: readonly string[], widths: readonly number[]): string {\n  return values.map((value, index) => value.padEnd(widths[index] ?? 0)).join(\" │ \");\n}\n\nfunction cell(value: unknown): string {\n  if (value === null || value === undefined) return \"\";\n  if (typeof value === \"object\") return JSON.stringify(value);\n  return String(value);\n}\n","/**\n * Renders a value as indented XML.\n *\n * A map's keys become tags; a list repeats the tag it was given, once per item.\n * Text is escaped. Attributes are never produced, so a round trip through this\n * and back is not the identity.\n *\n * @param value What to render.\n * @param tag The name of the outermost element.\n * @param indent Depth to start at, two spaces per level. The recursion sets it.\n * @returns The XML text, with no declaration or prologue.\n */\nexport function toXml(value: unknown, tag = \"root\", indent = 0): string {\n  const pad = \"  \".repeat(indent);\n  if (Array.isArray(value)) return value.map((item) => toXml(item, tag, indent)).join(\"\\n\");\n  if (isMap(value)) return element({ tag, body: children(value, indent), pad, block: true });\n  return element({ tag, body: escaped(text(value)), pad, block: false });\n}\n\nfunction children(map: Record<string, unknown>, indent: number): string {\n  return Object.entries(map)\n    .map(([key, item]) => toXml(item, key, indent + 1))\n    .join(\"\\n\");\n}\n\nfunction element(args: { tag: string; body: string; pad: string; block: boolean }): string {\n  const { tag, body, pad } = args;\n  if (!args.block) return `${pad}<${tag}>${body}</${tag}>`;\n  return body === \"\" ? `${pad}<${tag}/>` : `${pad}<${tag}>\\n${body}\\n${pad}</${tag}>`;\n}\n\nfunction isMap(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction text(value: unknown): string {\n  return value === null || value === undefined ? \"\" : String(value);\n}\n\nfunction escaped(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\");\n}\n","/**\n * Renders a value as YAML: maps, lists and scalars, two spaces per level.\n *\n * A string is quoted only where plain style would change what it means. Empty\n * maps and lists print as `{}` and `[]`, since a block with nothing under it\n * would read as an absent value.\n *\n * @param value What to render.\n * @param indent Depth to start at. The recursion sets it.\n * @returns The YAML text, with no document marker.\n */\nexport function toYaml(value: unknown, indent = 0): string {\n  const pad = \"  \".repeat(indent);\n  if (Array.isArray(value)) return listYaml(value, indent, pad);\n  if (isMap(value)) return mapYaml(value, indent, pad);\n  return `${pad}${scalar(value)}`;\n}\n\nfunction listYaml(items: readonly unknown[], indent: number, pad: string): string {\n  if (items.length === 0) return `${pad}[]`;\n  return items.map((item) => `${pad}- ${nested(item, indent)}`).join(\"\\n\");\n}\n\nfunction mapYaml(map: Record<string, unknown>, indent: number, pad: string): string {\n  const entries = Object.entries(map);\n  if (entries.length === 0) return `${pad}{}`;\n  return entries.map(([key, item]) => `${pad}${key}:${suffix(item, indent)}`).join(\"\\n\");\n}\n\n/** A scalar sits on the key's line; a map or list opens a block below it. */\nfunction suffix(value: unknown, indent: number): string {\n  if (isEmpty(value)) return ` ${Array.isArray(value) ? \"[]\" : \"{}\"}`;\n  if (Array.isArray(value) || isMap(value)) return `\\n${toYaml(value, indent + 1)}`;\n  return ` ${scalar(value)}`;\n}\n\n/** A nested value under `- `, with its first line already positioned. */\nfunction nested(value: unknown, indent: number): string {\n  if (isEmpty(value) || (!Array.isArray(value) && !isMap(value))) return scalar(value);\n  return toYaml(value, indent + 1).trimStart();\n}\n\nfunction isEmpty(value: unknown): boolean {\n  if (Array.isArray(value)) return value.length === 0;\n  return isMap(value) && Object.keys(value).length === 0;\n}\n\nfunction isMap(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nconst PLAIN = /^[A-Za-z_][\\w .-]*$/;\n\nfunction scalar(value: unknown): string {\n  if (value === null || value === undefined) return \"null\";\n  if (typeof value !== \"string\") return String(value);\n  return value === \"\" || !PLAIN.test(value) ? JSON.stringify(value) : value;\n}\n","import { type ActionDefinition, arg, defineAction, optionalArg } from \"@venn-lang/sdk\";\nimport { t } from \"@venn-lang/types\";\nimport { toCsv } from \"../render/csv.js\";\nimport { toJson } from \"../render/json.js\";\nimport { toTable } from \"../render/table.js\";\nimport { toXml } from \"../render/xml.js\";\nimport { toYaml } from \"../render/yaml.js\";\n\nfunction list(value: unknown): unknown[] {\n  return Array.isArray(value) ? value : [value];\n}\n\nfunction number(value: unknown, fallback: number): number {\n  const parsed = Number(value);\n  return value === undefined || Number.isNaN(parsed) ? fallback : parsed;\n}\n\n/**\n * The verbs of the `fmt` namespace: a value in, a string out.\n *\n * Formatting is kept apart from printing on purpose. The string is a value you\n * can compare in a test, send in a request or write to a file, not something\n * that only ever reaches a terminal.\n *\n * Every verb is positional and none reads an options map, so none declares a\n * params schema: one would put a `{ … }` in the editor's hover that the verb\n * never looks at, and would quietly strip the keys a caller wrote there.\n */\nexport const fmtActions: ActionDefinition[] = [\n  defineAction({\n    name: \"json\",\n    doc: \"JSON text. `fmt.json(x, 0)` puts it on one line; the default indents by 2.\",\n    // Anything at all can be serialised, so the first parameter promises nothing.\n    args: [\n      arg(\"value\", t.dynamic, \"What to render.\"),\n      optionalArg(\"indent\", t.number, \"Spaces per level. 0 puts it on one line.\"),\n    ],\n    result: t.string,\n    run: (_ctx, input) => toJson(input.args[0], number(input.args[1], 2)),\n  }),\n  defineAction({\n    name: \"table\",\n    doc: \"An aligned ASCII table of a list of records.\",\n    // The columns are read off the records at runtime, so the element type\n    // promises nothing. A lone record is tolerated, but this verb wants a list.\n    args: [arg(\"rows\", t.list(t.dynamic), \"A list of records. Their keys become the columns.\")],\n    result: t.string,\n    run: (_ctx, input) => toTable(list(input.args[0])),\n  }),\n  defineAction({\n    name: \"yaml\",\n    doc: \"YAML text, for a map, a list or a scalar.\",\n    args: [arg(\"value\", t.dynamic, \"What to render.\")],\n    result: t.string,\n    run: (_ctx, input) => toYaml(input.args[0]),\n  }),\n  defineAction({\n    name: \"csv\",\n    doc: \"CSV with a header row. `fmt.csv(rows, ';')` changes the separator.\",\n    args: [\n      arg(\"rows\", t.list(t.dynamic), \"A list of records. Their keys become the header row.\"),\n      optionalArg(\"separator\", t.string, \"What goes between fields. A comma by default.\"),\n    ],\n    result: t.string,\n    run: (_ctx, input) => toCsv(list(input.args[0]), String(input.args[1] ?? \",\")),\n  }),\n  defineAction({\n    name: \"xml\",\n    doc: \"XML text. `fmt.xml(x, 'user')` names the root element.\",\n    args: [\n      arg(\"value\", t.dynamic, \"What to render.\"),\n      optionalArg(\"root\", t.string, \"What to call the outermost element.\"),\n    ],\n    result: t.string,\n    run: (_ctx, input) => toXml(input.args[0], String(input.args[1] ?? \"root\")),\n  }),\n];\n","import { definePlugin, type PluginDefinition } from \"@venn-lang/sdk\";\nimport { fmtActions } from \"./actions/fmt-actions.js\";\n\n/**\n * The `fmt` plugin: a value to text, as JSON, a table, YAML, CSV or XML.\n *\n * Every verb is pure, so the plugin needs no host capability and runs anywhere,\n * the LSP included. What comes back is a string, yours to print, compare or send.\n */\nexport const fmtPlugin: PluginDefinition = definePlugin({\n  name: \"venn/fmt\",\n  version: \"0.0.0\",\n  namespace: \"fmt\",\n  actions: fmtActions,\n});\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@venn-lang/fmt",
+  "version": "0.1.0",
+  "description": "The fmt namespace: a value in, formatted text out. JSON, tables, YAML, CSV and XML.",
+  "keywords": [
+    "venn",
+    "testing",
+    "e2e",
+    "fmt"
+  ],
+  "homepage": "https://github.com/venn-lang/venn/tree/main/packages/std-fmt#readme",
+  "bugs": "https://github.com/venn-lang/venn/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/venn-lang/venn.git",
+    "directory": "packages/std-fmt"
+  },
+  "license": "MIT",
+  "author": "Vinicius Borges",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.suite.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@venn-lang/sdk": "0.1.0",
+    "@venn-lang/types": "0.1.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/actions/fmt-actions.ts

@@ -0,0 +1,77 @@
+import { type ActionDefinition, arg, defineAction, optionalArg } from "@venn-lang/sdk";
+import { t } from "@venn-lang/types";
+import { toCsv } from "../render/csv.js";
+import { toJson } from "../render/json.js";
+import { toTable } from "../render/table.js";
+import { toXml } from "../render/xml.js";
+import { toYaml } from "../render/yaml.js";
+
+function list(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [value];
+}
+
+function number(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return value === undefined || Number.isNaN(parsed) ? fallback : parsed;
+}
+
+/**
+ * The verbs of the `fmt` namespace: a value in, a string out.
+ *
+ * Formatting is kept apart from printing on purpose. The string is a value you
+ * can compare in a test, send in a request or write to a file, not something
+ * that only ever reaches a terminal.
+ *
+ * Every verb is positional and none reads an options map, so none declares a
+ * params schema: one would put a `{ … }` in the editor's hover that the verb
+ * never looks at, and would quietly strip the keys a caller wrote there.
+ */
+export const fmtActions: ActionDefinition[] = [
+  defineAction({
+    name: "json",
+    doc: "JSON text. `fmt.json(x, 0)` puts it on one line; the default indents by 2.",
+    // Anything at all can be serialised, so the first parameter promises nothing.
+    args: [
+      arg("value", t.dynamic, "What to render."),
+      optionalArg("indent", t.number, "Spaces per level. 0 puts it on one line."),
+    ],
+    result: t.string,
+    run: (_ctx, input) => toJson(input.args[0], number(input.args[1], 2)),
+  }),
+  defineAction({
+    name: "table",
+    doc: "An aligned ASCII table of a list of records.",
+    // The columns are read off the records at runtime, so the element type
+    // promises nothing. A lone record is tolerated, but this verb wants a list.
+    args: [arg("rows", t.list(t.dynamic), "A list of records. Their keys become the columns.")],
+    result: t.string,
+    run: (_ctx, input) => toTable(list(input.args[0])),
+  }),
+  defineAction({
+    name: "yaml",
+    doc: "YAML text, for a map, a list or a scalar.",
+    args: [arg("value", t.dynamic, "What to render.")],
+    result: t.string,
+    run: (_ctx, input) => toYaml(input.args[0]),
+  }),
+  defineAction({
+    name: "csv",
+    doc: "CSV with a header row. `fmt.csv(rows, ';')` changes the separator.",
+    args: [
+      arg("rows", t.list(t.dynamic), "A list of records. Their keys become the header row."),
+      optionalArg("separator", t.string, "What goes between fields. A comma by default."),
+    ],
+    result: t.string,
+    run: (_ctx, input) => toCsv(list(input.args[0]), String(input.args[1] ?? ",")),
+  }),
+  defineAction({
+    name: "xml",
+    doc: "XML text. `fmt.xml(x, 'user')` names the root element.",
+    args: [
+      arg("value", t.dynamic, "What to render."),
+      optionalArg("root", t.string, "What to call the outermost element."),
+    ],
+    result: t.string,
+    run: (_ctx, input) => toXml(input.args[0], String(input.args[1] ?? "root")),
+  }),
+];

package/src/index.ts

@@ -0,0 +1,8 @@
+// The `fmt` namespace: a value in, formatted text out.
+export { fmtActions } from "./actions/fmt-actions.js";
+export { fmtPlugin, fmtPlugin as default } from "./plugin.js";
+export { toCsv } from "./render/csv.js";
+export { toJson } from "./render/json.js";
+export { toTable } from "./render/table.js";
+export { toXml } from "./render/xml.js";
+export { toYaml } from "./render/yaml.js";

package/src/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin, type PluginDefinition } from "@venn-lang/sdk";
+import { fmtActions } from "./actions/fmt-actions.js";
+
+/**
+ * The `fmt` plugin: a value to text, as JSON, a table, YAML, CSV or XML.
+ *
+ * Every verb is pure, so the plugin needs no host capability and runs anywhere,
+ * the LSP included. What comes back is a string, yours to print, compare or send.
+ */
+export const fmtPlugin: PluginDefinition = definePlugin({
+  name: "venn/fmt",
+  version: "0.0.0",
+  namespace: "fmt",
+  actions: fmtActions,
+});

package/src/render/csv.ts

@@ -0,0 +1,42 @@
+type Row = Record<string, unknown>;
+
+/**
+ * Renders a list of records as CSV with a header row.
+ *
+ * Columns are the union of every record's keys, in first-seen order, so a
+ * record missing a field still lines up. A field is quoted only when it holds a
+ * separator, a quote or a newline, and inner quotes are doubled (RFC 4180).
+ *
+ * @param rows The records to render. Anything that is not a record is skipped.
+ * @param separator What goes between fields. A comma by default.
+ * @returns The CSV text, or an empty string when no record survives the filter.
+ */
+export function toCsv(rows: readonly unknown[], separator = ","): string {
+  const records = rows.filter(isRow);
+  if (records.length === 0) return "";
+  const columns = columnsOf(records);
+  const header = columns.map(quote).join(separator);
+  const body = records.map((row) => columns.map((c) => quote(cell(row[c]))).join(separator));
+  return [header, ...body].join("\n");
+}
+
+function isRow(value: unknown): value is Row {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function columnsOf(rows: readonly Row[]): string[] {
+  const seen = new Set<string>();
+  for (const row of rows) for (const key of Object.keys(row)) seen.add(key);
+  return [...seen];
+}
+
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+
+/** Quote when the field holds a separator, a quote or a newline; double inner quotes. */
+function quote(field: string): string {
+  if (!/[",;\t\n\r]/.test(field)) return field;
+  return `"${field.replace(/"/g, '""')}"`;
+}

package/src/render/json.ts

@@ -0,0 +1,17 @@
+/**
+ * Renders a value as JSON text.
+ *
+ * A value JSON cannot express (a cycle, a BigInt) falls back to `String(value)`
+ * instead of throwing: formatting is not where a run should die.
+ *
+ * @param value What to render.
+ * @param spaces Spaces per level of nesting. 0 puts it all on one line.
+ * @returns The JSON text.
+ */
+export function toJson(value: unknown, spaces = 2): string {
+  try {
+    return JSON.stringify(value, null, spaces) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/render/table.ts

@@ -0,0 +1,51 @@
+type Row = Record<string, unknown>;
+
+/**
+ * Renders a list of records as an aligned table, for reading in a terminal.
+ *
+ * Columns are the union of every row's keys, in first-seen order, so a row
+ * missing a field still lines up. Each column is as wide as its widest cell.
+ *
+ * @param rows The records to render. Anything that is not a record is skipped.
+ * @returns The table text, or `(no rows)` when there is nothing to show.
+ */
+export function toTable(rows: readonly unknown[]): string {
+  const records = rows.filter(isRow);
+  if (records.length === 0) return "(no rows)";
+  const columns = columnsOf(records);
+  const widths = columns.map((column) => widthOf(column, records));
+  return [
+    line(columns, widths),
+    widths.map((width) => "─".repeat(width)).join("─┼─"),
+    ...records.map((row) =>
+      line(
+        columns.map((column) => cell(row[column])),
+        widths,
+      ),
+    ),
+  ].join("\n");
+}
+
+function isRow(value: unknown): value is Row {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function columnsOf(rows: readonly Row[]): string[] {
+  const seen = new Set<string>();
+  for (const row of rows) for (const key of Object.keys(row)) seen.add(key);
+  return [...seen];
+}
+
+function widthOf(column: string, rows: readonly Row[]): number {
+  return rows.reduce((width, row) => Math.max(width, cell(row[column]).length), column.length);
+}
+
+function line(values: readonly string[], widths: readonly number[]): string {
+  return values.map((value, index) => value.padEnd(widths[index] ?? 0)).join(" │ ");
+}
+
+function cell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}

package/src/render/xml.ts

@@ -0,0 +1,46 @@
+/**
+ * Renders a value as indented XML.
+ *
+ * A map's keys become tags; a list repeats the tag it was given, once per item.
+ * Text is escaped. Attributes are never produced, so a round trip through this
+ * and back is not the identity.
+ *
+ * @param value What to render.
+ * @param tag The name of the outermost element.
+ * @param indent Depth to start at, two spaces per level. The recursion sets it.
+ * @returns The XML text, with no declaration or prologue.
+ */
+export function toXml(value: unknown, tag = "root", indent = 0): string {
+  const pad = "  ".repeat(indent);
+  if (Array.isArray(value)) return value.map((item) => toXml(item, tag, indent)).join("\n");
+  if (isMap(value)) return element({ tag, body: children(value, indent), pad, block: true });
+  return element({ tag, body: escaped(text(value)), pad, block: false });
+}
+
+function children(map: Record<string, unknown>, indent: number): string {
+  return Object.entries(map)
+    .map(([key, item]) => toXml(item, key, indent + 1))
+    .join("\n");
+}
+
+function element(args: { tag: string; body: string; pad: string; block: boolean }): string {
+  const { tag, body, pad } = args;
+  if (!args.block) return `${pad}<${tag}>${body}</${tag}>`;
+  return body === "" ? `${pad}<${tag}/>` : `${pad}<${tag}>\n${body}\n${pad}</${tag}>`;
+}
+
+function isMap(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function text(value: unknown): string {
+  return value === null || value === undefined ? "" : String(value);
+}
+
+function escaped(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/src/render/yaml.ts

@@ -0,0 +1,58 @@
+/**
+ * Renders a value as YAML: maps, lists and scalars, two spaces per level.
+ *
+ * A string is quoted only where plain style would change what it means. Empty
+ * maps and lists print as `{}` and `[]`, since a block with nothing under it
+ * would read as an absent value.
+ *
+ * @param value What to render.
+ * @param indent Depth to start at. The recursion sets it.
+ * @returns The YAML text, with no document marker.
+ */
+export function toYaml(value: unknown, indent = 0): string {
+  const pad = "  ".repeat(indent);
+  if (Array.isArray(value)) return listYaml(value, indent, pad);
+  if (isMap(value)) return mapYaml(value, indent, pad);
+  return `${pad}${scalar(value)}`;
+}
+
+function listYaml(items: readonly unknown[], indent: number, pad: string): string {
+  if (items.length === 0) return `${pad}[]`;
+  return items.map((item) => `${pad}- ${nested(item, indent)}`).join("\n");
+}
+
+function mapYaml(map: Record<string, unknown>, indent: number, pad: string): string {
+  const entries = Object.entries(map);
+  if (entries.length === 0) return `${pad}{}`;
+  return entries.map(([key, item]) => `${pad}${key}:${suffix(item, indent)}`).join("\n");
+}
+
+/** A scalar sits on the key's line; a map or list opens a block below it. */
+function suffix(value: unknown, indent: number): string {
+  if (isEmpty(value)) return ` ${Array.isArray(value) ? "[]" : "{}"}`;
+  if (Array.isArray(value) || isMap(value)) return `\n${toYaml(value, indent + 1)}`;
+  return ` ${scalar(value)}`;
+}
+
+/** A nested value under `- `, with its first line already positioned. */
+function nested(value: unknown, indent: number): string {
+  if (isEmpty(value) || (!Array.isArray(value) && !isMap(value))) return scalar(value);
+  return toYaml(value, indent + 1).trimStart();
+}
+
+function isEmpty(value: unknown): boolean {
+  if (Array.isArray(value)) return value.length === 0;
+  return isMap(value) && Object.keys(value).length === 0;
+}
+
+function isMap(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+const PLAIN = /^[A-Za-z_][\w .-]*$/;
+
+function scalar(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (typeof value !== "string") return String(value);
+  return value === "" || !PLAIN.test(value) ? JSON.stringify(value) : value;
+}