feat: add utility functions to retrieve node references

findNodes, getNode, getFirstNode

Author: JesusTheHun

src/utils/findNodes.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest';
+import { Graph } from '../Graph.js';
+import { findNodes } from './findNodes.js';
+import { getFirstNode } from './getFirstNode.js';
+import { getNode } from './getNode.js';
+
+describe('findNodes', () => {
+  type Node = { id: string; type: string };
+
+  it('should retrieve a node successfully when it exists in the graph', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(findNodes(graph, (n) => n.id === '1')).toEqual([node1]);
+    expect(findNodes(graph, (n) => n.id === '2')).toEqual([node2]);
+  });
+
+  it('should return an empty array when no matching node is found', ({ expect }) => {
+    const graph = new Graph<Node>();
+    expect(findNodes(graph, (n) => n.id === 'nope')).toEqual([]);
+  });
+
+  it('should return all the nodes matching', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(findNodes(graph, (n) => n.type === 'foo')).toEqual([node1, node2]);
+  });
+});

src/utils/findNodes.ts

@@ -0,0 +1,20 @@
+import { Graph } from '../Graph.js';
+import { NoInfer } from '../types.js';
+
+/**
+ * Returns all the nodes matching your function.
+ */
+export function findNodes<Node>(
+  graph: Graph<Node>,
+  fn: (node: NoInfer<Node>) => boolean,
+): Node[] {
+  const nodes: Node[] = [];
+
+  graph.nodes.forEach((node) => {
+    if (fn(node)) {
+      nodes.push(node);
+    }
+  });
+
+  return nodes;
+}

src/utils/getFirstNode.spec.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { Graph } from '../Graph.js';
+import { getFirstNode } from './getFirstNode.js';
+import { getNode } from './getNode.js';
+
+describe('getFirstNode', () => {
+  type Node = { id: string; type: string };
+
+  it('should retrieve a node successfully when it exists in the graph', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(getFirstNode(graph, (n) => n.id === '1')).toEqual(node1);
+    expect(getFirstNode(graph, (n) => n.id === '2')).toEqual(node2);
+  });
+
+  it('should throw when the node is not found', ({ expect }) => {
+    const graph = new Graph<Node>();
+    expect(() => getFirstNode(graph, (n) => n.id === 'nope')).toThrowError();
+  });
+
+  it('should not throw when more than one node is found', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(getFirstNode(graph, (n) => n.type === 'foo')).toEqual(node1);
+  });
+});

src/utils/getFirstNode.ts

@@ -0,0 +1,18 @@
+import { Graph } from '../Graph.js';
+import { NoInfer } from '../types.js';
+
+/**
+ * Return the first node matching your function and throws if none is found.
+ */
+export function getFirstNode<Node>(
+  graph: Graph<Node>,
+  fn: (node: NoInfer<Node>) => boolean,
+): Node {
+  for (const node of graph.nodes) {
+    if (fn(node)) {
+      return node;
+    }
+  }
+
+  throw new Error('Node not found.');
+}

src/utils/getNode.spec.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { Graph } from '../Graph.js';
+import { getNode } from './getNode.js';
+
+describe('getNode', () => {
+  type Node = { id: string; type: string };
+
+  it('should retrieve a node successfully when it exists in the graph', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(getNode(graph, (n) => n.id === '1')).toEqual(node1);
+    expect(getNode(graph, (n) => n.id === '2')).toEqual(node2);
+  });
+
+  it('should throw when the node is not found', ({ expect }) => {
+    const graph = new Graph<Node>();
+    expect(() => getNode(graph, (n) => n.id === 'nope')).toThrowError();
+  });
+
+  it('should throw when more than one node is found', ({ expect }) => {
+    const graph = new Graph<Node>();
+    const node1 = { id: '1', type: 'foo' };
+    const node2 = { id: '2', type: 'foo' };
+
+    graph.addNode(node1);
+    graph.addNode(node2);
+
+    expect(() => getNode(graph, (n) => n.type === 'foo')).toThrowError();
+  });
+});

src/utils/getNode.ts

@@ -0,0 +1,28 @@
+import { Graph } from '../Graph.js';
+import { NoInfer } from '../types.js';
+
+/**
+ * Return the node matching your function. Throws if none is found or if more than one node if found.
+ */
+export function getNode<Node>(
+  graph: Graph<Node>,
+  fn: (node: NoInfer<Node>) => boolean,
+): Node {
+  const foundNodes: Node[] = [];
+
+  for (const node of graph.nodes) {
+    if (fn(node)) {
+      foundNodes.push(node);
+    }
+  }
+
+  if (foundNodes.length === 0) {
+    throw new Error('Node not found.');
+  }
+
+  if (foundNodes.length > 1) {
+    throw new Error('More than one node found.');
+  }
+
+  return foundNodes[0];
+}