graph

Functional graph data-structure.

Documentation

Example

import{Graph}from"@monstermann/graph";// Define your node and edge typestypeNodes=|{type: "User";id: string;name: string}|{type: "Post";id: string;title: string}|{type: "Comment";id: string;text: string};typeEdges={User: {Post: {role: "author"|"editor"};Comment: void};Post: {Comment: void};};// Create a graphconstgraph=Graph.create<Nodes,Edges>();// Add nodesletg=Graph.setNode(graph,{type: "User",id: "1",name: "Alice"});g=Graph.setNode(g,{type: "Post",id: "1",title: "Hello World"});g=Graph.setNode(g,{type: "Comment",id: "1",text: "Great post!"});// Add edges with datag=Graph.setEdge(g,["User","1"],["Post","1"],{role: "author"});g=Graph.setEdge(g,["User","1"],["Comment","1"]);g=Graph.setEdge(g,["Post","1"],["Comment","1"]);// Query the graphconstuser=Graph.getNode(g,["User","1"]);// user: { type: "User", id: "1", name: "Alice" }constuserPosts=Graph.getNeighbors(g,["User","1"],"Post");// userPosts: [{ type: "Post", id: "1", title: "Hello World" }]constpostEdge=Graph.getEdge(g,["User","1"],["Post","1"]);// postEdge: { role: "author" }

Installation

npm install @monstermann/graph

pnpm add @monstermann/graph

yarn add @monstermann/graph

bun add @monstermann/graph

Tree-shaking

Installation

npm install -D @monstermann/unplugin-graph

pnpm -D add @monstermann/unplugin-graph

yarn -D add @monstermann/unplugin-graph

bun -D add @monstermann/unplugin-graph

Usage

// vite.config.tsimportgraphfrom"@monstermann/unplugin-graph/vite";exportdefaultdefineConfig({plugins: [graph()],});

// rollup.config.jsimportgraphfrom"@monstermann/unplugin-graph/rollup";exportdefault{plugins: [graph()],};

// rolldown.config.jsimportgraphfrom"@monstermann/unplugin-graph/rolldown";exportdefault{plugins: [graph()],};

// webpack.config.jsconstgraph=require("@monstermann/unplugin-graph/webpack");module.exports={plugins: [graph()],};

// rspack.config.jsconstgraph=require("@monstermann/unplugin-graph/rspack");module.exports={plugins: [graph()],};

// esbuild.config.jsimport{build}from"esbuild";importgraphfrom"@monstermann/unplugin-graph/esbuild";build({plugins: [graph()],});

Graph

batch

functionGraph.batch(graph: Graph,transform: (graph: Graph)=>Graph|void,): Graph

Performs multiple graph mutations efficiently by batching them together. Returns the original graph if no changes were made, optimizing for structural sharing.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string;name: string}|{type: "Project";id: string;name: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();// Add multiple nodes and edges in a single batchconstupdated=Graph.batch(graph,(g)=>{g=Graph.setNode(g,{type: "Project",id: "1",name: "My Project"});g=Graph.setNode(g,{type: "Task",id: "1",title: "Task 1"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Task 2"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);g=Graph.setEdge(g,["Project","1"],["Task","2"]);returng;});

create

functionGraph.create<Nodes,Edges>(): Graph<Nodes,Edges>

Creates a new empty graph with the provided nodes & edges configuration.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={// Project <-> TaskProject: {Task: void};// Section <-> TaskSection: {Task: void};};constgraph=Graph.create<Nodes,Edges>();

findEdge

functionGraph.findEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,find: (edge: EdgeData)=>boolean,): EdgeData|undefined

Finds the first edge of a specific type from a source node that matches the predicate. Returns undefined if no matching edge is found.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number;assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setNode(g,{type: "Task",id: "2"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1,assignedAt: newDate(),});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2,assignedAt: newDate(),});consthighPriorityEdge=Graph.findEdge(g,["Project","1"],"Task",(edge)=>edge.priority>1,);// highPriorityEdge: { priority: 2, assignedAt: Date }

findEdges

functionGraph.findEdges(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,find: (edge: EdgeData)=>boolean,): EdgeData[]

Finds all edges of a specific type from a source node that match the predicate.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number;assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setNode(g,{type: "Task",id: "2"});g=Graph.setNode(g,{type: "Task",id: "3"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1,assignedAt: newDate(),});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2,assignedAt: newDate(),});g=Graph.setEdge(g,["Project","1"],["Task","3"],{priority: 3,assignedAt: newDate(),});consthighPriorityEdges=Graph.findEdges(g,["Project","1"],"Task",(edge)=>edge.priority>=2,);// highPriorityEdges: [{ priority: 2, ... }, { priority: 3, ... }]

