data-structure-typed 2.2.2 → 2.2.3

package/test/unit/data-structures/binary-tree/red-black-tree.test.ts

@@ -838,47 +838,99 @@ describe('real world data', () => {
 });
 
 describe('classic use', () => {
-  it('@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
+  it('@example 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
+    expect([...tree.keys()]).toEqual([1, 2, 5, 8, 9]);
+
+    // Check size
+    expect(tree.size).toBe(5);
+  });
+
+  it('@example Red-Black Tree with key-value pairs for lookups', () => {
+    interface Employee {
+      id: number;
+      name: string;
+    }
+
+    // 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);
+    expect(alice?.name).toBe('Alice');
+
+    // Verify sorted order by ID
+    expect([...employees.keys()]).toEqual([1, 2, 3]);
+  });
+
+  it('@example Red-Black Tree range search for filtering', () => {
+    interface Product {
+      name: string;
+      price: number;
     }
 
-    // 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 }
-    ];
-
-    // Extend the stock record type to include metadata for database usage
-    type StockTableRecord = StockRecord & { lastUpdated: Date };
-
-    // 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
-        }
-      ]
+    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 }]
+    ]);
+
+    // 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();
-    expect(priceIndex.get(highestPricedStock)?.symbol).toBe('AMZN'); // Amazon has the highest price
+    expect(pricesInRange).toEqual(['Item B', 'Item C']);
+  });
+
+  it('@example Red-Black Tree as database index for stock market data', () => {
+    interface StockPrice {
+      symbol: string;
+      volume: number;
+      timestamp: Date;
+    }
 
-    // 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
-    );
-    expect(stocksInRange).toEqual(['GOOGL', 'META', 'MSFT']); // Verify stocks in the range
+    // 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();
+    expect(priceIndex.get(maxPrice)?.symbol).toBe('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
+      };
+    });
+
+    expect(stocksInRange.length).toBe(3);
+    expect(stocksInRange.some((s: any) => s.symbol === 'GOOGL')).toBe(true);
+    expect(stocksInRange.some((s: any) => s.symbol === 'META')).toBe(true);
+    expect(stocksInRange.some((s: any) => s.symbol === 'MSFT')).toBe(true);
   });
 });

package/test/unit/data-structures/graph/directed-graph.test.ts

@@ -1050,3 +1050,136 @@ describe('delete', () => {
   //
   // })
 });
+
+describe('classic use', () => {
+  it('@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
+    expect(graph.hasVertex('A')).toBe(true);
+    expect(graph.hasVertex('B')).toBe(true);
+    expect(graph.hasVertex('C')).toBe(true);
+    expect(graph.hasVertex('D')).toBe(false);
+
+    // Check vertex count
+    expect(graph.size).toBe(3);
+  });
+
+  it('@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
+    expect(graph.hasEdge('A', 'B')).toBe(true);
+    expect(graph.hasEdge('B', 'C')).toBe(true);
+    expect(graph.hasEdge('C', 'B')).toBe(false); // Graph is directed
+
+    // Get neighbors of A
+    const neighborsA = graph.getNeighbors('A');
+    expect(neighborsA[0].key).toBe('B');
+    expect(neighborsA[1].key).toBe('C');
+  });
+
+  it('@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');
+    expect(graph.hasEdge('X', 'Y')).toBe(false);
+
+    // Edge in other direction should not exist
+    expect(graph.hasEdge('Y', 'X')).toBe(false);
+
+    // Other edges should remain
+    expect(graph.hasEdge('Y', 'Z')).toBe(true);
+
+    // Delete a vertex
+    graph.deleteVertex('Y');
+    expect(graph.hasVertex('Y')).toBe(false);
+    expect(graph.size).toBe(2);
+  });
+
+  it('@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();
+    expect(executionOrder).toBeDefined();
+    expect(executionOrder).toEqual(['Design', 'Implement', 'Test', 'Deploy']);
+
+    // All vertices should be included
+    expect(executionOrder?.length).toBe(4);
+  });
+
+  it('@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
+    expect(minDist).toBeDefined();
+    expect(minPath).toBeDefined();
+
+    // 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
+    expect(minDist).toBeLessThanOrEqual(16);
+
+    // Verify path is valid (includes start and end)
+    expect(minPath?.[0].key).toBe('Router-A');
+    expect(minPath?.[minPath.length - 1].key).toBe('Router-E');
+  });
+});

package/test/unit/data-structures/graph/undirected-graph.test.ts

@@ -613,3 +613,170 @@ describe('UndirectedGraph tarjan', () => {
   //   expect(getAsVerticesArrays(ccs)).toEqual([["K", "J", "I", "H", "D", "C", "B"], ["G", "F", "E"], ["A"]]);
   // });
 });
