@monstermann/graph 0.0.0 → 0.2.0

package/dist/Graph/batch.d.mts

@@ -0,0 +1,47 @@
+import { Edges, Graph, Node } from "./types.mjs";
+
+//#region src/Graph/batch.d.ts
+/**
+ * # batch
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string }
+ *     | { type: "Section"; id: string; name: string }
+ *     | { type: "Project"; id: string; name: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ *
+ * // Add multiple nodes and edges in a single batch
+ * const updated = 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"]);
+ *     return g;
+ * });
+ * ```
+ *
+ */
+declare function batch<N extends Node, E extends Edges<N>>(prevGraph: Graph<N, E>, transform: (graph: Graph<N, E>) => Graph<N, E> | void): Graph<N, E>;
+//#endregion
+export { batch };

package/dist/Graph/batch.mjs

@@ -0,0 +1,57 @@
+//#region src/Graph/batch.ts
+/**
+* # batch
+*
+* ```ts
+* function Graph.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
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string; title: string }
+*     | { type: "Section"; id: string; name: string }
+*     | { type: "Project"; id: string; name: string };
+*
+* type Edges = {
+*     Project: { Task: void };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+*
+* // Add multiple nodes and edges in a single batch
+* const updated = 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"]);
+*     return g;
+* });
+* ```
+*
+*/
+function batch(prevGraph, transform) {
+	if (prevGraph.has("clones")) return transform(prevGraph) ?? prevGraph;
+	const clone = new Map(prevGraph);
+	clone.set("clones", new Set([clone]));
+	const nextGraph = transform(clone) ?? clone;
+	if (isEqual(prevGraph, nextGraph)) return prevGraph;
+	nextGraph.delete("clones");
+	return nextGraph;
+}
+function isEqual(before, after) {
+	return before.get("nodes") === after.get("nodes") && before.get("edges") === after.get("edges");
+}
+
+//#endregion
+export { batch };

package/dist/Graph/create.d.mts

@@ -0,0 +1,36 @@
+import { Edges, Graph, Node, NodeType } from "./types.mjs";
+
+//#region src/Graph/create.d.ts
+/**
+ * # create
+ *
+ * ```ts
+ * function Graph.create<Nodes, Edges>(): Graph<Nodes, Edges>
+ * ```
+ *
+ * Creates a new empty graph with the provided nodes & edges configuration.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     // Project <-> Task
+ *     Project: { Task: void };
+ *     // Section <-> Task
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * ```
+ *
+ */
+declare function create<N extends Node, E extends Edges<N> = Record<NodeType<N>, Record<NodeType<N>, void>>>(): Graph<N, E>;
+//#endregion
+export { create };

package/dist/Graph/create.mjs

@@ -0,0 +1,37 @@
+//#region src/Graph/create.ts
+/**
+* # create
+*
+* ```ts
+* function Graph.create<Nodes, Edges>(): Graph<Nodes, Edges>
+* ```
+*
+* Creates a new empty graph with the provided nodes & edges configuration.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     // Project <-> Task
+*     Project: { Task: void };
+*     // Section <-> Task
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+* ```
+*
+*/
+function create() {
+	return /* @__PURE__ */ new Map();
+}
+
+//#endregion
+export { create };

package/dist/Graph/findEdge.d.mts

