tessl/npm-graphlib

A directed and undirected multi-graph library with comprehensive graph algorithms

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Graph Management

Name: tessl/npm-graphlib
Author: tessl

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