findNeighbor

functionGraph.findNeighbor(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,find: (target: Node,edge: EdgeData,source: Node)=>boolean,): Node|undefined

Finds the first neighbor node of a specific type that matches the predicate. The predicate receives the target node, edge data, and source node. Returns undefined if no matching neighbor is found.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1",title: "Low Priority Task"});g=Graph.setNode(g,{type: "Task",id: "2",title: "High Priority Task"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 3});consthighPriorityTask=Graph.findNeighbor(g,["Project","1"],"Task",(task,edge,project)=>edge.priority>2,);// highPriorityTask: { type: "Task", id: "2", title: "High Priority Task" }

findNeighbors

functionGraph.findNeighbors(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,find: (target: Node,edge: EdgeData,source: Node)=>boolean,): Node[]

Finds all neighbor nodes of a specific type that match the predicate. The predicate receives the target node, edge data, and source node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1",title: "Low Priority Task"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Medium Priority Task"});g=Graph.setNode(g,{type: "Task",id: "3",title: "High Priority Task"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2});g=Graph.setEdge(g,["Project","1"],["Task","3"],{priority: 3});constmediumAndHighPriority=Graph.findNeighbors(g,["Project","1"],"Task",(task,edge,project)=>edge.priority>=2,);// mediumAndHighPriority: [// { type: "Task", id: "2", title: "Medium Priority Task" },// { type: "Task", id: "3", title: "High Priority Task" }// ]

findNode

functionGraph.findNode(graph: Graph,type: NodeType,find: (node: Node)=>boolean,): Node|undefined

Finds the first node of a specific type that matches the predicate. Returns undefined if no matching node is found.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string;completed: boolean}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "First Task",completed: false,});g=Graph.setNode(g,{type: "Task",id: "2",title: "Second Task",completed: true,});g=Graph.setNode(g,{type: "Task",id: "3",title: "Third Task",completed: false,});constcompletedTask=Graph.findNode(g,"Task",(task)=>task.completed);// completedTask: { type: "Task", id: "2", title: "Second Task", completed: true }consttaskWithTitle=Graph.findNode(g,"Task",(task)=>task.title==="First Task",);// taskWithTitle: { type: "Task", id: "1", title: "First Task", completed: false }

findNodes

functionGraph.findNodes(graph: Graph,type: NodeType,find: (node: Node)=>boolean,): Node[]

Finds all nodes of a specific type that match the predicate.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string;completed: boolean}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "First Task",completed: false,});g=Graph.setNode(g,{type: "Task",id: "2",title: "Second Task",completed: true,});g=Graph.setNode(g,{type: "Task",id: "3",title: "Third Task",completed: false,});constincompleteTasks=Graph.findNodes(g,"Task",(task)=>!task.completed);// incompleteTasks: [// { type: "Task", id: "1", title: "First Task", completed: false },// { type: "Task", id: "3", title: "Third Task", completed: false }// ]

forEachEdge

functionGraph.forEachEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,fn: (edge: EdgeData)=>void,): Graph

Iterates over all edges of a specific type from a source node, executing a function for each edge. Returns the graph unchanged (for chaining).

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setNode(g,{type: "Task",id: "2"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2});Graph.forEachEdge(g,["Project","1"],"Task",(edge)=>{console.log(edge.priority);});// Logs:// 1// 2

forEachNeighbor

functionGraph.forEachNeighbor(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,fn: (target: Node,edge: EdgeData,source: Node)=>void,): Graph

Iterates over all neighbor nodes of a specific type, executing a function for each neighbor. The function receives the target node, edge data, and source node. Returns the graph unchanged (for chaining).

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string;name: string};typeEdges={Project: {Task: {priority: number}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1",name: "My Project"});g=Graph.setNode(g,{type: "Task",id: "1",title: "First Task"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Second Task"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2});Graph.forEachNeighbor(g,["Project","1"],"Task",(task,edge,project)=>{console.log(`${project.name}: ${task.title} (priority: ${edge.priority})`);});// Logs:// "My Project: First Task (priority: 1)"// "My Project: Second Task (priority: 2)"

forEachNode

functionGraph.forEachNode(graph: Graph,type: NodeType,fn: (node: Node)=>void,): Graph

Iterates over all nodes of a specific type, executing a function for each node. Returns the graph unchanged (for chaining).

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "First Task"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Second Task"});g=Graph.setNode(g,{type: "Task",id: "3",title: "Third Task"});Graph.forEachNode(g,"Task",(task)=>{console.log(task.title);});// Logs:// "First Task"// "Second Task"// "Third Task"

fromJS

functionGraph.fromJS(data: {nodes: Node[];edges: [NodeType,NodeId,NodeType,NodeId,EdgeData][];}): Graph