@@ -0,0 +1,60 @@
+import { Bimap } from "./internals/types.mjs";
+import { Edges, Graph, Node, NodeIdentifier, NodeType } from "./types.mjs";
+
+//#region src/Graph/findEdge.d.ts
+/**
+ * # findEdge
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: { priority: number; assignedAt: Date } };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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: new Date(),
+ * });
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "2"], {
+ *     priority: 2,
+ *     assignedAt: new Date(),
+ * });
+ *
+ * const highPriorityEdge = Graph.findEdge(
+ *     g,
+ *     ["Project", "1"],
+ *     "Task",
+ *     (edge) => edge.priority > 1,
+ * );
+ * // highPriorityEdge: { priority: 2, assignedAt: Date }
+ * ```
+ *
+ */
+declare function findEdge<N extends Node, E extends Edges<N>, N1 extends keyof Bimap<E> & NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>, E2 extends Bimap<E>[N1][N2]>(graph: Graph<N, E>, source: NodeIdentifier<N, N1>, type: N2, find: (edge: NoInfer<Bimap<E>[N1][N2]>) => edge is E2): E2 | undefined;
+declare function findEdge<N extends Node, E extends Edges<N>, N1 extends keyof Bimap<E> & NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>>(graph: Graph<N, E>, source: NodeIdentifier<N, N1>, type: N2, find: (edge: NoInfer<Bimap<E>[N1][N2]>) => boolean): Bimap<E>[N1][N2] | undefined;
+//#endregion
+export { findEdge };

package/dist/Graph/findEdge.mjs

@@ -0,0 +1,10 @@
+import { parseNodeIdentifier } from "./internals/parseNodeIdentifier.mjs";
+
+//#region src/Graph/findEdge.ts
+function findEdge(graph, source, type, find) {
+	const [sourceType, sourceId] = parseNodeIdentifier(source);
+	for (const edge of graph.get("edges")?.get(sourceType)?.get(sourceId)?.get(type)?.values() ?? []) if (find(edge)) return edge;
+}
+
+//#endregion
+export { findEdge };

package/dist/Graph/findEdges.d.mts

@@ -0,0 +1,65 @@
+import { Bimap } from "./internals/types.mjs";
+import { Edges, Graph, Node, NodeIdentifier, NodeType } from "./types.mjs";
+
+//#region src/Graph/findEdges.d.ts
+/**
+ * # findEdges
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: { priority: number; assignedAt: Date } };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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: new Date(),
+ * });
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "2"], {
+ *     priority: 2,
+ *     assignedAt: new Date(),
+ * });
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "3"], {
+ *     priority: 3,
+ *     assignedAt: new Date(),
+ * });
+ *
+ * const highPriorityEdges = Graph.findEdges(
+ *     g,
+ *     ["Project", "1"],
+ *     "Task",
+ *     (edge) => edge.priority >= 2,
+ * );
+ * // highPriorityEdges: [{ priority: 2, ... }, { priority: 3, ... }]
+ * ```
+ *
+ */
+declare function findEdges<N extends Node, E extends Edges<N>, N1 extends keyof Bimap<E> & NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>, E2 extends Bimap<E>[N1][N2]>(graph: Graph<N, E>, source: NodeIdentifier<N, N1>, type: N2, find: (edge: NoInfer<Bimap<E>[N1][N2]>) => edge is E2): E2[];
+declare function findEdges<N extends Node, E extends Edges<N>, N1 extends keyof Bimap<E> & NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>>(graph: Graph<N, E>, source: NodeIdentifier<N, N1>, type: N2, find: (edge: NoInfer<Bimap<E>[N1][N2]>) => boolean): Bimap<E>[N1][N2][];
+//#endregion
+export { findEdges };

package/dist/Graph/findEdges.mjs

@@ -0,0 +1,12 @@
+import { parseNodeIdentifier } from "./internals/parseNodeIdentifier.mjs";
+
+//#region src/Graph/findEdges.ts
+function findEdges(graph, source, type, find) {
+	const result = [];
+	const [sourceType, sourceId] = parseNodeIdentifier(source);
+	for (const edge of graph.get("edges")?.get(sourceType)?.get(sourceId)?.get(type)?.values() ?? []) if (find(edge)) result.push(edge);
+	return result;
+}
+
+//#endregion
+export { findEdges };

package/dist/Graph/findNeighbor.d.mts

