data-structure-typed 2.2.1 → 2.2.3

package/test/unit/data-structures/heap/heap.test.ts

@@ -452,18 +452,106 @@ describe('FibonacciHeap Stress Test', () => {
 });
 
 describe('classic use', () => {
-  it('@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
+  it('@example basic Heap creation and add operation', () => {
+    // Create a min heap (default)
+    const minHeap = new Heap([5, 3, 7, 1, 9, 2]);
+
+    // Verify size
+    expect(minHeap.size).toBe(6);
+
+    // Add new element
+    minHeap.add(4);
+    expect(minHeap.size).toBe(7);
+
+    // Min heap property: smallest element at root
+    const min = minHeap.peek();
+    expect(min).toBe(1);
+  });
+
+  it('@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
+    });
+
+    expect(maxHeap.size).toBe(3);
+
+    // Peek returns highest priority task
+    const topTask = maxHeap.peek();
+    expect(topTask?.priority).toBe(8);
+    expect(topTask?.name).toBe('Alert');
+  });
+
+  it('@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' });
+
+    expect(eventHeap.size).toBe(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];
-    expect(heapSort(array)).toEqual([1, 2, 3, 4, 5, 8]);
+    // Verify critical events came first
+    expect(processedOrder[0].type).toBe('critical');
+    expect(processedOrder[1].type).toBe('critical');
+    expect(processedOrder[2].type).toBe('warning');
+    expect(processedOrder[3].type).toBe('info');
+    expect(processedOrder[4].type).toBe('info');
+
+    // Verify O(log n) operations
+    const newHeap = new Heap<number>([5, 3, 7, 1]);
+
+    // Add - O(log n)
+    newHeap.add(2);
+    expect(newHeap.size).toBe(5);
+
+    // Poll - O(log n)
+    const removed = newHeap.poll();
+    expect(removed).toBe(1);
+
+    // Peek - O(1)
+    const top = newHeap.peek();
+    expect(top).toBe(2);
   });
 
   it('@example Use Heap to solve top k problems', () => {
@@ -480,44 +568,6 @@ describe('classic use', () => {
     expect(topKElements(numbers, 3)).toEqual([15, 10, 5]);
   });
 
-  it('@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]
-    ];
-    expect(mergeSortedSequences(sequences)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9]);
-  });
-
   it('@example Use Heap to dynamically maintain the median', () => {
     class MedianFinder {
       private low: MaxHeap<number>; // Max heap, stores the smaller half
@@ -622,4 +672,89 @@ describe('classic use', () => {
     ]);
     expect(scheduleTasks(tasks, 2)).toEqual(expectedMap);
   });
+
+  it('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
+      }
+      return sorted;
+    }
+
+    const array = [5, 3, 8, 4, 1, 2];
+    expect(heapSort(array)).toEqual([1, 2, 3, 4, 5, 8]);
+  });
+
+  it('Heap getHeight and structure', () => {
+    const heap = new Heap<number>([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]);
+
+    // Complete binary tree (heap property)
+    expect(heap.size).toBe(15);
+
+    // Verify min heap property (parent <= children)
+    const min = heap.peek();
+    expect(min).toBe(1);
+  });
+
+  it('Heap poll and priority extraction', () => {
+    // Create max heap (higher numbers first)
+    const heap = new Heap([3, 7, 1, 9, 5], {
+      comparator: (a: number, b: number) => b - a
+    });
+
+    expect(heap.size).toBe(5);
+
+    // Poll removes and returns the highest priority element
+    const first = heap.poll();
+    expect(first).toBe(9);
+    expect(heap.size).toBe(4);
+
+    const second = heap.poll();
+    expect(second).toBe(7);
+    expect(heap.size).toBe(3);
+
+    // Remaining elements are still in heap order
+    const third = heap.peek();
+    expect(third).toBe(5);
+  });
+
+  it('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]
+    ];
+    expect(mergeSortedSequences(sequences)).toEqual([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+  });
 });

package/test/unit/data-structures/linked-list/doubly-linked-list.test.ts

