red-black-tree-typed 2.2.2 → 2.2.3

package/src/data-structures/queue/deque.ts

@@ -27,93 +27,121 @@ import { LinearBase } from '../base/linear-base';
  * 4. Efficiency: Adding and removing elements at both ends of a deque is usually very fast. However, when the dynamic array needs to expand, it may involve copying the entire array to a larger one, and this operation has a time complexity of O(n).
  * 5. Performance jitter: Deque may experience performance jitter, but DoublyLinkedList will not
  * @example
- * // prize roulette
- *     class PrizeRoulette {
- *       private deque: Deque<string>;
+ * // basic Deque creation and push/pop operations
+ *  // Create a simple Deque with initial values
+ *     const deque = new Deque([1, 2, 3, 4, 5]);
  *
- *       constructor(prizes: string[]) {
- *         // Initialize the deque with prizes
- *         this.deque = new Deque<string>(prizes);
- *       }
+ *     // Verify the deque maintains insertion order
+ *     console.log([...deque]); // [1, 2, 3, 4, 5];
  *
- *       // Rotate clockwise to the right (forward)
- *       rotateClockwise(steps: number): void {
- *         const n = this.deque.length;
- *         if (n === 0) return;
+ *     // Check length
+ *     console.log(deque.length); // 5;
  *
- *         for (let i = 0; i < steps; i++) {
- *           const last = this.deque.pop(); // Remove the last element
- *           this.deque.unshift(last!); // Add it to the front
- *         }
- *       }
+ *     // Push to the end
+ *     deque.push(6);
+ *     console.log(deque.length); // 6;
  *
- *       // Rotate counterclockwise to the left (backward)
- *       rotateCounterClockwise(steps: number): void {
- *         const n = this.deque.length;
- *         if (n === 0) return;
+ *     // Pop from the end
+ *     const last = deque.pop();
+ *     console.log(last); // 6;
+ * @example
+ * // Deque shift and unshift operations
+ *  const deque = new Deque<number>([20, 30, 40]);
  *
- *         for (let i = 0; i < steps; i++) {
- *           const first = this.deque.shift(); // Remove the first element
- *           this.deque.push(first!); // Add it to the back
- *         }
- *       }
+ *     // Unshift adds to the front
+ *     deque.unshift(10);
+ *     console.log([...deque]); // [10, 20, 30, 40];
  *
- *       // Display the current prize at the head
- *       display() {
- *         return this.deque.first;
- *       }
- *     }
+ *     // Shift removes from the front (O(1) complexity!)
+ *     const first = deque.shift();
+ *     console.log(first); // 10;
  *
- *     // Example usage
- *     const prizes = ['Car', 'Bike', 'Laptop', 'Phone', 'Watch', 'Headphones']; // Initialize the prize list
- *     const roulette = new PrizeRoulette(prizes);
+ *     // Verify remaining elements
+ *     console.log([...deque]); // [20, 30, 40];
+ *     console.log(deque.length); // 3;
+ * @example
+ * // Deque peek at both ends
+ *  const deque = new Deque<number>([10, 20, 30, 40, 50]);
  *
- *     // Display the initial state
- *     console.log(roulette.display()); // 'Car' // Car
+ *     // Get first element without removing
+ *     const first = deque.at(0);
+ *     console.log(first); // 10;
  *
- *     // Rotate clockwise by 3 steps
- *     roulette.rotateClockwise(3);
- *     console.log(roulette.display()); // 'Phone' // Phone
+ *     // Get last element without removing
+ *     const last = deque.at(deque.length - 1);
+ *     console.log(last); // 50;
  *
- *     // Rotate counterclockwise by 2 steps
- *     roulette.rotateCounterClockwise(2);
- *     console.log(roulette.display()); // 'Headphones'
+ *     // Length unchanged
+ *     console.log(deque.length); // 5;
  * @example
