or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

algorithms.mdgraph.mdindex.mdjson.md
tile.json

graph.mddocs/

Graph Management

The Graph class is the core data structure in GraphLib, providing comprehensive functionality for creating and managing directed/undirected, simple/multi, and compound/flat graphs.

Capabilities

Graph Constructor

Creates a new graph instance with configurable properties.

/**
 * Creates a new graph instance
 * @param opts - Configuration options
 * @param opts.directed - Whether graph is directed (default: true)
 * @param opts.multigraph - Whether multiple edges between same nodes are allowed (default: false)
 * @param opts.compound - Whether hierarchical/compound nodes are supported (default: false)
 */
constructor(opts?: GraphOptions);

interface GraphOptions {
  directed?: boolean;
  multigraph?: boolean;
  compound?: boolean;
}

Usage Examples:

import { Graph } from "graphlib";

// Directed graph (default)
const directedGraph = new Graph();

// Undirected graph  
const undirectedGraph = new Graph({ directed: false });

// Multigraph allowing multiple edges
const multiGraph = new Graph({ multigraph: true });

// Compound graph supporting hierarchical nodes
const compoundGraph = new Graph({ compound: true });

Graph Properties

Methods to query graph configuration and metadata.

/**
 * Returns whether graph is directed
 */
isDirected(): boolean;

/**
 * Returns whether graph allows multiple edges
 */
isMultigraph(): boolean;

/**
 * Returns whether graph supports compound nodes
 */
isCompound(): boolean;

/**
 * Sets graph-level label/metadata (chainable)
 * @param label - Any value to associate with the graph
 */
setGraph(label: any): Graph;

/**
 * Returns graph-level label/metadata
 */
graph(): any;

Node Management

Core functionality for adding, removing, and querying nodes.

/**
 * Returns number of nodes in graph
 */
nodeCount(): number;

/**
 * Returns array of all node IDs
 */
nodes(): string[];

/**
 * Checks if node exists
 * @param v - Node ID to check
 */
hasNode(v: string): boolean;

/**
 * Adds/updates node with optional value (chainable)
 * @param v - Node ID
 * @param value - Optional value/label to associate with node
 */
setNode(v: string, value?: any): Graph;

/**
 * Adds/updates multiple nodes with same value (chainable)
 * @param vs - Array of node IDs
 * @param value - Optional value/label for all nodes
 */
setNodes(vs: string[], value?: any): Graph;

/**
 * Returns node value/label
 * @param v - Node ID
 */
node(v: string): any;

/**
 * Removes node and all connected edges (chainable)
 * @param v - Node ID to remove
 */
removeNode(v: string): Graph;

/**
 * Sets default node label function/value (chainable)
 * @param newDefault - Function or value for default node labels
 */
setDefaultNodeLabel(newDefault: any | Function): Graph;

Usage Examples:

const g = new Graph();

// Add nodes with labels
g.setNode("user1", { name: "Alice", role: "admin" });
g.setNode("user2", { name: "Bob", role: "user" });

// Add multiple nodes at once
g.setNodes(["temp1", "temp2", "temp3"], { temporary: true });

// Query nodes
console.log(g.nodeCount()); // 5
console.log(g.nodes()); // ["user1", "user2", "temp1", "temp2", "temp3"]
console.log(g.node("user1")); // { name: "Alice", role: "admin" }

// Set default node label
g.setDefaultNodeLabel(() => ({ created: Date.now() }));
g.setNode("user3"); // Gets default label automatically

Edge Management

Core functionality for adding, removing, and querying edges.

/**
 * Returns number of edges
 */
edgeCount(): number;

/**
 * Returns array of all edges as {v, w, name} objects
 */
edges(): EdgeObj[];

/**
 * Checks if edge exists
 * @param v - Source node ID
 * @param w - Target node ID  
 * @param name - Optional edge name (for multigraphs)
 */
hasEdge(v: string, w: string, name?: string): boolean;

/**
 * Checks if edge exists using edge object
 * @param edgeObj - Edge object {v, w, name?}
 */
hasEdge(edgeObj: EdgeObj): boolean;

/**
 * Adds/updates edge (chainable)
 * @param v - Source node ID
 * @param w - Target node ID
 * @param value - Optional value/label for edge
 * @param name - Optional edge name (for multigraphs)
 */
setEdge(v: string, w: string, value?: any, name?: string): Graph;

/**
 * Adds/updates edge using edge object (chainable)
 * @param edgeObj - Edge object {v, w, name?}
 * @param value - Optional value/label for edge
 */
setEdge(edgeObj: EdgeObj, value?: any): Graph;

/**
 * Returns edge value/label
 * @param v - Source node ID
 * @param w - Target node ID
 * @param name - Optional edge name
 */
edge(v: string, w: string, name?: string): any;

/**
 * Returns edge value using edge object
 * @param edgeObj - Edge object {v, w, name?}
 */
edge(edgeObj: EdgeObj): any;

/**
 * Removes edge (chainable)
 * @param v - Source node ID
 * @param w - Target node ID
 * @param name - Optional edge name
 */
removeEdge(v: string, w: string, name?: string): Graph;

/**
 * Removes edge using edge object (chainable)
 * @param edgeObj - Edge object {v, w, name?}
 */
removeEdge(edgeObj: EdgeObj): Graph;

/**
 * Sets default edge label function/value (chainable)
 * @param newDefault - Function or value for default edge labels
 */
