| Linux premium331.web-hosting.com 4.18.0-553.80.1.lve.el8.x86_64 #1 SMP Wed Oct 22 19:29:36 UTC 2025 x86_64 Path : /proc/self/root/home/livedhms/lmgt/node_modules/effect/dist/esm/ |
| Current File : //proc/self/root/home/livedhms/lmgt/node_modules/effect/dist/esm/Graph.js |
/**
* @experimental
* @since 3.18.0
*/
import * as Data from "./Data.js";
import * as Equal from "./Equal.js";
import { dual } from "./Function.js";
import * as Hash from "./Hash.js";
import { format, NodeInspectSymbol } from "./Inspectable.js";
import * as Option from "./Option.js";
import { pipeArguments } from "./Pipeable.js";
/**
* Unique identifier for Graph instances.
*
* @since 3.18.0
* @category symbol
*/
export const TypeId = "~effect/Graph";
/**
* Edge data containing source, target, and user data.
*
* @since 3.18.0
* @category models
*/
export class Edge extends Data.Class {}
// =============================================================================
// Proto Objects
// =============================================================================
/** @internal */
const ProtoGraph = {
[TypeId]: TypeId,
[Symbol.iterator]() {
return this.nodes[Symbol.iterator]();
},
[NodeInspectSymbol]() {
return this.toJSON();
},
[Equal.symbol](that) {
if (isGraph(that)) {
if (this.nodes.size !== that.nodes.size || this.edges.size !== that.edges.size || this.type !== that.type) {
return false;
}
// Compare nodes
for (const [nodeIndex, nodeData] of this.nodes) {
if (!that.nodes.has(nodeIndex)) {
return false;
}
const otherNodeData = that.nodes.get(nodeIndex);
if (!Equal.equals(nodeData, otherNodeData)) {
return false;
}
}
// Compare edges
for (const [edgeIndex, edgeData] of this.edges) {
if (!that.edges.has(edgeIndex)) {
return false;
}
const otherEdge = that.edges.get(edgeIndex);
if (!Equal.equals(edgeData, otherEdge)) {
return false;
}
}
return true;
}
return false;
},
[Hash.symbol]() {
let hash = Hash.string("Graph");
hash = hash ^ Hash.string(this.type);
hash = hash ^ Hash.number(this.nodes.size);
hash = hash ^ Hash.number(this.edges.size);
for (const [nodeIndex, nodeData] of this.nodes) {
hash = hash ^ Hash.hash(nodeIndex) + Hash.hash(nodeData);
}
for (const [edgeIndex, edgeData] of this.edges) {
hash = hash ^ Hash.hash(edgeIndex) + Hash.hash(edgeData);
}
return hash;
},
toJSON() {
return {
_id: "Graph",
nodeCount: this.nodes.size,
edgeCount: this.edges.size,
type: this.type
};
},
toString() {
return format(this);
},
pipe() {
return pipeArguments(this, arguments);
}
};
// =============================================================================
// Errors
// =============================================================================
/**
* Error thrown when a graph operation fails.
*
* @since 3.18.0
* @category errors
*/
export class GraphError extends /*#__PURE__*/Data.TaggedError("GraphError") {}
/** @internal */
const missingNode = node => new GraphError({
message: `Node ${node} does not exist`
});
// =============================================================================
// Constructors
// =============================================================================
/** @internal */
export const isGraph = u => typeof u === "object" && u !== null && TypeId in u;
/**
* Creates a directed graph, optionally with initial mutations.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* // Directed graph with initial nodes and edges
* const graph = Graph.directed<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, "A->B")
* Graph.addEdge(mutable, b, c, "B->C")
* })
* ```
*
* @since 3.18.0
* @category constructors
*/
export const directed = mutate => {
const graph = Object.create(ProtoGraph);
graph.type = "directed";
graph.nodes = new Map();
graph.edges = new Map();
graph.adjacency = new Map();
graph.reverseAdjacency = new Map();
graph.nextNodeIndex = 0;
graph.nextEdgeIndex = 0;
graph.isAcyclic = Option.some(true);
graph.mutable = false;
if (mutate) {
const mutable = beginMutation(graph);
mutate(mutable);
return endMutation(mutable);
}
return graph;
};
/**
* Creates an undirected graph, optionally with initial mutations.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* // Undirected graph with initial nodes and edges
* const graph = Graph.undirected<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, "A-B")
* Graph.addEdge(mutable, b, c, "B-C")
* })
* ```
*
* @since 3.18.0
* @category constructors
*/
export const undirected = mutate => {
const graph = Object.create(ProtoGraph);
graph.type = "undirected";
graph.nodes = new Map();
graph.edges = new Map();
graph.adjacency = new Map();
graph.reverseAdjacency = new Map();
graph.nextNodeIndex = 0;
graph.nextEdgeIndex = 0;
graph.isAcyclic = Option.some(true);
graph.mutable = false;
if (mutate) {
const mutable = beginMutation(graph);
mutate(mutable);
return endMutation(mutable);
}
return graph;
};
// =============================================================================
// Scoped Mutable API
// =============================================================================
/**
* Creates a mutable scope for safe graph mutations by copying the data structure.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>()
* const mutable = Graph.beginMutation(graph)
* // Now mutable can be safely modified without affecting original graph
* ```
*
* @since 3.18.0
* @category mutations
*/
export const beginMutation = graph => {
// Copy adjacency maps with deep cloned arrays
const adjacency = new Map();
const reverseAdjacency = new Map();
for (const [nodeIndex, edges] of graph.adjacency) {
adjacency.set(nodeIndex, [...edges]);
}
for (const [nodeIndex, edges] of graph.reverseAdjacency) {
reverseAdjacency.set(nodeIndex, [...edges]);
}
const mutable = Object.create(ProtoGraph);
mutable.type = graph.type;
mutable.nodes = new Map(graph.nodes);
mutable.edges = new Map(graph.edges);
mutable.adjacency = adjacency;
mutable.reverseAdjacency = reverseAdjacency;
mutable.nextNodeIndex = graph.nextNodeIndex;
mutable.nextEdgeIndex = graph.nextEdgeIndex;
mutable.isAcyclic = graph.isAcyclic;
mutable.mutable = true;
return mutable;
};
/**
* Converts a mutable graph back to an immutable graph, ending the mutation scope.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>()
* const mutable = Graph.beginMutation(graph)
* // ... perform mutations on mutable ...
* const newGraph = Graph.endMutation(mutable)
* ```
*
* @since 3.18.0
* @category mutations
*/
export const endMutation = mutable => {
const graph = Object.create(ProtoGraph);
graph.type = mutable.type;
graph.nodes = new Map(mutable.nodes);
graph.edges = new Map(mutable.edges);
graph.adjacency = mutable.adjacency;
graph.reverseAdjacency = mutable.reverseAdjacency;
graph.nextNodeIndex = mutable.nextNodeIndex;
graph.nextEdgeIndex = mutable.nextEdgeIndex;
graph.isAcyclic = mutable.isAcyclic;
graph.mutable = false;
return graph;
};
/**
* Performs scoped mutations on a graph, automatically managing the mutation lifecycle.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>()
* const newGraph = Graph.mutate(graph, (mutable) => {
* // Safe mutations go here
* // mutable gets automatically converted back to immutable
* })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const mutate = /*#__PURE__*/dual(2, (graph, f) => {
const mutable = beginMutation(graph);
f(mutable);
return endMutation(mutable);
});
// =============================================================================
// Basic Node Operations
// =============================================================================
/**
* Adds a new node to a mutable graph and returns its index.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* console.log(nodeA) // NodeIndex with value 0
* console.log(nodeB) // NodeIndex with value 1
* })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const addNode = (mutable, data) => {
const nodeIndex = mutable.nextNodeIndex;
// Add node data
mutable.nodes.set(nodeIndex, data);
// Initialize empty adjacency lists
mutable.adjacency.set(nodeIndex, []);
mutable.reverseAdjacency.set(nodeIndex, []);
// Update graph allocators
mutable.nextNodeIndex = mutable.nextNodeIndex + 1;
return nodeIndex;
};
/**
* Gets the data associated with a node index, if it exists.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* Graph.addNode(mutable, "Node A")
* })
*
* const nodeIndex = 0
* const nodeData = Graph.getNode(graph, nodeIndex)
*
* if (Option.isSome(nodeData)) {
* console.log(nodeData.value) // "Node A"
* }
* ```
*
* @since 3.18.0
* @category getters
*/
export const getNode = (graph, nodeIndex) => graph.nodes.has(nodeIndex) ? Option.some(graph.nodes.get(nodeIndex)) : Option.none();
/**
* Checks if a node with the given index exists in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* Graph.addNode(mutable, "Node A")
* })
*
* const nodeIndex = 0
* const exists = Graph.hasNode(graph, nodeIndex)
* console.log(exists) // true
*
* const nonExistentIndex = 999
* const notExists = Graph.hasNode(graph, nonExistentIndex)
* console.log(notExists) // false
* ```
*
* @since 3.18.0
* @category getters
*/
export const hasNode = (graph, nodeIndex) => graph.nodes.has(nodeIndex);
/**
* Returns the number of nodes in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const emptyGraph = Graph.directed<string, number>()
* console.log(Graph.nodeCount(emptyGraph)) // 0
*
* const graphWithNodes = Graph.mutate(emptyGraph, (mutable) => {
* Graph.addNode(mutable, "Node A")
* Graph.addNode(mutable, "Node B")
* Graph.addNode(mutable, "Node C")
* })
*
* console.log(Graph.nodeCount(graphWithNodes)) // 3
* ```
*
* @since 3.18.0
* @category getters
*/
export const nodeCount = graph => graph.nodes.size;
/**
* Finds the first node that matches the given predicate.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* Graph.addNode(mutable, "Node A")
* Graph.addNode(mutable, "Node B")
* Graph.addNode(mutable, "Node C")
* })
*
* const result = Graph.findNode(graph, (data) => data.startsWith("Node B"))
* console.log(result) // Option.some(1)
*
* const notFound = Graph.findNode(graph, (data) => data === "Node D")
* console.log(notFound) // Option.none()
* ```
*
* @since 3.18.0
* @category getters
*/
export const findNode = (graph, predicate) => {
for (const [index, data] of graph.nodes) {
if (predicate(data)) {
return Option.some(index);
}
}
return Option.none();
};
/**
* Finds all nodes that match the given predicate.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* Graph.addNode(mutable, "Start A")
* Graph.addNode(mutable, "Node B")
* Graph.addNode(mutable, "Start C")
* })
*
* const result = Graph.findNodes(graph, (data) => data.startsWith("Start"))
* console.log(result) // [0, 2]
*
* const empty = Graph.findNodes(graph, (data) => data === "Not Found")
* console.log(empty) // []
* ```
*
* @since 3.18.0
* @category getters
*/
export const findNodes = (graph, predicate) => {
const results = [];
for (const [index, data] of graph.nodes) {
if (predicate(data)) {
results.push(index);
}
}
return results;
};
/**
* Finds the first edge that matches the given predicate.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 10)
* Graph.addEdge(mutable, nodeB, nodeC, 20)
* })
*
* const result = Graph.findEdge(graph, (data) => data > 15)
* console.log(result) // Option.some(1)
*
* const notFound = Graph.findEdge(graph, (data) => data > 100)
* console.log(notFound) // Option.none()
* ```
*
* @since 3.18.0
* @category getters
*/
export const findEdge = (graph, predicate) => {
for (const [edgeIndex, edgeData] of graph.edges) {
if (predicate(edgeData.data, edgeData.source, edgeData.target)) {
return Option.some(edgeIndex);
}
}
return Option.none();
};
/**
* Finds all edges that match the given predicate.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 10)
* Graph.addEdge(mutable, nodeB, nodeC, 20)
* Graph.addEdge(mutable, nodeC, nodeA, 30)
* })
*
* const result = Graph.findEdges(graph, (data) => data >= 20)
* console.log(result) // [1, 2]
*
* const empty = Graph.findEdges(graph, (data) => data > 100)
* console.log(empty) // []
* ```
*
* @since 3.18.0
* @category getters
*/
export const findEdges = (graph, predicate) => {
const results = [];
for (const [edgeIndex, edgeData] of graph.edges) {
if (predicate(edgeData.data, edgeData.source, edgeData.target)) {
results.push(edgeIndex);
}
}
return results;
};
/**
* Updates a single node's data by applying a transformation function.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* Graph.addNode(mutable, "Node A")
* Graph.addNode(mutable, "Node B")
* Graph.updateNode(mutable, 0, (data) => data.toUpperCase())
* })
*
* const nodeData = Graph.getNode(graph, 0)
* console.log(nodeData) // Option.some("NODE A")
* ```
*
* @since 3.18.0
* @category transformations
*/
export const updateNode = (mutable, index, f) => {
if (!mutable.nodes.has(index)) {
return;
}
const currentData = mutable.nodes.get(index);
const newData = f(currentData);
mutable.nodes.set(index, newData);
};
/**
* Updates a single edge's data by applying a transformation function.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const edgeIndex = Graph.addEdge(mutable, nodeA, nodeB, 10)
* Graph.updateEdge(mutable, edgeIndex, (data) => data * 2)
* })
*
* const edgeData = Graph.getEdge(result, 0)
* console.log(edgeData) // Option.some({ source: 0, target: 1, data: 20 })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const updateEdge = (mutable, edgeIndex, f) => {
if (!mutable.edges.has(edgeIndex)) {
return;
}
const currentEdge = mutable.edges.get(edgeIndex);
const newData = f(currentEdge.data);
mutable.edges.set(edgeIndex, {
...currentEdge,
data: newData
});
};
/**
* Creates a new graph with transformed node data using the provided mapping function.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* Graph.addNode(mutable, "node a")
* Graph.addNode(mutable, "node b")
* Graph.addNode(mutable, "node c")
* Graph.mapNodes(mutable, (data) => data.toUpperCase())
* })
*
* const nodeData = Graph.getNode(graph, 0)
* console.log(nodeData) // Option.some("NODE A")
* ```
*
* @since 3.18.0
* @category transformations
*/
export const mapNodes = (mutable, f) => {
// Transform existing node data in place
for (const [index, data] of mutable.nodes) {
const newData = f(data);
mutable.nodes.set(index, newData);
}
};
/**
* Transforms all edge data in a mutable graph using the provided mapping function.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 10)
* Graph.addEdge(mutable, b, c, 20)
* Graph.mapEdges(mutable, (data) => data * 2)
* })
*
* const edgeData = Graph.getEdge(graph, 0)
* console.log(edgeData) // Option.some({ source: 0, target: 1, data: 20 })
* ```
*
* @since 3.18.0
* @category transformations
*/
export const mapEdges = (mutable, f) => {
// Transform existing edge data in place
for (const [index, edgeData] of mutable.edges) {
const newData = f(edgeData.data);
mutable.edges.set(index, {
...edgeData,
data: newData
});
}
};
/**
* Reverses all edge directions in a mutable graph by swapping source and target nodes.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1) // A -> B
* Graph.addEdge(mutable, b, c, 2) // B -> C
* Graph.reverse(mutable) // Now B -> A, C -> B
* })
*
* const edge0 = Graph.getEdge(graph, 0)
* console.log(edge0) // Option.some({ source: 1, target: 0, data: 1 }) - B -> A
* ```
*
* @since 3.18.0
* @category transformations
*/
export const reverse = mutable => {
// Reverse all edges by swapping source and target
for (const [index, edgeData] of mutable.edges) {
mutable.edges.set(index, {
source: edgeData.target,
target: edgeData.source,
data: edgeData.data
});
}
// Clear and rebuild adjacency lists with reversed directions
mutable.adjacency.clear();
mutable.reverseAdjacency.clear();
// Rebuild adjacency lists with reversed directions
for (const [edgeIndex, edgeData] of mutable.edges) {
// Add to forward adjacency (source -> target)
const sourceEdges = mutable.adjacency.get(edgeData.source) || [];
sourceEdges.push(edgeIndex);
mutable.adjacency.set(edgeData.source, sourceEdges);
// Add to reverse adjacency (target <- source)
const targetEdges = mutable.reverseAdjacency.get(edgeData.target) || [];
targetEdges.push(edgeIndex);
mutable.reverseAdjacency.set(edgeData.target, targetEdges);
}
// Invalidate cycle flag since edge directions changed
mutable.isAcyclic = Option.none();
};
/**
* Filters and optionally transforms nodes in a mutable graph using a predicate function.
* Nodes that return Option.none are removed along with all their connected edges.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "active")
* const b = Graph.addNode(mutable, "inactive")
* const c = Graph.addNode(mutable, "active")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 2)
*
* // Keep only "active" nodes and transform to uppercase
* Graph.filterMapNodes(mutable, (data) =>
* data === "active" ? Option.some(data.toUpperCase()) : Option.none()
* )
* })
*
* console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
* ```
*
* @since 3.18.0
* @category transformations
*/
export const filterMapNodes = (mutable, f) => {
const nodesToRemove = [];
// First pass: identify nodes to remove and transform data for nodes to keep
for (const [index, data] of mutable.nodes) {
const result = f(data);
if (Option.isSome(result)) {
// Transform node data
mutable.nodes.set(index, result.value);
} else {
// Mark for removal
nodesToRemove.push(index);
}
}
// Second pass: remove filtered out nodes and their edges
for (const nodeIndex of nodesToRemove) {
removeNode(mutable, nodeIndex);
}
};
/**
* Filters and optionally transforms edges in a mutable graph using a predicate function.
* Edges that return Option.none are removed from the graph.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 5)
* Graph.addEdge(mutable, b, c, 15)
* Graph.addEdge(mutable, c, a, 25)
*
* // Keep only edges with weight >= 10 and double their weight
* Graph.filterMapEdges(mutable, (data) =>
* data >= 10 ? Option.some(data * 2) : Option.none()
* )
* })
*
* console.log(Graph.edgeCount(graph)) // 2 (edges with weight 5 removed)
* ```
*
* @since 3.18.0
* @category transformations
*/
export const filterMapEdges = (mutable, f) => {
const edgesToRemove = [];
// First pass: identify edges to remove and transform data for edges to keep
for (const [index, edgeData] of mutable.edges) {
const result = f(edgeData.data);
if (Option.isSome(result)) {
// Transform edge data
mutable.edges.set(index, {
...edgeData,
data: result.value
});
} else {
// Mark for removal
edgesToRemove.push(index);
}
}
// Second pass: remove filtered out edges
for (const edgeIndex of edgesToRemove) {
removeEdge(mutable, edgeIndex);
}
};
/**
* Filters nodes by removing those that don't match the predicate.
* This function modifies the mutable graph in place.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* Graph.addNode(mutable, "active")
* Graph.addNode(mutable, "inactive")
* Graph.addNode(mutable, "pending")
* Graph.addNode(mutable, "active")
*
* // Keep only "active" nodes
* Graph.filterNodes(mutable, (data) => data === "active")
* })
*
* console.log(Graph.nodeCount(graph)) // 2 (only "active" nodes remain)
* ```
*
* @since 3.18.0
* @category transformations
*/
export const filterNodes = (mutable, predicate) => {
const nodesToRemove = [];
// Identify nodes to remove
for (const [index, data] of mutable.nodes) {
if (!predicate(data)) {
nodesToRemove.push(index);
}
}
// Remove filtered out nodes (this also removes connected edges)
for (const nodeIndex of nodesToRemove) {
removeNode(mutable, nodeIndex);
}
};
/**
* Filters edges by removing those that don't match the predicate.
* This function modifies the mutable graph in place.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
*
* Graph.addEdge(mutable, a, b, 5)
* Graph.addEdge(mutable, b, c, 15)
* Graph.addEdge(mutable, c, a, 25)
*
* // Keep only edges with weight >= 10
* Graph.filterEdges(mutable, (data) => data >= 10)
* })
*
* console.log(Graph.edgeCount(graph)) // 2 (edge with weight 5 removed)
* ```
*
* @since 3.18.0
* @category transformations
*/
export const filterEdges = (mutable, predicate) => {
const edgesToRemove = [];
// Identify edges to remove
for (const [index, edgeData] of mutable.edges) {
if (!predicate(edgeData.data)) {
edgesToRemove.push(index);
}
}
// Remove filtered out edges
for (const edgeIndex of edgesToRemove) {
removeEdge(mutable, edgeIndex);
}
};
// =============================================================================
// Cycle Flag Management (Internal)
// =============================================================================
/** @internal */
const invalidateCycleFlagOnRemoval = mutable => {
// Only invalidate if the graph had cycles (removing edges/nodes cannot introduce cycles in acyclic graphs)
// If already unknown (null) or acyclic (true), no need to change
if (Option.isSome(mutable.isAcyclic) && mutable.isAcyclic.value === false) {
mutable.isAcyclic = Option.none();
}
};
/** @internal */
const invalidateCycleFlagOnAddition = mutable => {
// Only invalidate if the graph was acyclic (adding edges cannot remove cycles from cyclic graphs)
// If already unknown (null) or cyclic (false), no need to change
if (Option.isSome(mutable.isAcyclic) && mutable.isAcyclic.value === true) {
mutable.isAcyclic = Option.none();
}
};
// =============================================================================
// Edge Operations
// =============================================================================
/**
* Adds a new edge to a mutable graph and returns its index.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const edge = Graph.addEdge(mutable, nodeA, nodeB, 42)
* console.log(edge) // EdgeIndex with value 0
* })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const addEdge = (mutable, source, target, data) => {
// Validate that both nodes exist
if (!mutable.nodes.has(source)) {
throw missingNode(source);
}
if (!mutable.nodes.has(target)) {
throw missingNode(target);
}
const edgeIndex = mutable.nextEdgeIndex;
// Create edge data
const edgeData = new Edge({
source,
target,
data
});
mutable.edges.set(edgeIndex, edgeData);
// Update adjacency lists
const sourceAdjacency = mutable.adjacency.get(source);
if (sourceAdjacency !== undefined) {
sourceAdjacency.push(edgeIndex);
}
const targetReverseAdjacency = mutable.reverseAdjacency.get(target);
if (targetReverseAdjacency !== undefined) {
targetReverseAdjacency.push(edgeIndex);
}
// For undirected graphs, add reverse connections
if (mutable.type === "undirected") {
const targetAdjacency = mutable.adjacency.get(target);
if (targetAdjacency !== undefined) {
targetAdjacency.push(edgeIndex);
}
const sourceReverseAdjacency = mutable.reverseAdjacency.get(source);
if (sourceReverseAdjacency !== undefined) {
sourceReverseAdjacency.push(edgeIndex);
}
}
// Update allocators
mutable.nextEdgeIndex = mutable.nextEdgeIndex + 1;
// Only invalidate cycle flag if the graph was acyclic
// Adding edges cannot remove cycles from cyclic graphs
invalidateCycleFlagOnAddition(mutable);
return edgeIndex;
};
/**
* Removes a node and all its incident edges from a mutable graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* Graph.addEdge(mutable, nodeA, nodeB, 42)
*
* // Remove nodeA and all edges connected to it
* Graph.removeNode(mutable, nodeA)
* })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const removeNode = (mutable, nodeIndex) => {
// Check if node exists
if (!mutable.nodes.has(nodeIndex)) {
return; // Node doesn't exist, nothing to remove
}
// Collect all incident edges for removal
const edgesToRemove = [];
// Get outgoing edges
const outgoingEdges = mutable.adjacency.get(nodeIndex);
if (outgoingEdges !== undefined) {
for (const edge of outgoingEdges) {
edgesToRemove.push(edge);
}
}
// Get incoming edges
const incomingEdges = mutable.reverseAdjacency.get(nodeIndex);
if (incomingEdges !== undefined) {
for (const edge of incomingEdges) {
edgesToRemove.push(edge);
}
}
// Remove all incident edges
for (const edgeIndex of edgesToRemove) {
removeEdgeInternal(mutable, edgeIndex);
}
// Remove the node itself
mutable.nodes.delete(nodeIndex);
mutable.adjacency.delete(nodeIndex);
mutable.reverseAdjacency.delete(nodeIndex);
// Only invalidate cycle flag if the graph wasn't already known to be acyclic
// Removing nodes cannot introduce cycles in an acyclic graph
invalidateCycleFlagOnRemoval(mutable);
};
/**
* Removes an edge from a mutable graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const result = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const edge = Graph.addEdge(mutable, nodeA, nodeB, 42)
*
* // Remove the edge
* Graph.removeEdge(mutable, edge)
* })
* ```
*
* @since 3.18.0
* @category mutations
*/
export const removeEdge = (mutable, edgeIndex) => {
const wasRemoved = removeEdgeInternal(mutable, edgeIndex);
// Only invalidate cycle flag if an edge was actually removed
// and only if the graph wasn't already known to be acyclic
if (wasRemoved) {
invalidateCycleFlagOnRemoval(mutable);
}
};
/** @internal */
const removeEdgeInternal = (mutable, edgeIndex) => {
// Get edge data
const edge = mutable.edges.get(edgeIndex);
if (edge === undefined) {
return false; // Edge doesn't exist, no mutation occurred
}
const {
source,
target
} = edge;
// Remove from adjacency lists
const sourceAdjacency = mutable.adjacency.get(source);
if (sourceAdjacency !== undefined) {
const index = sourceAdjacency.indexOf(edgeIndex);
if (index !== -1) {
sourceAdjacency.splice(index, 1);
}
}
const targetReverseAdjacency = mutable.reverseAdjacency.get(target);
if (targetReverseAdjacency !== undefined) {
const index = targetReverseAdjacency.indexOf(edgeIndex);
if (index !== -1) {
targetReverseAdjacency.splice(index, 1);
}
}
// For undirected graphs, remove reverse connections
if (mutable.type === "undirected") {
const targetAdjacency = mutable.adjacency.get(target);
if (targetAdjacency !== undefined) {
const index = targetAdjacency.indexOf(edgeIndex);
if (index !== -1) {
targetAdjacency.splice(index, 1);
}
}
const sourceReverseAdjacency = mutable.reverseAdjacency.get(source);
if (sourceReverseAdjacency !== undefined) {
const index = sourceReverseAdjacency.indexOf(edgeIndex);
if (index !== -1) {
sourceReverseAdjacency.splice(index, 1);
}
}
}
// Remove edge data
mutable.edges.delete(edgeIndex);
return true; // Edge was successfully removed
};
// =============================================================================
// Edge Query Operations
// =============================================================================
/**
* Gets the edge data associated with an edge index, if it exists.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* Graph.addEdge(mutable, nodeA, nodeB, 42)
* })
*
* const edgeIndex = 0
* const edgeData = Graph.getEdge(graph, edgeIndex)
*
* if (Option.isSome(edgeData)) {
* console.log(edgeData.value.data) // 42
* console.log(edgeData.value.source) // NodeIndex(0)
* console.log(edgeData.value.target) // NodeIndex(1)
* }
* ```
*
* @since 3.18.0
* @category getters
*/
export const getEdge = (graph, edgeIndex) => graph.edges.has(edgeIndex) ? Option.some(graph.edges.get(edgeIndex)) : Option.none();
/**
* Checks if an edge exists between two nodes in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 42)
* })
*
* const nodeA = 0
* const nodeB = 1
* const nodeC = 2
*
* const hasAB = Graph.hasEdge(graph, nodeA, nodeB)
* console.log(hasAB) // true
*
* const hasAC = Graph.hasEdge(graph, nodeA, nodeC)
* console.log(hasAC) // false
* ```
*
* @since 3.18.0
* @category getters
*/
export const hasEdge = (graph, source, target) => {
const adjacencyList = graph.adjacency.get(source);
if (adjacencyList === undefined) {
return false;
}
// Check if any edge in the adjacency list connects to the target
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined && edge.target === target) {
return true;
}
}
return false;
};
/**
* Returns the number of edges in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const emptyGraph = Graph.directed<string, number>()
* console.log(Graph.edgeCount(emptyGraph)) // 0
*
* const graphWithEdges = Graph.mutate(emptyGraph, (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 1)
* Graph.addEdge(mutable, nodeB, nodeC, 2)
* Graph.addEdge(mutable, nodeC, nodeA, 3)
* })
*
* console.log(Graph.edgeCount(graphWithEdges)) // 3
* ```
*
* @since 3.18.0
* @category getters
*/
export const edgeCount = graph => graph.edges.size;
/**
* Returns the neighboring nodes (targets of outgoing edges) for a given node.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 1)
* Graph.addEdge(mutable, nodeA, nodeC, 2)
* })
*
* const nodeA = 0
* const nodeB = 1
* const nodeC = 2
*
* const neighborsA = Graph.neighbors(graph, nodeA)
* console.log(neighborsA) // [NodeIndex(1), NodeIndex(2)]
*
* const neighborsB = Graph.neighbors(graph, nodeB)
* console.log(neighborsB) // []
* ```
*
* @since 3.18.0
* @category getters
*/
export const neighbors = (graph, nodeIndex) => {
// For undirected graphs, use the specialized helper that returns the other endpoint
if (graph.type === "undirected") {
return getUndirectedNeighbors(graph, nodeIndex);
}
const adjacencyList = graph.adjacency.get(nodeIndex);
if (adjacencyList === undefined) {
return [];
}
const result = [];
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
result.push(edge.target);
}
}
return result;
};
/**
* Get neighbors of a node in a specific direction for bidirectional traversal.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, "A->B")
* })
*
* const nodeA = 0
* const nodeB = 1
*
* // Get outgoing neighbors (nodes that nodeA points to)
* const outgoing = Graph.neighborsDirected(graph, nodeA, "outgoing")
*
* // Get incoming neighbors (nodes that point to nodeB)
* const incoming = Graph.neighborsDirected(graph, nodeB, "incoming")
* ```
*
* @since 3.18.0
* @category queries
*/
export const neighborsDirected = (graph, nodeIndex, direction) => {
const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
const adjacencyList = adjacencyMap.get(nodeIndex);
if (adjacencyList === undefined) {
return [];
}
const result = [];
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
// For incoming direction, we want the source node instead of target
const neighborNode = direction === "incoming" ? edge.source : edge.target;
result.push(neighborNode);
}
}
return result;
};
/**
* Exports a graph to GraphViz DOT format for visualization.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const nodeA = Graph.addNode(mutable, "Node A")
* const nodeB = Graph.addNode(mutable, "Node B")
* const nodeC = Graph.addNode(mutable, "Node C")
* Graph.addEdge(mutable, nodeA, nodeB, 1)
* Graph.addEdge(mutable, nodeB, nodeC, 2)
* Graph.addEdge(mutable, nodeC, nodeA, 3)
* })
*
* const dot = Graph.toGraphViz(graph)
* console.log(dot)
* // digraph G {
* // "0" [label="Node A"];
* // "1" [label="Node B"];
* // "2" [label="Node C"];
* // "0" -> "1" [label="1"];
* // "1" -> "2" [label="2"];
* // "2" -> "0" [label="3"];
* // }
* ```
*
* @since 3.18.0
* @category utils
*/
export const toGraphViz = (graph, options) => {
const {
edgeLabel = data => String(data),
graphName = "G",
nodeLabel = data => String(data)
} = options ?? {};
const isDirected = graph.type === "directed";
const graphType = isDirected ? "digraph" : "graph";
const edgeOperator = isDirected ? "->" : "--";
const lines = [];
lines.push(`${graphType} ${graphName} {`);
// Add nodes
for (const [nodeIndex, nodeData] of graph.nodes) {
const label = nodeLabel(nodeData).replace(/"/g, "\\\"");
lines.push(` "${nodeIndex}" [label="${label}"];`);
}
// Add edges
for (const [, edgeData] of graph.edges) {
const label = edgeLabel(edgeData.data).replace(/"/g, "\\\"");
lines.push(` "${edgeData.source}" ${edgeOperator} "${edgeData.target}" [label="${label}"];`);
}
lines.push("}");
return lines.join("\n");
};
/** @internal */
const escapeMermaidLabel = label => {
// Escape special characters for Mermaid using HTML entity codes
// According to: https://mermaid.js.org/syntax/flowchart.html#special-characters-that-break-syntax
return label.replace(/#/g, "#35;").replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;").replace(/&/g, "#amp;").replace(/\[/g, "#91;").replace(/\]/g, "#93;").replace(/\{/g, "#123;").replace(/\}/g, "#125;").replace(/\(/g, "#40;").replace(/\)/g, "#41;").replace(/\|/g, "#124;").replace(/\\/g, "#92;").replace(/\n/g, "<br/>");
};
/** @internal */
const formatMermaidNode = (nodeId, label, shape) => {
switch (shape) {
case "rectangle":
return `${nodeId}["${label}"]`;
case "rounded":
return `${nodeId}("${label}")`;
case "circle":
return `${nodeId}(("${label}"))`;
case "diamond":
return `${nodeId}{"${label}"}`;
case "hexagon":
return `${nodeId}{{"${label}"}}`;
case "stadium":
return `${nodeId}(["${label}"])`;
case "subroutine":
return `${nodeId}[["${label}"]]`;
case "cylindrical":
return `${nodeId}[("${label}")]`;
}
};
/**
* Exports a graph to Mermaid diagram format for visualization.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.mutate(Graph.directed<string, number>(), (mutable) => {
* const app = Graph.addNode(mutable, "App")
* const db = Graph.addNode(mutable, "Database")
* const cache = Graph.addNode(mutable, "Cache")
* Graph.addEdge(mutable, app, db, 1)
* Graph.addEdge(mutable, app, cache, 2)
* })
*
* const mermaid = Graph.toMermaid(graph)
* console.log(mermaid)
* // flowchart TD
* // 0["App"]
* // 1["Database"]
* // 2["Cache"]
* // 0 -->|"1"| 1
* // 0 -->|"2"| 2
* ```
*
* @since 3.18.0
* @category utils
*/
export const toMermaid = (graph, options) => {
// Extract and validate options with defaults
const {
diagramType,
direction = "TD",
edgeLabel = data => String(data),
nodeLabel = data => String(data),
nodeShape = () => "rectangle"
} = options ?? {};
// Auto-detect diagram type if not specified
const finalDiagramType = diagramType ?? (graph.type === "directed" ? "flowchart" : "graph");
// Generate diagram header
const lines = [];
lines.push(`${finalDiagramType} ${direction}`);
// Add nodes
for (const [nodeIndex, nodeData] of graph.nodes) {
const nodeId = String(nodeIndex);
const label = escapeMermaidLabel(nodeLabel(nodeData));
const shape = nodeShape(nodeData);
const formattedNode = formatMermaidNode(nodeId, label, shape);
lines.push(` ${formattedNode}`);
}
// Add edges
const edgeOperator = finalDiagramType === "flowchart" ? "-->" : "---";
for (const [, edgeData] of graph.edges) {
const sourceId = String(edgeData.source);
const targetId = String(edgeData.target);
const label = escapeMermaidLabel(edgeLabel(edgeData.data));
if (label) {
lines.push(` ${sourceId} ${edgeOperator}|"${label}"| ${targetId}`);
} else {
lines.push(` ${sourceId} ${edgeOperator} ${targetId}`);
}
}
return lines.join("\n");
};
// =============================================================================
// =============================================================================
// Graph Structure Analysis Algorithms (Phase 5A)
// =============================================================================
/**
* Checks if the graph is acyclic (contains no cycles).
*
* Uses depth-first search to detect back edges, which indicate cycles.
* For directed graphs, any back edge creates a cycle. For undirected graphs,
* a back edge that doesn't go to the immediate parent creates a cycle.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* // Acyclic directed graph (DAG)
* const dag = Graph.directed<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, "A->B")
* Graph.addEdge(mutable, b, c, "B->C")
* })
* console.log(Graph.isAcyclic(dag)) // true
*
* // Cyclic directed graph
* const cyclic = Graph.directed<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, "A->B")
* Graph.addEdge(mutable, b, a, "B->A") // Creates cycle
* })
* console.log(Graph.isAcyclic(cyclic)) // false
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const isAcyclic = graph => {
// Use existing cycle flag if available
if (Option.isSome(graph.isAcyclic)) {
return graph.isAcyclic.value;
}
// Stack-safe DFS cycle detection using iterative approach
const visited = new Set();
const recursionStack = new Set();
// Get all nodes to handle disconnected components
for (const startNode of graph.nodes.keys()) {
if (visited.has(startNode)) {
continue; // Already processed this component
}
// Iterative DFS with explicit stack
const stack = [[startNode, [], 0, true]];
while (stack.length > 0) {
const [node, neighbors, neighborIndex, isFirstVisit] = stack[stack.length - 1];
// First visit to this node
if (isFirstVisit) {
if (recursionStack.has(node)) {
// Back edge found - cycle detected
graph.isAcyclic = Option.some(false);
return false;
}
if (visited.has(node)) {
stack.pop();
continue;
}
visited.add(node);
recursionStack.add(node);
// Get neighbors for this node
const nodeNeighbors = Array.from(neighborsDirected(graph, node, "outgoing"));
stack[stack.length - 1] = [node, nodeNeighbors, 0, false];
continue;
}
// Process next neighbor
if (neighborIndex < neighbors.length) {
const neighbor = neighbors[neighborIndex];
stack[stack.length - 1] = [node, neighbors, neighborIndex + 1, false];
if (recursionStack.has(neighbor)) {
// Back edge found - cycle detected
graph.isAcyclic = Option.some(false);
return false;
}
if (!visited.has(neighbor)) {
stack.push([neighbor, [], 0, true]);
}
} else {
// Done with this node - backtrack
recursionStack.delete(node);
stack.pop();
}
}
}
// Cache the result
graph.isAcyclic = Option.some(true);
return true;
};
/**
* Checks if an undirected graph is bipartite.
*
* A bipartite graph is one whose vertices can be divided into two disjoint sets
* such that no two vertices within the same set are adjacent. Uses BFS coloring
* to determine bipartiteness.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* // Bipartite graph (alternating coloring possible)
* const bipartite = Graph.undirected<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* const d = Graph.addNode(mutable, "D")
* Graph.addEdge(mutable, a, b, "edge") // Set 1: {A, C}, Set 2: {B, D}
* Graph.addEdge(mutable, b, c, "edge")
* Graph.addEdge(mutable, c, d, "edge")
* })
* console.log(Graph.isBipartite(bipartite)) // true
*
* // Non-bipartite graph (odd cycle)
* const triangle = Graph.undirected<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, "edge")
* Graph.addEdge(mutable, b, c, "edge")
* Graph.addEdge(mutable, c, a, "edge") // Triangle (3-cycle)
* })
* console.log(Graph.isBipartite(triangle)) // false
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const isBipartite = graph => {
const coloring = new Map();
const discovered = new Set();
let isBipartiteGraph = true;
// Get all nodes to handle disconnected components
for (const startNode of graph.nodes.keys()) {
if (!discovered.has(startNode)) {
// Start BFS coloring from this component
const queue = [startNode];
coloring.set(startNode, 0); // Color start node with 0
discovered.add(startNode);
while (queue.length > 0 && isBipartiteGraph) {
const current = queue.shift();
const currentColor = coloring.get(current);
const neighborColor = currentColor === 0 ? 1 : 0;
// Get all neighbors for undirected graph
const nodeNeighbors = getUndirectedNeighbors(graph, current);
for (const neighbor of nodeNeighbors) {
if (!discovered.has(neighbor)) {
// Color unvisited neighbor with opposite color
coloring.set(neighbor, neighborColor);
discovered.add(neighbor);
queue.push(neighbor);
} else {
// Check if neighbor has the same color (conflict)
if (coloring.get(neighbor) === currentColor) {
isBipartiteGraph = false;
break;
}
}
}
}
// Early exit if not bipartite
if (!isBipartiteGraph) {
break;
}
}
}
return isBipartiteGraph;
};
/**
* Get neighbors for undirected graphs by checking both adjacency and reverse adjacency.
* For undirected graphs, we need to find the other endpoint of each edge incident to the node.
*/
const getUndirectedNeighbors = (graph, nodeIndex) => {
const neighbors = new Set();
// Check edges where this node is the source
const adjacencyList = graph.adjacency.get(nodeIndex);
if (adjacencyList !== undefined) {
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
// For undirected graphs, the neighbor is the other endpoint
const otherNode = edge.source === nodeIndex ? edge.target : edge.source;
neighbors.add(otherNode);
}
}
}
return Array.from(neighbors);
};
/**
* Find connected components in an undirected graph.
* Each component is represented as an array of node indices.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.undirected<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* const d = Graph.addNode(mutable, "D")
* Graph.addEdge(mutable, a, b, "edge") // Component 1: A-B
* Graph.addEdge(mutable, c, d, "edge") // Component 2: C-D
* })
*
* const components = Graph.connectedComponents(graph)
* console.log(components) // [[0, 1], [2, 3]]
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const connectedComponents = graph => {
const visited = new Set();
const components = [];
for (const startNode of graph.nodes.keys()) {
if (!visited.has(startNode)) {
// DFS to find all nodes in this component
const component = [];
const stack = [startNode];
while (stack.length > 0) {
const current = stack.pop();
if (!visited.has(current)) {
visited.add(current);
component.push(current);
// Add all unvisited neighbors to stack
const nodeNeighbors = getUndirectedNeighbors(graph, current);
for (const neighbor of nodeNeighbors) {
if (!visited.has(neighbor)) {
stack.push(neighbor);
}
}
}
}
components.push(component);
}
}
return components;
};
/**
* Find strongly connected components in a directed graph using Kosaraju's algorithm.
* Each SCC is represented as an array of node indices.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, string>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, "A->B")
* Graph.addEdge(mutable, b, c, "B->C")
* Graph.addEdge(mutable, c, a, "C->A") // Creates SCC: A-B-C
* })
*
* const sccs = Graph.stronglyConnectedComponents(graph)
* console.log(sccs) // [[0, 1, 2]]
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const stronglyConnectedComponents = graph => {
const visited = new Set();
const finishOrder = [];
for (const startNode of graph.nodes.keys()) {
if (visited.has(startNode)) {
continue;
}
const stack = [[startNode, [], 0, true]];
while (stack.length > 0) {
const [node, nodeNeighbors, neighborIndex, isFirstVisit] = stack[stack.length - 1];
if (isFirstVisit) {
if (visited.has(node)) {
stack.pop();
continue;
}
visited.add(node);
const nodeNeighborsList = neighbors(graph, node);
stack[stack.length - 1] = [node, nodeNeighborsList, 0, false];
continue;
}
// Process next neighbor
if (neighborIndex < nodeNeighbors.length) {
const neighbor = nodeNeighbors[neighborIndex];
stack[stack.length - 1] = [node, nodeNeighbors, neighborIndex + 1, false];
if (!visited.has(neighbor)) {
stack.push([neighbor, [], 0, true]);
}
} else {
// Done with this node - add to finish order (post-order)
finishOrder.push(node);
stack.pop();
}
}
}
// Step 2: Stack-safe DFS on transpose graph in reverse finish order
visited.clear();
const sccs = [];
for (let i = finishOrder.length - 1; i >= 0; i--) {
const startNode = finishOrder[i];
if (visited.has(startNode)) {
continue;
}
const scc = [];
const stack = [startNode];
while (stack.length > 0) {
const node = stack.pop();
if (visited.has(node)) {
continue;
}
visited.add(node);
scc.push(node);
// Use reverse adjacency (transpose graph)
const reverseAdjacency = graph.reverseAdjacency.get(node);
if (reverseAdjacency !== undefined) {
for (const edgeIndex of reverseAdjacency) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
const predecessor = edge.source;
if (!visited.has(predecessor)) {
stack.push(predecessor);
}
}
}
}
}
sccs.push(scc);
}
return sccs;
};
/**
* Find the shortest path between two nodes using Dijkstra's algorithm.
*
* Dijkstra's algorithm works with non-negative edge weights and finds the shortest
* path from a source node to a target node in O((V + E) log V) time complexity.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 5)
* Graph.addEdge(mutable, a, c, 10)
* Graph.addEdge(mutable, b, c, 2)
* })
*
* const result = Graph.dijkstra(graph, { source: 0, target: 2, cost: (edgeData) => edgeData })
* if (Option.isSome(result)) {
* console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
* console.log(result.value.distance) // 7 - total distance
* }
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const dijkstra = (graph, config) => {
const {
cost,
source,
target
} = config;
// Validate that source and target nodes exist
if (!graph.nodes.has(source)) {
throw missingNode(source);
}
if (!graph.nodes.has(target)) {
throw missingNode(target);
}
// Early return if source equals target
if (source === target) {
return Option.some({
path: [source],
distance: 0,
costs: []
});
}
// Distance tracking and priority queue simulation
const distances = new Map();
const previous = new Map();
const visited = new Set();
// Initialize distances
// Iterate directly over node keys
for (const node of graph.nodes.keys()) {
distances.set(node, node === source ? 0 : Infinity);
previous.set(node, null);
}
// Simple priority queue using array (can be optimized with proper heap)
const priorityQueue = [{
node: source,
distance: 0
}];
while (priorityQueue.length > 0) {
// Find minimum distance node (priority queue extract-min)
let minIndex = 0;
for (let i = 1; i < priorityQueue.length; i++) {
if (priorityQueue[i].distance < priorityQueue[minIndex].distance) {
minIndex = i;
}
}
const current = priorityQueue.splice(minIndex, 1)[0];
const currentNode = current.node;
// Skip if already visited (can happen with duplicate entries)
if (visited.has(currentNode)) {
continue;
}
visited.add(currentNode);
// Early termination if we reached the target
if (currentNode === target) {
break;
}
// Get current distance
const currentDistance = distances.get(currentNode);
// Examine all outgoing edges
const adjacencyList = graph.adjacency.get(currentNode);
if (adjacencyList !== undefined) {
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
const neighbor = edge.target;
const weight = cost(edge.data);
// Validate non-negative weights
if (weight < 0) {
throw new Error(`Dijkstra's algorithm requires non-negative edge weights, found ${weight}`);
}
const newDistance = currentDistance + weight;
const neighborDistance = distances.get(neighbor);
// Relaxation step
if (newDistance < neighborDistance) {
distances.set(neighbor, newDistance);
previous.set(neighbor, {
node: currentNode,
edgeData: edge.data
});
// Add to priority queue if not visited
if (!visited.has(neighbor)) {
priorityQueue.push({
node: neighbor,
distance: newDistance
});
}
}
}
}
}
}
// Check if target is reachable
const targetDistance = distances.get(target);
if (targetDistance === Infinity) {
return Option.none(); // No path exists
}
// Reconstruct path
const path = [];
const costs = [];
let currentNode = target;
while (currentNode !== null) {
path.unshift(currentNode);
const prev = previous.get(currentNode);
if (prev !== null) {
costs.unshift(prev.edgeData);
currentNode = prev.node;
} else {
currentNode = null;
}
}
return Option.some({
path,
distance: targetDistance,
costs
});
};
/**
* Find shortest paths between all pairs of nodes using Floyd-Warshall algorithm.
*
* Floyd-Warshall algorithm computes shortest paths between all pairs of nodes in O(V³) time.
* It can handle negative edge weights and detect negative cycles.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 3)
* Graph.addEdge(mutable, b, c, 2)
* Graph.addEdge(mutable, a, c, 7)
* })
*
* const result = Graph.floydWarshall(graph, (edgeData) => edgeData)
* const distanceAToC = result.distances.get(0)?.get(2) // 5 (A->B->C)
* const pathAToC = result.paths.get(0)?.get(2) // [0, 1, 2]
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const floydWarshall = (graph, cost) => {
// Get all nodes for Floyd-Warshall algorithm (needs array for nested iteration)
const allNodes = Array.from(graph.nodes.keys());
// Initialize distance matrix
const dist = new Map();
const next = new Map();
const edgeMatrix = new Map();
// Initialize with infinity for all pairs
for (const i of allNodes) {
dist.set(i, new Map());
next.set(i, new Map());
edgeMatrix.set(i, new Map());
for (const j of allNodes) {
dist.get(i).set(j, i === j ? 0 : Infinity);
next.get(i).set(j, null);
edgeMatrix.get(i).set(j, null);
}
}
// Set edge weights
for (const [, edgeData] of graph.edges) {
const weight = cost(edgeData.data);
const i = edgeData.source;
const j = edgeData.target;
// Use minimum weight if multiple edges exist
const currentWeight = dist.get(i).get(j);
if (weight < currentWeight) {
dist.get(i).set(j, weight);
next.get(i).set(j, j);
edgeMatrix.get(i).set(j, edgeData.data);
}
}
// Floyd-Warshall main loop
for (const k of allNodes) {
for (const i of allNodes) {
for (const j of allNodes) {
const distIK = dist.get(i).get(k);
const distKJ = dist.get(k).get(j);
const distIJ = dist.get(i).get(j);
if (distIK !== Infinity && distKJ !== Infinity && distIK + distKJ < distIJ) {
dist.get(i).set(j, distIK + distKJ);
next.get(i).set(j, next.get(i).get(k));
}
}
}
}
// Check for negative cycles
for (const i of allNodes) {
if (dist.get(i).get(i) < 0) {
throw new Error(`Negative cycle detected involving node ${i}`);
}
}
// Build result paths and edge weights
const paths = new Map();
const resultCosts = new Map();
for (const i of allNodes) {
paths.set(i, new Map());
resultCosts.set(i, new Map());
for (const j of allNodes) {
if (i === j) {
paths.get(i).set(j, [i]);
resultCosts.get(i).set(j, []);
} else if (dist.get(i).get(j) === Infinity) {
paths.get(i).set(j, null);
resultCosts.get(i).set(j, []);
} else {
// Reconstruct path iteratively
const path = [];
const weights = [];
let current = i;
path.push(current);
while (current !== j) {
const nextNode = next.get(current).get(j);
if (nextNode === null) break;
const edgeData = edgeMatrix.get(current).get(nextNode);
if (edgeData !== null) {
weights.push(edgeData);
}
current = nextNode;
path.push(current);
}
paths.get(i).set(j, path);
resultCosts.get(i).set(j, weights);
}
}
}
return {
distances: dist,
paths,
costs: resultCosts
};
};
/**
* Find the shortest path between two nodes using A* pathfinding algorithm.
*
* A* is an extension of Dijkstra's algorithm that uses a heuristic function to guide
* the search towards the target, potentially finding paths faster than Dijkstra's.
* The heuristic must be admissible (never overestimate the actual cost).
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.directed<{x: number, y: number}, number>((mutable) => {
* const a = Graph.addNode(mutable, {x: 0, y: 0})
* const b = Graph.addNode(mutable, {x: 1, y: 0})
* const c = Graph.addNode(mutable, {x: 2, y: 0})
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 1)
* })
*
* // Manhattan distance heuristic
* const heuristic = (nodeData: {x: number, y: number}, targetData: {x: number, y: number}) =>
* Math.abs(nodeData.x - targetData.x) + Math.abs(nodeData.y - targetData.y)
*
* const result = Graph.astar(graph, { source: 0, target: 2, cost: (edgeData) => edgeData, heuristic })
* if (Option.isSome(result)) {
* console.log(result.value.path) // [0, 1, 2] - shortest path
* console.log(result.value.distance) // 2 - total distance
* }
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const astar = (graph, config) => {
const {
cost,
heuristic,
source,
target
} = config;
// Validate that source and target nodes exist
if (!graph.nodes.has(source)) {
throw missingNode(source);
}
if (!graph.nodes.has(target)) {
throw missingNode(target);
}
// Early return if source equals target
if (source === target) {
return Option.some({
path: [source],
distance: 0,
costs: []
});
}
// Get target node data for heuristic calculations
const targetNodeData = graph.nodes.get(target);
if (targetNodeData === undefined) {
throw new Error(`Target node ${target} data not found`);
}
// Distance tracking (g-score) and f-score (g + h)
const gScore = new Map();
const fScore = new Map();
const previous = new Map();
const visited = new Set();
// Initialize scores
// Iterate directly over node keys
for (const node of graph.nodes.keys()) {
gScore.set(node, node === source ? 0 : Infinity);
fScore.set(node, Infinity);
previous.set(node, null);
}
// Calculate initial f-score for source
const sourceNodeData = graph.nodes.get(source);
if (sourceNodeData !== undefined) {
const h = heuristic(sourceNodeData, targetNodeData);
fScore.set(source, h);
}
// Priority queue using f-score (total estimated cost)
const openSet = [{
node: source,
fScore: fScore.get(source)
}];
while (openSet.length > 0) {
// Find node with lowest f-score
let minIndex = 0;
for (let i = 1; i < openSet.length; i++) {
if (openSet[i].fScore < openSet[minIndex].fScore) {
minIndex = i;
}
}
const current = openSet.splice(minIndex, 1)[0];
const currentNode = current.node;
// Skip if already visited
if (visited.has(currentNode)) {
continue;
}
visited.add(currentNode);
// Early termination if we reached the target
if (currentNode === target) {
break;
}
// Get current g-score
const currentGScore = gScore.get(currentNode);
// Examine all outgoing edges
const adjacencyList = graph.adjacency.get(currentNode);
if (adjacencyList !== undefined) {
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
const neighbor = edge.target;
const weight = cost(edge.data);
// Validate non-negative weights
if (weight < 0) {
throw new Error(`A* algorithm requires non-negative edge weights, found ${weight}`);
}
const tentativeGScore = currentGScore + weight;
const neighborGScore = gScore.get(neighbor);
// If this path to neighbor is better than any previous one
if (tentativeGScore < neighborGScore) {
// Update g-score and previous
gScore.set(neighbor, tentativeGScore);
previous.set(neighbor, {
node: currentNode,
edgeData: edge.data
});
// Calculate f-score using heuristic
const neighborNodeData = graph.nodes.get(neighbor);
if (neighborNodeData !== undefined) {
const h = heuristic(neighborNodeData, targetNodeData);
const f = tentativeGScore + h;
fScore.set(neighbor, f);
// Add to open set if not visited
if (!visited.has(neighbor)) {
openSet.push({
node: neighbor,
fScore: f
});
}
}
}
}
}
}
}
// Check if target is reachable
const targetGScore = gScore.get(target);
if (targetGScore === Infinity) {
return Option.none(); // No path exists
}
// Reconstruct path
const path = [];
const costs = [];
let currentNode = target;
while (currentNode !== null) {
path.unshift(currentNode);
const prev = previous.get(currentNode);
if (prev !== null) {
costs.unshift(prev.edgeData);
currentNode = prev.node;
} else {
currentNode = null;
}
}
return Option.some({
path,
distance: targetGScore,
costs
});
};
/**
* Find the shortest path between two nodes using Bellman-Ford algorithm.
*
* Bellman-Ford algorithm can handle negative edge weights and detects negative cycles.
* It has O(VE) time complexity, slower than Dijkstra's but more versatile.
* Returns Option.none() if a negative cycle is detected that affects the path.
*
* @example
* ```ts
* import { Graph, Option } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, -1) // Negative weight allowed
* Graph.addEdge(mutable, b, c, 3)
* Graph.addEdge(mutable, a, c, 5)
* })
*
* const result = Graph.bellmanFord(graph, { source: 0, target: 2, cost: (edgeData) => edgeData })
* if (Option.isSome(result)) {
* console.log(result.value.path) // [0, 1, 2] - shortest path A->B->C
* console.log(result.value.distance) // 2 - total distance
* }
* ```
*
* @since 3.18.0
* @category algorithms
*/
export const bellmanFord = (graph, config) => {
const {
cost,
source,
target
} = config;
// Validate that source and target nodes exist
if (!graph.nodes.has(source)) {
throw missingNode(source);
}
if (!graph.nodes.has(target)) {
throw missingNode(target);
}
// Early return if source equals target
if (source === target) {
return Option.some({
path: [source],
distance: 0,
costs: []
});
}
// Initialize distances and predecessors
const distances = new Map();
const previous = new Map();
// Iterate directly over node keys
for (const node of graph.nodes.keys()) {
distances.set(node, node === source ? 0 : Infinity);
previous.set(node, null);
}
// Collect all edges for relaxation
const edges = [];
for (const [, edgeData] of graph.edges) {
const weight = cost(edgeData.data);
edges.push({
source: edgeData.source,
target: edgeData.target,
weight,
edgeData: edgeData.data
});
}
// Relax edges up to V-1 times
const nodeCount = graph.nodes.size;
for (let i = 0; i < nodeCount - 1; i++) {
let hasUpdate = false;
for (const edge of edges) {
const sourceDistance = distances.get(edge.source);
const targetDistance = distances.get(edge.target);
// Relaxation step
if (sourceDistance !== Infinity && sourceDistance + edge.weight < targetDistance) {
distances.set(edge.target, sourceDistance + edge.weight);
previous.set(edge.target, {
node: edge.source,
edgeData: edge.edgeData
});
hasUpdate = true;
}
}
// Early termination if no updates
if (!hasUpdate) {
break;
}
}
// Check for negative cycles
for (const edge of edges) {
const sourceDistance = distances.get(edge.source);
const targetDistance = distances.get(edge.target);
if (sourceDistance !== Infinity && sourceDistance + edge.weight < targetDistance) {
// Negative cycle detected - check if it affects the path to target
const affectedNodes = new Set();
const queue = [edge.target];
while (queue.length > 0) {
const node = queue.shift();
if (affectedNodes.has(node)) continue;
affectedNodes.add(node);
// Add all nodes reachable from this node
const adjacencyList = graph.adjacency.get(node);
if (adjacencyList !== undefined) {
for (const edgeIndex of adjacencyList) {
const edge = graph.edges.get(edgeIndex);
if (edge !== undefined) {
queue.push(edge.target);
}
}
}
}
// If target is affected by negative cycle, return null
if (affectedNodes.has(target)) {
return Option.none();
}
}
}
// Check if target is reachable
const targetDistance = distances.get(target);
if (targetDistance === Infinity) {
return Option.none(); // No path exists
}
// Reconstruct path
const path = [];
const costs = [];
let currentNode = target;
while (currentNode !== null) {
path.unshift(currentNode);
const prev = previous.get(currentNode);
if (prev !== null) {
costs.unshift(prev.edgeData);
currentNode = prev.node;
} else {
currentNode = null;
}
}
return Option.some({
path,
distance: targetDistance,
costs
});
};
/**
* Concrete class for iterables that produce [NodeIndex, NodeData] tuples.
*
* This class provides a common abstraction for all iterables that return node data,
* including traversal iterators (DFS, BFS, etc.) and element iterators (nodes, externals).
* It uses a mapEntry function pattern for flexible iteration and transformation.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* // Both traversal and element iterators return NodeWalker
* const dfsNodes: Graph.NodeWalker<string> = Graph.dfs(graph, { start: [0] })
* const allNodes: Graph.NodeWalker<string> = Graph.nodes(graph)
*
* // Common interface for working with node iterables
* function processNodes<N>(nodeIterable: Graph.NodeWalker<N>): Array<number> {
* return Array.from(Graph.indices(nodeIterable))
* }
*
* // Access node data using values() or entries()
* const nodeData = Array.from(Graph.values(dfsNodes)) // ["A", "B"]
* const nodeEntries = Array.from(Graph.entries(allNodes)) // [[0, "A"], [1, "B"]]
* ```
*
* @since 3.18.0
* @category models
*/
export class Walker {
/**
* @since 3.18.0
*/
// @ts-ignore
[Symbol.iterator];
/**
* Visits each element and maps it to a value using the provided function.
*
* Takes a function that receives the index and data,
* and returns an iterable of the mapped values. Skips elements that
* no longer exist in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const dfs = Graph.dfs(graph, { start: [0] })
*
* // Map to just the node data
* const values = Array.from(dfs.visit((index, data) => data))
* console.log(values) // ["A", "B"]
*
* // Map to custom objects
* const custom = Array.from(dfs.visit((index, data) => ({ id: index, name: data })))
* console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
* ```
*
* @since 3.18.0
* @category iterators
*/
visit;
constructor(
/**
* Visits each element and maps it to a value using the provided function.
*
* Takes a function that receives the index and data,
* and returns an iterable of the mapped values. Skips elements that
* no longer exist in the graph.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const dfs = Graph.dfs(graph, { start: [0] })
*
* // Map to just the node data
* const values = Array.from(dfs.visit((index, data) => data))
* console.log(values) // ["A", "B"]
*
* // Map to custom objects
* const custom = Array.from(dfs.visit((index, data) => ({ id: index, name: data })))
* console.log(custom) // [{ id: 0, name: "A" }, { id: 1, name: "B" }]
* ```
*
* @since 3.18.0
* @category iterators
*/
visit) {
this.visit = visit;
this[Symbol.iterator] = visit((index, data) => [index, data])[Symbol.iterator];
}
}
/**
* Returns an iterator over the indices in the walker.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const dfs = Graph.dfs(graph, { start: [0] })
* const indices = Array.from(Graph.indices(dfs))
* console.log(indices) // [0, 1]
* ```
*
* @since 3.18.0
* @category utilities
*/
export const indices = walker => walker.visit((index, _) => index);
/**
* Returns an iterator over the values (data) in the walker.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const dfs = Graph.dfs(graph, { start: [0] })
* const values = Array.from(Graph.values(dfs))
* console.log(values) // ["A", "B"]
* ```
*
* @since 3.18.0
* @category utilities
*/
export const values = walker => walker.visit((_, data) => data);
/**
* Returns an iterator over [index, data] entries in the walker.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const dfs = Graph.dfs(graph, { start: [0] })
* const entries = Array.from(Graph.entries(dfs))
* console.log(entries) // [[0, "A"], [1, "B"]]
* ```
*
* @since 3.18.0
* @category utilities
*/
export const entries = walker => walker.visit((index, data) => [index, data]);
/**
* Creates a new DFS iterator with optional configuration.
*
* The iterator maintains a stack of nodes to visit and tracks discovered nodes.
* It provides lazy evaluation of the depth-first search.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 1)
* })
*
* // Start from a specific node
* const dfs1 = Graph.dfs(graph, { start: [0] })
* for (const nodeIndex of Graph.indices(dfs1)) {
* console.log(nodeIndex) // Traverses in DFS order: 0, 1, 2
* }
*
* // Empty iterator (no starting nodes)
* const dfs2 = Graph.dfs(graph)
* // Can be used programmatically
* ```
*
* @since 3.18.0
* @category iterators
*/
export const dfs = (graph, config = {}) => {
const start = config.start ?? [];
const direction = config.direction ?? "outgoing";
// Validate that all start nodes exist
for (const nodeIndex of start) {
if (!hasNode(graph, nodeIndex)) {
throw missingNode(nodeIndex);
}
}
return new Walker(f => ({
[Symbol.iterator]: () => {
const stack = [...start];
const discovered = new Set();
const nextMapped = () => {
while (stack.length > 0) {
const current = stack.pop();
if (discovered.has(current)) {
continue;
}
discovered.add(current);
const nodeDataOption = graph.nodes.get(current);
if (nodeDataOption === undefined) {
continue;
}
const neighbors = neighborsDirected(graph, current, direction);
for (let i = neighbors.length - 1; i >= 0; i--) {
const neighbor = neighbors[i];
if (!discovered.has(neighbor)) {
stack.push(neighbor);
}
}
return {
done: false,
value: f(current, nodeDataOption)
};
}
return {
done: true,
value: undefined
};
};
return {
next: nextMapped
};
}
}));
};
/**
* Creates a new BFS iterator with optional configuration.
*
* The iterator maintains a queue of nodes to visit and tracks discovered nodes.
* It provides lazy evaluation of the breadth-first search.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 1)
* })
*
* // Start from a specific node
* const bfs1 = Graph.bfs(graph, { start: [0] })
* for (const nodeIndex of Graph.indices(bfs1)) {
* console.log(nodeIndex) // Traverses in BFS order: 0, 1, 2
* }
*
* // Empty iterator (no starting nodes)
* const bfs2 = Graph.bfs(graph)
* // Can be used programmatically
* ```
*
* @since 3.18.0
* @category iterators
*/
export const bfs = (graph, config = {}) => {
const start = config.start ?? [];
const direction = config.direction ?? "outgoing";
// Validate that all start nodes exist
for (const nodeIndex of start) {
if (!hasNode(graph, nodeIndex)) {
throw missingNode(nodeIndex);
}
}
return new Walker(f => ({
[Symbol.iterator]: () => {
const queue = [...start];
const discovered = new Set();
const nextMapped = () => {
while (queue.length > 0) {
const current = queue.shift();
if (!discovered.has(current)) {
discovered.add(current);
const neighbors = neighborsDirected(graph, current, direction);
for (const neighbor of neighbors) {
if (!discovered.has(neighbor)) {
queue.push(neighbor);
}
}
const nodeData = getNode(graph, current);
if (Option.isSome(nodeData)) {
return {
done: false,
value: f(current, nodeData.value)
};
}
return nextMapped();
}
}
return {
done: true,
value: undefined
};
};
return {
next: nextMapped
};
}
}));
};
/**
* Creates a new topological sort iterator with optional configuration.
*
* The iterator uses Kahn's algorithm to lazily produce nodes in topological order.
* Throws an error if the graph contains cycles.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 1)
* })
*
* // Standard topological sort
* const topo1 = Graph.topo(graph)
* for (const nodeIndex of Graph.indices(topo1)) {
* console.log(nodeIndex) // 0, 1, 2 (topological order)
* }
*
* // With initial nodes
* const topo2 = Graph.topo(graph, { initials: [0] })
*
* // Throws error for cyclic graph
* const cyclicGraph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, a, 2) // Creates cycle
* })
*
* try {
* Graph.topo(cyclicGraph) // Throws: "Cannot perform topological sort on cyclic graph"
* } catch (error) {
* console.log((error as Error).message)
* }
* ```
*
* @since 3.18.0
* @category iterators
*/
export const topo = (graph, config = {}) => {
// Check if graph is acyclic first
if (!isAcyclic(graph)) {
throw new Error("Cannot perform topological sort on cyclic graph");
}
const initials = config.initials ?? [];
// Validate that all initial nodes exist
for (const nodeIndex of initials) {
if (!hasNode(graph, nodeIndex)) {
throw missingNode(nodeIndex);
}
}
return new Walker(f => ({
[Symbol.iterator]: () => {
const inDegree = new Map();
const remaining = new Set();
const queue = [...initials];
// Initialize in-degree counts
for (const [nodeIndex] of graph.nodes) {
inDegree.set(nodeIndex, 0);
remaining.add(nodeIndex);
}
// Calculate in-degrees
for (const [, edgeData] of graph.edges) {
const currentInDegree = inDegree.get(edgeData.target) || 0;
inDegree.set(edgeData.target, currentInDegree + 1);
}
// Add nodes with zero in-degree to queue if no initials provided
if (initials.length === 0) {
for (const [nodeIndex, degree] of inDegree) {
if (degree === 0) {
queue.push(nodeIndex);
}
}
}
const nextMapped = () => {
while (queue.length > 0) {
const current = queue.shift();
if (remaining.has(current)) {
remaining.delete(current);
// Process outgoing edges, reducing in-degree of targets
const neighbors = neighborsDirected(graph, current, "outgoing");
for (const neighbor of neighbors) {
if (remaining.has(neighbor)) {
const currentInDegree = inDegree.get(neighbor) || 0;
const newInDegree = currentInDegree - 1;
inDegree.set(neighbor, newInDegree);
// If in-degree becomes 0, add to queue
if (newInDegree === 0) {
queue.push(neighbor);
}
}
}
const nodeData = getNode(graph, current);
if (Option.isSome(nodeData)) {
return {
done: false,
value: f(current, nodeData.value)
};
}
return nextMapped();
}
}
return {
done: true,
value: undefined
};
};
return {
next: nextMapped
};
}
}));
};
/**
* Creates a new DFS postorder iterator with optional configuration.
*
* The iterator maintains a stack with visit state tracking and emits nodes
* in postorder (after all descendants have been processed). Essential for
* dependency resolution and tree destruction algorithms.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const root = Graph.addNode(mutable, "root")
* const child1 = Graph.addNode(mutable, "child1")
* const child2 = Graph.addNode(mutable, "child2")
* Graph.addEdge(mutable, root, child1, 1)
* Graph.addEdge(mutable, root, child2, 1)
* })
*
* // Postorder: children before parents
* const postOrder = Graph.dfsPostOrder(graph, { start: [0] })
* for (const node of postOrder) {
* console.log(node) // 1, 2, 0
* }
* ```
*
* @since 3.18.0
* @category iterators
*/
export const dfsPostOrder = (graph, config = {}) => {
const start = config.start ?? [];
const direction = config.direction ?? "outgoing";
// Validate that all start nodes exist
for (const nodeIndex of start) {
if (!hasNode(graph, nodeIndex)) {
throw missingNode(nodeIndex);
}
}
return new Walker(f => ({
[Symbol.iterator]: () => {
const stack = [];
const discovered = new Set();
const finished = new Set();
// Initialize stack with start nodes
for (let i = start.length - 1; i >= 0; i--) {
stack.push({
node: start[i],
visitedChildren: false
});
}
const nextMapped = () => {
while (stack.length > 0) {
const current = stack[stack.length - 1];
if (!discovered.has(current.node)) {
discovered.add(current.node);
current.visitedChildren = false;
}
if (!current.visitedChildren) {
current.visitedChildren = true;
const neighbors = neighborsDirected(graph, current.node, direction);
for (let i = neighbors.length - 1; i >= 0; i--) {
const neighbor = neighbors[i];
if (!discovered.has(neighbor) && !finished.has(neighbor)) {
stack.push({
node: neighbor,
visitedChildren: false
});
}
}
} else {
const nodeToEmit = stack.pop().node;
if (!finished.has(nodeToEmit)) {
finished.add(nodeToEmit);
const nodeData = getNode(graph, nodeToEmit);
if (Option.isSome(nodeData)) {
return {
done: false,
value: f(nodeToEmit, nodeData.value)
};
}
return nextMapped();
}
}
}
return {
done: true,
value: undefined
};
};
return {
next: nextMapped
};
}
}));
};
/**
* Creates an iterator over all node indices in the graph.
*
* The iterator produces node indices in the order they were added to the graph.
* This provides access to all nodes regardless of connectivity.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1)
* })
*
* const indices = Array.from(Graph.indices(Graph.nodes(graph)))
* console.log(indices) // [0, 1, 2]
* ```
*
* @since 3.18.0
* @category iterators
*/
export const nodes = graph => new Walker(f => ({
[Symbol.iterator]() {
const nodeMap = graph.nodes;
const iterator = nodeMap.entries();
return {
next() {
const result = iterator.next();
if (result.done) {
return {
done: true,
value: undefined
};
}
const [nodeIndex, nodeData] = result.value;
return {
done: false,
value: f(nodeIndex, nodeData)
};
}
};
}
}));
/**
* Creates an iterator over all edge indices in the graph.
*
* The iterator produces edge indices in the order they were added to the graph.
* This provides access to all edges regardless of connectivity.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const a = Graph.addNode(mutable, "A")
* const b = Graph.addNode(mutable, "B")
* const c = Graph.addNode(mutable, "C")
* Graph.addEdge(mutable, a, b, 1)
* Graph.addEdge(mutable, b, c, 2)
* })
*
* const indices = Array.from(Graph.indices(Graph.edges(graph)))
* console.log(indices) // [0, 1]
* ```
*
* @since 3.18.0
* @category iterators
*/
export const edges = graph => new Walker(f => ({
[Symbol.iterator]() {
const edgeMap = graph.edges;
const iterator = edgeMap.entries();
return {
next() {
const result = iterator.next();
if (result.done) {
return {
done: true,
value: undefined
};
}
const [edgeIndex, edgeData] = result.value;
return {
done: false,
value: f(edgeIndex, edgeData)
};
}
};
}
}));
/**
* Creates an iterator over external nodes (nodes without edges in specified direction).
*
* External nodes are nodes that have no outgoing edges (direction="outgoing") or
* no incoming edges (direction="incoming"). These are useful for finding
* sources, sinks, or isolated nodes.
*
* @example
* ```ts
* import { Graph } from "effect"
*
* const graph = Graph.directed<string, number>((mutable) => {
* const source = Graph.addNode(mutable, "source") // 0 - no incoming
* const middle = Graph.addNode(mutable, "middle") // 1 - has both
* const sink = Graph.addNode(mutable, "sink") // 2 - no outgoing
* const isolated = Graph.addNode(mutable, "isolated") // 3 - no edges
*
* Graph.addEdge(mutable, source, middle, 1)
* Graph.addEdge(mutable, middle, sink, 2)
* })
*
* // Nodes with no outgoing edges (sinks + isolated)
* const sinks = Array.from(Graph.indices(Graph.externals(graph, { direction: "outgoing" })))
* console.log(sinks) // [2, 3]
*
* // Nodes with no incoming edges (sources + isolated)
* const sources = Array.from(Graph.indices(Graph.externals(graph, { direction: "incoming" })))
* console.log(sources) // [0, 3]
* ```
*
* @since 3.18.0
* @category iterators
*/
export const externals = (graph, config = {}) => {
const direction = config.direction ?? "outgoing";
return new Walker(f => ({
[Symbol.iterator]: () => {
const nodeMap = graph.nodes;
const adjacencyMap = direction === "incoming" ? graph.reverseAdjacency : graph.adjacency;
const nodeIterator = nodeMap.entries();
const nextMapped = () => {
let current = nodeIterator.next();
while (!current.done) {
const [nodeIndex, nodeData] = current.value;
const adjacencyList = adjacencyMap.get(nodeIndex);
// Node is external if it has no edges in the specified direction
if (adjacencyList === undefined || adjacencyList.length === 0) {
return {
done: false,
value: f(nodeIndex, nodeData)
};
}
current = nodeIterator.next();
}
return {
done: true,
value: undefined
};
};
return {
next: nextMapped
};
}
}));
};
//# sourceMappingURL=Graph.js.map