data-structure-typed 2.0.5 → 2.1.1

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

@@ -0,0 +1,308 @@
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import type { ElementCallback, LinearBaseOptions, QueueOptions } from '../../types';
+import { SinglyLinkedList } from '../linked-list';
+import { LinearBase } from '../base/linear-base';
+/**
+ * Array-backed queue with amortized O(1) enqueue/dequeue via an offset pointer and optional auto-compaction.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @template R
+ * 1. First In, First Out (FIFO): The core feature of a queue is its first in, first out nature. The element added to the queue first will be the one to be removed first.
+ * 2. Operations: The main operations include enqueue (adding an element to the end of the queue) and dequeue (removing and returning the element at the front of the queue). Typically, there is also a peek operation (looking at the front element without removing it).
+ * 3. Uses: Queues are commonly used to manage a series of tasks or elements that need to be processed in order. For example, managing task queues in a multi-threaded environment, or in algorithms for data structures like trees and graphs for breadth-first search.
+ * 4. Task Scheduling: Managing the order of task execution in operating systems or applications.
+ * 5. Data Buffering: Acting as a buffer for data packets in network communication.
+ * 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>();
+ *
+ *     let maxSum = 0;
+ *     let currentSum = 0;
+ *
+ *     nums.forEach(num => {
+ *       queue.push(num);
+ *       currentSum += num;
+ *
+ *       if (queue.length > k) {
+ *         currentSum -= queue.shift()!;
+ *       }
+ *
+ *       if (queue.length === k) {
+ *         maxSum = Math.max(maxSum, currentSum);
+ *       }
+ *     });
+ *
+ *     console.log(maxSum); // 7
+ * @example
+ * // Breadth-First Search (BFS) using Queue
+ *     const graph: { [key in number]: number[] } = {
+ *       1: [2, 3],
+ *       2: [4, 5],
+ *       3: [],
+ *       4: [],
+ *       5: []
+ *     };
+ *
+ *     const queue = new Queue<number>();
+ *     const visited: number[] = [];
+ *
+ *     queue.push(1);
+ *
+ *     while (!queue.isEmpty()) {
+ *       const node = queue.shift()!;
+ *       if (!visited.includes(node)) {
+ *         visited.push(node);
+ *         graph[node].forEach(neighbor => queue.push(neighbor));
+ *       }
+ *     }
+ *
+ *     console.log(visited); // [1, 2, 3, 4, 5]
+ */
+export declare class Queue<E = any, R = any> extends LinearBase<E, R> {
+    /**
+     * Create a Queue and optionally bulk-insert elements.
+     * @remarks Time O(N), Space O(N)
+     * @param [elements] - Iterable of elements (or raw records if toElementFn is set).
+     * @param [options] - Options such as toElementFn, maxLen, and autoCompactRatio.
+     * @returns New Queue instance.
+     */
+    constructor(elements?: Iterable<E> | Iterable<R>, options?: QueueOptions<E, R>);
+    protected _elements: E[];
+    /**
+     * Get the underlying array buffer.
+     * @remarks Time O(1), Space O(1)
+     * @returns Backing array of elements.
+     */
+    get elements(): E[];
+    protected _offset: number;
+    /**
+     * Get the current start offset into the array.
+     * @remarks Time O(1), Space O(1)
+     * @returns Zero-based offset.
+     */
+    get offset(): number;
+    protected _autoCompactRatio: number;
+    /**
+     * Get the compaction threshold (offset/size).
+     * @remarks Time O(1), Space O(1)
+     * @returns Auto-compaction ratio in (0,1].
+     */
+    get autoCompactRatio(): number;
+    /**
+     * Set the compaction threshold.
+     * @remarks Time O(1), Space O(1)
+     * @param value - New ratio; compacts when offset/size exceeds this value.
+     * @returns void
+     */
+    set autoCompactRatio(value: number);
+    /**
+     * Get the number of elements currently in the queue.
+     * @remarks Time O(1), Space O(1)
+     * @returns Current length.
+     */
+    get length(): number;
+    /**
+     * Get the first element (front) without removing it.
+     * @remarks Time O(1), Space O(1)
+     * @returns Front element or undefined.
+     */
+    get first(): E | undefined;
+    /**
+     * Get the last element (back) without removing it.
+     * @remarks Time O(1), Space O(1)
+     * @returns Back element or undefined.
+     */
+    get last(): E | undefined;
+    /**
+     * Create a queue from an array of elements.
+     * @remarks Time O(N), Space O(N)
+     * @template E
+     * @param elements - Array of elements to enqueue in order.
+     * @returns A new queue populated from the array.
+     */
+    static fromArray<E>(elements: E[]): Queue<E>;
+    /**
+     * Check whether the queue is empty.
+     * @remarks Time O(1), Space O(1)
+     * @returns True if length is 0.
+     */
+    isEmpty(): boolean;
+    /**
+     * Enqueue one element at the back.
+     * @remarks Time O(1), Space O(1)
+     * @param element - Element to enqueue.
+     * @returns True on success.
+     */
+    push(element: E): boolean;
+    /**
+     * Enqueue many elements from an iterable.
+     * @remarks Time O(N), Space O(1)
+     * @param elements - Iterable of elements (or raw records if toElementFn is set).
+     * @returns Array of per-element success flags.
+     */
+    pushMany(elements: Iterable<E> | Iterable<R>): boolean[];
+    /**
+     * Dequeue one element from the front (amortized via offset).
+     * @remarks Time O(1) amortized, Space O(1)
+     * @returns Removed element or undefined.
+     */
+    shift(): E | undefined;
+    /**
+     * Delete the first occurrence of a specific element.
+     * @remarks Time O(N), Space O(1)
+     * @param element - Element to remove (strict equality via Object.is).
+     * @returns True if an element was removed.
+     */
+    delete(element: E): boolean;
+    /**
+     * Get the element at a given logical index.
+     * @remarks Time O(1), Space O(1)
+     * @param index - Zero-based index from the front.
+     * @returns Element or undefined.
+     */
+    at(index: number): E | undefined;
+    /**
+     * Delete the element at a given index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index from the front.
+     * @returns Removed element or undefined.
+     */
+    deleteAt(index: number): E | undefined;
+    /**
+     * Insert a new element at a given index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index from the front.
+     * @param newElement - Element to insert.
+     * @returns True if inserted.
+     */
+    addAt(index: number, newElement: E): boolean;
+    /**
+     * Replace the element at a given index.
+     * @remarks Time O(1), Space O(1)
+     * @param index - Zero-based index from the front.
+     * @param newElement - New element to set.
+     * @returns True if updated.
+     */
+    setAt(index: number, newElement: E): boolean;
+    /**
+     * Reverse the queue in-place by compacting then reversing.
+     * @remarks Time O(N), Space O(N)
+     * @returns This queue.
+     */
+    reverse(): this;
+    /**
+     * Remove all elements and reset offset.
+     * @remarks Time O(1), Space O(1)
+     * @returns void
+     */
+    clear(): void;
+    /**
+     * Compact storage by discarding consumed head elements.
+     * @remarks Time O(N), Space O(N)
+     * @returns True when compaction performed.
+     */
+    compact(): boolean;
+    /**
+     * Remove and/or insert elements at a position (array-like).
+     * @remarks Time O(N + M), Space O(M)
+     * @param start - Start index (clamped to [0, length]).
+     * @param [deleteCount] - Number of elements to remove (default 0).
+     * @param [items] - Elements to insert after `start`.
+     * @returns A new queue containing the removed elements (typed as `this`).
+     */
+    splice(start: number, deleteCount?: number, ...items: E[]): this;
+    /**
+     * Deep clone this queue and its parameters.
+     * @remarks Time O(N), Space O(N)
+     * @returns A new queue with the same content and options.
+     */
+    clone(): this;
+    /**
+     * Filter elements into a new queue of the same class.
+     * @remarks Time O(N), Space O(N)
+     * @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.
+     */
+    filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
+    /**
+     * Map each element to a new element in a possibly different-typed queue.
+     * @remarks Time O(N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param callback - Mapping function (element, index, queue) → newElement.
+     * @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.
+     */
+    map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: QueueOptions<EM, RM>, thisArg?: unknown): Queue<EM, RM>;
+    /**
+     * Map each element to a new value of the same type.
+     * @remarks Time O(N), Space O(N)
+     * @param callback - Mapping function (element, index, queue) → element.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new queue with mapped elements (same element type).
+     */
+    mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;
+    /**
+     * (Protected) Set the internal auto-compaction ratio.
+     * @remarks Time O(1), Space O(1)
+     * @param value - New ratio to assign.
+     * @returns void
+     */
+    protected _setAutoCompactRatio(value: number): void;
+    /**
+     * (Protected) Iterate elements from front to back.
+     * @remarks Time O(N), Space O(1)
+     * @returns Iterator of E.
+     */
+    protected _getIterator(): IterableIterator<E>;
+    /**
+     * (Protected) Iterate elements from back to front.
+     * @remarks Time O(N), Space O(1)
+     * @returns Iterator of E.
+     */
+    protected _getReverseIterator(): IterableIterator<E>;
+    /**
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @param [options] - Options forwarded to the constructor.
+     * @returns An empty like-kind queue instance.
+     */
+    protected _createInstance(options?: LinearBaseOptions<E, R>): this;
+    /**
+     * (Protected) Create a like-kind queue and seed it from an iterable.
+     * @remarks Time O(N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param [elements] - Iterable used to seed the new queue.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A like-kind Queue instance.
+     */
+    protected _createLike<EM = E, RM = R>(elements?: Iterable<EM> | Iterable<RM>, options?: QueueOptions<EM, RM>): Queue<EM, RM>;
+}
+/**
+ * Queue implemented over a singly linked list; preserves head/tail operations with linear scans for queries.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @template R
+ * @example examples will be generated by unit test
+ */
+export declare class LinkedListQueue<E = any, R = any> extends SinglyLinkedList<E, R> {
+    /**
+     * Deep clone this linked-list-based queue.
+     * @remarks Time O(N), Space O(N)
+     * @returns A new queue with the same sequence of elements.
+     */
+    clone(): this;
+}

