binary-tree-typed 2.4.5 → 2.5.0

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

@@ -21,48 +21,6 @@ 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
- * // basic Queue creation and push operation
- *  // Create a simple Queue with initial values
- *     const queue = new Queue([1, 2, 3, 4, 5]);
- *
- *     // Verify the queue maintains insertion order
- *     console.log([...queue]); // [1, 2, 3, 4, 5];
- *
- *     // Check length
- *     console.log(queue.length); // 5;
- * @example
- * // Queue shift and peek operations
- *  const queue = new Queue<number>([10, 20, 30, 40]);
- *
- *     // Peek at the front element without removing it
- *     console.log(queue.first); // 10;
- *
- *     // Remove and get the first element (FIFO)
- *     const first = queue.shift();
- *     console.log(first); // 10;
- *
- *     // Verify remaining elements and length decreased
- *     console.log([...queue]); // [20, 30, 40];
- *     console.log(queue.length); // 3;
- * @example
- * // 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'];
- *
- *     // 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;
@@ -123,6 +81,10 @@ import { LinearBase } from '../base/linear-base';
  *
  *     // Queue should be empty after processing all messages
  *     console.log(messageQueue.length); // 0;
+ * @example
+ * // Convert queue to array
+ *  const q = new Queue<number>([10, 20, 30]);
+ *     console.log(q.toArray()); // [10, 20, 30];
  */
 export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
     /**
@@ -165,12 +127,46 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * Get the number of elements currently in the queue.
      * @remarks Time O(1), Space O(1)
      * @returns Current length.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Track queue length
+   *  const q = new Queue<number>();
+   *     console.log(q.length); // 0;
+   *     q.push(1);
+   *     q.push(2);
+   *     console.log(q.length); // 2;
      */
     get length(): number;
     /**
      * Get the first element (front) without removing it.
      * @remarks Time O(1), Space O(1)
      * @returns Front element or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // View the front element
+   *  const q = new Queue<string>(['first', 'second', 'third']);
+   *     console.log(q.first); // 'first';
+   *     console.log(q.length); // 3;
      */
     get first(): E | undefined;
     /**
@@ -191,6 +187,35 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * Check whether the queue is empty.
      * @remarks Time O(1), Space O(1)
      * @returns True if length is 0.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // 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'];
+   *
+   *     // Process all elements
+   *     while (queue.length > 0) {
+   *       queue.shift();
+   *     }
+   *
+   *     console.log(queue.length); // 0;
      */
     isEmpty(): boolean;
     /**
@@ -198,6 +223,27 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * @remarks Time O(1), Space O(1)
      * @param element - Element to enqueue.
      * @returns True on success.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // basic Queue creation and push operation
+   *  // Create a simple Queue with initial values
+   *     const queue = new Queue([1, 2, 3, 4, 5]);
+   *
+   *     // Verify the queue maintains insertion order
+   *     console.log([...queue]); // [1, 2, 3, 4, 5];
+   *
+   *     // Check length
+   *     console.log(queue.length); // 5;
      */
     push(element: E): boolean;
     /**
@@ -211,6 +257,31 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * Dequeue one element from the front (amortized via offset).
      * @remarks Time O(1) amortized, Space O(1)
      * @returns Removed element or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Queue shift and peek operations
+   *  const queue = new Queue<number>([10, 20, 30, 40]);
+   *
+   *     // Peek at the front element without removing it
+   *     console.log(queue.first); // 10;
+   *
+   *     // Remove and get the first element (FIFO)
+   *     const first = queue.shift();
+   *     console.log(first); // 10;
+   *
+   *     // Verify remaining elements and length decreased
+   *     console.log([...queue]); // [20, 30, 40];
+   *     console.log(queue.length); // 3;
      */
     shift(): E | undefined;
     /**
@@ -218,6 +289,19 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * @remarks Time O(N), Space O(1)
      * @param element - Element to remove (strict equality via Object.is).
      * @returns True if an element was removed.
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove specific element
+   *  const q = new Queue<number>([1, 2, 3, 2]);
+   *     q.delete(2);
+   *     console.log(q.length); // 3;
      */
     delete(element: E): boolean;
     /**
@@ -225,6 +309,19 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * @remarks Time O(1), Space O(1)
      * @param index - Zero-based index from the front.
      * @returns Element or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Access element by index
+   *  const q = new Queue<string>(['a', 'b', 'c']);
+   *     console.log(q.at(0)); // 'a';
+   *     console.log(q.at(2)); // 'c';
      */
     at(index: number): E | undefined;
     /**
@@ -260,12 +357,41 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * Remove all elements and reset offset.
      * @remarks Time O(1), Space O(1)
      * @returns void
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove all elements
+   *  const q = new Queue<number>([1, 2, 3]);
+   *     q.clear();
+   *     console.log(q.length); // 0;
      */
     clear(): void;
     /**
      * Compact storage by discarding consumed head elements.
      * @remarks Time O(N), Space O(N)
      * @returns True when compaction performed.
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Reclaim unused memory
+   *  const q = new Queue<number>([1, 2, 3, 4, 5]);
+   *     q.shift();
+   *     q.shift();
+   *     q.compact();
+   *     console.log(q.length); // 3;
      */
     compact(): boolean;
     /**
@@ -281,6 +407,22 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * Deep clone this queue and its parameters.
      * @remarks Time O(N), Space O(N)
      * @returns A new queue with the same content and options.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Create independent copy
+   *  const q = new Queue<number>([1, 2, 3]);
+   *     const copy = q.clone();
+   *     copy.shift();
+   *     console.log(q.length); // 3;
+   *     console.log(copy.length); // 2;
      */
     clone(): this;
     /**
@@ -289,6 +431,20 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * @param predicate - Predicate (element, index, queue) → boolean to keep element.
      * @param [thisArg] - Value for `this` inside the predicate.
      * @returns A new queue with kept elements.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Filter elements
+   *  const q = new Queue<number>([1, 2, 3, 4, 5]);
+   *     const evens = q.filter(x => x % 2 === 0);
+   *     console.log(evens.length); // 2;
      */
     filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
     /**
@@ -300,6 +456,19 @@ export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
      * @param [options] - Options for the output queue (e.g., toElementFn, maxLen, autoCompactRatio).
      * @param [thisArg] - Value for `this` inside the callback.
      * @returns A new Queue with mapped elements.
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform elements
+   *  const q = new Queue<number>([1, 2, 3]);
+   *     const doubled = q.map(x => x * 2);
+   *     console.log(doubled.toArray()); // [2, 4, 6];
      */
     map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: QueueOptions<EM, RM>, thisArg?: unknown): Queue<EM, RM>;
     /**

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

@@ -19,38 +19,6 @@ 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');
@@ -157,6 +125,10 @@ import { IterableElementBase } from '../base';
  *       else if (segment && segment !== '.') stack.push(segment);
  *     });
  *     console.log(stack.elements.join('/')); // 'c';
+ * @example
+ * // Convert stack to array
+ *  const stack = new Stack<number>([1, 2, 3]);
+ *     console.log(stack.toArray()); // [1, 2, 3];
  */
 export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
     protected _equals: (a: E, b: E) => boolean;