@@ -0,0 +1,54 @@
+import { Bimap } from "./internals/types.mjs";
+import { Edges, Graph, Node, NodeIdentifier, NodeOfType, NodeType } from "./types.mjs";
+
+//#region src/Graph/findNeighbor.d.ts
+/**
+ * # findNeighbor
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: { priority: number } };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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 });
+ *
+ * const highPriorityTask = Graph.findNeighbor(
+ *     g,
+ *     ["Project", "1"],
+ *     "Task",
+ *     (task, edge, project) => edge.priority > 2,
+ * );
+ * // highPriorityTask: { type: "Task", id: "2", title: "High Priority Task" }
+ * ```
+ *
+ */
+declare function findNeighbor<N extends Node, E extends Edges<N>, N1 extends NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>, N3 extends NodeOfType<N, N2>>(graph: Graph<N, E>, node: NodeIdentifier<N, N1>, type: N2, find: (target: NoInfer<NodeOfType<N, N2>>, edge: NoInfer<Bimap<E>[N1][N2]>, source: NoInfer<NodeOfType<N, N1>>) => target is N3): N3 | undefined;
+declare function findNeighbor<N extends Node, E extends Edges<N>, N1 extends NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>>(graph: Graph<N, E>, node: NodeIdentifier<N, N1>, type: N2, find: (target: NoInfer<NodeOfType<N, N2>>, edge: NoInfer<Bimap<E>[N1][N2]>, source: NoInfer<NodeOfType<N, N1>>) => boolean): NodeOfType<N, N2> | undefined;
+//#endregion
+export { findNeighbor };

package/dist/Graph/findNeighbor.mjs

@@ -0,0 +1,16 @@
+import { getNode } from "./getNode.mjs";
+
+//#region src/Graph/findNeighbor.ts
+function findNeighbor(graph, node, type, find) {
+	const sourceNode = getNode(graph, node);
+	if (!sourceNode) return void 0;
+	const nodeMap = graph.get("nodes")?.get(type);
+	if (!nodeMap) return void 0;
+	for (const [targetId, edge] of graph.get("edges")?.get(sourceNode.type)?.get(sourceNode.id)?.get(type) ?? []) {
+		const targetNode = nodeMap.get(targetId);
+		if (find(targetNode, edge, sourceNode)) return targetNode;
+	}
+}
+
+//#endregion
+export { findNeighbor };

package/dist/Graph/findNeighbors.d.mts

@@ -0,0 +1,59 @@
+import { Bimap } from "./internals/types.mjs";
+import { Edges, Graph, Node, NodeIdentifier, NodeOfType, NodeType } from "./types.mjs";
+
+//#region src/Graph/findNeighbors.d.ts
+/**
+ * # findNeighbors
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: { priority: number } };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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 });
+ *
+ * const mediumAndHighPriority = 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" }
+ * // ]
+ * ```
+ *
+ */
+declare function findNeighbors<N extends Node, E extends Edges<N>, N1 extends NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>, N3 extends NodeOfType<N, N2>>(graph: Graph<N, E>, node: NodeIdentifier<N, N1>, type: N2, find: (target: NoInfer<NodeOfType<N, N2>>, edge: NoInfer<Bimap<E>[N1][N2]>, source: NoInfer<NodeOfType<N, N1>>) => target is N3): N3[];
+declare function findNeighbors<N extends Node, E extends Edges<N>, N1 extends NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>>(graph: Graph<N, E>, node: NodeIdentifier<N, N1>, type: N2, find: (target: NoInfer<NodeOfType<N, N2>>, edge: NoInfer<Bimap<E>[N1][N2]>, source: NoInfer<NodeOfType<N, N1>>) => boolean): NodeOfType<N, N2>[];
+//#endregion
+export { findNeighbors };

package/dist/Graph/findNeighbors.mjs