setDefaultEdgeLabel(newDefault: any | Function): Graph;

/**
 * Creates path through array of nodes (chainable)
 * @param vs - Array of node IDs to connect in sequence
 * @param value - Optional value/label for all edges in path
 */
setPath(vs: string[], value?: any): Graph;

Usage Examples:

const g = new Graph();
g.setNodes(["a", "b", "c"]);

// Add edges with weights
g.setEdge("a", "b", { weight: 5 });
g.setEdge("b", "c", { weight: 3 });

// Create a path
g.setPath(["d", "e", "f"], { pathEdge: true });

// Multigraph with named edges
const mg = new Graph({ multigraph: true });
mg.setNodes(["x", "y"]);
mg.setEdge("x", "y", { type: "friend" }, "social");
mg.setEdge("x", "y", { type: "colleague" }, "work");

console.log(mg.edges()); 
// [{v:"x", w:"y", name:"social"}, {v:"x", w:"y", name:"work"}]

Node Navigation

Methods for traversing and analyzing node relationships.

/**
 * Returns nodes with no incoming edges
 */
sources(): string[];

/**
 * Returns nodes with no outgoing edges
 */
sinks(): string[];

/**
 * Returns nodes with edges to v
 * @param v - Target node ID
 */
predecessors(v: string): string[];

/**
 * Returns nodes with edges from v
 * @param v - Source node ID
 */
successors(v: string): string[];

/**
 * Returns union of predecessors and successors
 * @param v - Node ID
 */
neighbors(v: string): string[];

/**
 * Returns true if node has no successors (directed) or neighbors (undirected)
 * @param v - Node ID to check
 */
isLeaf(v: string): boolean;

Edge Navigation

Methods for querying edges connected to specific nodes.

/**
 * Returns incoming edges to v
 * @param v - Target node ID
 * @param u - Optional source node ID to filter by
 */
inEdges(v: string, u?: string): EdgeObj[];

/**
 * Returns outgoing edges from v
 * @param v - Source node ID
 * @param w - Optional target node ID to filter by
 */
outEdges(v: string, w?: string): EdgeObj[];

/**
 * Returns all edges connected to v
 * @param v - Node ID
 * @param w - Optional other node ID to filter by
 */
nodeEdges(v: string, w?: string): EdgeObj[];

Usage Examples:

const g = new Graph();
g.setPath(["a", "b", "c", "d"]);
g.setEdge("e", "c"); // Branch to c

console.log(g.sources()); // ["a", "e"]
console.log(g.sinks()); // ["d"] 
console.log(g.predecessors("c")); // ["b", "e"]
console.log(g.successors("c")); // ["d"]
console.log(g.neighbors("c")); // ["b", "e", "d"]

console.log(g.inEdges("c")); // [{v:"b", w:"c"}, {v:"e", w:"c"}]
console.log(g.outEdges("c")); // [{v:"c", w:"d"}]

Compound Graph Functions

Hierarchical node management (requires compound: true).

/**
 * Sets parent of node v (chainable)
 * @param v - Child node ID
 * @param parent - Parent node ID
 */
setParent(v: string, parent: string): Graph;

/**
 * Returns parent of node v
 * @param v - Node ID
 */
parent(v: string): string | undefined;

/**
 * Returns children of node v (or root children if v not specified)
 * @param v - Optional parent node ID
 */
children(v?: string): string[];

Usage Examples:

const g = new Graph({ compound: true });

// Create hierarchical structure
g.setNode("root");
g.setNode("group1");
g.setNode("group2");
g.setNode("item1");
g.setNode("item2");
g.setNode("item3");

// Set up hierarchy
g.setParent("group1", "root");
g.setParent("group2", "root");
g.setParent("item1", "group1");
g.setParent("item2", "group1");
g.setParent("item3", "group2");

console.log(g.children("root")); // ["group1", "group2"]
console.log(g.children("group1")); // ["item1", "item2"]
console.log(g.parent("item1")); // "group1"

Graph Filtering

Create new graphs based on filtering criteria.

/**
 * Returns new graph with only nodes matching filter function
 * @param filter - Function that receives node ID and returns boolean
 */
filterNodes(filter: (v: string) => boolean): Graph;

Usage Examples:

const g = new Graph();
g.setNode("user1", { role: "admin" });
g.setNode("user2", { role: "user" });
g.setNode("user3", { role: "admin" });
g.setEdge("user1", "user2");

// Filter to only admin users
const adminGraph = g.filterNodes((v) => {
  const nodeData = g.node(v);
  return nodeData && nodeData.role === "admin";
});

console.log(adminGraph.nodes()); // ["user1", "user3"]
console.log(adminGraph.edges()); // [] (edge removed as user2 filtered out)

Error Handling

Common errors and exceptions:

  • Error: "Cannot set parent in a non-compound graph" - Attempting to set parent on graph with compound: false
  • Error: "Cannot set a named edge when isMultigraph = false" - Attempting to create named edge on simple graph
  • Error: "Setting X as parent of Y would create a cycle" - Invalid parent relationship that would create circular hierarchy
  • Error: "Graph does not have node: X" - Operations on non-existent nodes

Performance Notes

  • Node/edge addition/removal: O(1) amortized
  • Node/edge lookup: O(1)
  • Graph storage: O(V + E) where V = nodes, E = edges
  • Compound operations maintain parent-child relationships efficiently