@hpcc-js/wasm-graphviz 1.22.2 → 1.24.0

package/types/graphviz.d.ts

@@ -1,7 +1,23 @@
+import type { MainModule, CGraph as CGraphWasm, CSubgraph as CSubgraphWasm } from "../types/graphvizlib.js";
+import type { NodeDotAttr, NodeAttrs, EdgeDotAttr, EdgeAttrs, ClusterDotAttr, ClusterAttrs, GraphDotAttr, GraphAttrs as GraphAttrs } from "./types.ts";
 /**
  * Various graphic and data formats for end user, web, documents and other applications.  See [Output Formats](https://graphviz.gitlab.io/docs/outputs/) for more information.
  */
 export type Format = "svg" | "svg_inline" | "dot" | "json" | "dot_json" | "xdot_json" | "plain" | "plain-ext" | "canon";
+/**
+ * An edge returned by graph-traversal methods.
+ */
+export interface EdgeInfo {
+    /** The tail (source) node name. */
+    tail: string;
+    /** The head (target) node name. */
+    head: string;
+    /**
+     * The cgraph edge key that distinguishes parallel edges.
+     * Typically `""` for single (non-keyed) edges.
+     */
+    key: string;
+}
 /**
  * Various algorithms for projecting abstract graphs into a space for visualization.  See [Layout Engines](https://graphviz.gitlab.io/docs/layouts/) for more details.
  */
@@ -40,6 +56,388 @@ export interface Options {
     yInvert?: boolean;
     nop?: number;
 }