@@ -0,0 +1,18 @@
+import { getNode } from "./getNode.mjs";
+
+//#region src/Graph/findNeighbors.ts
+function findNeighbors(graph, node, type, find) {
+	const result = [];
+	const sourceNode = getNode(graph, node);
+	if (!sourceNode) return result;
+	const nodeMap = graph.get("nodes")?.get(type);
+	if (!nodeMap) return result;
+	for (const [targetId, edge] of graph.get("edges")?.get(sourceNode.type)?.get(sourceNode.id)?.get(type) ?? []) {
+		const targetNode = nodeMap.get(targetId);
+		if (find(targetNode, edge, sourceNode)) result.push(targetNode);
+	}
+	return result;
+}
+
+//#endregion
+export { findNeighbors };

package/dist/Graph/findNode.d.mts

@@ -0,0 +1,67 @@
+import { Edges, Graph, Node, NodeOfType, NodeType } from "./types.mjs";
+
+//#region src/Graph/findNode.d.ts
+/**
+ * # findNode
+ *
+ * ```ts
+ * function Graph.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
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string; completed: boolean }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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,
+ * });
+ *
+ * const completedTask = Graph.findNode(g, "Task", (task) => task.completed);
+ * // completedTask: { type: "Task", id: "2", title: "Second Task", completed: true }
+ *
+ * const taskWithTitle = Graph.findNode(
+ *     g,
+ *     "Task",
+ *     (task) => task.title === "First Task",
+ * );
+ * // taskWithTitle: { type: "Task", id: "1", title: "First Task", completed: false }
+ * ```
+ *
+ */
+declare function findNode<N extends Node, E extends Edges<N>, U extends NodeType<N>, V extends NodeOfType<N, U>>(graph: Graph<N, E>, type: U, find: (node: NoInfer<NodeOfType<N, U>>) => node is V): V | undefined;
+declare function findNode<N extends Node, E extends Edges<N>, U extends NodeType<N>>(graph: Graph<N, E>, type: U, find: (node: NoInfer<NodeOfType<N, U>>) => boolean): NodeOfType<N, U> | undefined;
+//#endregion
+export { findNode };

package/dist/Graph/findNode.mjs

@@ -0,0 +1,7 @@
+//#region src/Graph/findNode.ts
+function findNode(graph, type, find) {
+	for (const node of graph.get("nodes")?.get(type)?.values() ?? []) if (find(node)) return node;
+}
+
+//#endregion
+export { findNode };

package/dist/Graph/findNodes.d.mts

@@ -0,0 +1,63 @@
+import { Edges, Graph, Node, NodeOfType, NodeType } from "./types.mjs";
+
+//#region src/Graph/findNodes.d.ts
+/**
+ * # findNodes
+ *
+ * ```ts
+ * function Graph.findNodes(
+ *     graph: Graph,
+ *     type: NodeType,
+ *     find: (node: Node) => boolean,
+ * ): Node[]
+ * ```
+ *
+ * Finds all nodes of a specific type that match the predicate.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string; completed: boolean }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = 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,
+ * });
+ *
+ * const incompleteTasks = 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 }
+ * // ]
+ * ```
+ *
+ */
+declare function findNodes<N extends Node, E extends Edges<N>, U extends NodeType<N>, V extends NodeOfType<N, U>>(graph: Graph<N, E>, type: U, find: (node: NoInfer<NodeOfType<N, U>>) => node is V): V[];
+declare function findNodes<N extends Node, E extends Edges<N>, U extends NodeType<N>>(graph: Graph<N, E>, type: U, find: (node: NoInfer<NodeOfType<N, U>>) => boolean): NodeOfType<N, U>[];
+//#endregion
+export { findNodes };

package/dist/Graph/findNodes.mjs

@@ -0,0 +1,9 @@
+//#region src/Graph/findNodes.ts
+function findNodes(graph, type, find) {
+	const result = [];
+	for (const node of graph.get("nodes")?.get(type)?.values() ?? []) if (find(node)) result.push(node);
+	return result;
+}
+
+//#endregion
+export { findNodes };