@@ -612,17 +612,51 @@ describe('iterable methods', () => {
 });
 
 describe('classic use', () => {
-  it('@example text editor operation history', () => {
-    const actions = [
-      { type: 'insert', content: 'first line of text' },
-      { type: 'insert', content: 'second line of text' },
-      { type: 'delete', content: 'delete the first line' }
-    ];
-    const editorHistory = new DoublyLinkedList<{ type: string; content: string }>(actions);
+  it('@example basic DoublyLinkedList creation and push operation', () => {
+    // Create a simple DoublyLinkedList with initial values
+    const list = new DoublyLinkedList([1, 2, 3, 4, 5]);
 
-    expect(editorHistory.last?.type).toBe('delete');
-    expect(editorHistory.pop()?.content).toBe('delete the first line');
-    expect(editorHistory.last?.type).toBe('insert');
+    // Verify the list maintains insertion order
+    expect([...list]).toEqual([1, 2, 3, 4, 5]);
+
+    // Check length
+    expect(list.length).toBe(5);
+
+    // Push a new element to the end
+    list.push(6);
+    expect(list.length).toBe(6);
+    expect([...list]).toEqual([1, 2, 3, 4, 5, 6]);
+  });
+
+  it('@example DoublyLinkedList pop and shift operations', () => {
+    const list = new DoublyLinkedList<number>([10, 20, 30, 40, 50]);
+
+    // Pop removes from the end
+    const last = list.pop();
+    expect(last).toBe(50);
+
+    // Shift removes from the beginning
+    const first = list.shift();
+    expect(first).toBe(10);
+
+    // Verify remaining elements
+    expect([...list]).toEqual([20, 30, 40]);
+    expect(list.length).toBe(3);
+  });
+
+  it('@example DoublyLinkedList for...of iteration and map operation', () => {
+    const list = new DoublyLinkedList<number>([1, 2, 3, 4, 5]);
+
+    // Iterate through list
+    const doubled = list.map(value => value * 2);
+    expect(doubled.length).toBe(5);
+
+    // Use for...of loop
+    const result: number[] = [];
+    for (const item of list) {
+      result.push(item);
+    }
+    expect(result).toEqual([1, 2, 3, 4, 5]);
   });
 
   it('@example Browser history', () => {
@@ -637,7 +671,77 @@ describe('classic use', () => {
     expect(browserHistory.last).toBe('search page');
   });
 
-  it('@example Use DoublyLinkedList to implement music player', () => {
+  it('@example DoublyLinkedList for LRU cache implementation', () => {
+    interface CacheEntry {
+      key: string;
+      value: string;
+    }
+
+    // Simulate LRU cache using DoublyLinkedList
+    // DoublyLinkedList is perfect because:
+    // - O(1) delete from any position
+    // - O(1) push to end
+    // - Bidirectional traversal for LRU policy
+
+    const cacheList = new DoublyLinkedList<CacheEntry>();
+    const maxSize = 3;
+
+    // Add cache entries
+    cacheList.push({ key: 'user:1', value: 'Alice' });
+    cacheList.push({ key: 'user:2', value: 'Bob' });
+    cacheList.push({ key: 'user:3', value: 'Charlie' });
+
+    // Try to add a new entry when cache is full
+    if (cacheList.length >= maxSize) {
+      // Remove the oldest (first) entry
+      const evicted = cacheList.shift();
+      expect(evicted?.key).toBe('user:1');
+    }
+
+    // Add new entry
+    cacheList.push({ key: 'user:4', value: 'Diana' });
+
+    // Verify current cache state
+    expect(cacheList.length).toBe(3);
+    const cachedKeys = [...cacheList].map(entry => entry.key);
+    expect(cachedKeys).toEqual(['user:2', 'user:3', 'user:4']);
+
+    // Access entry (in real LRU, this would move it to end)
+    const foundEntry = [...cacheList].find(entry => entry.key === 'user:2');
+    expect(foundEntry?.value).toBe('Bob');
+  });
+
+  it('DoublyLinkedList unshift and bidirectional traversal', () => {
+    const list = new DoublyLinkedList<number>([20, 30, 40]);
+
+    // Unshift adds to the beginning
+    list.unshift(10);
+    expect([...list]).toEqual([10, 20, 30, 40]);
+
+    // Access elements by index (bidirectional advantage)
+    const second = list.at(1);
+    expect(second).toBe(20);
+
+    const last = list.at(list.length - 1);
+    expect(last).toBe(40);
+
+    expect(list.length).toBe(4);
+  });
+
+  it('text editor operation history', () => {
+    const actions = [
+      { type: 'insert', content: 'first line of text' },
+      { type: 'insert', content: 'second line of text' },
+      { type: 'delete', content: 'delete the first line' }
+    ];
+    const editorHistory = new DoublyLinkedList<{ type: string; content: string }>(actions);
+
+    expect(editorHistory.last?.type).toBe('delete');
+    expect(editorHistory.pop()?.content).toBe('delete the first line');
+    expect(editorHistory.last?.type).toBe('insert');
+  });
+
+  it('Use DoublyLinkedList to implement music player', () => {
     // Define the Song interface
     interface Song {
       title: string;
@@ -763,7 +867,7 @@ describe('classic use', () => {
     ]);
   });
 
-  it('@example Use DoublyLinkedList to implement LRU cache', () => {
+  it('Use DoublyLinkedList to implement LRU cache', () => {
     interface CacheEntry<K, V> {
       key: K;
       value: V;
@@ -926,7 +1030,7 @@ describe('classic use', () => {
     expect(cache.isEmpty).toBe(true);
   });
 
-  it('@example finding lyrics by timestamp in Coldplay\'s "Fix You"', () => {
+  it('Finding lyrics by timestamp in Coldplay\'s "Fix You"', () => {
     // Create a DoublyLinkedList to store song lyrics with timestamps
     const lyricsList = new DoublyLinkedList<{ time: number; text: string }>();
 
@@ -967,7 +1071,7 @@ describe('classic use', () => {
     expect(lateTimeLyric?.text).toBe('And I will try to fix you');
   });
 
-  it('@example cpu process schedules', () => {
+  it('Cpu process schedules', () => {
     class Process {
       constructor(
         public id: number,

package/test/unit/data-structures/linked-list/singly-linked-list.test.ts

@@ -646,6 +646,127 @@ describe('iterable methods', () => {
 });
 
 describe('classic uses', () => {
+  it('@example basic SinglyLinkedList creation and push operation', () => {
+    // Create a simple SinglyLinkedList with initial values
+    const list = new SinglyLinkedList([1, 2, 3, 4, 5]);
+
+    // Verify the list maintains insertion order
+    expect([...list]).toEqual([1, 2, 3, 4, 5]);
+
+    // Check length
+    expect(list.length).toBe(5);
+
+    // Push a new element to the end
+    list.push(6);
+    expect(list.length).toBe(6);
+    expect([...list]).toEqual([1, 2, 3, 4, 5, 6]);
+  });
+
+  it('@example SinglyLinkedList pop and shift operations', () => {
+    const list = new SinglyLinkedList<number>([10, 20, 30, 40, 50]);
+
+    // Pop removes from the end
+    const last = list.pop();
+    expect(last).toBe(50);
+
+    // Shift removes from the beginning
+    const first = list.shift();
+    expect(first).toBe(10);
+
+    // Verify remaining elements
+    expect([...list]).toEqual([20, 30, 40]);
+    expect(list.length).toBe(3);
+  });
+
+  it('@example SinglyLinkedList unshift and forward traversal', () => {
+    const list = new SinglyLinkedList<number>([20, 30, 40]);
+
+    // Unshift adds to the beginning
+    list.unshift(10);
+    expect([...list]).toEqual([10, 20, 30, 40]);
+
+    // Access elements (forward traversal only for singly linked)
+    const second = list.at(1);
+    expect(second).toBe(20);
+
+    // SinglyLinkedList allows forward iteration only
+    const elements: number[] = [];
+    for (const item of list) {
+      elements.push(item);
+    }
+    expect(elements).toEqual([10, 20, 30, 40]);
+
+    expect(list.length).toBe(4);
+  });
+
+  it('@example SinglyLinkedList filter and map operations', () => {
+    const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
+
+    // Filter even numbers
+    const filtered = list.filter(value => value % 2 === 0);
+    expect(filtered.length).toBe(2);
+
+    // Map to double values
+    const doubled = list.map(value => value * 2);
+    expect(doubled.length).toBe(5);
+
+    // Use reduce to sum
+    const sum = list.reduce((acc, value) => acc + value, 0);
+    expect(sum).toBe(15);
+  });
+
+  it('@example SinglyLinkedList for sequentially processed data stream', () => {
+    interface LogEntry {
+      timestamp: number;
+      level: 'INFO' | 'WARN' | 'ERROR';
+      message: string;
+    }
+
+    // SinglyLinkedList is ideal for sequential processing where you only need forward iteration
+    // O(1) insertion/deletion at head, O(n) for tail operations
+    const logStream = new SinglyLinkedList<LogEntry>();
+
+    // Simulate incoming log entries
+    const entries: LogEntry[] = [
+      { timestamp: 1000, level: 'INFO', message: 'Server started' },
+      { timestamp: 1100, level: 'WARN', message: 'Memory usage high' },
+      { timestamp: 1200, level: 'ERROR', message: 'Connection failed' },
+      { timestamp: 1300, level: 'INFO', message: 'Connection restored' }
+    ];
+
+    // Add entries to the stream
+    for (const entry of entries) {
+      logStream.push(entry);
+    }
+
+    expect(logStream.length).toBe(4);
+
+    // Process logs sequentially (only forward iteration needed)
+    const processedLogs: string[] = [];
+    for (const log of logStream) {
+      processedLogs.push(`[${log.level}] ${log.message}`);
+    }
+
+    expect(processedLogs).toEqual([
+      '[INFO] Server started',
+      '[WARN] Memory usage high',
+      '[ERROR] Connection failed',
+      '[INFO] Connection restored'
+    ]);
+
+    // Get first log (O(1) - direct head access)
+    const firstLog = logStream.at(0);
+    expect(firstLog?.message).toBe('Server started');
+
+    // Remove oldest log (O(1) operation at head)
+    const removed = logStream.shift();
+    expect(removed?.message).toBe('Server started');
+    expect(logStream.length).toBe(3);
+
+    // Remaining logs still maintain order for sequential processing
+    expect(logStream.length).toBe(3);
+  });
+
   it('@example implementation of a basic text editor', () => {
     class TextEditor {
       private content: SinglyLinkedList<string>;