@statelyai/graph 0.3.0 → 0.4.0

package/dist/formats/mermaid/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/mermaid/shared.ts
 const MERMAID_TO_DIRECTION = {
@@ -123,6 +123,18 @@ function parseArrow(arrow) {
 	for (const [pattern, info] of ARROW_PATTERNS) if (arrow === pattern) return info;
 }
 const MESSAGE_RE = /^(\S+?)\s*(<<-->>|<<->>|-->>|-->|--x|--\)|->>|->|-x|-\))\s*(\S+?)\s*:\s*(.*)$/;
+/**
+* Parses a Mermaid sequence diagram string into a Graph.
+*
+* @example
+* const graph = fromMermaidSequence(`
+* sequenceDiagram
+*     participant Alice
+*     participant Bob
+*     Alice->>Bob: Hello
+*     Bob-->>Alice: Hi back
+* `);
+*/
 function fromMermaidSequence(input) {
 	validateInput(input, "Mermaid sequence");
 	const { lines } = prepareLines(input);
@@ -420,9 +432,17 @@ const ARROW_MAP = {
 		async: "--)"
 	}
 };
+/**
+* Converts a sequence diagram Graph to a Mermaid sequence diagram string.
+*
+* @example
+* const mermaid = toMermaidSequence(graph);
+* // "sequenceDiagram\n    participant Alice\n    ..."
+*/
 function toMermaidSequence(graph) {
 	const lines = ["sequenceDiagram"];
-	if (graph.data?.autonumber) lines.push("    autonumber");
+	const gd = graph.data;
+	if (gd?.autonumber) lines.push("    autonumber");
 	for (const node of graph.nodes) {
 		const d = node.data;
 		const keyword = d?.actorType === "actor" ? "actor" : "participant";
@@ -430,28 +450,182 @@ function toMermaidSequence(graph) {
 		if (d?.created) lines.push(`    create ${keyword} ${node.id}${alias}`);
 		else lines.push(`    ${keyword} ${node.id}${alias}`);
 	}
+	const blocks = gd?.blocks ?? [];
+	const edgeIdSet = new Set(graph.edges.map((e) => e.id));
+	const beforeEdge = /* @__PURE__ */ new Map();
+	const afterEdge = /* @__PURE__ */ new Map();
+	for (const block of blocks) if (block.type === "alt") {
+		const firstEdge = block.branches[0]?.edgeIds[0];
+		if (firstEdge && edgeIdSet.has(firstEdge)) {
+			const events = beforeEdge.get(firstEdge) ?? [];
+			events.push({
+				type: "open",
+				block
+			});
+			beforeEdge.set(firstEdge, events);
+		}
+		for (let bi = 1; bi < block.branches.length; bi++) {
+			const branchFirstEdge = block.branches[bi]?.edgeIds[0];
+			if (branchFirstEdge && edgeIdSet.has(branchFirstEdge)) {
+				const events = beforeEdge.get(branchFirstEdge) ?? [];
+				events.push({
+					type: "branch",
+					block,
+					branchIndex: bi,
+					label: block.branches[bi].label
+				});
+				beforeEdge.set(branchFirstEdge, events);
+			}
+		}
+		const lastBranch = block.branches[block.branches.length - 1];
+		const lastEdge = lastBranch?.edgeIds[lastBranch.edgeIds.length - 1];
+		if (lastEdge && edgeIdSet.has(lastEdge)) {
+			const events = afterEdge.get(lastEdge) ?? [];
+			events.push({
+				type: "close",
+				block
+			});
+			afterEdge.set(lastEdge, events);
+		}
+	} else if (block.type === "par") {
+		const firstEdge = block.branches[0]?.edgeIds[0];
+		if (firstEdge && edgeIdSet.has(firstEdge)) {
+			const events = beforeEdge.get(firstEdge) ?? [];
+			events.push({
+				type: "open",
+				block
+			});
+			beforeEdge.set(firstEdge, events);
+		}
+		for (let bi = 1; bi < block.branches.length; bi++) {
+			const branchFirstEdge = block.branches[bi]?.edgeIds[0];
+			if (branchFirstEdge && edgeIdSet.has(branchFirstEdge)) {
+				const events = beforeEdge.get(branchFirstEdge) ?? [];
+				events.push({
+					type: "branch",
+					block,
+					branchIndex: bi,
+					label: block.branches[bi].label
+				});
+				beforeEdge.set(branchFirstEdge, events);
+			}
+		}
+		const lastBranch = block.branches[block.branches.length - 1];
+		const lastEdge = lastBranch?.edgeIds[lastBranch.edgeIds.length - 1];
+		if (lastEdge && edgeIdSet.has(lastEdge)) {
+			const events = afterEdge.get(lastEdge) ?? [];
+			events.push({
+				type: "close",
+				block
+			});
+			afterEdge.set(lastEdge, events);
+		}
+	} else if (block.type === "critical") {
+		const firstEdge = block.edgeIds[0];
+		if (firstEdge && edgeIdSet.has(firstEdge)) {
+			const events = beforeEdge.get(firstEdge) ?? [];
+			events.push({
+				type: "open",
+				block
+			});
+			beforeEdge.set(firstEdge, events);
+		}
+		if (block.options) for (const opt of block.options) {
+			const optFirstEdge = opt.edgeIds[0];
+			if (optFirstEdge && edgeIdSet.has(optFirstEdge)) {
+				const events = beforeEdge.get(optFirstEdge) ?? [];
+				events.push({
+					type: "branch",
+					block,
+					label: opt.label
+				});
+				beforeEdge.set(optFirstEdge, events);
+			}
+		}
+		const allEdgeIds = [...block.edgeIds, ...block.options?.flatMap((o) => o.edgeIds) ?? []];
+		const lastEdge = allEdgeIds[allEdgeIds.length - 1];
+		if (lastEdge && edgeIdSet.has(lastEdge)) {
+			const events = afterEdge.get(lastEdge) ?? [];
+			events.push({
+				type: "close",
+				block
+			});
+			afterEdge.set(lastEdge, events);
+		}
+	} else {
+		const edgeIds = block.edgeIds;
+		const firstEdge = edgeIds[0];
+		const lastEdge = edgeIds[edgeIds.length - 1];
+		if (firstEdge && edgeIdSet.has(firstEdge)) {
+			const events = beforeEdge.get(firstEdge) ?? [];
+			events.push({
+				type: "open",
+				block
+			});
+			beforeEdge.set(firstEdge, events);
+		}
+		if (lastEdge && edgeIdSet.has(lastEdge)) {
+			const events = afterEdge.get(lastEdge) ?? [];
+			events.push({
+				type: "close",
+				block
+			});
+			afterEdge.set(lastEdge, events);
+		}
+	}
+	let depth = 1;
+	const indent = () => "    ".repeat(depth);
 	for (const edge of graph.edges) {
+		const befores = beforeEdge.get(edge.id);
+		if (befores) {
+			for (const ev of befores) if (ev.type === "open") {
+				const b = ev.block;
+				if (b.type === "alt") lines.push(`${indent()}alt ${b.label}`);
+				else if (b.type === "par") lines.push(`${indent()}par ${b.branches[0].label}`);
+				else if (b.type === "critical") lines.push(`${indent()}critical ${b.label}`);
+				else if (b.type === "rect") lines.push(`${indent()}rect ${b.color}`);
+				else if (b.type === "loop" || b.type === "opt" || b.type === "break") lines.push(`${indent()}${b.type} ${b.label}`);
+				depth++;
+			} else if (ev.type === "branch") {
+				depth--;
+				const b = ev.block;
+				if (b.type === "alt") lines.push(`${indent()}else${ev.label ? ` ${ev.label}` : ""}`);
+				else if (b.type === "par") lines.push(`${indent()}and ${ev.label ?? ""}`);
+				else if (b.type === "critical") lines.push(`${indent()}option ${ev.label ?? ""}`);
+				depth++;
+			}
+		}
 		const d = edge.data;
 		if (!d) continue;
-		if (d.kind === "activation") {
-			lines.push(`    activate ${edge.sourceId}`);
-			continue;
+		if (d.kind === "activation") lines.push(`${indent()}activate ${edge.sourceId}`);
+		else if (d.kind === "deactivation") lines.push(`${indent()}deactivate ${edge.sourceId}`);
+		else {
+			const stroke = d.stroke ?? "solid";
+			const arrowType = d.arrowType ?? "filled";
+			let arrow;
+			if (d.bidirectional) arrow = stroke === "dotted" ? "<<-->>" : "<<->>";
+			else arrow = ARROW_MAP[stroke]?.[arrowType] ?? "->>";
+			const label = edge.label ? `: ${escapeMermaidLabel(edge.label)}` : ":";
+			lines.push(`${indent()}${edge.sourceId}${arrow}${edge.targetId}${label}`);
 		}
-		if (d.kind === "deactivation") {
-			lines.push(`    deactivate ${edge.sourceId}`);
-			continue;
+		const afters = afterEdge.get(edge.id);
+		if (afters) for (const _ev of afters) {
+			depth--;
+			lines.push(`${indent()}end`);
 		}
-		const stroke = d.stroke ?? "solid";
-		const arrowType = d.arrowType ?? "filled";
-		let arrow;
-		if (d.bidirectional) arrow = stroke === "dotted" ? "<<-->>" : "<<->>";
-		else arrow = ARROW_MAP[stroke]?.[arrowType] ?? "->>";
-		const label = edge.label ? `: ${escapeMermaidLabel(edge.label)}` : ":";
-		lines.push(`    ${edge.sourceId}${arrow}${edge.targetId}${label}`);
 	}
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid sequence diagram format. */
+/**
+* Bidirectional converter for Mermaid sequence diagram format.
+*
+* @example
+* const graph = mermaidSequenceConverter.from(`
+* sequenceDiagram
+*     Alice->>Bob: Hello
+* `);
+* const str = mermaidSequenceConverter.to(graph);
+*/
 const mermaidSequenceConverter = createFormatConverter(toMermaidSequence, fromMermaidSequence);
 
 //#endregion
@@ -707,6 +881,16 @@ function findEdge(line) {
 	}
 	return null;
 }
+/**
+* Parses a Mermaid flowchart string into a Graph.
+*
+* @example
+* const graph = fromMermaidFlowchart(`
+* flowchart TD
+*     A[Start] --> B{Decision}
+*     B -->|Yes| C[End]
+* `);
+*/
 function fromMermaidFlowchart(input) {
 	validateInput(input, "Mermaid flowchart");
 	const { lines } = prepareLines(input);
@@ -897,6 +1081,13 @@ function fromMermaidFlowchart(input) {
 		direction
 	};
 }
+/**
+* Converts a flowchart Graph to a Mermaid flowchart string.
+*
+* @example
+* const mermaid = toMermaidFlowchart(graph);
+* // "flowchart TD\n    A[Start] --> B{Decision}\n    ..."
+*/
 function toMermaidFlowchart(graph) {
 	const lines = [`flowchart ${DIRECTION_TO_MERMAID[graph.direction ?? "down"] ?? "TD"}`];
 	const gd = graph.data;
@@ -906,7 +1097,7 @@ function toMermaidFlowchart(graph) {
 	}
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -951,11 +1142,31 @@ function toMermaidFlowchart(graph) {
 	}
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid flowchart format. */
+/**
+* Bidirectional converter for Mermaid flowchart format.
+*
+* @example
+* const graph = mermaidFlowchartConverter.from(`
+* flowchart TD
+*     A --> B
+* `);
+* const str = mermaidFlowchartConverter.to(graph);
+*/
 const mermaidFlowchartConverter = createFormatConverter(toMermaidFlowchart, fromMermaidFlowchart);
 
 //#endregion
 //#region src/formats/mermaid/state.ts
+/**
+* Parses a Mermaid state diagram string into a Graph.
+*
+* @example
+* const graph = fromMermaidState(`
+* stateDiagram-v2
+*     [*] --> Idle
+*     Idle --> Running : start
+*     Running --> [*]
+* `);
+*/
 function fromMermaidState(input) {
 	validateInput(input, "Mermaid state");
 	const { lines } = prepareLines(input);
@@ -1082,11 +1293,18 @@ function fromMermaidState(input) {
 		data: { diagramType: "stateDiagram" }
 	};
 }
+/**
+* Converts a state diagram Graph to a Mermaid state diagram string.
+*
+* @example
+* const mermaid = toMermaidState(graph);
+* // "stateDiagram-v2\n    [*] --> Idle\n    ..."
+*/
 function toMermaidState(graph) {
 	const lines = ["stateDiagram-v2"];
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -1119,7 +1337,16 @@ function toMermaidState(graph) {
 	}
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid state diagram format. */
+/**
+* Bidirectional converter for Mermaid state diagram format.
+*
+* @example
+* const graph = mermaidStateConverter.from(`
+* stateDiagram-v2
+*     [*] --> Active
+* `);
+* const str = mermaidStateConverter.to(graph);
+*/
 const mermaidStateConverter = createFormatConverter(toMermaidState, fromMermaidState);
 
 //#endregion
@@ -1283,6 +1510,19 @@ function parseMember(line) {
 		isMethod
 	};
 }
+/**
+* Parses a Mermaid class diagram string into a Graph.
+*
+* @example
+* const graph = fromMermaidClass(`
+* classDiagram
+*     class Animal {
+*         +String name
+*         +eat() void
+*     }
+*     Animal <|-- Dog
+* `);
+*/
 function fromMermaidClass(input) {
 	validateInput(input, "Mermaid class");
 	const { lines } = prepareLines(input);
@@ -1402,6 +1642,13 @@ const VISIBILITY_SYMBOLS = {
 	"#": "#",
 	"~": "~"
 };
+/**
+* Converts a class diagram Graph to a Mermaid class diagram string.
+*
+* @example
+* const mermaid = toMermaidClass(graph);
+* // "classDiagram\n    class Animal {\n    ..."
+*/
 function toMermaidClass(graph) {
 	const lines = ["classDiagram"];
 	for (const node of graph.nodes) if (node.data?.members && node.data.members.length > 0) {
@@ -1429,7 +1676,16 @@ function toMermaidClass(graph) {
 	}
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid class diagram format. */
+/**
+* Bidirectional converter for Mermaid class diagram format.
+*
+* @example
+* const graph = mermaidClassConverter.from(`
+* classDiagram
+*     Animal <|-- Dog
+* `);
+* const str = mermaidClassConverter.to(graph);
+*/
 const mermaidClassConverter = createFormatConverter(toMermaidClass, fromMermaidClass);
 
 //#endregion
@@ -1477,6 +1733,16 @@ function parseERRelationship(symbol) {
 	};
 }
 const ER_LINE_RE = /^(\S+)\s+([|}{o.][|}{o.][-.][-.][|}{o.][|}{o.])\s+(\S+)\s*:\s*"?([^"]*)"?\s*$/;
+/**
+* Parses a Mermaid ER diagram string into a Graph.
+*
+* @example
+* const graph = fromMermaidER(`
+* erDiagram
+*     CUSTOMER ||--o{ ORDER : places
+*     ORDER ||--|{ LINE_ITEM : contains
+* `);
+*/
 function fromMermaidER(input) {
 	validateInput(input, "Mermaid ER");
 	const { lines } = prepareLines(input);
@@ -1560,6 +1826,13 @@ function fromMermaidER(input) {
 		data: { diagramType: "erDiagram" }
 	};
 }
+/**
+* Converts an ER diagram Graph to a Mermaid ER diagram string.
+*
+* @example
+* const mermaid = toMermaidER(graph);
+* // "erDiagram\n    CUSTOMER ||--o{ ORDER : \"places\"\n    ..."
+*/
 function toMermaidER(graph) {
 	const lines = ["erDiagram"];
 	for (const node of graph.nodes) if (node.data?.attributes && node.data.attributes.length > 0) {
@@ -1582,7 +1855,16 @@ function toMermaidER(graph) {
 	}
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid ER diagram format. */
+/**
+* Bidirectional converter for Mermaid ER diagram format.
+*
+* @example
+* const graph = mermaidERConverter.from(`
+* erDiagram
+*     CUSTOMER ||--o{ ORDER : places
+* `);
+* const str = mermaidERConverter.to(graph);
+*/
 const mermaidERConverter = createFormatConverter(toMermaidER, fromMermaidER);
 
 //#endregion
@@ -1628,6 +1910,18 @@ function parseNodeText(text) {
 	};
 	return { label: text.trim() };
 }
+/**
+* Parses a Mermaid mindmap string into a Graph.
+*
+* @example
+* const graph = fromMermaidMindmap(`
+* mindmap
+*   Root
+*     Child A
+*       Grandchild
+*     Child B
+* `);
+*/
 function fromMermaidMindmap(input) {
 	validateInput(input, "Mermaid mindmap");
 	const { lines } = prepareLines(input);
@@ -1690,11 +1984,18 @@ function fromMermaidMindmap(input) {
 		data: { diagramType: "mindmap" }
 	};
 }
+/**
+* Converts a mindmap Graph to a Mermaid mindmap string.
+*
+* @example
+* const mermaid = toMermaidMindmap(graph);
+* // "mindmap\n  Root\n    Child A\n    ..."
+*/
 function toMermaidMindmap(graph) {
 	const lines = ["mindmap"];
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -1715,7 +2016,17 @@ function toMermaidMindmap(graph) {
 	writeNode(null, 0);
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid mindmap format. */
+/**
+* Bidirectional converter for Mermaid mindmap format.
+*
+* @example
+* const graph = mermaidMindmapConverter.from(`
+* mindmap
+*   Root
+*     Branch
+* `);
+* const str = mermaidMindmapConverter.to(graph);
+*/
 const mermaidMindmapConverter = createFormatConverter(toMermaidMindmap, fromMermaidMindmap);
 
 //#endregion
@@ -1772,6 +2083,17 @@ function parseBlockNode(text) {
 	};
 	return null;
 }
+/**
+* Parses a Mermaid block diagram string into a Graph.
+*
+* @example
+* const graph = fromMermaidBlock(`
+* block-beta
+*     columns 2
+*     a["Task A"] b["Task B"]
+*     a --> b
+* `);
+*/
 function fromMermaidBlock(input) {
 	validateInput(input, "Mermaid block");
 	const { lines } = prepareLines(input);
@@ -1864,12 +2186,19 @@ function fromMermaidBlock(input) {
 		}
 	};
 }
+/**
+* Converts a block diagram Graph to a Mermaid block diagram string.
+*
+* @example
+* const mermaid = toMermaidBlock(graph);
+* // "block-beta\n    columns 2\n    a[\"Task A\"]\n    ..."
+*/
 function toMermaidBlock(graph) {
 	const lines = ["block-beta"];
 	if (graph.data?.columns) lines.push(`    columns ${graph.data.columns}`);
 	const childrenMap = /* @__PURE__ */ new Map();
 	for (const node of graph.nodes) {
-		const pid = node.parentId;
+		const pid = node.parentId ?? null;
 		if (!childrenMap.has(pid)) childrenMap.set(pid, []);
 		childrenMap.get(pid).push(node);
 	}
@@ -1891,7 +2220,17 @@ function toMermaidBlock(graph) {
 	for (const edge of graph.edges) lines.push(`    ${edge.sourceId} --> ${edge.targetId}`);
 	return lines.join("\n");
 }
-/** Bidirectional converter for Mermaid block diagram format. */
+/**
+* Bidirectional converter for Mermaid block diagram format.
+*
+* @example
+* const graph = mermaidBlockConverter.from(`
+* block-beta
+*     columns 2
+*     a b
+* `);
+* const str = mermaidBlockConverter.to(graph);
+*/
 const mermaidBlockConverter = createFormatConverter(toMermaidBlock, fromMermaidBlock);
 
 //#endregion

package/dist/formats/tgf/index.d.mts

@@ -1,9 +1,54 @@
-import { c as Graph, f as GraphFormatConverter } from "../../types-B6Tpeerk.mjs";
+import { c as Graph, f as GraphFormatConverter } from "../../types-Bq_fmLwW.mjs";
 
 //#region src/formats/tgf/index.d.ts
+
+/**
+ * Converts a graph to TGF (Trivial Graph Format) string.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { toTGF } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b', label: 'go' }],
+ * });
+ *
+ * const tgf = toTGF(graph);
+ * // "a A\nb B\n#\na b go"
+ * ```
+ */
 declare function toTGF(graph: Graph): string;
+/**
+ * Parses a TGF (Trivial Graph Format) string into a graph.
+ *
+ * @example
+ * ```ts
+ * import { fromTGF } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = fromTGF('a A\nb B\n#\na b go');
+ * // graph.nodes = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]
+ * ```
+ */
 declare function fromTGF(tgf: string): Graph;
-/** Bidirectional converter for TGF (Trivial Graph Format). */
+/**
+ * Bidirectional converter for TGF (Trivial Graph Format).
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { tgfConverter } from '@statelyai/graph/formats/tgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const tgf = tgfConverter.to(graph);
+ * const roundTripped = tgfConverter.from(tgf);
+ * ```
+ */
 declare const tgfConverter: GraphFormatConverter<string>;
 //#endregion
 export { fromTGF, tgfConverter, toTGF };

package/dist/formats/tgf/index.mjs

@@ -1,6 +1,23 @@
-import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/tgf/index.ts
+/**
+* Converts a graph to TGF (Trivial Graph Format) string.
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { toTGF } from '@statelyai/graph/formats/tgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b', label: 'go' }],
+* });
+*
+* const tgf = toTGF(graph);
+* // "a A\nb B\n#\na b go"
+* ```
+*/
 function toTGF(graph) {
 	const lines = [];
 	for (const node of graph.nodes) lines.push(node.label ? `${node.id} ${node.label}` : node.id);
@@ -12,6 +29,17 @@ function toTGF(graph) {
 	}
 	return lines.join("\n");
 }
+/**
+* Parses a TGF (Trivial Graph Format) string into a graph.
+*
+* @example
+* ```ts
+* import { fromTGF } from '@statelyai/graph/formats/tgf';
+*
+* const graph = fromTGF('a A\nb B\n#\na b go');
+* // graph.nodes = [{ id: 'a', label: 'A' }, { id: 'b', label: 'B' }]
+* ```
+*/
 function fromTGF(tgf) {
 	if (typeof tgf !== "string") throw new Error("TGF: expected a string");
 	const lines = tgf.split("\n");
@@ -60,7 +88,23 @@ function fromTGF(tgf) {
 		data: void 0
 	};
 }
-/** Bidirectional converter for TGF (Trivial Graph Format). */
+/**
+* Bidirectional converter for TGF (Trivial Graph Format).
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { tgfConverter } from '@statelyai/graph/formats/tgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const tgf = tgfConverter.to(graph);
+* const roundTripped = tgfConverter.from(tgf);
+* ```
+*/
 const tgfConverter = createFormatConverter(toTGF, fromTGF);
 
 //#endregion