All mutation functions modify the graph in place and are marked with Mutable in their documentation.
addNode
Mutable. Add a node to the graph. Mutates graph.nodes in place.
export function addNode<N>(
graph: Graph<N>,
config: NodeConfig<N>
): GraphNode<N>
The graph to add the node to.
The resolved node that was added to the graph.
Behavior
- Throws if
config.id is empty or already exists in the graph
- Throws if
config.parentId is specified but the parent node doesn’t exist
- Resolves defaults:
label → '', data → undefined
- Updates internal indexes automatically
Examples
const graph = createGraph();
const node = addNode(graph, { id: 'a', label: 'Node A' });
// graph.nodes.length === 1
// node.type === 'node'
// node.label === 'Node A'
addEdge
Mutable. Add an edge to the graph. Mutates graph.edges in place.
export function addEdge<E>(
graph: Graph<any, E>,
config: EdgeConfig<E>
): GraphEdge<E>
The graph to add the edge to.
The resolved edge that was added to the graph.
Behavior
- Throws if
config.id is empty or already exists
- Throws if
config.sourceId or config.targetId is empty or references a non-existent node
- Resolves defaults:
label → '', data → undefined
- Updates internal indexes automatically
Examples
const graph = createGraph({ nodes: [{ id: 'a' }, { id: 'b' }] });
const edge = addEdge(graph, { id: 'e1', sourceId: 'a', targetId: 'b' });
// graph.edges.length === 1
// edge.type === 'edge'
deleteNode
Mutable. Delete a node and its connected edges. Mutates graph.nodes and graph.edges in place.
export function deleteNode(
graph: Graph,
id: string,
opts?: DeleteNodeOptions
): void
The graph to delete the node from.
ID of the node to delete.
Options for handling child nodes.Show DeleteNodeOptions properties
If true, children are re-parented to the deleted node’s parent. If false (default), children are deleted recursively.
Behavior
- Throws if the node doesn’t exist
- By default, deletes all descendant nodes recursively
- Deletes all edges connected to the deleted node(s)
- With
{ reparent: true }, children are moved to the deleted node’s parent
- Invalidates internal indexes (rebuilds on next access)
Examples
const graph = createGraph({
nodes: [{ id: 'a' }, { id: 'b' }],
edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
});
deleteNode(graph, 'a');
// graph.nodes.length === 1
// graph.edges.length === 0 (e1 removed with node a)
deleteEdge
Mutable. Delete an edge. Mutates graph.edges in place.
export function deleteEdge(graph: Graph, id: string): void
The graph to delete the edge from.
ID of the edge to delete.
Behavior
- Throws if the edge doesn’t exist
- Invalidates internal indexes (rebuilds on next access)
Examples
const graph = createGraph({
nodes: [{ id: 'a' }, { id: 'b' }],
edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
});
deleteEdge(graph, 'e1');
// graph.edges.length === 0
updateNode
Mutable. Update a node in place.
export function updateNode<N>(
graph: Graph<N>,
id: string,
update: Partial<Omit<NodeConfig<N>, 'id'>>
): GraphNode<N>
The graph containing the node.
ID of the node to update.
update
Partial<Omit<NodeConfig<N>, 'id'>>
required
Partial update object. Can include any NodeConfig property except id.
Behavior
- Throws if the node doesn’t exist
- Throws if
update.parentId is specified but the parent node doesn’t exist
- Updates only the specified properties (shallow merge)
- Updates hierarchy indexes if
parentId changes
Examples
const graph = createGraph({ nodes: [{ id: 'a', label: 'old' }] });
const updated = updateNode(graph, 'a', { label: 'new' });
// updated.label === 'new'
// getNode(graph, 'a').label === 'new'
updateEdge
Mutable. Update an edge in place.
export function updateEdge<E>(
graph: Graph<any, E>,
id: string,
update: Partial<Omit<EdgeConfig<E>, 'id'>>
): GraphEdge<E>
The graph containing the edge.
ID of the edge to update.
update
Partial<Omit<EdgeConfig<E>, 'id'>>
required
Partial update object. Can include any EdgeConfig property except id.
Behavior
- Throws if the edge doesn’t exist
- Throws if
update.sourceId or update.targetId is specified but references a non-existent node
- Updates only the specified properties (shallow merge)
- Updates adjacency indexes if
sourceId or targetId changes
Examples
const graph = createGraph({
nodes: [{ id: 'a' }, { id: 'b' }],
edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
});
const updated = updateEdge(graph, 'e1', { label: 'new' });
// updated.label === 'new'
addEntities
Mutable. Add multiple nodes and edges to the graph. Nodes are added first, then edges (so edges can reference new nodes).
export function addEntities<N, E>(
graph: Graph<N, E>,
entities: EntitiesConfig<N, E>
): void
The graph to add entities to.
entities
EntitiesConfig<N, E>
required
Configuration with arrays of nodes and/or edges.Show EntitiesConfig properties
Array of node configurations to add.
Array of edge configurations to add.
Examples
const graph = createGraph();
addEntities(graph, {
nodes: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
edges: [
{ id: 'e1', sourceId: 'a', targetId: 'b' },
{ id: 'e2', sourceId: 'b', targetId: 'c' },
],
});
// graph.nodes.length === 3
// graph.edges.length === 2
deleteEntities
Mutable. Delete entities by id(s). Automatically detects whether each id is a node or edge. Node deletions cascade to children and connected edges.
export function deleteEntities(
graph: Graph,
ids: string | string[],
opts?: DeleteNodeOptions
): void
The graph to delete entities from.
ids
string | string[]
required
Single ID or array of IDs to delete. Can be mixed node and edge IDs.
Options passed to deleteNode for node deletions. See deleteNode for details. Examples
const graph = createGraph({
nodes: [{ id: 'a' }, { id: 'b' }],
edges: [{ id: 'e1', sourceId: 'a', targetId: 'b' }],
});
deleteEntities(graph, 'a');
// graph.nodes.length === 1
// graph.edges.length === 0 (e1 removed with node a)
updateEntities
Mutable. Update multiple nodes and edges in place. Each entry must include an id to identify which entity to update.
export function updateEntities<N, E>(
graph: Graph<N, E>,
updates: EntitiesUpdate<N, E>
): void
The graph to update entities in.
updates
EntitiesUpdate<N, E>
required
Update configuration with arrays of node and/or edge updates.Show EntitiesUpdate properties
nodes
(Partial<Omit<NodeConfig<N>, 'id'>> & { id: string })[]
Array of node updates. Each must include id plus properties to update.
edges
(Partial<Omit<EdgeConfig<E>, 'id'>> & { id: string })[]
Array of edge updates. Each must include id plus properties to update.
Examples
const graph = createGraph({
nodes: [
{ id: 'a', label: 'A' },
{ id: 'b', label: 'B' },
],
edges: [{ id: 'e1', sourceId: 'a', targetId: 'b', label: 'old' }],
});
updateEntities(graph, {
nodes: [
{ id: 'a', label: 'A-updated' },
{ id: 'b', label: 'B-updated' },
],
edges: [{ id: 'e1', label: 'new' }],
});
// getNode(graph, 'a').label === 'A-updated'
// getNode(graph, 'b').label === 'B-updated'
// getEdge(graph, 'e1').label === 'new'