stack-typed 2.2.2 → 2.2.3

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

@@ -201,8 +201,57 @@ export class BSTNode<K = any, V = any> {
  * 7. No Auto-Balancing: Standard BSTs don't automatically balance themselves.
  *
  * @example
+ * // basic BST creation and add operation
+ *  // Create a simple BST with numeric keys
+ *     const bst = new BST<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     bst.print();
+ *     //         _______8__________
+ *     //        /                  \
+ *     //     ___4___          ____12_____
+ *     //    /       \        /           \
+ *     //   _2_     _6_     _10__       _14__
+ *     //  /   \   /   \   /     \     /     \
+ *     //  1   3   5   7   9    11    13    15__
+ *     //                                       \
+ *     //                                      16
+ *
+ *     // Verify size
+ *     console.log(bst.size); // 16;
+ *
+ *     // Add new elements
+ *     bst.add(17);
+ *     bst.add(0);
+ *     console.log(bst.size); // 18;
+ *
+ *     // Verify keys are searchable
+ *     console.log(bst.has(11)); // true;
+ *     console.log(bst.has(100)); // false;
+ * @example
+ * // BST delete and search after deletion
+ *  const bst = new BST<number>([11, 3, 15, 1, 8, 13, 16, 2, 6, 9, 12, 14, 4, 7, 10, 5]);
+ *
+ *     // Delete a leaf node
+ *     bst.delete(1);
+ *     console.log(bst.has(1)); // false;
+ *
+ *     // Delete a node with one child
+ *     bst.delete(2);
+ *     console.log(bst.has(2)); // false;
+ *
+ *     // Delete a node with two children
+ *     bst.delete(3);
+ *     console.log(bst.has(3)); // false;
+ *
+ *     // Size decreases with each deletion
+ *     console.log(bst.size); // 13;
+ *
+ *     // Other nodes remain searchable
+ *     console.log(bst.has(11)); // true;
+ *     console.log(bst.has(15)); // true;
+ * @example
  * // Merge 3 sorted datasets
- *     const dataset1 = new BST<number, string>([
+ *  const dataset1 = new BST<number, string>([
  *       [1, 'A'],
  *       [7, 'G']
  *     ]);
@@ -222,18 +271,58 @@ export class BSTNode<K = any, V = any> {
  *     merged.merge(dataset3);
  *
  *     // Verify merged dataset is in sorted order
- *     console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G']
+ *     console.log([...merged.values()]); // ['A', 'B', 'C', 'D', 'E', 'F', 'G'];
  * @example
- * // Find elements in a range
- *     const bst = new BST<number>([10, 5, 15, 3, 7, 12, 18]);
- *     console.log(bst.search(new Range(5, 10))); // [5, 7, 10]
- *     console.log(bst.rangeSearch([4, 12], node => node.key.toString())); // ['5', '7', '10', '12']
- *     console.log(bst.search(new Range(4, 12, true, false))); // [5, 7, 10]
- *     console.log(bst.rangeSearch([15, 20])); // [15, 18]
- *     console.log(bst.search(new Range(15, 20, false))); // [18]
+ * // BST with custom objects for expression evaluation
+ *  interface Expression {
+ *       id: number;
+ *       operator: string;
+ *       precedence: number;
+ *     }
+ *
+ *     // BST efficiently stores and retrieves operators by precedence
+ *     const operatorTree = new BST<number, Expression>(
+ *       [
+ *         [1, { id: 1, operator: '+', precedence: 1 }],
+ *         [2, { id: 2, operator: '*', precedence: 2 }],
+ *         [3, { id: 3, operator: '/', precedence: 2 }],
+ *         [4, { id: 4, operator: '-', precedence: 1 }],
+ *         [5, { id: 5, operator: '^', precedence: 3 }]
+ *       ],
+ *       { isMapMode: false }
+ *     );
+ *
+ *     console.log(operatorTree.size); // 5;
+ *
+ *     // Quick lookup of operators
+ *     const mult = operatorTree.get(2);
+ *     console.log(mult?.operator); // '*';
+ *     console.log(mult?.precedence); // 2;
+ *
+ *     // Check if operator exists
+ *     console.log(operatorTree.has(5)); // true;
+ *     console.log(operatorTree.has(99)); // false;
+ *
+ *     // Retrieve operator by precedence level
+ *     const expNode = operatorTree.getNode(3);
+ *     console.log(expNode?.key); // 3;
+ *     console.log(expNode?.value?.precedence); // 2;
+ *
+ *     // Delete operator and verify
+ *     operatorTree.delete(1);
+ *     console.log(operatorTree.has(1)); // false;
+ *     console.log(operatorTree.size); // 4;
+ *
+ *     // Get tree height for optimization analysis
+ *     const treeHeight = operatorTree.getHeight();
+ *     console.log(treeHeight); // > 0;
+ *
+ *     // Remaining operators are still accessible
+ *     const remaining = operatorTree.get(2);
+ *     console.log(remaining); // defined;
  * @example
  * // Find lowest common ancestor
- *     const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
+ *  const bst = new BST<number>([20, 10, 30, 5, 15, 25, 35, 3, 7, 12, 18]);
  *
  *     // LCA helper function
  *     const findLCA = (num1: number, num2: number): number | undefined => {
@@ -253,9 +342,9 @@ export class BSTNode<K = any, V = any> {
  *     }
  *
  *     // Assertions
- *     console.log(findLCA(3, 10)); // 7
- *     console.log(findLCA(5, 35)); // 15
- *     console.log(findLCA(20, 30)); // 25
+ *     console.log(findLCA(3, 10)); // 7;
+ *     console.log(findLCA(5, 35)); // 15;
+ *     console.log(findLCA(20, 30)); // 25;
  */
 export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implements IBinaryTree<K, V, R> {
   /**
@@ -756,6 +845,52 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return inserted;
   }
 
+  /**
+   * Returns the first node with a key greater than or equal to the given key.
+   * This is equivalent to C++ std::lower_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key >= given key, or undefined if no such node exists.
+   */
+  lowerBound(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType = this.iterationType
+  ): BSTNode<K, V> | undefined {
+    return this._bound(keyNodeEntryOrPredicate, true, iterationType);
+  }
+
+  /**
+   * Returns the first node with a key strictly greater than the given key.
+   * This is equivalent to C++ std::upper_bound on a BST.
+   * Supports RECURSIVE and ITERATIVE implementations.
+   * Time Complexity: O(log n) on average, O(h) where h is tree height.
+   * Space Complexity: O(h) for recursion, O(1) for iteration.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param iterationType The iteration type (RECURSIVE or ITERATIVE). Defaults to this.iterationType.
+   * @returns The first node with key > given key, or undefined if no such node exists.
+   */
+  upperBound(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType = this.iterationType
+  ): BSTNode<K, V> | undefined {
+    return this._bound(keyNodeEntryOrPredicate, false, iterationType);
+  }
+
   /**
    * Traverses the tree and returns nodes that are lesser or greater than a target node.
    * @remarks Time O(N), as it performs a full traversal. Space O(log N) or O(N).
@@ -945,6 +1080,180 @@ export class BST<K = any, V = any, R = any> extends BinaryTree<K, V, R> implemen
     return false;
   }
 
+  /**
+   * (Protected) Core bound search implementation supporting all parameter types.
+   * Unified logic for both lowerBound and upperBound.
+   * Resolves various input types (Key, Node, Entry, Predicate) using parent class utilities.
+   * @param keyNodeEntryOrPredicate - The key, node, entry, or predicate function to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first matching node, or undefined if no such node exists.
+   */
+  protected _bound(
+    keyNodeEntryOrPredicate:
+      | K
+      | BSTNode<K, V>
+      | [K | null | undefined, V | undefined]
+      | null
+      | undefined
+      | NodePredicate<BSTNode<K, V>>,
+    isLower: boolean,
+    iterationType: IterationType
+  ): BSTNode<K, V> | undefined {
+    if (keyNodeEntryOrPredicate === null || keyNodeEntryOrPredicate === undefined) {
+      return undefined;
+    }
+
+    // Check if input is a predicate function first
+    if (this._isPredicate(keyNodeEntryOrPredicate)) {
+      return this._boundByPredicate(keyNodeEntryOrPredicate, iterationType);
+    }
+
+    // Resolve input to a comparable key
+    let targetKey: K | undefined;
+
+    if (this.isNode(keyNodeEntryOrPredicate)) {
+      // Input is a BSTNode - extract its key
+      targetKey = keyNodeEntryOrPredicate.key;
+    } else if (this.isEntry(keyNodeEntryOrPredicate)) {
+      // Input is a [key, value] entry - extract the key
+      const key = keyNodeEntryOrPredicate[0];
+      if (key === null || key === undefined) {
+        return undefined;
+      }
+      targetKey = key;
+    } else {
+      // Input is a raw key
+      targetKey = keyNodeEntryOrPredicate;
+    }
+
+    // Execute key-based search with binary search optimization
+    if (targetKey !== undefined) {
+      return this._boundByKey(targetKey, isLower, iterationType);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * (Protected) Binary search for bound by key with pruning optimization.
+   * Performs standard BST binary search, choosing left or right subtree based on comparator result.
+   * For lowerBound: finds first node where key >= target.
+   * For upperBound: finds first node where key > target.
+   * @param key - The target key to search for.
+   * @param isLower - True for lowerBound (>=), false for upperBound (>).
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node matching the bound condition, or undefined if none exists.
+   */
+  protected _boundByKey(key: K, isLower: boolean, iterationType: IterationType): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive binary search implementation
+      const dfs = (cur: BSTNode<K, V> | null | undefined): BSTNode<K, V> | undefined => {
+        if (!this.isRealNode(cur)) return undefined;
+
+        const cmp = this.comparator(cur.key!, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+
+        if (condition) {
+          // Current node satisfies the bound condition.
+          // Try to find a closer (smaller key) candidate in the left subtree.
+          const leftResult = dfs(cur.left);
+          return leftResult ?? cur;
+        } else {
+          // Current node does not satisfy the condition.
+          // Move right to find larger keys.
+          return dfs(cur.right);
+        }
+      };
+
+      return dfs(this.root);
+    } else {
+      // Iterative binary search implementation
+      let current: BSTNode<K, V> | undefined = this.root;
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      while (this.isRealNode(current)) {
+        const cmp = this.comparator(current.key!, key);
+        const condition = isLower ? cmp >= 0 : cmp > 0;
+
+        if (condition) {
+          // Current node is a candidate. Save it and try left subtree for a closer match.
+          result = current;
+          current = current.left ?? undefined;
+        } else {
+          // Move right to find larger keys.
+          current = current.right ?? undefined;
+        }
+      }
+
+      return result;
+    }
+  }
+
+  /**
+   * (Protected) In-order traversal search by predicate.
+   * Falls back to linear in-order traversal when predicate-based search is required.
+   * Returns the first node that satisfies the predicate function.
+   * Note: Predicate-based search cannot leverage BST's binary search optimization.
+   * Time Complexity: O(n) since it may visit every node.
+   * @param predicate - The predicate function to test nodes.
+   * @param iterationType - The iteration type (RECURSIVE or ITERATIVE).
+   * @returns The first node satisfying predicate, or undefined if none found.
+   */
+  protected _boundByPredicate(
+    predicate: NodePredicate<BSTNode<K, V>>,
+    iterationType: IterationType
+  ): BSTNode<K, V> | undefined {
+    if (iterationType === 'RECURSIVE') {
+      // Recursive in-order traversal
+      let result: BSTNode<K, V> | undefined = undefined;
+
+      const dfs = (cur: BSTNode<K, V> | null | undefined): void => {
+        if (result || !this.isRealNode(cur)) return;
+
+        // In-order: process left subtree first
+        if (this.isRealNode(cur.left)) dfs(cur.left);
+
+        // Check current node
+        if (!result && predicate(cur)) {
+          result = cur;
+        }
+
+        // Process right subtree
+        if (!result && this.isRealNode(cur.right)) dfs(cur.right);
+      };
+
+      dfs(this.root);
+      return result;
+    } else {
+      // Iterative in-order traversal using explicit stack
+      const stack: (BSTNode<K, V> | null | undefined)[] = [];
+      let current: BSTNode<K, V> | null | undefined = this.root;
+
+      while (stack.length > 0 || this.isRealNode(current)) {
+        if (this.isRealNode(current)) {
+          // Go to the leftmost node
+          stack.push(current);
+          current = current.left;
+        } else {
+          // Pop from stack and process
+          const node = stack.pop();
+          if (!this.isRealNode(node)) break;
+
+          // Check if current node satisfies predicate
+          if (predicate(node)) {
+            return node;
+          }
+
+          // Visit right subtree
+          current = node.right;
+        }
+      }
+
+      return undefined;
+    }
+  }
+
   /**
    * (Protected) Creates a new, empty instance of the same BST constructor.
    * @remarks Time O(1)

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

@@ -188,48 +188,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> {

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

@@ -186,7 +186,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 +347,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> {
   /**

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,