@@ -179,6 +151,19 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * Get the number of stored elements.
      * @remarks Time O(1), Space O(1)
      * @returns Current size.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Get number of elements
+   *  const stack = new Stack<number>([1, 2, 3]);
+   *     console.log(stack.size); // 3;
      */
     get size(): number;
     /**
@@ -196,12 +181,45 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * Check whether the stack is empty.
      * @remarks Time O(1), Space O(1)
      * @returns True if size is 0.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Check if stack has elements
+   *  const stack = new Stack<number>();
+   *     console.log(stack.isEmpty()); // true;
+   *     stack.push(1);
+   *     console.log(stack.isEmpty()); // false;
      */
     isEmpty(): boolean;
     /**
      * Get the top element without removing it.
      * @remarks Time O(1), Space O(1)
      * @returns Top element or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // View the top element without removing it
+   *  const stack = new Stack<string>(['a', 'b', 'c']);
+   *     console.log(stack.peek()); // 'c';
+   *     console.log(stack.size); // 3;
      */
     peek(): E | undefined;
     /**
@@ -209,12 +227,66 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * @remarks Time O(1), Space O(1)
      * @param element - Element to push.
      * @returns True when pushed.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @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;
      */
     push(element: E): boolean;
     /**
      * Pop and return the top element.
      * @remarks Time O(1), Space O(1)
      * @returns Removed element or undefined.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @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;
      */
     pop(): E | undefined;
     /**
@@ -229,6 +301,19 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<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 stack = new Stack<number>([1, 2, 3]);
+   *     stack.delete(2);
+   *     console.log(stack.toArray()); // [1, 3];
      */
     delete(element: E): boolean;
     /**
@@ -249,12 +334,42 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * Remove all elements and reset storage.
      * @remarks Time O(1), Space O(1)
      * @returns void
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Remove all elements
+   *  const stack = new Stack<number>([1, 2, 3]);
+   *     stack.clear();
+   *     console.log(stack.isEmpty()); // true;
      */
     clear(): void;
     /**
      * Deep clone this stack.
      * @remarks Time O(N), Space O(N)
      * @returns A new stack with the same content.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Create independent copy
+   *  const stack = new Stack<number>([1, 2, 3]);
+   *     const copy = stack.clone();
+   *     copy.pop();
+   *     console.log(stack.size); // 3;
+   *     console.log(copy.size); // 2;
      */
     clone(): this;
     /**
@@ -263,6 +378,20 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * @param predicate - Predicate (value, index, stack) → boolean to keep value.
      * @param [thisArg] - Value for `this` inside the predicate.
      * @returns A new stack with kept values.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Filter elements
+   *  const stack = new Stack<number>([1, 2, 3, 4, 5]);
+   *     const evens = stack.filter(x => x % 2 === 0);
+   *     console.log(evens.toArray()); // [2, 4];
      */
     filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
     /**
@@ -282,6 +411,19 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
      * @param [options] - Options for the output stack (e.g., toElementFn).
      * @param [thisArg] - Value for `this` inside the callback.
      * @returns A new Stack with mapped elements.
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Transform elements
+   *  const stack = new Stack<number>([1, 2, 3]);
+   *     const doubled = stack.map(x => x * 2);
+   *     console.log(doubled.toArray()); // [2, 4, 6];
      */
     map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: IterableElementBaseOptions<EM, RM>, thisArg?: unknown): Stack<EM, RM>;
     /**