+/**
+ * The type of graph to create.
+ * - `"directed"` – directed graph (`digraph`)
+ * - `"undirected"` – undirected graph (`graph`)
+ * - `"strict directed"` – directed graph that disallows parallel edges and self-loops
+ * - `"strict undirected"` – undirected graph that disallows parallel edges and self-loops
+ */
+export type GraphType = "directed" | "undirected" | "strict directed" | "strict undirected";
+/**
+ * A subgraph (or cluster) inside a {@link Graph}.
+ *
+ * Obtain via {@link Graph.addSubgraph}.  All mutation methods return `this`
+ * for chaining.  **Call {@link Subgraph.delete} (or use the `using` keyword)
+ * when finished** to free the underlying WASM wrapper — the actual subgraph
+ * data is owned by the parent {@link Graph} and is freed with it.
+ *
+ * Clusters are subgraphs whose name starts with `"cluster"`.  Layout engines
+ * draw them as a bounded rectangle:
+ *
+ * ```ts
+ * using cluster = graph.addSubgraph("cluster_0");
+ * cluster
+ *   .setAttr("label", "My Cluster")
+ *   .setAttr("style", "filled")
+ *   .setAttr("color", "lightblue")
+ *   .addEdge("a", "b");
+ * ```
+ */
+export declare class Subgraph {
+    private _sg;
+    /** @internal */
+    constructor(sg: CSubgraphWasm);
+    /**
+     * Create (or find) a node and add it to this subgraph.
+     */
+    addNode(name: string): this;
+    /**
+     * Create an edge inside this subgraph.  Both endpoints are created
+     * automatically if they do not already exist.
+     */
+    addEdge(tail: string, head: string, key?: string): this;
+    /**
+     * Remove a node from this subgraph only.  The node (and any edges
+     * connecting it) remains in the root graph and all other subgraphs.
+     * No-op if the node is not in this subgraph.
+     */
+    removeNode(name: string): this;
+    /**
+     * Remove a single edge from this subgraph only.  The edge remains in the
+     * root graph and all other subgraphs.  No-op if the edge is not present.
+     */
+    removeEdge(tail: string, head: string, key?: string): this;
+    /**
+     * Set an attribute on the subgraph itself (e.g. `"label"`, `"style"`,
+     * `"color"`, `"bgcolor"`).
+     *
+     * When `attr` is a known cluster attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom or less-common attributes.
+     */
+    setAttr<K extends ClusterDotAttr>(attr: K, value: NonNullable<ClusterAttrs[K]>): this;
+    setAttr(attr: string, value: string | number | boolean): this;
+    /**
+     * Clear a subgraph-level attribute by resetting it to its default (empty)
+     * value.  Equivalent to `setAttr(attr, "")`.
+     */
+    removeAttr(attr: string): this;
+    /**
+     * Set an attribute on a node inside this subgraph.
+     *
+     * When `attr` is a known node attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom attributes.
+     */
+    setNodeAttr<K extends NodeDotAttr>(node: string, attr: K, value: NonNullable<NodeAttrs[K]>): this;
+    setNodeAttr(node: string, attr: string, value: string | number | boolean): this;
+    /**
+     * Clear a node attribute inside this subgraph by resetting it to its
+     * default (empty) value.  Equivalent to `setNodeAttr(node, attr, "")`.
+     */
+    removeNodeAttr(node: string, attr: string): this;
+    /**
+     * Set an attribute on an edge inside this subgraph (identified by
+     * `tail`, `head`, and `key`).
+     *
+     * When `attr` is a known edge attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom attributes.
+     */
+    setEdgeAttr<K extends EdgeDotAttr>(tail: string, head: string, key: string, attr: K, value: NonNullable<EdgeAttrs[K]>): this;
+    setEdgeAttr(tail: string, head: string, key: string, attr: string, value: string | number | boolean): this;
+    /**
+     * Clear an edge attribute inside this subgraph by resetting it to its
+     * default (empty) value.  Equivalent to `setEdgeAttr(tail, head, key, attr, "")`.
+     */
+    removeEdgeAttr(tail: string, head: string, key: string, attr: string): this;
+    /**
+     * Returns `true` if a node with the given name exists in this subgraph.
+     */
+    hasNode(name: string): boolean;
+    /**
+     * Returns `true` if an edge from `tail` to `head` exists in this subgraph.
+     * Pass `key` to check for a specific parallel edge; omit (or pass `""`) to
+     * check for any edge between the two nodes.
+     */
+    hasEdge(tail: string, head: string, key?: string): boolean;
+    /** Returns the number of nodes in this subgraph. */
+    nodeCount(): number;
+    /** Returns the number of edges in this subgraph. */
+    edgeCount(): number;
+    /**
+     * Returns the current value of a subgraph-level attribute, or `""` if
+     * the attribute has not been set.
+     */
+    getAttr(attr: string): string;
+    /**
+     * Returns the current value of the named attribute on a node in this
+     * subgraph, or `""` if the node or attribute does not exist.
+     */
+    getNodeAttr(node: string, attr: string): string;
+    /**
+     * Returns the current value of the named attribute on an edge in this
+     * subgraph, or `""` if the edge or attribute does not exist.
+     * Pass `key = ""` for the first (or only) edge between `tail` and `head`.
+     */
+    getEdgeAttr(tail: string, head: string, key: string, attr: string): string;
+    /**
+     * Returns the names of all nodes in this subgraph (in internal iteration
+     * order).
+     */
+    nodeNames(): string[];
+    /**
+     * Returns all edges in this subgraph.  Each unique edge is listed exactly
+     * once.
+     */
+    edges(): EdgeInfo[];
+    /**
+     * Returns the out-edges of the named node in this subgraph.  Returns `[]`
+     * if the node does not exist.
+     */
+    outEdges(node: string): EdgeInfo[];
+    /**
+     * Returns the in-edges of the named node in this subgraph.  Returns `[]`
+     * if the node does not exist.
+     */
+    inEdges(node: string): EdgeInfo[];
+    /**
+     * Returns all edges incident to the named node in this subgraph (both in
+     * and out).  Returns `[]` if the node does not exist.
+     */
+    nodeEdges(node: string): EdgeInfo[];
+    /**
+     * Release the WASM wrapper.  The subgraph data itself is freed when the
+     * parent {@link Graph} is deleted.
+     */
+    delete(): void;
+    /** @internal – supports the `using` keyword (explicit resource management). */
+    [Symbol.dispose](): void;
+}
+/**
+ * A programmatic graph builder backed by the cgraph library.
+ *
+ * Obtain an instance via {@link Graphviz.createGraph} and call
+ * {@link Graph.toDot} to serialise to a DOT string that can be passed to
+ * {@link Graphviz.layout} (or any of its convenience wrappers).
+ *
+ * **Always call {@link Graph.delete} (or use the `using` keyword) when
+ * finished** to release the underlying WASM memory.
+ *
+ * ```ts
+ * const graphviz = await Graphviz.load();
+ *
+ * using graph = graphviz.createGraph("G");
+ * graph.addNode("a");
+ * graph.addNode("b");
+ * graph.addEdge("a", "b");
+ * graph.setNodeAttr("a", "color", "red");
+ * graph.setEdgeAttr("a", "b", "", "label", "hello");
+ * graph.setGraphAttr("rankdir", "LR");
+ *
+ * const svg = graphviz.dot(graph.toDot());
+ * ```
+ */
+export declare class Graph {
+    private _graph;
+    private _module;
+    /** @internal */
+    constructor(g: CGraphWasm, module: MainModule);
+    /**
+     * Create a node.  If a node with this name already exists it is returned
+     * unchanged.
+     */
+    addNode(name: string): this;
+    /**
+     * Create an edge from `tail` to `head`.  Both nodes are created
+     * automatically if they do not already exist.  `key` distinguishes
+     * parallel edges between the same pair of nodes; omit (or pass `""`) for
+     * an anonymous edge.
+     */
+    addEdge(tail: string, head: string, key?: string): this;
+    /**
+     * Set a graph-level attribute (e.g. `"rankdir"`, `"label"`, `"bgcolor"`).
+     *
+     * When `attr` is a known graph attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom or less-common attributes.
+     */
+    setGraphAttr<K extends GraphDotAttr>(attr: K, value: NonNullable<GraphAttrs[K]>): this;
+    setGraphAttr(attr: string, value: string | number | boolean): this;
+    /**
+     * Set an attribute on a named node (e.g. `"color"`, `"label"`, `"shape"`).
+     * The node must exist; call {@link addNode} first if needed.
+     *
+     * When `attr` is a known node attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom attributes.
+     */
+    setNodeAttr<K extends NodeDotAttr>(node: string, attr: K, value: NonNullable<NodeAttrs[K]>): this;
+    setNodeAttr(node: string, attr: string, value: string | number | boolean): this;
+    /**
+     * Set an attribute on an edge identified by `(tail, head, key)`.
+     * Use the same `key` that was passed to {@link addEdge}; pass `""` for
+     * anonymous edges.
+     *
+     * When `attr` is a known edge attribute the value type is inferred
+     * automatically.  A generic `string | number | boolean` fallback is
+     * provided for custom attributes.
+     */
+    setEdgeAttr<K extends EdgeDotAttr>(tail: string, head: string, key: string, attr: K, value: NonNullable<EdgeAttrs[K]>): this;
+    setEdgeAttr(tail: string, head: string, key: string, attr: string, value: string | number | boolean): this;
+    /**
+     * Remove a node and all its edges from the graph.  Removing from the root
+     * graph also removes the node from every subgraph.
+     * No-op if the node does not exist.
+     */
+    removeNode(name: string): this;
+    /**
+     * Remove a single edge identified by `(tail, head, key)`.
+     * Pass `""` for `key` on anonymous edges.
+     * No-op if the edge does not exist.
+     */
+    removeEdge(tail: string, head: string, key?: string): this;
+    /**
+     * Dissolve a subgraph / cluster boundary.  Nodes and edges that belonged
+     * to the subgraph remain in the parent graph.
+     * No-op if no subgraph with that name exists.
+     */
+    removeSubgraph(name: string): this;
+    /**
+     * Clear a graph-level attribute by resetting it to its default (empty)
+     * value.  Equivalent to `setGraphAttr(attr, "")`.
+     */
+    removeGraphAttr(attr: string): this;
+    /**
+     * Clear a node attribute by resetting it to its default (empty) value.
+     * Equivalent to `setNodeAttr(node, attr, "")`.
+     */
+    removeNodeAttr(node: string, attr: string): this;
+    /**
+     * Clear an edge attribute by resetting it to its default (empty) value.
+     * Equivalent to `setEdgeAttr(tail, head, key, attr, "")`.
+     */
+    removeEdgeAttr(tail: string, head: string, key: string, attr: string): this;
+    /**
+     * Returns `true` if a node with the given name exists in the graph.
+     */
+    hasNode(name: string): boolean;
+    /**
+     * Returns `true` if an edge from `tail` to `head` exists in the graph.
+     * Pass `key` to check for a specific parallel edge; omit (or pass `""`) to
+     * check for any edge between the two nodes.
+     */
+    hasEdge(tail: string, head: string, key?: string): boolean;
+    /**
+     * Returns `true` if a subgraph with the given name exists.
+     */
+    hasSubgraph(name: string): boolean;
+    /** Returns the number of nodes in the graph. */
+    nodeCount(): number;
+    /** Returns the number of edges in the graph. */
+    edgeCount(): number;
+    /** Returns the number of direct subgraphs of this graph. */
+    subgraphCount(): number;
+    /**
+     * Returns the current value of a graph-level attribute, or `""` if the
+     * attribute has not been set.
+     */
+    getGraphAttr(attr: string): string;
+    /**
+     * Returns the current value of the named attribute on a node, or `""` if
+     * the node or attribute does not exist.
+     */
+    getNodeAttr(node: string, attr: string): string;
+    /**
+     * Returns the current value of the named attribute on an edge, or `""` if
+     * the edge or attribute does not exist.
+     * Pass `key = ""` for the first (or only) edge between `tail` and `head`.
+     */
+    getEdgeAttr(tail: string, head: string, key: string, attr: string): string;
+    /**
+     * Returns the names of all nodes in the graph (in internal iteration
+     * order).
+     */
+    nodeNames(): string[];
+    /**
+     * Returns the names of all direct subgraphs.
+     */
+    subgraphNames(): string[];
+    /**
+     * Returns all edges in the graph.  Each unique edge is listed exactly
+     * once.
+     */
+    edges(): EdgeInfo[];
+    /**
+     * Returns the out-edges of the named node.  Returns `[]` if the node does
+     * not exist.
+     */
+    outEdges(node: string): EdgeInfo[];
+    /**
+     * Returns the in-edges of the named node.  Returns `[]` if the node does
+     * not exist.
+     */
+    inEdges(node: string): EdgeInfo[];
+    /**
+     * Returns all edges incident to the named node (both in and out).
+     * Returns `[]` if the node does not exist.
+     */
+    nodeEdges(node: string): EdgeInfo[];
+    /**
+     * Create (or return an existing) named subgraph.  Use a name beginning
+     * with `"cluster"` to have layout engines render it as a bounded cluster.
+     *
+     * Returns a {@link Subgraph} wrapper.  **Call {@link Subgraph.delete} (or
+     * use the `using` keyword) when finished** to free the WASM wrapper.  The
+     * subgraph data itself is owned by this graph.
+     *
+     * ```ts
+     * using cluster = graph.addSubgraph("cluster_0");
+     * cluster.setAttr("label", "My Cluster").addEdge("a", "b");
+     * ```
+     */
+    addSubgraph(name: string): Subgraph;
+    /**
+     * Look up an existing subgraph by name without creating a new one.
+     * Returns a {@link Subgraph} wrapper if a subgraph with that name exists,
+     * or `null` if it does not.  **Call {@link Subgraph.delete} (or use the
+     * `using` keyword) when finished** to free the WASM wrapper.
+     *
+     * ```ts
+     * using sg = graph.getSubgraph("cluster_0");
+     * if (sg) {
+     *     console.log(sg.nodeNames());
+     * }
+     * ```
+     */
+    getSubgraph(name: string): Subgraph | null;
+    /**
+     * Render the graph directly to the specified format without first
+     * serialising to DOT.  Equivalent to:
+     * ```ts
+     * graphviz.layout(graph.toDot(), outputFormat, layoutEngine, options)
+     * ```
+     * but avoids the DOT round-trip.
+     *
+     * @param outputFormat The output format (default `"svg"`).
+     * @param layoutEngine The layout engine to use (default `"dot"`).
+     * @param options       Optional images / extra files for the renderer.
+     * @returns The rendered output as a string.
+     */
+    layout(outputFormat?: Format, layoutEngine?: Engine, options?: Options): string;
+    /**
+     * Serialise the graph to a DOT-language string.
+     */
+    toDot(): string;
+    /**
+     * Release the underlying WASM object.  Must be called when the graph is
+     * no longer needed (or use the `using` keyword with TypeScript ≥ 5.2).
+     */
+    delete(): void;
+    /** @internal – supports the `using` keyword (explicit resource management). */
+    [Symbol.dispose](): void;
+}
 /**
  * The Graphviz layout algorithms take descriptions of graphs in a simple text language, and make diagrams in useful formats, such as images and SVG for web pages or display in an interactive graph browser.
  *
@@ -47,6 +445,7 @@ export interface Options {
  *
  * See [graphviz.org](https://graphviz.org/) for more details.
  *
+ * ### Rendering from a DOT string
  * ```ts
  * import { Graphviz } from "@hpcc-js/wasm/graphviz";
  *
@@ -56,6 +455,23 @@ export interface Options {
  * const svg = graphviz.dot(dot);
  * ```
  *
+ * ### Programmatic graph construction
+ * ```ts
+ * import { Graphviz } from "@hpcc-js/wasm/graphviz";
+ *
+ * const graphviz = await Graphviz.load();
+ *
+ * using graph = graphviz.createGraph("G");
+ * graph
+ *   .addNode("a")
+ *   .addNode("b")
+ *   .addEdge("a", "b")
+ *   .setNodeAttr("a", "color", "red")
+ *   .setGraphAttr("rankdir", "LR");
+ *
+ * const svg = graph.layout(); // render without a DOT round-trip
+ * ```
+ *
  * ### Online Demos
  * * https://raw.githack.com/hpcc-systems/hpcc-js-wasm/main/index.html
  * * https://observablehq.com/@gordonsmith/graphviz
@@ -212,4 +628,31 @@ export declare class Graphviz {
      * @returns A string containing the "pretty printed" dotSource.
      */
     nop2(dotSource: string): string;
