max-heap-typed 2.2.2 → 2.2.4

package/src/data-structures/binary-tree/red-black-tree.ts

@@ -8,7 +8,6 @@
 
 import type {
   BinaryTreeDeleteResult,
-  BinaryTreeOptions,
   CRUD,
   EntryCallback,
   FamilyPosition,
@@ -188,48 +187,97 @@ export class RedBlackTreeNode<K = any, V = any> {
  * 2. It is BST itself. Compared with Heap which is not completely ordered, RedBlackTree is completely ordered.
  *
  * @example
- * // using Red-Black Tree as a price-based index for stock data
- *     // Define the structure of individual stock records
- *     interface StockRecord {
- *       price: number; // Stock price (key for indexing)
- *       symbol: string; // Stock ticker symbol
- *       volume: number; // Trade volume
+ * // basic Red-Black Tree with simple number keys
+ *  // Create a simple Red-Black Tree with numeric keys
+ *     const tree = new RedBlackTree([5, 2, 8, 1, 9]);
+ *
+ *     tree.print();
+ *     //   _2___
+ *     //  /     \
+ *     //  1    _8_
+ *     //      /   \
+ *     //      5   9
+ *
+ *     // Verify the tree maintains sorted order
+ *     console.log([...tree.keys()]); // [1, 2, 5, 8, 9];
+ *
+ *     // Check size
+ *     console.log(tree.size); // 5;
+ * @example
+ * // Red-Black Tree with key-value pairs for lookups
+ *  interface Employee {
+ *       id: number;
+ *       name: string;
  *     }
  *
- *     // Simulate stock market data as it might come from an external feed
- *     const marketStockData: StockRecord[] = [
- *       { price: 142.5, symbol: 'AAPL', volume: 1000000 },
- *       { price: 335.2, symbol: 'MSFT', volume: 800000 },
- *       { price: 3285.04, symbol: 'AMZN', volume: 500000 },
- *       { price: 267.98, symbol: 'META', volume: 750000 },
- *       { price: 234.57, symbol: 'GOOGL', volume: 900000 }
- *     ];
+ *     // Create tree with employee data
+ *     const employees = new RedBlackTree<number, Employee>([
+ *       [1, { id: 1, name: 'Alice' }],
+ *       [3, { id: 3, name: 'Charlie' }],
+ *       [2, { id: 2, name: 'Bob' }]
+ *     ]);
+ *
+ *     // Retrieve employee by ID
+ *     const alice = employees.get(1);
+ *     console.log(alice?.name); // 'Alice';
+ *
+ *     // Verify sorted order by ID
+ *     console.log([...employees.keys()]); // [1, 2, 3];
+ * @example
+ * // Red-Black Tree range search for filtering
+ *  interface Product {
+ *       name: string;
+ *       price: number;
+ *     }
  *
- *     // Extend the stock record type to include metadata for database usage
- *     type StockTableRecord = StockRecord & { lastUpdated: Date };
+ *     const products = new RedBlackTree<number, Product>([
+ *       [10, { name: 'Item A', price: 10 }],
+ *       [25, { name: 'Item B', price: 25 }],
+ *       [40, { name: 'Item C', price: 40 }],
+ *       [50, { name: 'Item D', price: 50 }]
+ *     ]);
  *
- *     // Create a Red-Black Tree to index stock records by price
- *     // Simulates a database index with stock price as the key for quick lookups
- *     const priceIndex = new RedBlackTree<number, StockTableRecord, StockRecord>(marketStockData, {
- *       toEntryFn: stockRecord => [
- *         stockRecord.price, // Use stock price as the key
- *         {
- *           ...stockRecord,
- *           lastUpdated: new Date() // Add a timestamp for when the record was indexed
- *         }
- *       ]
+ *     // Find products in price range [20, 45]
+ *     const pricesInRange = products.rangeSearch([20, 45], node => {
+ *       return products.get(node)?.name;
  *     });
  *
- *     // Query the stock with the highest price
- *     const highestPricedStock = priceIndex.getRightMost();
- *     console.log(priceIndex.get(highestPricedStock)?.symbol); // 'AMZN' // Amazon has the highest price
+ *     console.log(pricesInRange); // ['Item B', 'Item C'];
+ * @example
+ * // Red-Black Tree as database index for stock market data
+ *  interface StockPrice {
+ *       symbol: string;
+ *       volume: number;
+ *       timestamp: Date;
+ *     }
+ *
+ *     // Simulate real-time stock price index
+ *     const priceIndex = new RedBlackTree<number, StockPrice>([
+ *       [142.5, { symbol: 'AAPL', volume: 1000000, timestamp: new Date() }],
+ *       [335.2, { symbol: 'MSFT', volume: 800000, timestamp: new Date() }],
+ *       [3285.04, { symbol: 'AMZN', volume: 500000, timestamp: new Date() }],
+ *       [267.98, { symbol: 'META', volume: 750000, timestamp: new Date() }],
+ *       [234.57, { symbol: 'GOOGL', volume: 900000, timestamp: new Date() }]
+ *     ]);
+ *
+ *     // Find highest-priced stock
+ *     const maxPrice = priceIndex.getRightMost();
+ *     console.log(priceIndex.get(maxPrice)?.symbol); // 'AMZN';
+ *
+ *     // Find stocks in price range [200, 400] for portfolio balancing
+ *     const stocksInRange = priceIndex.rangeSearch([200, 400], node => {
+ *       const stock = priceIndex.get(node);
+ *       return {
+ *         symbol: stock?.symbol,
+ *         price: node,
+ *         volume: stock?.volume
+ *       };
+ *     });
  *
- *     // Query stocks within a specific price range (200 to 400)
- *     const stocksInRange = priceIndex.rangeSearch(
- *       [200, 400], // Price range
- *       node => priceIndex.get(node)?.symbol // Extract stock symbols for the result
- *     );
- *     console.log(stocksInRange); // ['GOOGL', 'META', 'MSFT']
+ *     console.log(stocksInRange.length); // 3;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'GOOGL')); // true;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'META')); // true;
+ *     console.log(stocksInRange.some((s: any) => s.symbol === 'MSFT')); // true;
  */
 
 export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implements IBinaryTree<K, V, R> {
@@ -414,7 +462,7 @@ export class RedBlackTree<K = any, V = any, R = any> extends BST<K, V, R> implem
 
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
-    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): RedBlackTree<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);

package/src/data-structures/binary-tree/tree-counter.ts

@@ -8,7 +8,6 @@
 
 import type {
   BinaryTreeDeleteResult,
-  BinaryTreeOptions,
   BSTNOptKeyOrNode,
   EntryCallback,
   FamilyPosition,
@@ -17,7 +16,6 @@ import type {
   RBTNColor,
   TreeCounterOptions
 } from '../../types';
-import { BSTOptions } from '../../types';
 import { BSTNode } from './bst';
 import { IBinaryTree } from '../../interfaces';
 import { RedBlackTree } from './red-black-tree';
@@ -432,7 +430,7 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
    */
   override map<MK = K, MV = V, MR = any>(
     callback: EntryCallback<K, V | undefined, [MK, MV]>,
-    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    options?: Partial<TreeCounterOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): TreeCounter<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
@@ -465,10 +463,10 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
    * @param [options] - Optional constructor options for the like-kind instance.
    * @returns An empty like-kind instance.
    */
-  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<BSTOptions<TK, TV, TR>>): this {
+  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<TreeCounterOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: BSTOptions<TK, TV, TR>
+      opts?: TreeCounterOptions<TK, TV, TR>
     ) => this;
     return new Ctor([], { ...this._snapshotOptions<TK, TV, TR>(), ...(options ?? {}) }) as unknown as this;
   }
@@ -485,11 +483,11 @@ export class TreeCounter<K = any, V = any, R = any> extends RedBlackTree<K, V, R
    */
   protected override _createLike<TK = K, TV = V, TR = R>(
     iter: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR> = [],
-    options?: Partial<BSTOptions<TK, TV, TR>>
+    options?: Partial<TreeCounterOptions<TK, TV, TR>>
   ): TreeCounter<TK, TV, TR> {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | BSTNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: BSTOptions<TK, TV, TR>
+      opts?: TreeCounterOptions<TK, TV, TR>
     ) => TreeCounter<TK, TV, TR>;
     return new Ctor(iter as unknown as Iterable<TK | any>, {
       ...this._snapshotOptions<TK, TV, TR>(),

package/src/data-structures/binary-tree/tree-multi-map.ts

@@ -12,7 +12,6 @@ import type {
   EntryCallback,
   FamilyPosition,
   RBTNColor,
-  RedBlackTreeOptions,
   TreeMultiMapOptions
 } from '../../types';
 import { RedBlackTree, RedBlackTreeNode } from './red-black-tree';
@@ -186,7 +185,7 @@ export class TreeMultiMapNode<K = any, V = any> {
  *
  * @example
  * // players ranked by score with their equipment
- *     type Equipment = {
+ *  type Equipment = {
  *       name: string; // Equipment name
  *       quality: 'legendary' | 'epic' | 'rare' | 'common';
  *       level: number;
@@ -347,7 +346,7 @@ export class TreeMultiMapNode<K = any, V = any> {
  *  //        },
  *  //        { name: 'Level 3 Backpack', quality: 'epic', level: 80 }
  *  //      ]
- *  //    ]
+ *  //    ];
  */
 export class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[], R> implements IBinaryTree<K, V[], R> {
   /**
@@ -476,13 +475,13 @@ export class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[]
 
   override map<MK = K, MVArr extends unknown[] = V[], MR = any>(
     callback: EntryCallback<K, V[] | undefined, [MK, MVArr]>,
-    options?: Partial<RedBlackTreeOptions<MK, MVArr, MR>>,
+    options?: Partial<TreeMultiMapOptions<MK, MVArr, MR>>,
     thisArg?: unknown
   ): TreeMultiMap<MK, ElemOf<MVArr>, MR>;
 
   override map<MK = K, MV = V[], MR = any>(
     callback: EntryCallback<K, V[] | undefined, [MK, MV]>,
-    options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
+    options?: Partial<TreeMultiMapOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): RedBlackTree<MK, MV, MR>;
 
@@ -499,7 +498,7 @@ export class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[]
    */
   override map<MK, MV, MR extends object>(
     callback: EntryCallback<K, V[] | undefined, [MK, MV]>,
-    options?: Partial<RedBlackTreeOptions<MK, MV, MR>>,
+    options?: Partial<TreeMultiMapOptions<MK, MV, MR>>,
     thisArg?: unknown
   ): RedBlackTree<MK, MV, MR> {
     const out = this._createLike<MK, MV, MR>([], options);
@@ -517,10 +516,10 @@ export class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[]
    * @param [options] - Optional constructor options for the like-kind instance.
    * @returns An empty like-kind instance.
    */
-  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<RedBlackTreeOptions<TK, TV, TR>>): this {
+  protected override _createInstance<TK = K, TV = V, TR = R>(options?: Partial<TreeMultiMapOptions<TK, TV, TR>>): this {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: RedBlackTreeOptions<TK, TV, TR>
+      opts?: TreeMultiMapOptions<TK, TV, TR>
     ) => RedBlackTree<TK, TV, TR>;
     return new Ctor([], { ...(this._snapshotOptions?.<TK, TV, TR>() ?? {}), ...(options ?? {}) }) as unknown as this;
   }
@@ -539,11 +538,11 @@ export class TreeMultiMap<K = any, V = any, R = any> extends RedBlackTree<K, V[]
     iter: Iterable<
       TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR
     > = [],
-    options?: Partial<RedBlackTreeOptions<TK, TV, TR>>
+    options?: Partial<TreeMultiMapOptions<TK, TV, TR>>
   ): RedBlackTree<TK, TV, TR> {
     const Ctor = this.constructor as unknown as new (
       iter?: Iterable<TK | RedBlackTreeNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>,
-      opts?: RedBlackTreeOptions<TK, TV, TR>
+      opts?: TreeMultiMapOptions<TK, TV, TR>
     ) => RedBlackTree<TK, TV, TR>;
     return new Ctor(iter, { ...(this._snapshotOptions?.<TK, TV, TR>() ?? {}), ...(options ?? {}) });
   }

package/src/data-structures/graph/directed-graph.ts

@@ -35,7 +35,132 @@ export class DirectedEdge<E = any> extends AbstractEdge<E> {
  * @template VO - Concrete vertex class (extends AbstractVertex<V>).
  * @template EO - Concrete edge class (extends AbstractEdge<E>).
  * @remarks Time O(1), Space O(1)
- * @example examples will be generated by unit test
+ * @example
+ * // basic DirectedGraph vertex and edge creation
+ *  // Create a simple directed graph
+ *     const graph = new DirectedGraph<string>();
+ *
+ *     // Add vertices
+ *     graph.addVertex('A');
+ *     graph.addVertex('B');
+ *     graph.addVertex('C');
+ *
+ *     // Verify vertices exist
+ *     console.log(graph.hasVertex('A')); // true;
+ *     console.log(graph.hasVertex('B')); // true;
+ *     console.log(graph.hasVertex('C')); // true;
+ *     console.log(graph.hasVertex('D')); // false;
+ *
+ *     // Check vertex count
+ *     console.log(graph.size); // 3;
+ * @example
+ * // DirectedGraph edge operations
+ *  const graph = new DirectedGraph<string>();
+ *
+ *     // Add vertices
+ *     graph.addVertex('A');
+ *     graph.addVertex('B');
+ *     graph.addVertex('C');
+ *
+ *     // Add directed edges
+ *     graph.addEdge('A', 'B', 1);
+ *     graph.addEdge('B', 'C', 2);
+ *     graph.addEdge('A', 'C', 3);
+ *
+ *     // Verify edges exist
+ *     console.log(graph.hasEdge('A', 'B')); // true;
+ *     console.log(graph.hasEdge('B', 'C')); // true;
+ *     console.log(graph.hasEdge('C', 'B')); // false; // Graph is directed
+ *
+ *     // Get neighbors of A
+ *     const neighborsA = graph.getNeighbors('A');
+ *     console.log(neighborsA[0].key); // 'B';
+ *     console.log(neighborsA[1].key); // 'C';
+ * @example
+ * // DirectedGraph deleteEdge and vertex operations
+ *  const graph = new DirectedGraph<string>();
+ *
+ *     // Build a small graph
+ *     graph.addVertex('X');
+ *     graph.addVertex('Y');
+ *     graph.addVertex('Z');
+ *     graph.addEdge('X', 'Y', 1);
+ *     graph.addEdge('Y', 'Z', 2);
+ *
+ *     // Delete an edge
+ *     graph.deleteEdgeSrcToDest('X', 'Y');
+ *     console.log(graph.hasEdge('X', 'Y')); // false;
+ *
+ *     // Edge in other direction should not exist
+ *     console.log(graph.hasEdge('Y', 'X')); // false;
+ *
+ *     // Other edges should remain
+ *     console.log(graph.hasEdge('Y', 'Z')); // true;
+ *
+ *     // Delete a vertex
+ *     graph.deleteVertex('Y');
+ *     console.log(graph.hasVertex('Y')); // false;
+ *     console.log(graph.size); // 2;
+ * @example
+ * // DirectedGraph topologicalSort for task scheduling
+ *  const graph = new DirectedGraph<string>();
+ *
+ *     // Build a DAG (Directed Acyclic Graph) for task dependencies
+ *     graph.addVertex('Design');
+ *     graph.addVertex('Implement');
+ *     graph.addVertex('Test');
+ *     graph.addVertex('Deploy');
+ *
+ *     // Add dependency edges
+ *     graph.addEdge('Design', 'Implement', 1); // Design must come before Implement
+ *     graph.addEdge('Implement', 'Test', 1); // Implement must come before Test
+ *     graph.addEdge('Test', 'Deploy', 1); // Test must come before Deploy
+ *
+ *     // Topological sort gives valid execution order
+ *     const executionOrder = graph.topologicalSort();
+ *     console.log(executionOrder); // defined;
+ *     console.log(executionOrder); // ['Design', 'Implement', 'Test', 'Deploy'];
+ *
+ *     // All vertices should be included
+ *     console.log(executionOrder?.length); // 4;
+ * @example
+ * // DirectedGraph dijkstra shortest path for network routing
+ *  // Build a weighted directed graph representing network nodes and costs
+ *     const network = new DirectedGraph<string>();
+ *
+ *     // Add network nodes
+ *     network.addVertex('Router-A');
+ *     network.addVertex('Router-B');
+ *     network.addVertex('Router-C');
+ *     network.addVertex('Router-D');
+ *     network.addVertex('Router-E');
+ *
+ *     // Add weighted edges (network latency costs)
+ *     network.addEdge('Router-A', 'Router-B', 5);
+ *     network.addEdge('Router-A', 'Router-C', 10);
+ *     network.addEdge('Router-B', 'Router-D', 3);
+ *     network.addEdge('Router-C', 'Router-D', 2);
+ *     network.addEdge('Router-D', 'Router-E', 4);
+ *     network.addEdge('Router-B', 'Router-E', 12);
+ *
+ *     // Find shortest path from Router-A to Router-E
+ *     const { minDist, minPath } = network.dijkstra('Router-A', 'Router-E', true, true) || {
+ *       minDist: undefined,
+ *       minPath: undefined
+ *     };
+ *
+ *     // Verify shortest path is found
+ *     console.log(minDist); // defined;
+ *     console.log(minPath); // defined;
+ *
+ *     // Shortest path should be A -> B -> D -> E with cost 5+3+4=12
+ *     // Or A -> C -> D -> E with cost 10+2+4=16
+ *     // So the minimum is 12
+ *     console.log(minDist); // <= 16;
+ *
+ *     // Verify path is valid (includes start and end)
+ *     console.log(minPath?.[0].key); // 'Router-A';
+ *     console.log(minPath?.[minPath.length - 1].key); // 'Router-E';
  */
 export class DirectedGraph<
   V = any,

package/src/data-structures/graph/undirected-graph.ts

@@ -33,7 +33,166 @@ export class UndirectedEdge<E = number> extends AbstractEdge<E> {
  * @template VO - Concrete vertex class (extends AbstractVertex<V>).
  * @template EO - Concrete edge class (extends AbstractEdge<E>).
  * @remarks Time O(1), Space O(1)
- * @example examples will be generated by unit test
+ * @example
+ * // basic UndirectedGraph vertex and edge creation
+ *  // Create a simple undirected graph
+ *     const graph = new UndirectedGraph<string>();
+ *
+ *     // Add vertices
+ *     graph.addVertex('A');
+ *     graph.addVertex('B');
+ *     graph.addVertex('C');
+ *     graph.addVertex('D');
+ *
+ *     // Verify vertices exist
+ *     console.log(graph.hasVertex('A')); // true;
+ *     console.log(graph.hasVertex('B')); // true;
+ *     console.log(graph.hasVertex('E')); // false;
+ *
+ *     // Check vertex count
+ *     console.log(graph.size); // 4;
+ * @example
+ * // UndirectedGraph edge operations (bidirectional)
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Add vertices
+ *     graph.addVertex('A');
+ *     graph.addVertex('B');
+ *     graph.addVertex('C');
+ *
+ *     // Add undirected edges (both directions automatically)
+ *     graph.addEdge('A', 'B', 1);
+ *     graph.addEdge('B', 'C', 2);
+ *     graph.addEdge('A', 'C', 3);
+ *
+ *     // Verify edges exist in both directions
+ *     console.log(graph.hasEdge('A', 'B')); // true;
+ *     console.log(graph.hasEdge('B', 'A')); // true; // Bidirectional!
+ *
+ *     console.log(graph.hasEdge('C', 'B')); // true;
+ *     console.log(graph.hasEdge('B', 'C')); // true; // Bidirectional!
+ *
+ *     // Get neighbors of A
+ *     const neighborsA = graph.getNeighbors('A');
+ *     console.log(neighborsA[0].key); // 'B';
+ *     console.log(neighborsA[1].key); // 'C';
+ * @example
+ * // UndirectedGraph deleteEdge and vertex operations
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Build a simple undirected graph
+ *     graph.addVertex('X');
+ *     graph.addVertex('Y');
+ *     graph.addVertex('Z');
+ *     graph.addEdge('X', 'Y', 1);
+ *     graph.addEdge('Y', 'Z', 2);
+ *     graph.addEdge('X', 'Z', 3);
+ *
+ *     // Delete an edge
+ *     graph.deleteEdge('X', 'Y');
+ *     console.log(graph.hasEdge('X', 'Y')); // false;
+ *
+ *     // Bidirectional deletion confirmed
+ *     console.log(graph.hasEdge('Y', 'X')); // false;
+ *
+ *     // Other edges should remain
+ *     console.log(graph.hasEdge('Y', 'Z')); // true;
+ *     console.log(graph.hasEdge('Z', 'Y')); // true;
+ *
+ *     // Delete a vertex
+ *     graph.deleteVertex('Y');
+ *     console.log(graph.hasVertex('Y')); // false;
+ *     console.log(graph.size); // 2;
+ * @example
+ * // UndirectedGraph connectivity and neighbors
+ *  const graph = new UndirectedGraph<string>();
+ *
+ *     // Build a friendship network
+ *     const people = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve'];
+ *     for (const person of people) {
+ *       graph.addVertex(person);
+ *     }
+ *
+ *     // Add friendships (undirected edges)
+ *     graph.addEdge('Alice', 'Bob', 1);
+ *     graph.addEdge('Alice', 'Charlie', 1);
+ *     graph.addEdge('Bob', 'Diana', 1);
+ *     graph.addEdge('Charlie', 'Eve', 1);
+ *     graph.addEdge('Diana', 'Eve', 1);
+ *
+ *     // Get friends of each person
+ *     const aliceFriends = graph.getNeighbors('Alice');
+ *     console.log(aliceFriends[0].key); // 'Bob';
+ *     console.log(aliceFriends[1].key); // 'Charlie';
+ *     console.log(aliceFriends.length); // 2;
+ *
+ *     const dianaFriends = graph.getNeighbors('Diana');
+ *     console.log(dianaFriends[0].key); // 'Bob';
+ *     console.log(dianaFriends[1].key); // 'Eve';
+ *     console.log(dianaFriends.length); // 2;
+ *
+ *     // Verify bidirectional friendship
+ *     const bobFriends = graph.getNeighbors('Bob');
+ *     console.log(bobFriends[0].key); // 'Alice'; // Alice -> Bob -> Alice ✓
+ *     console.log(bobFriends[1].key); // 'Diana';
+ * @example
+ * // UndirectedGraph for social network connectivity analysis
+ *  interface Person {
+ *       id: number;
+ *       name: string;
+ *       location: string;
+ *     }
+ *
+ *     // UndirectedGraph is perfect for modeling symmetric relationships
+ *     // (friendships, collaborations, partnerships)
+ *     const socialNetwork = new UndirectedGraph<number, Person>();
+ *
+ *     // Add people as vertices
+ *     const people: [number, Person][] = [
+ *       [1, { id: 1, name: 'Alice', location: 'New York' }],
+ *       [2, { id: 2, name: 'Bob', location: 'San Francisco' }],
+ *       [3, { id: 3, name: 'Charlie', location: 'Boston' }],
+ *       [4, { id: 4, name: 'Diana', location: 'New York' }],
+ *       [5, { id: 5, name: 'Eve', location: 'Seattle' }]
+ *     ];
+ *
+ *     for (const [id] of people) {
+ *       socialNetwork.addVertex(id);
+ *     }
+ *
+ *     // Add friendships (automatically bidirectional)
+ *     socialNetwork.addEdge(1, 2, 1); // Alice <-> Bob
+ *     socialNetwork.addEdge(1, 3, 1); // Alice <-> Charlie
+ *     socialNetwork.addEdge(2, 4, 1); // Bob <-> Diana
+ *     socialNetwork.addEdge(3, 5, 1); // Charlie <-> Eve
+ *     socialNetwork.addEdge(4, 5, 1); // Diana <-> Eve
+ *
+ *     console.log(socialNetwork.size); // 5;
+ *
+ *     // Find direct connections for Alice
+ *     const aliceConnections = socialNetwork.getNeighbors(1);
+ *     console.log(aliceConnections[0].key); // 2;
+ *     console.log(aliceConnections[1].key); // 3;
+ *     console.log(aliceConnections.length); // 2;
+ *
+ *     // Verify bidirectional connections
+ *     console.log(socialNetwork.hasEdge(1, 2)); // true;
+ *     console.log(socialNetwork.hasEdge(2, 1)); // true; // Friendship works both ways!
+ *
+ *     // Remove a person from network
+ *     socialNetwork.deleteVertex(2); // Bob leaves
+ *     console.log(socialNetwork.hasVertex(2)); // false;
+ *     console.log(socialNetwork.size); // 4;
+ *
+ *     // Alice loses Bob as a friend
+ *     const updatedAliceConnections = socialNetwork.getNeighbors(1);
+ *     console.log(updatedAliceConnections[0].key); // 3;
+ *     console.log(updatedAliceConnections[1]); // undefined;
+ *
+ *     // Diana loses Bob as a friend
+ *     const dianaConnections = socialNetwork.getNeighbors(4);
+ *     console.log(dianaConnections[0].key); // 5;
+ *     console.log(dianaConnections[1]); // undefined;
  */
 export class UndirectedGraph<
   V = any,