binary-tree-typed 2.4.4 → 2.5.0

package/dist/types/data-structures/queue/deque.d.ts

@@ -18,71 +18,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;
@@ -133,6 +68,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 declare class Deque<E = any, R = any> extends LinearBase<E, R> {
     protected _equals: (a: E, b: E) => boolean;
@@ -143,7 +82,10 @@ export declare class Deque<E = any, R = any> extends LinearBase<E, R> {
      * @param [options] - Options such as bucketSize, toElementFn, and maxLen.
      * @returns New Deque instance.
      */
-    constructor(elements?: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R>, options?: DequeOptions<E, R>);
+    constructor(elements?: IterableWithSizeOrLength<E>, options?: DequeOptions<E, R>);
+    constructor(elements: IterableWithSizeOrLength<R>, options: DequeOptions<E, R> & {
+        toElementFn: (rawElement: R) => E;
+    });
     protected _bucketSize: number;
     /**
      * Get the current bucket size.
@@ -151,6 +93,26 @@ export declare class Deque<E = any, R = any> extends LinearBase<E, R> {
      * @returns Bucket capacity per bucket.
      */
     get bucketSize(): number;
+    protected _autoCompactRatio: number;
+    /**
+     * 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;
+    /**
+     * 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);
+    /**
+     * Counter for shift/pop operations since last compaction check.
+     * Only checks ratio every `_bucketSize` operations to minimize overhead.
+     */
+    protected _compactCounter: number;
     protected _bucketFirst: number;
     /**
      * Get the index of the first bucket in use.
@@ -204,12 +166,53 @@ export declare 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;
     /**
      * 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;
     /**
@@ -228,18 +231,79 @@ export declare 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;
     /**
      * 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;
     /**
      * 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;
     /**
@@ -247,6 +311,32 @@ export declare 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;
     /**
@@ -267,12 +357,39 @@ export declare 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;
     /**
      * 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;
     /**
@@ -280,6 +397,19 @@ export declare 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;
     /**
@@ -336,6 +466,19 @@ export declare 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;
     /**
@@ -356,6 +499,35 @@ export declare 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;
     /**
@@ -369,11 +541,59 @@ export declare class Deque<E = any, R = any> extends LinearBase<E, R> {
      * @remarks Time O(N), Space O(1)
      * @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;
+    /**
+     * 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;
     shrinkToFit(): void;
     /**
      * 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;
     /**
@@ -382,6 +602,20 @@ export declare 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;
     /**
@@ -401,6 +635,19 @@ export declare 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>(callback: ElementCallback<E, R, EM>, options?: IterableElementBaseOptions<EM, RM>, thisArg?: any): Deque<EM, RM>;
     /**