@statelyai/graph 0.3.0 → 0.4.0

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

@@ -1,9 +1,65 @@
-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/gml/index.d.ts
+
+/**
+ * Converts a graph to GML (Graph Modelling Language) string.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { toGML } from '@statelyai/graph/formats/gml';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const gml = toGML(graph);
+ * // graph [
+ * //   directed 1
+ * //   node [ id "a" ]
+ * //   node [ id "b" ]
+ * //   edge [ id "e0" source "a" target "b" ]
+ * // ]
+ * ```
+ */
 declare function toGML(graph: Graph): string;
+/**
+ * Parses a GML (Graph Modelling Language) string into a graph.
+ *
+ * @example
+ * ```ts
+ * import { fromGML } from '@statelyai/graph/formats/gml';
+ *
+ * const graph = fromGML(`
+ *   graph [
+ *     directed 1
+ *     node [ id "a" ]
+ *     node [ id "b" ]
+ *     edge [ source "a" target "b" ]
+ *   ]
+ * `);
+ * ```
+ */
 declare function fromGML(gml: string): Graph;
-/** Bidirectional converter for GML (Graph Modelling Language) format. */
+/**
+ * Bidirectional converter for GML (Graph Modelling Language) format.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { gmlConverter } from '@statelyai/graph/formats/gml';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const gml = gmlConverter.to(graph);
+ * const roundTripped = gmlConverter.from(gml);
+ * ```
+ */
 declare const gmlConverter: GraphFormatConverter<string>;
 //#endregion
 export { fromGML, gmlConverter, toGML };

package/dist/formats/gml/index.mjs

@@ -1,6 +1,28 @@
-import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/gml/index.ts
+/**
+* Converts a graph to GML (Graph Modelling Language) string.
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { toGML } from '@statelyai/graph/formats/gml';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const gml = toGML(graph);
+* // graph [
+* //   directed 1
+* //   node [ id "a" ]
+* //   node [ id "b" ]
+* //   edge [ id "e0" source "a" target "b" ]
+* // ]
+* ```
+*/
 function toGML(graph) {
 	const lines = [];
 	lines.push("graph [");
@@ -8,7 +30,7 @@ function toGML(graph) {
 	if (graph.id) lines.push(`  id ${gmlString(graph.id)}`);
 	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);
 	}