- * // sliding window
- *     // Maximum function of sliding window
- *     function maxSlidingWindow(nums: number[], k: number): number[] {
- *       const n = nums.length;
- *       if (n * k === 0) return [];
+ * // Deque for...of iteration and reverse
+ *  const deque = new Deque<string>(['A', 'B', 'C', 'D']);
  *
- *       const deq = new Deque<number>();
- *       const result: number[] = [];
+ *     // Iterate forward
+ *     const forward: string[] = [];
+ *     for (const item of deque) {
+ *       forward.push(item);
+ *     }
+ *     console.log(forward); // ['A', 'B', 'C', 'D'];
  *
- *       for (let i = 0; i < n; i++) {
- *         // Delete indexes in the queue that are not within the window range
- *         if (deq.length > 0 && deq.first! === i - k) {
- *           deq.shift();
- *         }
+ *     // Reverse the deque
+ *     deque.reverse();
+ *     const backward: string[] = [];
+ *     for (const item of deque) {
+ *       backward.push(item);
+ *     }
+ *     console.log(backward); // ['D', 'C', 'B', 'A'];
+ * @example
+ * // Deque as sliding window for stream processing
+ *  interface DataPoint {
+ *       timestamp: number;
+ *       value: number;
+ *       sensor: string;
+ *     }
+ *
+ *     // Create a deque-based sliding window for real-time data aggregation
+ *     const windowSize = 3;
+ *     const dataWindow = new Deque<DataPoint>();
  *
- *         // Remove all indices less than the current value from the tail of the queue
- *         while (deq.length > 0 && nums[deq.last!] < nums[i]) {
- *           deq.pop();
- *         }
+ *     // Simulate incoming sensor data stream
+ *     const incomingData: DataPoint[] = [
+ *       { timestamp: 1000, value: 25.5, sensor: 'temp-01' },
+ *       { timestamp: 1100, value: 26.2, sensor: 'temp-01' },
+ *       { timestamp: 1200, value: 25.8, sensor: 'temp-01' },
+ *       { timestamp: 1300, value: 27.1, sensor: 'temp-01' },
+ *       { timestamp: 1400, value: 26.9, sensor: 'temp-01' }
+ *     ];
  *
- *         // Add the current index to the end of the queue
- *         deq.push(i);
+ *     const windowResults: Array<{ avgValue: number; windowSize: number }> = [];
+ *
+ *     for (const dataPoint of incomingData) {
+ *       // Add new data to the end
+ *       dataWindow.push(dataPoint);
+ *
+ *       // Remove oldest data when window exceeds size (O(1) from front)
+ *       if (dataWindow.length > windowSize) {
+ *         dataWindow.shift();
+ *       }
  *
- *         // Add the maximum value of the window to the results
- *         if (i >= k - 1) {
- *           result.push(nums[deq.first!]);
- *         }
+ *       // Calculate average of current window
+ *       let sum = 0;
+ *       for (const point of dataWindow) {
+ *         sum += point.value;
  *       }
+ *       const avg = sum / dataWindow.length;
  *
- *       return result;
+ *       windowResults.push({
+ *         avgValue: Math.round(avg * 10) / 10,
+ *         windowSize: dataWindow.length
+ *       });
  *     }
  *
- *     const nums = [1, 3, -1, -3, 5, 3, 6, 7];
- *     const k = 3;
- *     console.log(maxSlidingWindow(nums, k)); // [3, 3, 5, 5, 6, 7]
+ *     // Verify sliding window behavior
+ *     console.log(windowResults.length); // 5;
+ *     console.log(windowResults[0].windowSize); // 1; // First window has 1 element
+ *     console.log(windowResults[2].windowSize); // 3; // Windows are at max size from 3rd onwards
+ *     console.log(windowResults[4].windowSize); // 3; // Last window still has 3 elements
+ *     console.log(dataWindow.length); // 3;
  */
 export class Deque<E = any, R = any> extends LinearBase<E, R> {
   protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;

package/src/data-structures/queue/queue.ts

@@ -23,52 +23,108 @@ import { LinearBase } from '../base/linear-base';
  * 6. Breadth-First Search (BFS): In traversal algorithms for graphs and trees, queues store elements that are to be visited.
  * 7. Real-time Queuing: Like queuing systems in banks or supermarkets.
  * @example
- * // Sliding Window using Queue
- *     const nums = [2, 3, 4, 1, 5];
- *     const k = 2;
- *     const queue = new Queue<number>();
+ * // basic Queue creation and push operation
+ *  // Create a simple Queue with initial values
+ *     const queue = new Queue([1, 2, 3, 4, 5]);
  *
- *     let maxSum = 0;
- *     let currentSum = 0;
+ *     // Verify the queue maintains insertion order
+ *     console.log([...queue]); // [1, 2, 3, 4, 5];
  *
- *     nums.forEach(num => {
- *       queue.push(num);
- *       currentSum += num;
+ *     // Check length
+ *     console.log(queue.length); // 5;
+ * @example
+ * // Queue shift and peek operations
+ *  const queue = new Queue<number>([10, 20, 30, 40]);
  *
- *       if (queue.length > k) {
- *         currentSum -= queue.shift()!;
- *       }
+ *     // Peek at the front element without removing it
+ *     console.log(queue.first); // 10;
  *
- *       if (queue.length === k) {
- *         maxSum = Math.max(maxSum, currentSum);
- *       }
- *     });
+ *     // Remove and get the first element (FIFO)
+ *     const first = queue.shift();
+ *     console.log(first); // 10;
  *
- *     console.log(maxSum); // 7
+ *     // Verify remaining elements and length decreased
+ *     console.log([...queue]); // [20, 30, 40];
+ *     console.log(queue.length); // 3;
  * @example
- * // Breadth-First Search (BFS) using Queue
- *     const graph: { [key in number]: number[] } = {
- *       1: [2, 3],
- *       2: [4, 5],
- *       3: [],
- *       4: [],
- *       5: []
- *     };
+ * // Queue for...of iteration and isEmpty check
+ *  const queue = new Queue<string>(['A', 'B', 'C', 'D']);
+ *
+ *     const elements: string[] = [];
+ *     for (const item of queue) {
+ *       elements.push(item);
+ *     }
+ *
+ *     // Verify all elements are iterated in order
+ *     console.log(elements); // ['A', 'B', 'C', 'D'];
  *
- *     const queue = new Queue<number>();
- *     const visited: number[] = [];
+ *     // Process all elements
+ *     while (queue.length > 0) {
+ *       queue.shift();
+ *     }
+ *
+ *     console.log(queue.length); // 0;
+ * @example
+ * // Queue as message broker for event processing
+ *  interface Message {
+ *       id: string;
+ *       type: 'email' | 'sms' | 'push';
+ *       recipient: string;
+ *       content: string;
+ *       timestamp: Date;
+ *     }
  *
- *     queue.push(1);
+ *     // Create a message queue for real-time event processing
+ *     const messageQueue = new Queue<Message>([
+ *       {
+ *         id: 'msg-001',
+ *         type: 'email',
+ *         recipient: 'user@example.com',
+ *         content: 'Welcome!',
+ *         timestamp: new Date()
+ *       },
+ *       {
+ *         id: 'msg-002',
+ *         type: 'sms',
+ *         recipient: '+1234567890',
+ *         content: 'OTP: 123456',
+ *         timestamp: new Date()
+ *       },
+ *       {
+ *         id: 'msg-003',
+ *         type: 'push',
+ *         recipient: 'device-token-xyz',
+ *         content: 'New notification',
+ *         timestamp: new Date()
+ *       },
+ *       {
+ *         id: 'msg-004',
+ *         type: 'email',
+ *         recipient: 'admin@example.com',
+ *         content: 'Daily report',
+ *         timestamp: new Date()
+ *       }
+ *     ]);
  *
- *     while (!queue.isEmpty()) {
- *       const node = queue.shift()!;
- *       if (!visited.includes(node)) {
- *         visited.push(node);
- *         graph[node].forEach(neighbor => queue.push(neighbor));
+ *     // Process messages in FIFO order (first message first)
+ *     const processedMessages: string[] = [];
+ *     while (messageQueue.length > 0) {
+ *       const message = messageQueue.shift();
+ *       if (message) {
+ *         processedMessages.push(`${message.type}:${message.recipient}`);
  *       }
  *     }
  *
- *     console.log(visited); // [1, 2, 3, 4, 5]
+ *     // Verify messages were processed in order
+ *     console.log(processedMessages); // [
+ *  //      'email:user@example.com',
+ *  //      'sms:+1234567890',
+ *  //      'push:device-token-xyz',
+ *  //      'email:admin@example.com'
+ *  //    ];
+ *
+ *     // Queue should be empty after processing all messages
+ *     console.log(messageQueue.length); // 0;
  */
 export class Queue<E = any, R = any> extends LinearBase<E, R> {
   /**

package/src/data-structures/stack/stack.ts

@@ -21,8 +21,49 @@ import { IterableElementBase } from '../base';
  * 5. Expression Evaluation: Used for the evaluation of arithmetic or logical expressions, especially when dealing with parenthesis matching and operator precedence.
  * 6. Backtracking Algorithms: In problems where multiple branches need to be explored but only one branch can be explored at a time, stacks can be used to save the state at each branching point.
  * @example
+ * // basic Stack creation and push operation
+ *  // Create a simple Stack with initial values
+ *     const stack = new Stack([1, 2, 3, 4, 5]);
+ *
+ *     // Verify the stack maintains insertion order (LIFO will be shown in pop)
+ *     console.log([...stack]); // [1, 2, 3, 4, 5];
+ *
+ *     // Check length
+ *     console.log(stack.size); // 5;
+ *
+ *     // Push a new element to the top
+ *     stack.push(6);
+ *     console.log(stack.size); // 6;
+ * @example
+ * // Stack pop operation (LIFO - Last In First Out)
+ *  const stack = new Stack<number>([10, 20, 30, 40, 50]);
+ *
+ *     // Peek at the top element without removing
+ *     const top = stack.peek();
+ *     console.log(top); // 50;
+ *
+ *     // Pop removes from the top (LIFO order)
+ *     const popped = stack.pop();
+ *     console.log(popped); // 50;
+ *
+ *     // Next pop gets the previous element
+ *     const next = stack.pop();
+ *     console.log(next); // 40;
+ *
+ *     // Verify length decreased
+ *     console.log(stack.size); // 3;
+ * @example
+ * // Function Call Stack
+ *  const functionStack = new Stack<string>();
+ *     functionStack.push('main');
+ *     functionStack.push('foo');
+ *     functionStack.push('bar');
+ *     console.log(functionStack.pop()); // 'bar';
+ *     console.log(functionStack.pop()); // 'foo';
+ *     console.log(functionStack.pop()); // 'main';
+ * @example
  * // Balanced Parentheses or Brackets
- *     type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';
+ *  type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';
  *
  *     const stack = new Stack<string>();
  *     const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];
@@ -36,10 +77,10 @@ import { IterableElementBase } from '../base';
  *         }
  *       }
  *     }
- *     console.log(stack.isEmpty()); // true
+ *     console.log(stack.isEmpty()); // true;
  * @example
  * // Expression Evaluation and Conversion
- *     const stack = new Stack<number>();
+ *  const stack = new Stack<number>();
  *     const expression = [5, 3, '+']; // Equivalent to 5 + 3
  *     expression.forEach(token => {
  *       if (typeof token === 'number') {
@@ -50,24 +91,10 @@ import { IterableElementBase } from '../base';
  *         stack.push(token === '+' ? a + b : 0); // Only handling '+' here
  *       }
  *     });
- *     console.log(stack.pop()); // 8
- * @example
- * // Depth-First Search (DFS)
- *     const stack = new Stack<number>();
- *     const graph: { [key in number]: number[] } = { 1: [2, 3], 2: [4], 3: [5], 4: [], 5: [] };
- *     const visited: number[] = [];
- *     stack.push(1);
- *     while (!stack.isEmpty()) {
- *       const node = stack.pop()!;
- *       if (!visited.includes(node)) {
- *         visited.push(node);
- *         graph[node].forEach(neighbor => stack.push(neighbor));
- *       }
- *     }
- *     console.log(visited); // [1, 3, 5, 2, 4]
+ *     console.log(stack.pop()); // 8;
  * @example
  * // Backtracking Algorithms
- *     const stack = new Stack<[number, number]>();
+ *  const stack = new Stack<[number, number]>();
  *     const maze = [
  *       ['S', ' ', 'X'],
  *       ['X', ' ', 'X'],
@@ -109,28 +136,10 @@ import { IterableElementBase } from '../base';
  *       }
  *     }
  *
- *     expect(path).toContainEqual(end);
- * @example
- * // Function Call Stack
- *     const functionStack = new Stack<string>();
- *     functionStack.push('main');
- *     functionStack.push('foo');
- *     functionStack.push('bar');
- *     console.log(functionStack.pop()); // 'bar'
- *     console.log(functionStack.pop()); // 'foo'
- *     console.log(functionStack.pop()); // 'main'
- * @example
- * // Simplify File Paths
- *     const stack = new Stack<string>();
- *     const path = '/a/./b/../../c';
- *     path.split('/').forEach(segment => {
- *       if (segment === '..') stack.pop();
- *       else if (segment && segment !== '.') stack.push(segment);
- *     });
- *     console.log(stack.elements.join('/')); // 'c'
+ *     console.log(path); // contains end;
  * @example
  * // Stock Span Problem
- *     const stack = new Stack<number>();
+ *  const stack = new Stack<number>();
  *     const prices = [100, 80, 60, 70, 60, 75, 85];
  *     const spans: number[] = [];
  *     prices.forEach((price, i) => {
@@ -140,7 +149,16 @@ import { IterableElementBase } from '../base';
  *       spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);
  *       stack.push(i);
  *     });
- *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6]
+ *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6];
+ * @example
+ * // Simplify File Paths
+ *  const stack = new Stack<string>();
+ *     const path = '/a/./b/../../c';
+ *     path.split('/').forEach(segment => {
+ *       if (segment === '..') stack.pop();
+ *       else if (segment && segment !== '.') stack.push(segment);
+ *     });
+ *     console.log(stack.elements.join('/')); // 'c';
  */
 export class Stack<E = any, R = any> extends IterableElementBase<E, R> {
   protected _equals: (a: E, b: E) => boolean = Object.is as unknown as (a: E, b: E) => boolean;