package/dist/{cjs → types}/data-structures/stack/stack.d.ts

@@ -5,9 +5,13 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { ElementCallback, StackOptions } from '../../types';
+import type { ElementCallback, IterableElementBaseOptions, StackOptions } from '../../types';
 import { IterableElementBase } from '../base';
 /**
+ * LIFO stack with array storage and optional record→element conversion.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @template R
  * 1. Last In, First Out (LIFO): The core characteristic of a stack is its last in, first out nature, meaning the last element added to the stack will be the first to be removed.
  * 2. Uses: Stacks are commonly used for managing a series of tasks or elements that need to be processed in a last in, first out manner. They are widely used in various scenarios, such as in function calls in programming languages, evaluation of arithmetic expressions, and backtracking algorithms.
  * 3. Performance: Stack operations are typically O(1) in time complexity, meaning that regardless of the stack's size, adding, removing, and viewing the top element are very fast operations.
@@ -137,148 +141,166 @@ import { IterableElementBase } from '../base';
  *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6]
  */
 export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
+    protected _equals: (a: E, b: E) => boolean;
+    /**
+     * Create a Stack and optionally bulk-push elements.
+     * @remarks Time O(N), Space O(N)
+     * @param [elements] - Iterable of elements (or raw records if toElementFn is set).
+     * @param [options] - Options such as toElementFn and equality function.
+     * @returns New Stack instance.
+     */
     constructor(elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>);
     protected _elements: E[];
     /**
-     * The elements function returns the elements of this set.
-     * @return An array of elements
+     * Get the backing array of elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Internal elements array.
      */
     get elements(): E[];
     /**
-     * The size() function returns the number of elements in an array.
-     * @returns The size of the elements array.
+     * Get the number of stored elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Current size.
      */
     get size(): number;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The function "fromArray" creates a new Stack object from an array of elements.