+
+describe('classic use', () => {
+  it('@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
+    expect(graph.hasVertex('A')).toBe(true);
+    expect(graph.hasVertex('B')).toBe(true);
+    expect(graph.hasVertex('E')).toBe(false);
+
+    // Check vertex count
+    expect(graph.size).toBe(4);
+  });
+
+  it('@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
+    expect(graph.hasEdge('A', 'B')).toBe(true);
+    expect(graph.hasEdge('B', 'A')).toBe(true); // Bidirectional!
+
+    expect(graph.hasEdge('C', 'B')).toBe(true);
+    expect(graph.hasEdge('B', 'C')).toBe(true); // Bidirectional!
+
+    // Get neighbors of A
+    const neighborsA = graph.getNeighbors('A');
+    expect(neighborsA[0].key).toBe('B');
+    expect(neighborsA[1].key).toBe('C');
+  });
+
+  it('@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');
+    expect(graph.hasEdge('X', 'Y')).toBe(false);
+
+    // Bidirectional deletion confirmed
+    expect(graph.hasEdge('Y', 'X')).toBe(false);
+
+    // Other edges should remain
+    expect(graph.hasEdge('Y', 'Z')).toBe(true);
+    expect(graph.hasEdge('Z', 'Y')).toBe(true);
+
+    // Delete a vertex
+    graph.deleteVertex('Y');
+    expect(graph.hasVertex('Y')).toBe(false);
+    expect(graph.size).toBe(2);
+  });
+
+  it('@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');
+    expect(aliceFriends[0].key).toBe('Bob');
+    expect(aliceFriends[1].key).toBe('Charlie');
+    expect(aliceFriends.length).toBe(2);
+
+    const dianaFriends = graph.getNeighbors('Diana');
+    expect(dianaFriends[0].key).toBe('Bob');
+    expect(dianaFriends[1].key).toBe('Eve');
+    expect(dianaFriends.length).toBe(2);
+
+    // Verify bidirectional friendship
+    const bobFriends = graph.getNeighbors('Bob');
+    expect(bobFriends[0].key).toBe('Alice'); // Alice -> Bob -> Alice ✓
+    expect(bobFriends[1].key).toBe('Diana');
+  });
+
+  it('@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
+
+    expect(socialNetwork.size).toBe(5);
+
+    // Find direct connections for Alice
+    const aliceConnections = socialNetwork.getNeighbors(1);
+    expect(aliceConnections[0].key).toBe(2);
+    expect(aliceConnections[1].key).toBe(3);
+    expect(aliceConnections.length).toBe(2);
+
+    // Verify bidirectional connections
+    expect(socialNetwork.hasEdge(1, 2)).toBe(true);
+    expect(socialNetwork.hasEdge(2, 1)).toBe(true); // Friendship works both ways!
+
+    // Remove a person from network
+    socialNetwork.deleteVertex(2); // Bob leaves
+    expect(socialNetwork.hasVertex(2)).toBe(false);
+    expect(socialNetwork.size).toBe(4);
+
+    // Alice loses Bob as a friend
+    const updatedAliceConnections = socialNetwork.getNeighbors(1);
+    expect(updatedAliceConnections[0].key).toBe(3);
+    expect(updatedAliceConnections[1]).toBe(undefined);
+
+    // Diana loses Bob as a friend
+    const dianaConnections = socialNetwork.getNeighbors(4);
+    expect(dianaConnections[0].key).toBe(5);
+    expect(dianaConnections[1]).toBe(undefined);
+  });
+});

package/test/unit/data-structures/hash/hash-map.test.ts

