@hpcc-js/wasm-graphviz 1.24.0 → 1.25.0

package/README.md

@@ -6,11 +6,12 @@ outline: deep
 
 # @hpcc-js/wasm-graphviz
 
-This package provides a WebAssembly wrapper around the [Graphviz](https://www.graphviz.org/) library.  This allows for the rendering of DOT language graphs directly within a browser or NodeJS type environment.
+This package provides a WebAssembly wrapper around the [Graphviz](https://www.graphviz.org/) library. This allows for the rendering of DOT language graphs directly within a browser or NodeJS type environment.
 
 ## Installation
 
 ::: code-group
+
 ```sh [npm]
 npm install @hpcc-js/wasm-graphviz
 ```
@@ -22,6 +23,7 @@ yarn add @hpcc-js/wasm-graphviz
 ```sh [pnpm]
 pnpm add @hpcc-js/wasm-graphviz
 ```
+
 :::
 
 ## Quick Start
@@ -37,8 +39,15 @@ document.body.innerHTML = svg;
 ## Programmatic Graph Construction
 
 Instead of writing DOT source by hand you can build graphs programmatically using
-`createGraph`.  The resulting `Graph` object can be rendered directly via
-`graph.layout()` or serialised to DOT first with `graph.toDot()`.
+`createGraph`. The resulting `Graph` object can be rendered directly via
+`graph.layout()` or serialised to DOT first with `graph.write()` / `graph.toDot()`.
+
+Attribute names and values follow Graphviz itself; see the official Graphviz
+[attribute reference](https://graphviz.org/docs/attrs/) for the supported graph,
+node, edge, and cluster attributes.
+
+Existing DOT can also be parsed into a mutable graph with `read`, and any
+programmatic graph can be written back to DOT with `write` (`toDot` is an alias).
 
 ### Basic usage
 
@@ -51,18 +60,56 @@ const graphviz = await Graphviz.load();
 using graph = graphviz.createGraph("G");
 
 graph
-    .addNode("a")
-    .addNode("b")
-    .addEdge("a", "b")
-    .setNodeAttr("a", "shape", "box")
-    .setNodeAttr("a", "color", "red")
-    .setGraphAttr("rankdir", "LR");
+  .addNode("a")
+  .addNode("b")
+  .addEdge("a", "b")
+  .setNodeAttr("a", "shape", "box")
+  .setNodeAttr("a", "color", "red")
+  .setGraphAttr("rankdir", "LR");
 
 // Render directly — no DOT round-trip needed
 const svg = graph.layout("svg", "dot");
 document.body.innerHTML = svg;
 ```
 
+### One-shot JSON init objects
+
+You can also create graphs, clusters, nodes, and edges from a single object
+that includes their attributes.
+
+```typescript
+using graph = graphviz.createGraph({
+  name: "G",
+  type: "directed",
+  attrs: { rankdir: "LR" }
+});
+
+{
+  using cluster = graph.addSubgraph({
+    name: "cluster_0",
+    attrs: { label: "Group A", style: "filled", color: "lightgrey" }
+  });
+
+  cluster.addNode({
+    name: "a",
+    attrs: { shape: "box", color: "red" },
+    htmlAttrs: { label: "<B>A</B>" }
+  });
+
+  cluster.addEdge({
+    tail: "a",
+    head: "b",
+    attrs: { label: "hello" }
+  });
+}
+```
+
+```typescript
+using graph = graphviz.read(`digraph G { a -> b [label="hello"] }`);
+graph.setGraphAttr("rankdir", "LR");
+const dot = graph.write();
+```
+
 ### Graph types
 
 ```typescript
@@ -89,14 +136,14 @@ const svg2 = graph.layout(); // updated render
 
 The full set of mutation methods on `Graph`:
 
-| Method | Effect |
-|---|---|
-| `removeNode(name)` | Removes the node and all its edges from the root graph |
-| `removeEdge(tail, head, key?)` | Removes a single edge |
-| `removeSubgraph(name)` | Dissolves a cluster boundary (nodes/edges remain in the root graph) |
-| `removeGraphAttr(attr)` | Resets a graph-level attribute to its default |
-| `removeNodeAttr(node, attr)` | Resets a node attribute to its default |
-| `removeEdgeAttr(tail, head, key, attr)` | Resets an edge attribute to its default |
+| Method                                  | Effect                                                              |
+| --------------------------------------- | ------------------------------------------------------------------- |
+| `removeNode(name)`                      | Removes the node and all its edges from the root graph              |
+| `removeEdge(tail, head, key?)`          | Removes a single edge                                               |
+| `removeSubgraph(name)`                  | Dissolves a cluster boundary (nodes/edges remain in the root graph) |
+| `removeGraphAttr(attr)`                 | Resets a graph-level attribute to its default                       |
+| `removeNodeAttr(node, attr)`            | Resets a node attribute to its default                              |
+| `removeEdgeAttr(tail, head, key, attr)` | Resets an edge attribute to its default                             |
 
 `Subgraph` has the same `removeNode` / `removeEdge` pair (scoped to the
 subgraph only — root graph is unaffected) plus `removeAttr` /
@@ -115,19 +162,19 @@ graph.addNode("alice");
 graph.addEdge("alice", "bob");
 graph.addSubgraph("cluster_a");
 
-graph.hasNode("alice");          // true
-graph.hasNode("charlie");        // false
-graph.hasEdge("alice", "bob");   // true  (key defaults to "")
-graph.hasEdge("bob", "alice");   // false (directed)
-graph.hasSubgraph("cluster_a");  // true
+graph.hasNode("alice"); // true
+graph.hasNode("charlie"); // false
+graph.hasEdge("alice", "bob"); // true  (key defaults to "")
+graph.hasEdge("bob", "alice"); // false (directed)
+graph.hasSubgraph("cluster_a"); // true
 ```
 
 #### Count queries
 
 ```typescript
-graph.nodeCount();      // number of nodes
-graph.edgeCount();      // number of edges
-graph.subgraphCount();  // number of direct subgraphs
+graph.nodeCount(); // number of nodes
+graph.edgeCount(); // number of edges
+graph.subgraphCount(); // number of direct subgraphs
 ```
 
 #### Reading attributes
@@ -137,10 +184,26 @@ graph.setNodeAttr("alice", "color", "red");
 graph.setEdgeAttr("alice", "bob", "", "label", "hello");
 graph.setGraphAttr("rankdir", "LR");
 
-graph.getNodeAttr("alice", "color");       // "red"
+graph.getNodeAttr("alice", "color"); // "red"
 graph.getEdgeAttr("alice", "bob", "", "label"); // "hello"
-graph.getGraphAttr("rankdir");             // "LR"
-graph.getNodeAttr("alice", "missing");     // "" (unknown attr)
+graph.getGraphAttr("rankdir"); // "LR"
+graph.getNodeAttr("alice", "missing"); // "" (unknown attr)
+
+// Omit the value to reset an attribute to Graphviz's default empty value.
+graph.setNodeAttr("alice", "color");
+graph.getNodeAttr("alice", "color"); // ""
+
+// Pass a final defaultValue argument to declare Graphviz's default for unset objects.
+graph.addNode("charlie");
+graph.setNodeAttr("alice", "color", "red", "blue");
+graph.getNodeAttr("charlie", "color"); // "blue"
+
+// Or declare defaults directly for graph, node, and edge attributes.
+graph.setDefaultNodeAttr("shape", "box");
+graph.setDefaultEdgeAttr("color", "red");
+
+// Use HTML-like attributes for Graphviz HTML labels.
+graph.setNodeHtmlAttr("alice", "label", "<B>Alice</B>");
 ```
 
 #### Node / edge / subgraph lists
@@ -151,9 +214,9 @@ const nodes = graph.nodeNames();
 const subgraphs = graph.subgraphNames();
 
 // Returns EdgeInfo[] — { tail: string, head: string, key: string }
-const allEdges = graph.edges();          // every edge exactly once
+const allEdges = graph.edges(); // every edge exactly once
 const outgoing = graph.outEdges("alice"); // edges leaving alice
-const incoming = graph.inEdges("bob");    // edges entering bob
+const incoming = graph.inEdges("bob"); // edges entering bob
 const incident = graph.nodeEdges("alice"); // all edges on alice (in + out)
 ```
 
@@ -171,12 +234,12 @@ using graph = graphviz.createGraph("G");
 
 // Each Subgraph wrapper also needs to be deleted (or use `using`)
 {
-    using cluster = graph.addSubgraph("cluster_0");
-    cluster
-        .setAttr("label", "My Cluster")
-        .setAttr("style", "filled")
-        .setAttr("color", "lightblue")
-        .addEdge("a", "b");
+  using cluster = graph.addSubgraph("cluster_0");
+  cluster
+    .setAttr("label", "My Cluster")
+    .setAttr("style", "filled")
+    .setAttr("color", "lightblue")
+    .addEdge("a", "b");
 }
 
 const svg = graph.layout();
@@ -184,14 +247,15 @@ const svg = graph.layout();
 
 ### Memory management
 
-Every `Graph` and `Subgraph` wraps a native WASM object.  You must release it
+Every `Graph` and `Subgraph` wraps a native WASM object. You must release it
 when finished to avoid memory leaks:
 
 - **Preferred — `using` keyword** (TypeScript ≥ 5.2 with `"target": "ES2022"` or later):
+
   ```typescript
   {
-      using graph = graphviz.createGraph("G");
-      // ... graph is automatically deleted when the block exits
+    using graph = graphviz.createGraph("G");
+    // ... graph is automatically deleted when the block exits
   }
   ```
 
@@ -199,13 +263,13 @@ when finished to avoid memory leaks:
   ```typescript
   const graph = graphviz.createGraph("G");
   try {
-      // ...
+    // ...
   } finally {
-      graph.delete();
+    graph.delete();
   }
   ```
 
-Subgraph wrappers follow the same rule.  The underlying subgraph _data_ is
+Subgraph wrappers follow the same rule. The underlying subgraph _data_ is
 owned by the parent `Graph` and freed automatically when the parent is deleted;
 only the thin JS wrapper needs an explicit `delete()` / `using` block.
 
@@ -213,4 +277,4 @@ only the thin JS wrapper needs an explicit `delete()` / `using` block.
 
 ## Reference
 
-* [API Documentation](https://hpcc-systems.github.io/hpcc-js-wasm/docs/graphviz/src/graphviz/classes/Graphviz.html)
+- [API Documentation](https://hpcc-systems.github.io/hpcc-js-wasm/docs/graphviz/src/graphviz/classes/Graphviz.html)