-     * @param {E[]} elements - The `elements` parameter is an array of elements of type `E`.
-     * @returns {Stack} The method is returning a new instance of the Stack class, initialized with the elements from the input
-     * array.
+     * Create a stack from an array of elements.
+     * @remarks Time O(N), Space O(N)
+     * @template E
+     * @template R
+     * @param this - The constructor (subclass) to instantiate.
+     * @param elements - Array of elements to push in order.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A new Stack populated from the array.
      */
-    static fromArray<E>(elements: E[]): Stack<E>;
+    static fromArray<E, R = any>(this: new (elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>) => any, elements: E[], options?: StackOptions<E, R>): any;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function checks if an array is empty and returns a boolean value.
-     * @returns A boolean value indicating whether the `_elements` array is empty or not.
+     * Check whether the stack is empty.
+     * @remarks Time O(1), Space O(1)
+     * @returns True if size is 0.
      */
     isEmpty(): boolean;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `peek` function returns the last element of an array, or undefined if the array is empty.
-     * @returns The `peek()` function returns the last element of the `_elements` array, or `undefined` if the array is empty.
+     * Get the top element without removing it.
+     * @remarks Time O(1), Space O(1)
+     * @returns Top element or undefined.
      */
     peek(): E | undefined;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The push function adds an element to the stack and returns the updated stack.