Creates a graph from a plain JavaScript object representation. Useful for deserializing graphs from JSON or other storage formats.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constdata={nodes: [{type: "Project",id: "1"},{type: "Task",id: "1",title: "My Task"},{type: "Task",id: "2",title: "Another Task"},],edges: [["Project","1","Task","1",undefined],["Project","1","Task","2",undefined],],};constgraph=Graph.fromJS<Nodes,Edges>(data);Graph.hasNode(graph,["Project","1"]);// trueGraph.hasEdge(graph,["Project","1"],["Task","1"]);// true

getEdge

functionGraph.getEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},): EdgeData|undefined

Retrieves the edge data between two nodes. Returns undefined if the edge doesn't exist.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{assignedAt: newDate(),});constedge=Graph.getEdge(g,["Project","1"],["Task","1"]);// edge: { assignedAt: Date }constmissing=Graph.getEdge(g,["Project","1"],["Task","2"]);// missing: undefined

getEdges

functionGraph.getEdges(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,): EdgeData[]

Retrieves all edges of a specific type from a source node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setNode(g,{type: "Task",id: "2"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1});g=Graph.setEdge(g,["Project","1"],["Task","2"],{priority: 2});constedges=Graph.getEdges(g,["Project","1"],"Task");// edges: [{ priority: 1 }, { priority: 2 }]

getNeighbor

functionGraph.getNeighbor(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,): Node|undefined

Retrieves the first neighbor node of a specific type connected to the source node. Returns undefined if no neighbor of the specified type exists.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1",title: "Task 1"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Task 2"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);g=Graph.setEdge(g,["Project","1"],["Task","2"]);constfirstTask=Graph.getNeighbor(g,["Project","1"],"Task");// firstTask: { type: "Task", id: "1", title: "Task 1" }constnoSection=Graph.getNeighbor(g,["Project","1"],"Section");// noSection: undefined

getNeighbors

functionGraph.getNeighbors(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},type: NodeType,): Node[]

Retrieves all neighbor nodes of a specific type connected to the source node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1",title: "Task 1"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Task 2"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);g=Graph.setEdge(g,["Project","1"],["Task","2"]);consttasks=Graph.getNeighbors(g,["Project","1"],"Task");// tasks: [{ type: "Task", id: "1", title: "Task 1" }, { type: "Task", id: "2", title: "Task 2" }]

getNode

functionGraph.getNode(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},): Node|undefined

Retrieves a node from the graph. Returns undefined if the node doesn't exist.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();constwithNode=Graph.setNode(graph,{type: "Task",id: "1",title: "My Task",});consttask=Graph.getNode(withNode,["Task","1"]);// task: { type: "Task", id: "1", title: "My Task" }constmissing=Graph.getNode(withNode,["Task","2"]);// missing: undefined

getNodes

functionGraph.getNodes(graph: Graph,type: NodeType,): Node[]

Retrieves all nodes of a specific type from the graph.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "Task 1"});g=Graph.setNode(g,{type: "Task",id: "2",title: "Task 2"});g=Graph.setNode(g,{type: "Project",id: "1"});consttasks=Graph.getNodes(g,"Task");// tasks: [{ type: "Task", id: "1", title: "Task 1" }, { type: "Task", id: "2", title: "Task 2" }]constprojects=Graph.getNodes(g,"Project");// projects: [{ type: "Project", id: "1" }]

hasEdge

functionGraph.hasEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},): boolean

Checks if an edge exists between two nodes in the graph.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);Graph.hasEdge(g,["Project","1"],["Task","1"]);// trueGraph.hasEdge(g,["Task","1"],["Project","1"]);// true (bidirectional)Graph.hasEdge(g,["Project","1"],["Task","2"]);// false

hasNode

functionGraph.hasNode(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},): boolean

Checks if a node exists in the graph.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();constwithNode=Graph.setNode(graph,{type: "Task",id: "1"});Graph.hasNode(withNode,["Task","1"]);// trueGraph.hasNode(withNode,{type: "Task",id: "1"});// trueGraph.hasNode(withNode,["Task","2"]);// false

mapEdge

functionGraph.mapEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},update: (edge: EdgeData)=>EdgeData,): Graph

Updates an edge by applying a transformation function. Returns a new graph instance with the updated edge.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number;assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1,assignedAt: newDate(),});// Update edge datag=Graph.mapEdge(g,["Project","1"],["Task","1"],(edge)=>({
...edge,priority: 2,}));

mapNode

functionGraph.mapNode(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},update: (node: Node)=>Node,): Graph

