max-priority-queue-typed 2.2.2 → 2.2.3

package/dist/types/data-structures/graph/undirected-graph.d.ts

@@ -22,7 +22,166 @@ export declare 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 declare class UndirectedGraph<V = any, E = any, VO extends UndirectedVertex<V> = UndirectedVertex<V>, EO extends UndirectedEdge<E> = UndirectedEdge<E>> extends AbstractGraph<V, E, VO, EO> implements IGraph<V, E, VO, EO> {
     /**

package/dist/types/data-structures/hash/hash-map.d.ts

@@ -20,7 +20,7 @@ import { IterableEntryBase } from '../base';
  * 4. Unordered Collection: HashMap does not guarantee the order of entries, and the order may change over time.
  * @example
  * // should maintain insertion order
- *     const linkedHashMap = new LinkedHashMap<number, string>();
+ *  const linkedHashMap = new LinkedHashMap<number, string>();
  *     linkedHashMap.set(1, 'A');
  *     linkedHashMap.set(2, 'B');
  *     linkedHashMap.set(3, 'C');
@@ -30,40 +30,123 @@ import { IterableEntryBase } from '../base';
  *  //      [1, 'A'],
  *  //      [2, 'B'],
  *  //      [3, 'C']
- *  //    ]
+ *  //    ];
  * @example
- * // fast lookup of values by key
- *     const hashMap = new HashMap<number, string>();
- *     hashMap.set(1, 'A');
- *     hashMap.set(2, 'B');
- *     hashMap.set(3, 'C');
+ * // 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']
+ *     ]);
  *
- *     console.log(hashMap.get(1)); // 'A'
- *     console.log(hashMap.get(2)); // 'B'
- *     console.log(hashMap.get(3)); // 'C'
- *     console.log(hashMap.get(99)); // undefined
+ *     // Verify size
+ *     console.log(map.size); // 3;
+ *
+ *     // Set a new key-value pair
+ *     map.set(4, 'four');
+ *     console.log(map.size); // 4;
+ *
+ *     // Verify entries
+ *     console.log([...map.entries()]); // length: 4;
  * @example
- * // remove duplicates when adding multiple entries
- *     const hashMap = new HashMap<number, string>();
- *     hashMap.set(1, 'A');
- *     hashMap.set(2, 'B');
- *     hashMap.set(1, 'C'); // Update value for key 1
+ * // HashMap get and has operations
+ *  const map = new HashMap<string, number>([
+ *       ['apple', 1],
+ *       ['banana', 2],
+ *       ['cherry', 3]
+ *     ]);
+ *
+ *     // Check if key exists
+ *     console.log(map.has('apple')); // true;
+ *     console.log(map.has('date')); // false;
  *
- *     console.log(hashMap.size); // 2
- *     console.log(hashMap.get(1)); // 'C'
- *     console.log(hashMap.get(2)); // 'B'
+ *     // Get value by key
+ *     console.log(map.get('banana')); // 2;
+ *     console.log(map.get('grape')); // undefined;
+ *
+ *     // Get all keys and values
+ *     const keys = [...map.keys()];
+ *     const values = [...map.values()];
+ *     console.log(keys); // contains 'apple';
+ *     console.log(values); // contains 3;
  * @example
- * // count occurrences of keys
- *     const data = [1, 2, 1, 3, 2, 1];
+ * // 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]);
+ *     }
+ *     console.log(entries); // length: 5;
+ *
+ *     // Filter operation (for iteration with collection methods)
+ *     const filtered = [...map].filter(([key]) => key > 2);
+ *     console.log(filtered.length); // 3;
  *
- *     const countMap = new HashMap<number, number>();
- *     for (const key of data) {
- *       countMap.set(key, (countMap.get(key) || 0) + 1);
+ *     // Map operation
+ *     const values = [...map.values()].map(v => v.length);
+ *     console.log(values); // contains 3; // 'Bob', 'Eve'
+ *     console.log(values); // contains 7;
+ * @example
+ * // HashMap for user session caching O(1) performance
+ *  interface UserSession {
+ *       userId: number;
+ *       username: string;
+ *       loginTime: number;
+ *       lastActivity: number;
  *     }
  *
- *     console.log(countMap.get(1)); // 3
- *     console.log(countMap.get(2)); // 2
- *     console.log(countMap.get(3)); // 1
+ *     // 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);
+ *     }
+ *
+ *     console.log(sessionCache.size); // 3;
+ *
+ *     // Retrieve session with O(1) lookup
+ *     const userSession = sessionCache.get('session_001');
+ *     console.log(userSession?.username); // 'alice';
+ *     console.log(userSession?.userId); // 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');
+ *     console.log(updated?.lastActivity); // 2000;
+ *
+ *     // Cleanup: delete expired sessions
+ *     sessionCache.delete('session_002');
+ *     console.log(sessionCache.has('session_002')); // false;
+ *
+ *     // Verify remaining sessions
+ *     console.log(sessionCache.size); // 2;
+ *
+ *     // Get all active sessions
+ *     const activeCount = [...sessionCache.values()].length;
+ *     console.log(activeCount); // 2;
  */
 export declare class HashMap<K = any, V = any, R = [K, V]> extends IterableEntryBase<K, V> {
     /**

package/dist/types/data-structures/heap/heap.d.ts

@@ -23,21 +23,107 @@ import { IterableElementBase } from '../base';
  * 7. Efficient Sorting Algorithms: For example, heap sort. Heap sort uses the properties of a heap to sort elements.
  * 8. Graph Algorithms: Such as Dijkstra's shortest path algorithm and Prime's minimum-spanning tree algorithm, which use heaps to improve performance.
  * @example
- * // Use Heap to sort an array
- *     function heapSort(arr: number[]): number[] {
- *       const heap = new Heap<number>(arr, { comparator: (a, b) => a - b });
- *       const sorted: number[] = [];
- *       while (!heap.isEmpty()) {
- *         sorted.push(heap.poll()!); // Poll minimum element
+ * // basic Heap creation and add operation
+ *  // Create a min heap (default)
+ *     const minHeap = new Heap([5, 3, 7, 1, 9, 2]);
+ *
+ *     // Verify size
+ *     console.log(minHeap.size); // 6;
+ *
+ *     // Add new element
+ *     minHeap.add(4);
+ *     console.log(minHeap.size); // 7;
+ *
+ *     // Min heap property: smallest element at root
+ *     const min = minHeap.peek();
+ *     console.log(min); // 1;
+ * @example
+ * // Heap with custom comparator (MaxHeap behavior)
+ *  interface Task {
+ *       id: number;
+ *       priority: number;
+ *       name: string;
+ *     }
+ *
+ *     // Custom comparator for max heap behavior (higher priority first)
+ *     const tasks: Task[] = [
+ *       { id: 1, priority: 5, name: 'Email' },
+ *       { id: 2, priority: 3, name: 'Chat' },
+ *       { id: 3, priority: 8, name: 'Alert' }
+ *     ];
+ *
+ *     const maxHeap = new Heap(tasks, {
+ *       comparator: (a: Task, b: Task) => b.priority - a.priority
+ *     });
+ *
+ *     console.log(maxHeap.size); // 3;
+ *
+ *     // Peek returns highest priority task
+ *     const topTask = maxHeap.peek();
+ *     console.log(topTask?.priority); // 8;
+ *     console.log(topTask?.name); // 'Alert';
+ * @example
+ * // Heap for event processing with priority
+ *  interface Event {
+ *       id: number;
+ *       type: 'critical' | 'warning' | 'info';
+ *       timestamp: number;
+ *       message: string;
+ *     }
+ *
+ *     // Custom priority: critical > warning > info
+ *     const priorityMap = { critical: 3, warning: 2, info: 1 };
+ *
+ *     const eventHeap = new Heap<Event>([], {
+ *       comparator: (a: Event, b: Event) => {
+ *         const priorityA = priorityMap[a.type];
+ *         const priorityB = priorityMap[b.type];
+ *         return priorityB - priorityA; // Higher priority first
+ *       }
+ *     });
+ *
+ *     // Add events in random order
+ *     eventHeap.add({ id: 1, type: 'info', timestamp: 100, message: 'User logged in' });
+ *     eventHeap.add({ id: 2, type: 'critical', timestamp: 101, message: 'Server down' });
+ *     eventHeap.add({ id: 3, type: 'warning', timestamp: 102, message: 'High memory' });
+ *     eventHeap.add({ id: 4, type: 'info', timestamp: 103, message: 'Cache cleared' });
+ *     eventHeap.add({ id: 5, type: 'critical', timestamp: 104, message: 'Database error' });
+ *
+ *     console.log(eventHeap.size); // 5;
+ *
+ *     // Process events by priority (critical first)
+ *     const processedOrder: Event[] = [];
+ *     while (eventHeap.size > 0) {
+ *       const event = eventHeap.poll();
+ *       if (event) {
+ *         processedOrder.push(event);
  *       }
- *       return sorted;
  *     }
  *
- *     const array = [5, 3, 8, 4, 1, 2];
- *     console.log(heapSort(array)); // [1, 2, 3, 4, 5, 8]
+ *     // Verify critical events came first
+ *     console.log(processedOrder[0].type); // 'critical';
+ *     console.log(processedOrder[1].type); // 'critical';
+ *     console.log(processedOrder[2].type); // 'warning';
+ *     console.log(processedOrder[3].type); // 'info';
+ *     console.log(processedOrder[4].type); // 'info';
+ *
+ *     // Verify O(log n) operations
+ *     const newHeap = new Heap<number>([5, 3, 7, 1]);
+ *
+ *     // Add - O(log n)
+ *     newHeap.add(2);
+ *     console.log(newHeap.size); // 5;
+ *
+ *     // Poll - O(log n)
+ *     const removed = newHeap.poll();
+ *     console.log(removed); // 1;
+ *
+ *     // Peek - O(1)
+ *     const top = newHeap.peek();
+ *     console.log(top); // 2;
  * @example
  * // Use Heap to solve top k problems
- *     function topKElements(arr: number[], k: number): number[] {
+ *  function topKElements(arr: number[], k: number): number[] {
  *       const heap = new Heap<number>([], { comparator: (a, b) => b - a }); // Max heap
  *       arr.forEach(num => {
  *         heap.add(num);
@@ -47,47 +133,10 @@ import { IterableElementBase } from '../base';
  *     }
  *
  *     const numbers = [10, 30, 20, 5, 15, 25];
- *     console.log(topKElements(numbers, 3)); // [15, 10, 5]
- * @example
- * // Use Heap to merge sorted sequences
- *     function mergeSortedSequences(sequences: number[][]): number[] {
- *       const heap = new Heap<{ value: number; seqIndex: number; itemIndex: number }>([], {
- *         comparator: (a, b) => a.value - b.value // Min heap
- *       });
- *
- *       // Initialize heap
- *       sequences.forEach((seq, seqIndex) => {
- *         if (seq.length) {
- *           heap.add({ value: seq[0], seqIndex, itemIndex: 0 });
- *         }
- *       });
- *
- *       const merged: number[] = [];
- *       while (!heap.isEmpty()) {
- *         const { value, seqIndex, itemIndex } = heap.poll()!;
- *         merged.push(value);
- *
- *         if (itemIndex + 1 < sequences[seqIndex].length) {
- *           heap.add({
- *             value: sequences[seqIndex][itemIndex + 1],
- *             seqIndex,
- *             itemIndex: itemIndex + 1
- *           });
- *         }
- *       }
- *
- *       return merged;
- *     }
- *
- *     const sequences = [
- *       [1, 4, 7],
- *       [2, 5, 8],
- *       [3, 6, 9]
- *     ];
- *     console.log(mergeSortedSequences(sequences)); // [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ *     console.log(topKElements(numbers, 3)); // [15, 10, 5];
  * @example
  * // Use Heap to dynamically maintain the median
- *     class MedianFinder {
+ *  class MedianFinder {
  *       private low: MaxHeap<number>; // Max heap, stores the smaller half
  *       private high: MinHeap<number>; // Min heap, stores the larger half
  *
@@ -113,18 +162,18 @@ import { IterableElementBase } from '../base';
  *
  *     const medianFinder = new MedianFinder();
  *     medianFinder.addNum(10);
- *     console.log(medianFinder.findMedian()); // 10
+ *     console.log(medianFinder.findMedian()); // 10;
  *     medianFinder.addNum(20);
- *     console.log(medianFinder.findMedian()); // 15
+ *     console.log(medianFinder.findMedian()); // 15;
  *     medianFinder.addNum(30);
- *     console.log(medianFinder.findMedian()); // 20
+ *     console.log(medianFinder.findMedian()); // 20;
  *     medianFinder.addNum(40);
- *     console.log(medianFinder.findMedian()); // 25
+ *     console.log(medianFinder.findMedian()); // 25;
  *     medianFinder.addNum(50);
- *     console.log(medianFinder.findMedian()); // 30
+ *     console.log(medianFinder.findMedian()); // 30;
  * @example
  * // Use Heap for load balancing
- *     function loadBalance(requests: number[], servers: number): number[] {
+ *  function loadBalance(requests: number[], servers: number): number[] {
  *       const serverHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // min heap
  *       const serverLoads = new Array(servers).fill(0);
  *
@@ -143,10 +192,10 @@ import { IterableElementBase } from '../base';
  *     }
  *
  *     const requests = [5, 2, 8, 3, 7];
- *     console.log(loadBalance(requests, 3)); // [12, 8, 5]
+ *     console.log(loadBalance(requests, 3)); // [12, 8, 5];
  * @example
  * // Use Heap to schedule tasks
- *     type Task = [string, number];
+ *  type Task = [string, number];
  *
  *     function scheduleTasks(tasks: Task[], machines: number): Map<number, Task[]> {
  *       const machineHeap = new Heap<{ id: number; load: number }>([], { comparator: (a, b) => a.load - b.load }); // Min heap
@@ -186,7 +235,7 @@ import { IterableElementBase } from '../base';
  *       ['Task3', 2],
  *       ['Task5', 4]
  *     ]);
- *     console.log(scheduleTasks(tasks, 2)); // expectedMap
+ *     console.log(scheduleTasks(tasks, 2)); // expectedMap;
  */
 export declare class Heap<E = any, R = any> extends IterableElementBase<E, R> {
     protected _equals: (a: E, b: E) => boolean;