-     * @param {E} element - The parameter "element" is of type E, which means it can be any data type.
-     * @returns The `push` method is returning the updated `Stack<E>` object.
+     * Push one element onto the top.
+     * @remarks Time O(1), Space O(1)
+     * @param element - Element to push.
+     * @returns True when pushed.
      */
     push(element: E): boolean;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `pop` function removes and returns the last element from an array, or returns undefined if the array is empty.
-     * @returns The `pop()` method is returning the last element of the array `_elements` if the array is not empty. If the
-     * array is empty, it returns `undefined`.
+     * Pop and return the top element.
+     * @remarks Time O(1), Space O(1)
+     * @returns Removed element or undefined.
      */
     pop(): E | undefined;
     /**
-     * Time Complexity: O(k)
-     * Space Complexity: O(1)
-     *
-     * The function `pushMany` iterates over elements and pushes them into an array after applying a
-     * transformation function if provided.
-     * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the `pushMany` function
-     * is an iterable containing elements of type `E` or `R`. The function iterates over each element in
-     * the iterable and pushes it into the data structure. If a transformation function `toElementFn` is
-     * provided, it is used to
-     * @returns The `pushMany` function is returning an array of boolean values indicating whether each
-     * element was successfully pushed into the data structure.
+     * Push many elements from an iterable.
+     * @remarks Time O(N), Space O(1)
+     * @param elements - Iterable of elements (or raw records if toElementFn is set).
+     * @returns Array of per-element success flags.
      */
     pushMany(elements: Iterable<E> | Iterable<R>): boolean[];
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The toArray function returns a copy of the elements in an array.
-     * @returns An array of type E.
+     * Delete the first occurrence of a specific element.
+     * @remarks Time O(N), Space O(1)
+     * @param element - Element to remove (using the configured equality).
+     * @returns True if an element was removed.
      */
     delete(element: E): boolean;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The toArray function returns a copy of the elements in an array.
-     * @returns An array of type E.
+     * Delete the element at an index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index from the bottom.
+     * @returns True if removed.
      */
     deleteAt(index: number): boolean;
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The clear function clears the elements array.
+     * Delete the first element that satisfies a predicate.
+     * @remarks Time O(N), Space O(1)
+     * @param predicate - Function (value, index, stack) → boolean to decide deletion.
+     * @returns True if a match was removed.
+     */
+    deleteWhere(predicate: (value: E, index: number, stack: this) => boolean): boolean;
+    /**
+     * Remove all elements and reset storage.
+     * @remarks Time O(1), Space O(1)
+     * @returns void
      */
     clear(): void;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `clone()` function returns a new `Stack` object with the same elements as the original stack.