+    /**
+     * Programmatically create a graph using the cgraph library.
+     *
+     * Returns a {@link Graph} builder that lets you add nodes, edges, and
+     * attributes without writing DOT source by hand.  Call
+     * {@link Graph.toDot} to get the DOT string and pass it to
+     * {@link layout} (or any convenience wrapper).
+     *
+     * **You must call {@link Graph.delete} when finished** to free the
+     * underlying WASM memory, or use the `using` keyword (TypeScript ≥ 5.2).
+     *
+     * @param name  The graph name (default `"G"`).
+     * @param type  The graph type (default `"directed"`).
+     *
+     * ```ts
+     * using graph = graphviz.createGraph("G");
+     * graph
+     *   .addNode("a")
+     *   .addNode("b")
+     *   .addEdge("a", "b")
+     *   .setNodeAttr("a", "color", "red")
+     *   .setGraphAttr("rankdir", "LR");
+     *
+     * const svg = graphviz.dot(graph.toDot());
+     * ```
+     */
+    createGraph(name?: string, type?: GraphType): Graph;
 }

package/types/graphvizlib.d.ts

@@ -52,6 +52,62 @@ export interface CGraphviz extends ClassHandle {
   unflatten(_0: EmbindString, _1: number, _2: boolean, _3: number): string;
 }
 