@@ -918,7 +918,127 @@ describe('classic uses', () => {
 });
 
 describe('classic uses', () => {
-  it('@example fast lookup of values by key', () => {
+  it('@example basic HashMap creation and set operation', () => {
+    // Create a simple HashMap with key-value pairs
+    const map = new HashMap<number, string>([
+      [1, 'one'],
+      [2, 'two'],
+      [3, 'three']
+    ]);
+
+    // Verify size
+    expect(map.size).toBe(3);
+
+    // Set a new key-value pair
+    map.set(4, 'four');
+    expect(map.size).toBe(4);
+
+    // Verify entries
+    expect([...map.entries()]).toHaveLength(4);
+  });
+
+  it('@example HashMap get and has operations', () => {
+    const map = new HashMap<string, number>([
+      ['apple', 1],
+      ['banana', 2],
+      ['cherry', 3]
+    ]);
+
+    // Check if key exists
+    expect(map.has('apple')).toBe(true);
+    expect(map.has('date')).toBe(false);
+
+    // Get value by key
+    expect(map.get('banana')).toBe(2);
+    expect(map.get('grape')).toBeUndefined();
+
+    // Get all keys and values
+    const keys = [...map.keys()];
+    const values = [...map.values()];
+    expect(keys).toContain('apple');
+    expect(values).toContain(3);
+  });
+
+  it('@example HashMap iteration and filter operations', () => {
+    const map = new HashMap<number, string>([
+      [1, 'Alice'],
+      [2, 'Bob'],
+      [3, 'Charlie'],
+      [4, 'Diana'],
+      [5, 'Eve']
+    ]);
+
+    // Iterate through entries
+    const entries: [number, string][] = [];
+    for (const [key, value] of map) {
+      entries.push([key, value]);
+    }
+    expect(entries).toHaveLength(5);
+
+    // Filter operation (for iteration with collection methods)
+    const filtered = [...map].filter(([key]) => key > 2);
+    expect(filtered.length).toBe(3);
+
+    // Map operation
+    const values = [...map.values()].map(v => v.length);
+    expect(values).toContain(3); // 'Bob', 'Eve'
+    expect(values).toContain(7); // 'Charlie'
+  });
+
+  it('@example HashMap for user session caching O(1) performance', () => {
+    interface UserSession {
+      userId: number;
+      username: string;
+      loginTime: number;
+      lastActivity: number;
+    }
+
+    // HashMap provides O(1) average-case performance for set/get/delete
+    // Perfect for session management with fast lookups
+    const sessionCache = new HashMap<string, UserSession>();
+
+    // Simulate user sessions
+    const sessions: [string, UserSession][] = [
+      ['session_001', { userId: 1, username: 'alice', loginTime: 1000, lastActivity: 1050 }],
+      ['session_002', { userId: 2, username: 'bob', loginTime: 1100, lastActivity: 1150 }],
+      ['session_003', { userId: 3, username: 'charlie', loginTime: 1200, lastActivity: 1250 }]
+    ];
+
+    // Store sessions with O(1) insertion
+    for (const [token, session] of sessions) {
+      sessionCache.set(token, session);
+    }
+
+    expect(sessionCache.size).toBe(3);
+
+    // Retrieve session with O(1) lookup
+    const userSession = sessionCache.get('session_001');
+    expect(userSession?.username).toBe('alice');
+    expect(userSession?.userId).toBe(1);
+
+    // Update session with O(1) operation
+    if (userSession) {
+      userSession.lastActivity = 2000;
+      sessionCache.set('session_001', userSession);
+    }
+
+    // Check updated value
+    const updated = sessionCache.get('session_001');
+    expect(updated?.lastActivity).toBe(2000);
+
+    // Cleanup: delete expired sessions
+    sessionCache.delete('session_002');
+    expect(sessionCache.has('session_002')).toBe(false);
+
+    // Verify remaining sessions
+    expect(sessionCache.size).toBe(2);
+
+    // Get all active sessions
+    const activeCount = [...sessionCache.values()].length;
+    expect(activeCount).toBe(2);
+  });
+
+  it('Fast lookup of values by key', () => {
     const hashMap = new HashMap<number, string>();
     hashMap.set(1, 'A');
     hashMap.set(2, 'B');
@@ -930,7 +1050,7 @@ describe('classic uses', () => {
     expect(hashMap.get(99)).toBeUndefined(); // Key not present
   });
 
-  it('@example remove duplicates when adding multiple entries', () => {
+  it('Remove duplicates when adding multiple entries', () => {
     const hashMap = new HashMap<number, string>();
     hashMap.set(1, 'A');
     hashMap.set(2, 'B');
@@ -941,7 +1061,7 @@ describe('classic uses', () => {
     expect(hashMap.get(2)).toBe('B');
   });
 
-  it('@example count occurrences of keys', () => {
+  it('Count occurrences of keys', () => {
     const data = [1, 2, 1, 3, 2, 1];
 
     const countMap = new HashMap<number, number>();
@@ -976,4 +1096,30 @@ describe('classic uses', () => {
     expect(groupedMap.get('A')).toEqual([1, 3]);
     expect(groupedMap.get('B')).toEqual([2, 4]);
   });
+
+  it('HashMap delete and clear operations', () => {
+    const map = new HashMap<string, number>([
+      ['a', 10],
+      ['b', 20],
+      ['c', 30],
+      ['d', 40]
+    ]);
+
+    // Delete a key
+    map.delete('b');
+    expect(map.has('b')).toBe(false);
+    expect(map.size).toBe(3);
+
+    // Value for deleted key is undefined
+    expect(map.get('b')).toBeUndefined();
+
+    // Other entries remain
+    expect(map.get('a')).toBe(10);
+    expect(map.get('c')).toBe(30);
+
+    // Clear all entries
+    map.clear();
+    expect(map.size).toBe(0);
+    expect(map.has('a')).toBe(false);
+  });
 });