binary-tree-typed 2.4.4 → 2.5.0

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

@@ -11,6 +11,66 @@ import { Heap } from '../heap';
 
 /**
  * @example
+ * // Hospital emergency room triage
+ *  interface Patient {
+ *       name: string;
+ *       severity: number; // 1 = critical, 5 = minor
+ *     }
+ *
+ *     const er = new PriorityQueue<Patient>([], {
+ *       comparator: (a, b) => a.severity - b.severity
+ *     });
+ *
+ *     er.add({ name: 'Flu symptoms', severity: 4 });
+ *     er.add({ name: 'Heart attack', severity: 1 });
+ *     er.add({ name: 'Broken arm', severity: 3 });
+ *     er.add({ name: 'Stroke', severity: 1 });
+ *
+ *     // Most critical patients first
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 3;
+ *     console.log(er.poll()?.severity); // 4;
+ * @example
+ * // Task scheduler with deadlines
+ *  interface Task {
+ *       name: string;
+ *       deadline: number; // hours until due
+ *     }
+ *
+ *     const scheduler = new PriorityQueue<Task>([], {
+ *       comparator: (a, b) => a.deadline - b.deadline
+ *     });
+ *
+ *     scheduler.add({ name: 'Report', deadline: 24 });
+ *     scheduler.add({ name: 'Email', deadline: 2 });
+ *     scheduler.add({ name: 'Meeting prep', deadline: 4 });
+ *     scheduler.add({ name: 'Code review', deadline: 8 });
+ *
+ *     // Process most urgent first
+ *     console.log(scheduler.peek()?.name); // 'Email';
+ *     console.log(scheduler.size); // 4;
+ *
+ *     const order = [];
+ *     while (scheduler.size > 0) {
+ *       order.push(scheduler.poll()!.name);
+ *     }
+ *     console.log(order); // ['Email', 'Meeting prep', 'Code review', 'Report'];
+ * @example
+ * // Bandwidth allocation with priorities
+ *  const bandwidth = new PriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => a[0] - b[0]
+ *     });
+ *
+ *     bandwidth.add([1, 'Video call']);     // highest priority
+ *     bandwidth.add([3, 'File download']);
+ *     bandwidth.add([2, 'Web browsing']);
+ *     bandwidth.add([1, 'Voice call']);
+ *
+ *     // Allocate bandwidth to highest priority first
+ *     console.log(bandwidth.poll()?.[1]); // 'Video call';
+ *     console.log(bandwidth.poll()?.[1]); // 'Voice call';
+ *     console.log(bandwidth.size); // 2;
  */
 export class PriorityQueue<E = any, R = any> extends Heap<E, R> {
   constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {

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

@@ -27,71 +27,6 @@ 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
- * // basic Deque creation and push/pop operations
- *  // Create a simple Deque with initial values
- *     const deque = new Deque([1, 2, 3, 4, 5]);
- *
- *     // Verify the deque maintains insertion order
- *     console.log([...deque]); // [1, 2, 3, 4, 5];
- *
- *     // Check length
- *     console.log(deque.length); // 5;
- *
- *     // Push to the end
- *     deque.push(6);
- *     console.log(deque.length); // 6;
- *
- *     // 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]);
- *
- *     // Unshift adds to the front
- *     deque.unshift(10);
- *     console.log([...deque]); // [10, 20, 30, 40];
- *
- *     // Shift removes from the front (O(1) complexity!)
- *     const first = deque.shift();
- *     console.log(first); // 10;
- *
- *     // 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]);
- *
- *     // Get first element without removing
- *     const first = deque.at(0);
- *     console.log(first); // 10;
- *
- *     // Get last element without removing
- *     const last = deque.at(deque.length - 1);
- *     console.log(last); // 50;
- *
- *     // Length unchanged
- *     console.log(deque.length); // 5;
- * @example
- * // Deque for...of iteration and reverse
- *  const deque = new Deque<string>(['A', 'B', 'C', 'D']);
- *
- *     // Iterate forward
- *     const forward: string[] = [];
- *     for (const item of deque) {
- *       forward.push(item);
- *     }
- *     console.log(forward); // ['A', 'B', 'C', 'D'];
- *
- *     // 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;
@@ -142,6 +77,10 @@ import { LinearBase } from '../base/linear-base';
  *     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;
+ * @example
+ * // Convert deque to array
+ *  const dq = new Deque<number>([10, 20, 30]);
+ *     console.log(dq.toArray()); // [10, 20, 30];
  */
 export class Deque<E = any, R = any> extends LinearBase<E, R> {
   protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);
@@ -154,12 +93,15 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @returns New Deque instance.
    */
 
+  constructor(elements?: IterableWithSizeOrLength<E>, options?: DequeOptions<E, R>);
+  constructor(elements: IterableWithSizeOrLength<R>, options: DequeOptions<E, R> & { toElementFn: (rawElement: R) => E });
   constructor(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R> = [], options?: DequeOptions<E, R>) {
     super(options);
 
     if (options) {
-      const { bucketSize } = options;
+      const { bucketSize, autoCompactRatio } = options;
       if (typeof bucketSize === 'number') this._bucketSize = bucketSize;
+      if (typeof autoCompactRatio === 'number') this._autoCompactRatio = autoCompactRatio;
     }
 
     let _size: number;
@@ -191,6 +133,34 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
     return this._bucketSize;
   }
 
+  protected _autoCompactRatio = 0.5;
+
+  /**
+   * Get the auto-compaction ratio.
+   * When `elements / (bucketCount * bucketSize)` drops below this ratio after
+   * enough shift/pop operations, the deque auto-compacts.
+   * @remarks Time O(1), Space O(1)
+   * @returns Current ratio threshold. 0 means auto-compact is disabled.
+   */
+  get autoCompactRatio(): number {
+    return this._autoCompactRatio;
+  }
+
+  /**
+   * Set the auto-compaction ratio.
+   * @remarks Time O(1), Space O(1)
+   * @param value - Ratio in [0,1]. 0 disables auto-compact.
+   */
+  set autoCompactRatio(value: number) {
+    this._autoCompactRatio = value;
+  }
+
+  /**
+   * Counter for shift/pop operations since last compaction check.
+   * Only checks ratio every `_bucketSize` operations to minimize overhead.
+   */
+  protected _compactCounter = 0;
+
   protected _bucketFirst = 0;
 
   /**
@@ -279,6 +249,31 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Get the first element without removing it.
    * @remarks Time O(1), Space O(1)
    * @returns First element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deque peek at both ends
+ *  const deque = new Deque<number>([10, 20, 30, 40, 50]);
+ *
+ *     // Get first element without removing
+ *     const first = deque.at(0);
+ *     console.log(first); // 10;
+ *
+ *     // Get last element without removing
+ *     const last = deque.at(deque.length - 1);
+ *     console.log(last); // 50;
+ *
+ *     // Length unchanged
+ *     console.log(deque.length); // 5;
    */
 
   get first(): E | undefined {
@@ -290,6 +285,22 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Get the last element without removing it.
    * @remarks Time O(1), Space O(1)
    * @returns Last element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Peek at the back element
+ *  const dq = new Deque<string>(['a', 'b', 'c']);
+ *     console.log(dq.last); // 'c';
+ *     console.log(dq.first); // 'a';
    */
 
   get last(): E | undefined {
@@ -324,6 +335,35 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(1) amortized, Space O(1)
    * @param element - Element to append.
    * @returns True when appended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // basic Deque creation and push/pop operations
+ *  // Create a simple Deque with initial values
+ *     const deque = new Deque([1, 2, 3, 4, 5]);
+ *
+ *     // Verify the deque maintains insertion order
+ *     console.log([...deque]); // [1, 2, 3, 4, 5];
+ *
+ *     // Check length
+ *     console.log(deque.length); // 5;
+ *
+ *     // Push to the end
+ *     deque.push(6);
+ *     console.log(deque.length); // 6;
+ *
+ *     // Pop from the end
+ *     const last = deque.pop();
+ *     console.log(last); // 6;
    */
 
   push(element: E): boolean {
@@ -349,6 +389,22 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Remove and return the last element.
    * @remarks Time O(1), Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove from the back
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     console.log(dq.pop()); // 3;
+ *     console.log(dq.length); // 2;
    */
 
   pop(): E | undefined {
@@ -366,6 +422,7 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
 
@@ -373,6 +430,22 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Remove and return the first element.
    * @remarks Time O(1) amortized, Space O(1)
    * @returns Removed element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove from the front
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     console.log(dq.shift()); // 1;
+ *     console.log(dq.length); // 2;
    */
 
   shift(): E | undefined {
@@ -390,6 +463,7 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
       }
     }
     this._length -= 1;
+    this._autoCompact();
     return element;
   }
 
@@ -398,6 +472,32 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(1) amortized, Space O(1)
    * @param element - Element to prepend.
    * @returns True when prepended.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deque shift and unshift operations
+ *  const deque = new Deque<number>([20, 30, 40]);
+ *
+ *     // Unshift adds to the front
+ *     deque.unshift(10);
+ *     console.log([...deque]); // [10, 20, 30, 40];
+ *
+ *     // Shift removes from the front (O(1) complexity!)
+ *     const first = deque.shift();
+ *     console.log(first); // 10;
+ *
+ *     // Verify remaining elements
+ *     console.log([...deque]); // [20, 30, 40];
+ *     console.log(deque.length); // 3;
    */
 
   unshift(element: E): boolean {
@@ -461,6 +561,19 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Check whether the deque is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if length is 0.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Check if empty
+ *  const dq = new Deque();
+ *     console.log(dq.isEmpty()); // true;
    */
 
   isEmpty(): boolean {
@@ -471,6 +584,20 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Remove all elements and reset structure.
    * @remarks Time O(1), Space O(1)
    * @returns void
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove all elements
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     dq.clear();
+ *     console.log(dq.length); // 0;
    */
 
   clear(): void {
@@ -485,6 +612,19 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(1), Space O(1)
    * @param pos - Zero-based position from the front.
    * @returns Element or undefined.
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Access by index
+ *  const dq = new Deque<string>(['a', 'b', 'c']);
+ *     console.log(dq.at(0)); // 'a';
+ *     console.log(dq.at(2)); // 'c';
    */
 
   at(pos: number): E | undefined {
@@ -672,6 +812,19 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @remarks Time O(N), Space O(1)
    * @param element - Element to remove (using the configured equality).
    * @returns True if an element was removed.
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Remove element
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     dq.delete(2);
+ *     console.log(dq.length); // 2;
    */
 
   delete(element: E): boolean {
@@ -725,6 +878,35 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * Reverse the deque by reversing buckets and pointers.
    * @remarks Time O(N), Space O(N)
    * @returns This deque.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Deque for...of iteration and reverse
+ *  const deque = new Deque<string>(['A', 'B', 'C', 'D']);
+ *
+ *     // Iterate forward
+ *     const forward: string[] = [];
+ *     for (const item of deque) {
+ *       forward.push(item);
+ *     }
+ *     console.log(forward); // ['A', 'B', 'C', 'D'];
+ *
+ *     // Reverse the deque
+ *     deque.reverse();
+ *     const backward: string[] = [];
+ *     for (const item of deque) {
+ *       backward.push(item);
+ *     }
+ *     console.log(backward); // ['D', 'C', 'B', 'A'];
    */
 
   reverse(): this {
@@ -768,11 +950,59 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @returns void
    */
 
+  /**
+   * (Protected) Trigger auto-compaction if space utilization drops below threshold.
+   * Only checks every `_bucketSize` operations to minimize hot-path overhead.
+   * Uses element-based ratio: `elements / (bucketCount * bucketSize)`.
+   */
+  protected _autoCompact(): void {
+    if (this._autoCompactRatio <= 0 || this._bucketCount <= 1) return;
+
+    this._compactCounter++;
+    if (this._compactCounter < this._bucketSize) return;
+    this._compactCounter = 0;
+
+    const utilization = this._length / (this._bucketCount * this._bucketSize);
+    if (utilization < this._autoCompactRatio) {
+      this.shrinkToFit();
+    }
+  }
+
+  /**
+   * Compact the deque by removing unused buckets.
+   * @remarks Time O(N), Space O(1)
+   * @returns True if compaction was performed (bucket count reduced).
+   */
+  /**
+   * Compact the deque by removing unused buckets.
+   * @remarks Time O(N), Space O(1)
+   * @returns True if compaction was performed (bucket count reduced).
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Reclaim memory
+ *  const dq = new Deque<number>([1, 2, 3, 4, 5]);
+ *     dq.shift();
+ *     dq.shift();
+ *     dq.compact();
+ *     console.log(dq.length); // 3;
+   */
+  compact(): boolean {
+    const before = this._bucketCount;
+    this.shrinkToFit();
+    return this._bucketCount < before;
+  }
+
   shrinkToFit(): void {
     if (this._length === 0) return;
     const newBuckets = [] as E[][];
-    if (this._bucketFirst === this._bucketLast) return;
-    else if (this._bucketFirst < this._bucketLast) {
+    if (this._bucketFirst <= this._bucketLast) {
       for (let i = this._bucketFirst; i <= this._bucketLast; ++i) {
         newBuckets.push(this._buckets[i]);
       }
@@ -787,12 +1017,30 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
     this._bucketFirst = 0;
     this._bucketLast = newBuckets.length - 1;
     this._buckets = newBuckets;
+    this._bucketCount = newBuckets.length;
+    this._compactCounter = 0;
   }
 
   /**
    * Deep clone this deque, preserving options.
    * @remarks Time O(N), Space O(N)
    * @returns A new deque with the same content and options.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Create independent copy
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     const copy = dq.clone();
+ *     copy.pop();
+ *     console.log(dq.length); // 3;
+ *     console.log(copy.length); // 2;
    */
 
   clone(): this {
@@ -809,6 +1057,20 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @param predicate - Predicate (value, index, deque) → boolean to keep element.
    * @param [thisArg] - Value for `this` inside the predicate.
    * @returns A new deque with kept elements.
+   
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Filter elements
+ *  const dq = new Deque<number>([1, 2, 3, 4]);
+ *     const result = dq.filter(x => x > 2);
+ *     console.log(result.length); // 2;
    */
 
   filter(predicate: ElementCallback<E, R, boolean>, thisArg?: any): this {
@@ -850,6 +1112,19 @@ export class Deque<E = any, R = any> extends LinearBase<E, R> {
    * @param [options] - Options for the output deque (e.g., bucketSize, toElementFn, maxLen).
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new Deque with mapped elements.
+   
+   
+   
+   
+   
+   
+   
+   
+    * @example
+ * // Transform elements
+ *  const dq = new Deque<number>([1, 2, 3]);
+ *     const result = dq.map(x => x * 10);
+ *     console.log(result.toArray()); // [10, 20, 30];
    */
 
   map<EM, RM>(