+export interface CGraph extends ClassHandle {
+  get dot_out(): string;
+  set dot_out(value: EmbindString);
+  get layout_result(): string;
+  set layout_result(value: EmbindString);
+  nodeCount(): number;
+  edgeCount(): number;
+  subgraphCount(): number;
+  addNode(_0: EmbindString): void;
+  addEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  setGraphAttr(_0: EmbindString, _1: EmbindString): void;
+  setNodeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  setEdgeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString, _3: EmbindString, _4: EmbindString): void;
+  addSubgraph(_0: EmbindString): CSubgraph | null;
+  getSubgraph(_0: EmbindString): CSubgraph | null;
+  removeNode(_0: EmbindString): void;
+  removeEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  removeSubgraph(_0: EmbindString): void;
+  hasNode(_0: EmbindString): boolean;
+  hasEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): boolean;
+  hasSubgraph(_0: EmbindString): boolean;
+  getGraphAttr(_0: EmbindString): string;
+  getNodeAttr(_0: EmbindString, _1: EmbindString): string;
+  getEdgeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString, _3: EmbindString): string;
+  nodeNames(): string;
+  subgraphNames(): string;
+  edges(): string;
+  outEdges(_0: EmbindString): string;
+  inEdges(_0: EmbindString): string;
+  nodeEdges(_0: EmbindString): string;
+  toDot(): string;
+  layout(_0: EmbindString, _1: EmbindString): string;
+}
+
+export interface CSubgraph extends ClassHandle {
+  nodeCount(): number;
+  edgeCount(): number;
+  addNode(_0: EmbindString): void;
+  addEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  setAttr(_0: EmbindString, _1: EmbindString): void;
+  setNodeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  setEdgeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString, _3: EmbindString, _4: EmbindString): void;
+  removeNode(_0: EmbindString): void;
+  removeEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): void;
+  hasNode(_0: EmbindString): boolean;
+  hasEdge(_0: EmbindString, _1: EmbindString, _2: EmbindString): boolean;
+  getAttr(_0: EmbindString): string;
+  getNodeAttr(_0: EmbindString, _1: EmbindString): string;
+  getEdgeAttr(_0: EmbindString, _1: EmbindString, _2: EmbindString, _3: EmbindString): string;
+  nodeNames(): string;
+  edges(): string;
+  outEdges(_0: EmbindString): string;
+  inEdges(_0: EmbindString): string;
+  nodeEdges(_0: EmbindString): string;
+}
+
 interface EmbindModule {
   CGraphviz: {
     new(): CGraphviz;
@@ -59,6 +115,13 @@ interface EmbindModule {
     version(): string;
     lastError(): string;
   };
+  CGraph: {
+    new(): CGraph;
+    new(_0: EmbindString): CGraph;
+    new(_0: EmbindString, _1: number): CGraph;
+    new(_0: EmbindString, _1: number, _2: number): CGraph;
+  };
+  CSubgraph: {};
 }
 
 export type MainModule = WasmModule & typeof RuntimeExports & EmbindModule;