data-structure-typed 1.54.3 → 2.0.1

package/dist/esm/data-structures/queue/queue.js

@@ -1,5 +1,5 @@
-import { IterableElementBase } from '../base';
 import { SinglyLinkedList } from '../linked-list';
+import { LinearBase } from '../base/linear-base';
 /**
  * 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).
@@ -8,8 +8,55 @@ import { SinglyLinkedList } from '../linked-list';
  * 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, i) => {
+ *       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 class Queue extends IterableElementBase {
+export class Queue extends LinearBase {
     constructor(elements = [], options) {
         super(options);
         if (options) {
@@ -19,38 +66,33 @@ export class Queue extends IterableElementBase {
         this.pushMany(elements);
     }
     _elements = [];
-    /**
-     * The elements function returns the elements of this set.
-     * @return An array of the elements in the stack
-     */
     get elements() {
         return this._elements;
     }
     _offset = 0;
-    /**
-     * The offset function returns the offset of the current page.
-     * @return The value of the protected variable _offset
-     */
     get offset() {
         return this._offset;
     }
-    /**
-     * The size function returns the number of elements in an array.
-     * @returns {number} The size of the array, which is the difference between the length of the array and the offset.
-     */
-    get size() {
+    get length() {
         return this.elements.length - this.offset;
     }
+    _autoCompactRatio = 0.5;
+    get autoCompactRatio() {
+        return this._autoCompactRatio;
+    }
+    set autoCompactRatio(v) {
+        this._autoCompactRatio = v;
+    }
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
      * The `first` function returns the first element of the array `_elements` if it exists, otherwise it returns `undefined`.
      * @returns The `get first()` method returns the first element of the data structure, represented by the `_elements` array at
-     * the `_offset` index. If the data structure is empty (size is 0), it returns `undefined`.
+     * the `_offset` index. If the data structure is empty (length is 0), it returns `undefined`.
      */
     get first() {
-        return this.size > 0 ? this.elements[this.offset] : undefined;
+        return this.length > 0 ? this.elements[this.offset] : undefined;
     }
     /**
      * Time Complexity: O(1)
@@ -61,23 +103,7 @@ export class Queue extends IterableElementBase {
      * array is empty, it returns `undefined`.
      */
     get last() {
-        return this.size > 0 ? this.elements[this.elements.length - 1] : undefined;
-    }
-    _autoCompactRatio = 0.5;
-    /**
-     * This function returns the value of the autoCompactRatio property.
-     * @returns The `autoCompactRatio` property of the object, which is a number.
-     */
-    get autoCompactRatio() {
-        return this._autoCompactRatio;
-    }
-    /**
-     * The above function sets the autoCompactRatio property to a specified number in TypeScript.
-     * @param {number} v - The parameter `v` represents the value that will be assigned to the
-     * `_autoCompactRatio` property.
-     */
-    set autoCompactRatio(v) {
-        this._autoCompactRatio = v;
+        return this.length > 0 ? this.elements[this.elements.length - 1] : undefined;
     }
     /**
      * Time Complexity: O(n)
@@ -102,6 +128,8 @@ export class Queue extends IterableElementBase {
      */
     push(element) {
         this.elements.push(element);
+        if (this._maxLen > 0 && this.length > this._maxLen)
+            this.shift();
         return true;
     }
     /**
@@ -134,7 +162,7 @@ export class Queue extends IterableElementBase {
      * @returns The function `shift()` returns either the first element in the queue or `undefined` if the queue is empty.
      */
     shift() {
-        if (this.size === 0)
+        if (this.length === 0)
             return undefined;
         const first = this.first;
         this._offset += 1;
@@ -152,7 +180,7 @@ export class Queue extends IterableElementBase {
      */
     delete(element) {
         const index = this.elements.indexOf(element);
-        return this.deleteAt(index);
+        return !!this.deleteAt(index);
     }
     /**
      * Time Complexity: O(n)
@@ -163,8 +191,9 @@ export class Queue extends IterableElementBase {
      * @return A boolean value
      */
     deleteAt(index) {
-        const spliced = this.elements.splice(index, 1);
-        return spliced.length === 1;
+        const deleted = this.elements[index];
+        this.elements.splice(index, 1);
+        return deleted;
     }
     /**
      * Time Complexity: O(1)
@@ -180,25 +209,68 @@ export class Queue extends IterableElementBase {
     at(index) {
         return this.elements[index + this._offset];
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The `reverse` function in TypeScript reverses the elements of an array starting from a specified
+     * offset.
+     * @returns The `reverse()` method is returning the modified object itself (`this`) after reversing
+     * the elements in the array and resetting the offset to 0.
+     */
+    reverse() {
+        this._elements = this.elements.slice(this.offset).reverse();
+        this._offset = 0;
+        return this;
+    }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(1)
+     *
+     * The function `addAt` inserts a new element at a specified index in an array, returning true if
+     * successful and false if the index is out of bounds.
+     * @param {number} index - The `index` parameter represents the position at which the `newElement`
+     * should be added in the array.
+     * @param {E} newElement - The `newElement` parameter represents the element that you want to insert
+     * into the array at the specified index.
+     * @returns The `addAt` method returns a boolean value - `true` if the new element was successfully
+     * added at the specified index, and `false` if the index is out of bounds (less than 0 or greater
+     * than the length of the array).
+     */
+    addAt(index, newElement) {
+        if (index < 0 || index > this.length)
+            return false;
+        this._elements.splice(this.offset + index, 0, newElement);
+        return true;
+    }
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
      *
-     * The function checks if a data structure is empty by comparing its size to zero.
-     * @returns {boolean} A boolean value indicating whether the size of the object is 0 or not.
+     * The function `setAt` updates an element at a specified index in an array-like data structure.
+     * @param {number} index - The `index` parameter is a number that represents the position in the
+     * array where the new element will be set.
+     * @param {E} newElement - The `newElement` parameter represents the new value that you want to set
+     * at the specified index in the array.
+     * @returns The `setAt` method returns a boolean value - `true` if the element was successfully set
+     * at the specified index, and `false` if the index is out of bounds (less than 0 or greater than the
+     * length of the array).
      */
-    isEmpty() {
-        return this.size === 0;
+    setAt(index, newElement) {
+        if (index < 0 || index > this.length)
+            return false;
+        this._elements[this.offset + index] = newElement;
+        return true;
     }
     /**
      * Time Complexity: O(1)
-     * Space Complexity: O(n)
+     * Space Complexity: O(1)
      *
-     * The toArray() function returns an array of elements from the current offset to the end of the _elements array.
-     * @returns An array of type E is being returned.
+     * The function checks if a data structure is empty by comparing its length to zero.
+     * @returns {boolean} A boolean value indicating whether the length of the object is 0 or not.
      */
-    toArray() {
-        return this.elements.slice(this.offset);
+    isEmpty() {
+        return this.length === 0;
     }
     /**
      * Time Complexity: O(1)
@@ -223,6 +295,34 @@ export class Queue extends IterableElementBase {
         this._offset = 0;
         return true;
     }
+    /**
+     * Time Complexity: O(n)
+     * Space Complexity: O(n)
+     *
+     * The function overrides the splice method to remove and insert elements in a queue-like data
+     * structure.
+     * @param {number} start - The `start` parameter in the `splice` method specifies the index at which
+     * to start changing the array. Items will be added or removed starting from this index.
+     * @param {number} [deleteCount=0] - The `deleteCount` parameter in the `splice` method specifies the
+     * number of elements to remove from the array starting at the specified `start` index. If
+     * `deleteCount` is not provided, it defaults to 0, meaning no elements will be removed but new
+     * elements can still be inserted at
+     * @param {E[]} items - The `items` parameter in the `splice` method represents the elements that
+     * will be added to the array at the specified `start` index. These elements will replace the
+     * existing elements starting from the `start` index for the `deleteCount` number of elements.
+     * @returns The `splice` method is returning the `removedQueue`, which is an instance of the same
+     * class as the original object.
+     */
+    splice(start, deleteCount = 0, ...items) {
+        const removedQueue = this._createInstance();
+        start = Math.max(0, Math.min(start, this.length));
+        deleteCount = Math.max(0, Math.min(deleteCount, this.length - start));
+        const globalStartIndex = this.offset + start;
+        const removedElements = this._elements.splice(globalStartIndex, deleteCount, ...items);
+        removedQueue.pushMany(removedElements);
+        this.compact();
+        return removedQueue;
+    }
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -231,7 +331,7 @@ export class Queue extends IterableElementBase {
      * @returns The `clone()` method is returning a new instance of the `Queue` class.
      */
     clone() {
-        return new Queue(this.elements.slice(this.offset), { toElementFn: this.toElementFn });
+        return new Queue(this.elements.slice(this.offset), { toElementFn: this.toElementFn, maxLen: this._maxLen });
     }
     /**
      * Time Complexity: O(n)
@@ -250,7 +350,11 @@ export class Queue extends IterableElementBase {
      * satisfy the given predicate function.
      */
     filter(predicate, thisArg) {
-        const newDeque = new Queue([], { toElementFn: this.toElementFn });
+        const newDeque = this._createInstance({
+            toElementFn: this._toElementFn,
+            autoCompactRatio: this._autoCompactRatio,
+            maxLen: this._maxLen
+        });
         let index = 0;
         for (const el of this) {
             if (predicate.call(thisArg, el, index, this)) {
@@ -279,7 +383,11 @@ export class Queue extends IterableElementBase {
      * callback function to each element in the original Queue object.
      */
     map(callback, toElementFn, thisArg) {
-        const newDeque = new Queue([], { toElementFn });
+        const newDeque = new Queue([], {
+            toElementFn,
+            autoCompactRatio: this._autoCompactRatio,
+            maxLen: this._maxLen
+        });
         let index = 0;
         for (const el of this) {
             newDeque.push(callback.call(thisArg, el, index, this));
@@ -298,6 +406,29 @@ export class Queue extends IterableElementBase {
             yield item;
         }
     }
+    /**
+     * The function `_createInstance` returns a new instance of the `Queue` class with the specified
+     * options.
+     * @param [options] - The `options` parameter in the `_createInstance` method is of type
+     * `QueueOptions<E, R>`, which is used to configure the behavior of the queue being created. It
+     * allows you to specify settings or properties that can influence how the queue operates.
+     * @returns An instance of the `Queue` class with an empty array and the provided options is being
+     * returned.
+     */
+    _createInstance(options) {
+        return new Queue([], options);
+    }
+    /**
+     * The function `_getReverseIterator` returns an iterator that iterates over elements in reverse
+     * order.
+     */
+    *_getReverseIterator() {
+        for (let i = this.length - 1; i >= 0; i--) {
+            const cur = this.at(i); // `at()` handles the offset.
+            if (cur !== undefined)
+                yield cur;
+        }
+    }
 }
 /**
  * 1. First In, First Out (FIFO) Strategy: Like other queue implementations, LinkedListQueue follows the first in, first out principle, meaning the element that is added to the queue first will be the first to be removed.
@@ -315,7 +446,7 @@ export class LinkedListQueue extends SinglyLinkedList {
      * values as the original `LinkedListQueue`.
      */
     clone() {
-        return new LinkedListQueue(this, { toElementFn: this.toElementFn });
+        return new LinkedListQueue(this, { toElementFn: this.toElementFn, maxLen: this._maxLen });
     }
 }
 //# sourceMappingURL=queue.js.map

package/dist/esm/data-structures/queue/queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../../../src/data-structures/queue/queue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../../../src/data-structures/queue/queue.ts"],"names":[],"mappings":"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"}

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

@@ -14,8 +14,129 @@ import { IterableElementBase } from '../base';
  * 4. Function Calls: In most modern programming languages, the records of function calls are managed through a stack. When a function is called, its record (including parameters, local variables, and return address) is 'pushed' into the stack. When the function returns, its record is 'popped' from the stack.
  * 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
+ * // Balanced Parentheses or Brackets
+ *     type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';
+ *
+ *     const stack = new Stack<string>();
+ *     const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];
+ *     const matches: { [key in ValidCharacters]?: ValidCharacters } = { ')': '(', ']': '[', '}': '{' };
+ *     for (const char of input) {
+ *       if ('([{'.includes(char)) {
+ *         stack.push(char);
+ *       } else if (')]}'.includes(char)) {
+ *         if (stack.pop() !== matches[char]) {
+ *           fail('Parentheses are not balanced');
+ *         }
+ *       }
+ *     }
+ *     console.log(stack.isEmpty()); // true
+ * @example
+ * // Expression Evaluation and Conversion
+ *     const stack = new Stack<number>();
+ *     const expression = [5, 3, '+']; // Equivalent to 5 + 3
+ *     expression.forEach(token => {
+ *       if (typeof token === 'number') {
+ *         stack.push(token);
+ *       } else {
+ *         const b = stack.pop()!;
+ *         const a = stack.pop()!;
+ *         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]
+ * @example
+ * // Backtracking Algorithms
+ *     const stack = new Stack<[number, number]>();
+ *     const maze = [
+ *       ['S', ' ', 'X'],
+ *       ['X', ' ', 'X'],
+ *       [' ', ' ', 'E']
+ *     ];
+ *     const start: [number, number] = [0, 0];
+ *     const end = [2, 2];
+ *     const directions = [
+ *       [0, 1], // To the right
+ *       [1, 0], // down
+ *       [0, -1], // left
+ *       [-1, 0] // up
+ *     ];
+ *
+ *     const visited = new Set<string>(); // Used to record visited nodes
+ *     stack.push(start);
+ *     const path: number[][] = [];
+ *
+ *     while (!stack.isEmpty()) {
+ *       const [x, y] = stack.pop()!;
+ *       if (visited.has(`${x},${y}`)) continue; // Skip already visited nodes
+ *       visited.add(`${x},${y}`);
+ *
+ *       path.push([x, y]);
+ *
+ *       if (x === end[0] && y === end[1]) {
+ *         break; // Find the end point and exit
+ *       }
+ *
+ *       for (const [dx, dy] of directions) {
+ *         const nx = x + dx;
+ *         const ny = y + dy;
+ *         if (
+ *           maze[nx]?.[ny] === ' ' || // feasible path
+ *           maze[nx]?.[ny] === 'E' // destination
+ *         ) {
+ *           stack.push([nx, ny]);
+ *         }
+ *       }
+ *     }
+ *
+ *     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'
+ * @example
+ * // Stock Span Problem
+ *     const stack = new Stack<number>();
+ *     const prices = [100, 80, 60, 70, 60, 75, 85];
+ *     const spans: number[] = [];
+ *     prices.forEach((price, i) => {
+ *       while (!stack.isEmpty() && prices[stack.peek()!] <= price) {
+ *         stack.pop();
+ *       }
+ *       spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);
+ *       stack.push(i);
+ *     });
+ *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6]
  */
-export declare class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E, R>> {
+export declare class Stack<E = any, R = any> extends IterableElementBase<E, R> {
     constructor(elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>);
     protected _elements: E[];
     /**
@@ -102,14 +223,6 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R, S
      * @returns An array of type E.
      */
     deleteAt(index: number): boolean;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The toArray function returns a copy of the elements in an array.
-     * @returns An array of type E.
-     */
-    toArray(): E[];
     /**
      * Time Complexity: O(1)
      * Space Complexity: O(1)
@@ -141,7 +254,7 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R, S
      * @returns The `filter` method is returning a new `Stack` object that contains the elements that
      * satisfy the given predicate function.
      */
-    filter(predicate: ElementCallback<E, R, boolean, Stack<E, R>>, thisArg?: any): Stack<E, R>;
+    filter(predicate: ElementCallback<E, R, boolean>, thisArg?: any): Stack<E, R>;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)
@@ -159,7 +272,7 @@ export declare class Stack<E = any, R = any> extends IterableElementBase<E, R, S
      * value of
      * @returns a new Stack object with elements of type EM and raw elements of type RM.
      */
-    map<EM, RM>(callback: ElementCallback<E, R, EM, Stack<E, R>>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): Stack<EM, RM>;
+    map<EM, RM>(callback: ElementCallback<E, R, EM>, toElementFn?: (rawElement: RM) => EM, thisArg?: any): Stack<EM, RM>;
     /**
      * Time Complexity: O(n)
      * Space Complexity: O(n)