@@ -16,7 +38,7 @@ function toGML(graph) {
 		lines.push(`${indent}node [`);
 		lines.push(`${indent}  id ${gmlString(node.id)}`);
 		if (node.label) lines.push(`${indent}  label ${gmlString(node.label)}`);
-		if (node.initialNodeId !== null) lines.push(`${indent}  initialNodeId ${gmlString(node.initialNodeId)}`);
+		if (node.initialNodeId) lines.push(`${indent}  initialNodeId ${gmlString(node.initialNodeId)}`);
 		if (node.data !== void 0) lines.push(`${indent}  data ${gmlString(JSON.stringify(node.data))}`);
 		if (node.shape) lines.push(`${indent}  shape ${gmlString(node.shape)}`);
 		if (node.color) lines.push(`${indent}  color ${gmlString(node.color)}`);
@@ -50,6 +72,23 @@ function toGML(graph) {
 function gmlString(s) {
 	return `"${s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
 }
+/**
+* Parses a GML (Graph Modelling Language) string into a graph.
+*
+* @example
+* ```ts
+* import { fromGML } from '@statelyai/graph/formats/gml';
+*
+* const graph = fromGML(`
+*   graph [
+*     directed 1
+*     node [ id "a" ]
+*     node [ id "b" ]
+*     edge [ source "a" target "b" ]
+*   ]
+* `);
+* ```
+*/
 function fromGML(gml) {
 	if (typeof gml !== "string") throw new Error("GML: expected a string");
 	if (!gml.trim()) throw new Error("GML: input is empty");
@@ -229,7 +268,23 @@ function tryParseJSON(str) {
 		return str;
 	}
 }
-/** Bidirectional converter for GML (Graph Modelling Language) format. */
+/**
+* Bidirectional converter for GML (Graph Modelling Language) format.
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { gmlConverter } from '@statelyai/graph/formats/gml';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const gml = gmlConverter.to(graph);
+* const roundTripped = gmlConverter.from(gml);
+* ```
+*/
 const gmlConverter = createFormatConverter(toGML, fromGML);
 
 //#endregion

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

@@ -1,4 +1,4 @@
-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/graphml/index.d.ts
 declare function toGraphML(graph: Graph): string;

package/dist/formats/graphml/index.mjs

@@ -1,4 +1,4 @@
-import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 import { XMLBuilder, XMLParser } from "fast-xml-parser";
 
 //#region src/formats/graphml/index.ts
@@ -72,7 +72,7 @@ function toGraphML(graph) {
 			"@_key": "label",
 			"#text": n.label
 		});
-		if (n.parentId !== null) data.push({
+		if (n.parentId) data.push({
 			"@_key": "parentId",
 			"#text": n.parentId
 		});

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

@@ -1,4 +1,4 @@
-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/jgf/index.d.ts
 interface JGFNode {
@@ -22,9 +22,58 @@ interface JGFGraph {
     edges: JGFEdge[];
   };
 }
+/**
+ * Converts a graph to JSON Graph Format (JGF).
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { toJGF } from '@statelyai/graph/formats/jgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const jgf = toJGF(graph);
+ * // { graph: { directed: true, nodes: [...], edges: [...] } }
+ * ```
+ */
 declare function toJGF(graph: Graph): JGFGraph;
+/**
+ * Parses a JSON Graph Format (JGF) object into a graph.
+ *
+ * @example
+ * ```ts
+ * import { fromJGF } from '@statelyai/graph/formats/jgf';
+ *
+ * const graph = fromJGF({
+ *   graph: {
+ *     directed: true,
+ *     nodes: [{ id: 'a' }, { id: 'b' }],
+ *     edges: [{ source: 'a', target: 'b' }],
+ *   },
+ * });
+ * ```
+ */
 declare function fromJGF(jgf: JGFGraph): Graph;
-/** Bidirectional converter for JSON Graph Format. */
+/**
+ * Bidirectional converter for JSON Graph Format.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from '@statelyai/graph';
+ * import { jgfConverter } from '@statelyai/graph/formats/jgf';
+ *
+ * const graph = createGraph({
+ *   nodes: [{ id: 'a' }, { id: 'b' }],
+ *   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+ * });
+ *
+ * const jgf = jgfConverter.to(graph);
+ * const roundTripped = jgfConverter.from(jgf);
+ * ```
+ */
 declare const jgfConverter: GraphFormatConverter<JGFGraph>;
 //#endregion
 export { JGFEdge, JGFGraph, JGFNode, fromJGF, jgfConverter, toJGF };

package/dist/formats/jgf/index.mjs

@@ -1,9 +1,26 @@
-import { n as createFormatConverter } from "../../converter-DnbeyE_p.mjs";
+import { n as createFormatConverter } from "../../converter-C5DlzzHs.mjs";
 
 //#region src/formats/jgf/index.ts
+/**
+* Converts a graph to JSON Graph Format (JGF).
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { toJGF } from '@statelyai/graph/formats/jgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const jgf = toJGF(graph);
+* // { graph: { directed: true, nodes: [...], edges: [...] } }
+* ```
+*/
 function toJGF(graph) {
 	const metadata = {};
-	if (graph.initialNodeId !== null) metadata.initialNodeId = graph.initialNodeId;
+	if (graph.initialNodeId) metadata.initialNodeId = graph.initialNodeId;
 	if (graph.data !== void 0) metadata.data = graph.data;
 	if (graph.direction) metadata.direction = graph.direction;
 	return { graph: {
@@ -12,8 +29,8 @@ function toJGF(graph) {
 		...Object.keys(metadata).length > 0 && { metadata },
 		nodes: graph.nodes.map((n) => {
 			const meta = {};
-			if (n.parentId !== null) meta.parentId = n.parentId;
-			if (n.initialNodeId !== null) meta.initialNodeId = n.initialNodeId;
+			if (n.parentId) meta.parentId = n.parentId;
+			if (n.initialNodeId) meta.initialNodeId = n.initialNodeId;
 			if (n.data !== void 0) meta.data = n.data;
 			if (n.x !== void 0) meta.x = n.x;
 			if (n.y !== void 0) meta.y = n.y;
@@ -41,6 +58,22 @@ function toJGF(graph) {
 		})
 	} };
 }
+/**
+* Parses a JSON Graph Format (JGF) object into a graph.
+*
+* @example
+* ```ts
+* import { fromJGF } from '@statelyai/graph/formats/jgf';
+*
+* const graph = fromJGF({
+*   graph: {
+*     directed: true,
+*     nodes: [{ id: 'a' }, { id: 'b' }],
+*     edges: [{ source: 'a', target: 'b' }],
+*   },
+* });
+* ```
+*/
 function fromJGF(jgf) {
 	if (!jgf || typeof jgf !== "object") throw new Error("JGF: expected an object");
 	if (!jgf.graph || typeof jgf.graph !== "object") throw new Error("JGF: missing \"graph\" property");
@@ -78,7 +111,23 @@ function fromJGF(jgf) {
 		}))
 	};
 }
-/** Bidirectional converter for JSON Graph Format. */
+/**
+* Bidirectional converter for JSON Graph Format.
+*
+* @example
+* ```ts
+* import { createGraph } from '@statelyai/graph';
+* import { jgfConverter } from '@statelyai/graph/formats/jgf';
+*
+* const graph = createGraph({
+*   nodes: [{ id: 'a' }, { id: 'b' }],
+*   edges: [{ id: 'e0', sourceId: 'a', targetId: 'b' }],
+* });
+*
+* const jgf = jgfConverter.to(graph);
+* const roundTripped = jgfConverter.from(jgf);
+* ```
+*/
 const jgfConverter = createFormatConverter(toJGF, fromJGF);
 
 //#endregion

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

@@ -1,4 +1,4 @@
-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/mermaid/sequence.d.ts
 interface SequenceNodeData {
@@ -58,9 +58,37 @@ interface SequenceGraphData {
   blocks?: SequenceBlock[];
 }
 type SequenceGraph = Graph<SequenceNodeData, SequenceEdgeData, SequenceGraphData>;
+/**
+ * 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
+ * `);
+ */
 declare function fromMermaidSequence(input: string): SequenceGraph;
+/**
+ * Converts a sequence diagram Graph to a Mermaid sequence diagram string.
+ *
+ * @example
+ * const mermaid = toMermaidSequence(graph);
+ * // "sequenceDiagram\n    participant Alice\n    ..."
+ */
 declare function toMermaidSequence(graph: SequenceGraph): string;
-/** 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);
+ */
 declare const mermaidSequenceConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/flowchart.d.ts
@@ -82,9 +110,35 @@ interface FlowchartGraphData {
   classDefs?: Record<string, Record<string, string>>;
 }
 type FlowchartGraph = Graph<FlowchartNodeData, FlowchartEdgeData, FlowchartGraphData>;
+/**
+ * Parses a Mermaid flowchart string into a Graph.
+ *
+ * @example
+ * const graph = fromMermaidFlowchart(`
+ * flowchart TD
+ *     A[Start] --> B{Decision}
+ *     B -->|Yes| C[End]
+ * `);
+ */
 declare function fromMermaidFlowchart(input: string): FlowchartGraph;
+/**
+ * Converts a flowchart Graph to a Mermaid flowchart string.
+ *
+ * @example
+ * const mermaid = toMermaidFlowchart(graph);
+ * // "flowchart TD\n    A[Start] --> B{Decision}\n    ..."
+ */
 declare function toMermaidFlowchart(graph: FlowchartGraph): string;
-/** 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);
+ */
 declare const mermaidFlowchartConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/state.d.ts
@@ -103,9 +157,36 @@ interface StateGraphData {
   diagramType: 'stateDiagram';
 }
 type StateGraph = Graph<StateNodeData, StateEdgeData, StateGraphData>;
+/**
+ * Parses a Mermaid state diagram string into a Graph.
+ *
+ * @example
+ * const graph = fromMermaidState(`
+ * stateDiagram-v2
+ *     [*] --> Idle
+ *     Idle --> Running : start
+ *     Running --> [*]
+ * `);
+ */
 declare function fromMermaidState(input: string): StateGraph;
+/**
+ * Converts a state diagram Graph to a Mermaid state diagram string.
+ *
+ * @example
+ * const mermaid = toMermaidState(graph);
+ * // "stateDiagram-v2\n    [*] --> Idle\n    ..."
+ */
 declare function toMermaidState(graph: StateGraph): string;
-/** 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);
+ */
 declare const mermaidStateConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/class-diagram.d.ts
@@ -128,9 +209,38 @@ interface ClassGraphData {
   diagramType: 'classDiagram';
 }
 type ClassGraph = Graph<ClassNodeData, ClassEdgeData, ClassGraphData>;
+/**
+ * Parses a Mermaid class diagram string into a Graph.
+ *
+ * @example
+ * const graph = fromMermaidClass(`
+ * classDiagram
+ *     class Animal {
+ *         +String name
+ *         +eat() void
+ *     }
+ *     Animal <|-- Dog
+ * `);
+ */
 declare function fromMermaidClass(input: string): ClassGraph;
+/**
+ * Converts a class diagram Graph to a Mermaid class diagram string.
+ *
+ * @example
+ * const mermaid = toMermaidClass(graph);
+ * // "classDiagram\n    class Animal {\n    ..."
+ */
 declare function toMermaidClass(graph: ClassGraph): string;
-/** 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);
+ */
 declare const mermaidClassConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/er-diagram.d.ts
@@ -151,9 +261,35 @@ interface ERGraphData {
   diagramType: 'erDiagram';
 }
 type ERGraph = Graph<ERNodeData, EREdgeData, ERGraphData>;
+/**
+ * Parses a Mermaid ER diagram string into a Graph.
+ *
+ * @example
+ * const graph = fromMermaidER(`
+ * erDiagram
+ *     CUSTOMER ||--o{ ORDER : places
+ *     ORDER ||--|{ LINE_ITEM : contains
+ * `);
+ */
 declare function fromMermaidER(input: string): ERGraph;
+/**
+ * Converts an ER diagram Graph to a Mermaid ER diagram string.
+ *
+ * @example
+ * const mermaid = toMermaidER(graph);
+ * // "erDiagram\n    CUSTOMER ||--o{ ORDER : \"places\"\n    ..."
+ */
 declare function toMermaidER(graph: ERGraph): string;
-/** 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);
+ */
 declare const mermaidERConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/mindmap.d.ts
@@ -165,9 +301,38 @@ interface MindmapGraphData {
   diagramType: 'mindmap';
 }
 type MindmapGraph = Graph<MindmapNodeData, MindmapEdgeData, MindmapGraphData>;
+/**
+ * Parses a Mermaid mindmap string into a Graph.
+ *
+ * @example
+ * const graph = fromMermaidMindmap(`
+ * mindmap
+ *   Root
+ *     Child A
+ *       Grandchild
+ *     Child B
+ * `);
+ */
 declare function fromMermaidMindmap(input: string): MindmapGraph;
+/**
+ * Converts a mindmap Graph to a Mermaid mindmap string.
+ *
+ * @example
+ * const mermaid = toMermaidMindmap(graph);
+ * // "mindmap\n  Root\n    Child A\n    ..."
+ */
 declare function toMermaidMindmap(graph: MindmapGraph): string;
-/** 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);
+ */
 declare const mermaidMindmapConverter: GraphFormatConverter<string>;
 //#endregion
 //#region src/formats/mermaid/block.d.ts
@@ -180,9 +345,37 @@ interface BlockGraphData {
   columns?: number;
 }
 type BlockGraph = Graph<BlockNodeData, BlockEdgeData, BlockGraphData>;
+/**
+ * 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
+ * `);
+ */
 declare function fromMermaidBlock(input: string): BlockGraph;
+/**
+ * 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    ..."
+ */
 declare function toMermaidBlock(graph: BlockGraph): string;
-/** 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);
+ */
 declare const mermaidBlockConverter: GraphFormatConverter<string>;
 //#endregion
 export { type BlockEdgeData, type BlockGraphData, type BlockNodeData, type ClassEdgeData, type ClassGraphData, type ClassNodeData, type EREdgeData, type ERGraphData, type ERNodeData, type FlowchartEdgeData, type FlowchartGraphData, type FlowchartNodeData, type MindmapEdgeData, type MindmapGraphData, type MindmapNodeData, type SequenceBlock, type SequenceEdgeData, type SequenceGraphData, type SequenceNodeData, type StateEdgeData, type StateGraphData, type StateNodeData, fromMermaidBlock, fromMermaidClass, fromMermaidER, fromMermaidFlowchart, fromMermaidMindmap, fromMermaidSequence, fromMermaidState, mermaidBlockConverter, mermaidClassConverter, mermaidERConverter, mermaidFlowchartConverter, mermaidMindmapConverter, mermaidSequenceConverter, mermaidStateConverter, toMermaidBlock, toMermaidClass, toMermaidER, toMermaidFlowchart, toMermaidMindmap, toMermaidSequence, toMermaidState };