Updates a node by applying a transformation function. If the node's type or id changes, all edges are preserved. Returns a new graph instance with the updated node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string;completed: boolean}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "My Task",completed: false,});// Update a propertyg=Graph.mapNode(g,["Task","1"],(task)=>({
...task,completed: true,}));// Change id (edges are preserved)letg2=Graph.setNode(graph,{type: "Task",id: "1",title: "Task",completed: false,});g2=Graph.setNode(g2,{type: "Project",id: "1"});g2=Graph.setEdge(g2,["Project","1"],["Task","1"]);g2=Graph.mapNode(g2,["Task","1"],(task)=>({
...task,id: "2",}));// Edge now connects ["Project", "1"] -> ["Task", "2"]

mergeEdge

functionGraph.mergeEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},update: Partial<EdgeData>,): Graph

Partially updates an edge by merging the provided properties. Returns a new graph instance with the updated edge.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {priority: number;assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"],{priority: 1,assignedAt: newDate(),});// Merge partial updateg=Graph.mergeEdge(g,["Project","1"],["Task","1"],{priority: 2});constedge=Graph.getEdge(g,["Project","1"],["Task","1"]);// edge: { priority: 2, assignedAt: <original date> }

mergeNode

functionGraph.mergeNode(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},update: Partial<Node>,): Graph

Partially updates a node by merging the provided properties. Returns a new graph instance with the updated node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string;completed: boolean}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Task",id: "1",title: "My Task",completed: false,});// Merge partial updateg=Graph.mergeNode(g,["Task","1"],{completed: true});consttask=Graph.getNode(g,["Task","1"]);// task: { type: "Task", id: "1", title: "My Task", completed: true }

removeEdge

functionGraph.removeEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},): Graph

Removes an edge between two nodes. The nodes remain in the graph. Returns a new graph instance without the edge.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);// Remove the edgeg=Graph.removeEdge(g,["Project","1"],["Task","1"]);Graph.hasNode(g,["Project","1"]);// trueGraph.hasNode(g,["Task","1"]);// trueGraph.hasEdge(g,["Project","1"],["Task","1"]);// false

removeNode

functionGraph.removeNode(graph: Graph,node: [NodeType,NodeId]|{type: NodeType,id: NodeId},): Graph

Removes a node and all its associated edges from the graph. Returns a new graph instance without the node.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);// Remove the task (also removes the edge)g=Graph.removeNode(g,["Task","1"]);Graph.hasNode(g,["Task","1"]);// falseGraph.hasEdge(g,["Project","1"],["Task","1"]);// false

setEdge

functionGraph.setEdge(graph: Graph,source: [NodeType,NodeId]|{type: NodeType,id: NodeId},target: [NodeType,NodeId]|{type: NodeType,id: NodeId},data?: EdgeData,): Graph

Adds or updates an edge between two nodes. Both nodes must exist in the graph. Returns a new graph instance with the edge set. Edges are bidirectional.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: {assignedAt: Date}};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1"});// Add edge with datag=Graph.setEdge(g,["Project","1"],["Task","1"],{assignedAt: newDate(),});// Add edge without data (void)letg2=Graph.setNode(graph,{type: "Section",id: "1"});g2=Graph.setNode(g2,{type: "Task",id: "1"});g2=Graph.setEdge(g2,["Section","1"],["Task","1"]);

setNode

functionGraph.setNode(graph: Graph,node: Node,): Graph

Adds or updates a node in the graph. Returns a new graph instance with the node set.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();// Add a new nodeconstg1=Graph.setNode(graph,{type: "Task",id: "1",title: "My Task"});// Update existing nodeconstg2=Graph.setNode(g1,{type: "Task",id: "1",title: "Updated Task"});

toJS

functionGraph.toJS(graph: Graph,): {nodes: Node[];edges: [NodeType,NodeId,NodeType,NodeId,EdgeData][];}

Converts a graph to a plain JavaScript object representation. Useful for serializing graphs to JSON or other storage formats.

Example

import{Graph}from"@monstermann/graph";typeNodes=|{type: "Task";id: string;title: string}|{type: "Section";id: string}|{type: "Project";id: string};typeEdges={Project: {Task: void};Section: {Task: void};};constgraph=Graph.create<Nodes,Edges>();letg=Graph.setNode(graph,{type: "Project",id: "1"});g=Graph.setNode(g,{type: "Task",id: "1",title: "My Task"});g=Graph.setEdge(g,["Project","1"],["Task","1"]);constdata=Graph.toJS(g);// data: {// nodes: [// { type: "Project", id: "1" },// { type: "Task", id: "1", title: "My Task" }// ],// edges: [// ["Project", "1", "Task", "1", undefined]// ]// }// Can be serialized to JSONconstjson=JSON.stringify(data);