-     * @returns The `clone()` method is returning a new `Stack` object with a copy of the `_elements` array.
+     * Deep clone this stack.
+     * @remarks Time O(N), Space O(N)
+     * @returns A new stack with the same content.
+     */
+    clone(): this;
+    /**
+     * Filter elements into a new stack of the same class.
+     * @remarks Time O(N), Space O(N)
+     * @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.
+     */
+    filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
+    /**
+     * Map values into a new stack of the same element type.
+     * @remarks Time O(N), Space O(N)
+     * @param callback - Mapping function (value, index, stack) → newValue.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new stack with mapped values.
+     */
+    mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;
+    /**
+     * Map values into a new stack (possibly different element type).
+     * @remarks Time O(N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param callback - Mapping function (value, index, stack) → newElement.
+     * @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.
+     */
+    map<EM, RM>(callback: ElementCallback<E, R, EM>, options?: IterableElementBaseOptions<EM, RM>, thisArg?: unknown): Stack<EM, RM>;
+    /**
+     * Set the equality comparator used by delete/search operations.
+     * @remarks Time O(1), Space O(1)
+     * @param equals - Equality predicate (a, b) → boolean.
+     * @returns This stack.
+     */
+    setEquality(equals: (a: E, b: E) => boolean): this;
+    /**
+     * (Protected) Find the index of a target element using the equality function.
+     * @remarks Time O(N), Space O(1)
+     * @param target - Element to search for.
+     * @returns Index or -1 if not found.
      */
-    clone(): Stack<E, R>;
+    protected _indexOfByEquals(target: E): number;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `filter` function creates a new stack containing elements from the original stack that satisfy
-     * a given predicate function.
-     * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-     * the current element being iterated over, the index of the current element, and the stack itself.
-     * It should return a boolean value indicating whether the element should be included in the filtered
-     * stack or not.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-     * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
-     * passed as the `this` value to the `predicate` function. If `thisArg` is
-     * @returns The `filter` method is returning a new `Stack` object that contains the elements that
-     * satisfy the given predicate function.
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @param [options] - Options forwarded to the constructor.
+     * @returns An empty like-kind stack instance.
      */
-    filter(predicate: ElementCallback<E, R, boolean>, thisArg?: any): Stack<E, R>;
+    protected _createInstance(options?: StackOptions<E, R>): this;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `map` function takes a callback function and applies it to each element in the stack,
-     * returning a new stack with the results.
-     * @param callback - The callback parameter is a function that will be called for each element in the
-     * stack. It takes three arguments: the current element, the index of the element, and the stack
-     * itself. It should return a new value that will be added to the new stack.
-     * @param [toElementFn] - The `toElementFn` parameter is an optional function that can be used to
-     * transform the raw element (`RM`) into a new element (`EM`) before pushing it into the new stack.
-     * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
-     * specify the value of `this` within the callback function. It is used to set the context or scope
-     * in which the callback function will be executed. If `thisArg` is provided, it will be used as the
-     * value of
-     * @returns a new Stack object with elements of type EM and raw elements of type RM.
+     * (Protected) Create a like-kind stack and seed it from an iterable.
+     * @remarks Time O(N), Space O(N)
+     * @template T
+     * @template RR
+     * @param [elements] - Iterable used to seed the new stack.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A like-kind Stack instance.
      */
-    map<EM, RM>(callback: ElementCallback<E, R, EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): Stack<EM, RM>;
+    protected _createLike<T = E, RR = R>(elements?: Iterable<T> | Iterable<RR>, options?: StackOptions<T, RR>): Stack<T, RR>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * Custom iterator for the Stack class.
-     * @returns An iterator object.
+     * (Protected) Iterate elements from bottom to top.
+     * @remarks Time O(N), Space O(1)
+     * @returns Iterator of elements.
      */
     protected _getIterator(): IterableIterator<E>;
 }