data-structure-typed 1.48.1 → 1.48.2

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

@@ -4,42 +4,10 @@
  * @class
  */
 import { SinglyLinkedList } from '../linked-list';
+import { IterableElementBase } from "../base";
+import { ElementCallback } from "../../types";
 
-export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
-  /**
-   * The enqueue function adds a value to the end of an array.
-   * @param {E} value - The value parameter represents the value that you want to add to the queue.
-   */
-  enqueue(value: E) {
-    this.push(value);
-  }
-
-  /**
-   * The `dequeue` function removes and returns the first element from a queue, or returns undefined if the queue is empty.
-   * @returns The method is returning the element at the front of the queue, or undefined if the queue is empty.
-   */
-  dequeue(): E | undefined {
-    return this.shift();
-  }
-
-  /**
-   * The `getFirst` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
-   * @returns The `getFirst()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
-   */
-  getFirst(): E | undefined {
-    return this.head?.value;
-  }
-
-  /**
-   * The `peek` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
-   * @returns The `peek()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
-   */
-  peek(): E | undefined {
-    return this.getFirst();
-  }
-}
-
-export class Queue<E = any> {
+export class Queue<E = any> extends IterableElementBase<E> {
   /**
    * The constructor initializes an instance of a class with an optional array of elements and sets the offset to 0.
    * @param {E[]} [elements] - The `elements` parameter is an optional array of elements of type `E`. If provided, it
@@ -47,6 +15,7 @@ export class Queue<E = any> {
    * initialized as an empty array.
    */
   constructor(elements?: E[]) {
+    super();
     this._nodes = elements || [];
     this._offset = 0;
   }
@@ -304,34 +273,6 @@ export class Queue<E = any> {
     console.log([...this]);
   }
 
-  * [Symbol.iterator]() {
-    for (const item of this.nodes) {
-      yield item;
-    }
-  }
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   */
-
-  /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
-   *
-   * The `forEach` function iterates over each element in a deque and applies a callback function to
-   * each element.
-   * @param callback - The callback parameter is a function that will be called for each element in the
-   * deque. It takes three parameters:
-   */
-  forEach(callback: (element: E, index: number, queue: this) => void) {
-    let index = 0;
-    for (const el of this) {
-      callback(el, index, this);
-      index++;
-    }
-  }
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -341,18 +282,23 @@ export class Queue<E = any> {
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
-   * The `filter` function creates a new deque containing only the elements that satisfy the given
-   * predicate function.
-   * @param predicate - The `predicate` parameter is a function that takes three arguments: `element`,
-   * `index`, and `deque`.
-   * @returns The `filter` method is returning a new `Queue` object that contains only the elements
-   * that satisfy the given `predicate` function.
-   */
-  filter(predicate: (element: E, index: number, queue: this) => boolean): Queue<E> {
+   * The `filter` function creates a new `Queue` object containing elements from the original `Queue`
+   * 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 queue itself.
+   * It should return a boolean value indicating whether the element should be included in the filtered
+   * queue 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 `Queue` object that contains the elements that
+   * satisfy the given predicate function.
+   */
+  filter(predicate: ElementCallback<E, boolean>, thisArg?: any): Queue<E> {
     const newDeque = new Queue<E>([]);
     let index = 0;
     for (const el of this) {
-      if (predicate(el, index, this)) {
+      if (predicate.call(thisArg, el, index, this)) {
         newDeque.push(el);
       }
       index++;
@@ -364,33 +310,72 @@ export class Queue<E = any> {
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    */
-
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    *
-   * The `map` function takes a callback function and applies it to each element in the deque,
-   * returning a new deque with the results.
-   * @param callback - The `callback` parameter is a function that takes three arguments:
-   * @returns The `map` method is returning a new `Queue` object with the transformed elements.
-   */
-  map<T>(callback: (element: E, index: number, queue: this) => T): Queue<T> {
+   * The `map` function takes a callback function and applies it to each element in the queue,
+   * returning a new queue with the results.
+   * @param callback - The callback parameter is a function that will be called for each element in the
+   * queue. It takes three arguments: the current element, the index of the current element, and the
+   * queue itself. The callback function should return a new value that will be added to the new queue.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `callback` function. If `thisArg` is
+   * @returns The `map` function is returning a new `Queue` object with the transformed elements.
+   */
+  map<T>(callback: ElementCallback<E, T>, thisArg?: any): Queue<T> {
     const newDeque = new Queue<T>([]);
     let index = 0;
     for (const el of this) {
-      newDeque.push(callback(el, index, this));
+      newDeque.push(callback.call(thisArg, el, index, this));
       index++;
     }
     return newDeque;
   }
 
-  reduce<T>(callback: (accumulator: T, element: E, index: number, queue: this) => T, initialValue: T): T {
-    let accumulator = initialValue;
-    let index = 0;
-    for (const el of this) {
-      accumulator = callback(accumulator, el, index, this);
-      index++;
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+
+  protected* _getIterator() {
+    for (const item of this.nodes) {
+      yield item;
     }
-    return accumulator;
   }
 }
+
+export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
+  /**
+   * The enqueue function adds a value to the end of an array.
+   * @param {E} value - The value parameter represents the value that you want to add to the queue.
+   */
+  enqueue(value: E) {
+    this.push(value);
+  }
+
+  /**
+   * The `dequeue` function removes and returns the first element from a queue, or returns undefined if the queue is empty.
+   * @returns The method is returning the element at the front of the queue, or undefined if the queue is empty.
+   */
+  dequeue(): E | undefined {
+    return this.shift();
+  }
+
+  /**
+   * The `getFirst` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
+   * @returns The `getFirst()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
+   */
+  getFirst(): E | undefined {
+    return this.head?.value;
+  }
+
+  /**
+   * The `peek` function returns the value of the head node in a linked list, or `undefined` if the list is empty.
+   * @returns The `peek()` method is returning the value of the `head` node if it exists, otherwise it returns `undefined`.
+   */
+  peek(): E | undefined {
+    return this.getFirst();
+  }
+}

package/src/data-structures/stack/stack.ts

@@ -1,9 +1,12 @@
+import { IterableElementBase } from "../base";
+import { ElementCallback } from "../../types";
+
 /**
  * @license MIT
  * @copyright Tyler Zeng <zrwusa@gmail.com>
  * @class
  */
-export class Stack<E = any> {
+export class Stack<E = any> extends IterableElementBase<E> {
   /**
    * The constructor initializes an array of elements, which can be provided as an optional parameter.
    * @param {E[]} [elements] - The `elements` parameter is an optional parameter of type `E[]`, which represents an array
@@ -11,6 +14,7 @@ export class Stack<E = any> {
    * is provided and is an array, it is assigned to the `_elements
    */
   constructor(elements?: Iterable<E>) {
+    super();
     this._elements = [];
     if (elements) {
       for (const el of elements) {
@@ -154,33 +158,31 @@ export class Stack<E = any> {
   }
 
   /**
-   * Custom iterator for the Stack class.
-   * @returns An iterator object.
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
    */
-  * [Symbol.iterator]() {
-    for (let i = 0; i < this.elements.length; i++) {
-      yield this.elements[i];
-    }
-  }
 
   /**
-   * Applies a function to each element of the stack.
-   * @param {function(E): void} callback - A function to apply to each element.
-   */
-  forEach(callback: (element: E, index: number, stack: this) => void): void {
-    let index = 0;
-    for (const el of this) {
-      callback(el, index, this);
-      index++;
-    }
-  }
-
-
-  filter(predicate: (element: E, index: number, stack: this) => boolean): Stack<E> {
+   * 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.
+   */
+  filter(predicate: ElementCallback<E, boolean>, thisArg?: any): Stack<E> {
     const newStack = new Stack<E>();
     let index = 0;
     for (const el of this) {
-      if (predicate(el, index, this)) {
+      if (predicate.call(thisArg, el, index, this)) {
         newStack.push(el);
       }
       index++;
@@ -188,28 +190,45 @@ export class Stack<E = any> {
     return newStack;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
 
-  map<T>(callback: (element: E, index: number, stack: this) => T): Stack<T> {
+  /**
+   * 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:
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `callback` function. If `thisArg` is
+   * @returns The `map` method is returning a new `Stack` object.
+   */
+  map<T>(callback: ElementCallback<E, T>, thisArg?: any): Stack<T> {
     const newStack = new Stack<T>();
     let index = 0;
     for (const el of this) {
-      newStack.push(callback(el, index, this));
+      newStack.push(callback.call(thisArg, el, index, this));
       index++;
     }
     return newStack;
   }
 
-  reduce<T>(callback: (accumulator: T, element: E, index: number, stack: this) => T, initialValue: T): T {
-    let accumulator = initialValue;
-    let index = 0;
-    for (const el of this) {
-      accumulator = callback(accumulator, el, index, this);
-      index++;
-    }
-    return accumulator;
-  }
-
   print(): void {
     console.log([...this]);
   }
+
+  /**
+   * Custom iterator for the Stack class.
+   * @returns An iterator object.
+   */
+  protected* _getIterator() {
+    for (let i = 0; i < this.elements.length; i++) {
+      yield this.elements[i];
+    }
+  }
 }

package/src/data-structures/trie/trie.ts

@@ -6,6 +6,9 @@
  * @license MIT License
  */
 
+import { IterableElementBase } from "../base";
+import { ElementCallback } from "../../types";
+
 /**
  * TrieNode represents a node in the Trie data structure. It holds a character key, a map of children nodes,
  * and a flag indicating whether it's the end of a word.
@@ -25,8 +28,9 @@ export class TrieNode {
 /**
  * Trie represents a Trie data structure. It provides basic Trie operations and additional methods.
  */
-export class Trie {
+export class Trie extends IterableElementBase<string> {
   constructor(words?: string[], caseSensitive = true) {
+    super();
     this._root = new TrieNode('');
     this._caseSensitive = caseSensitive;
     this._size = 0;
@@ -339,32 +343,30 @@ export class Trie {
     return words;
   }
 
-  * [Symbol.iterator](): IterableIterator<string> {
-    function* _dfs(node: TrieNode, path: string): IterableIterator<string> {
-      if (node.isEnd) {
-        yield path;
-      }
-      for (const [char, childNode] of node.children) {
-        yield* _dfs(childNode, path + char);
-      }
-    }
-
-    yield* _dfs(this.root, '');
-  }
-
-  forEach(callback: (word: string, index: number, trie: this) => void): void {
-    let index = 0;
-    for (const word of this) {
-      callback(word, index, this);
-      index++;
-    }
-  }
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
 
-  filter(predicate: (word: string, index: number, trie: this) => boolean): string[] {
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `filter` function takes a predicate function and returns a new array containing all the
+   * elements for which the predicate function returns true.
+   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
+   * `word`, `index`, and `this`. It should return a boolean value indicating whether the current
+   * element should be included in the filtered results or not.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that allows you to
+   * specify the value of `this` within the `predicate` function. It is used when you want to bind a
+   * specific object as the context for the `predicate` function. If `thisArg` is provided, it will be
+   * @returns The `filter` method is returning an array of strings (`string[]`).
+   */
+  filter(predicate: ElementCallback<string, boolean>, thisArg?: any): string[] {
     const results: string[] = [];
     let index = 0;
     for (const word of this) {
-      if (predicate(word, index, this)) {
+      if (predicate.call(thisArg, word, index, this)) {
         results.push(word);
       }
       index++;
@@ -372,30 +374,51 @@ export class Trie {
     return results;
   }
 
-  map(callback: (word: string, index: number, trie: this) => string): Trie {
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   */
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `map` function creates a new Trie by applying a callback function to each element in the Trie.
+   * @param callback - The callback parameter is a function that will be called for each element in the
+   * Trie. It takes three arguments: the current element in the Trie, the index of the current element,
+   * and the Trie itself. The callback function should return a new value for the element.
+   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
+   * to be used as `this` when executing the `callback` function. If `thisArg` is provided, it will be
+   * passed as the `this` value to the `callback` function. If `thisArg` is
+   * @returns The `map` function is returning a new Trie object.
+   */
+  map(callback: ElementCallback<string, string>, thisArg?: any): Trie {
     const newTrie = new Trie();
     let index = 0;
     for (const word of this) {
-      newTrie.add(callback(word, index, this));
+      newTrie.add(callback.call(thisArg, word, index, this));
       index++;
     }
     return newTrie;
   }
 
-  reduce<T>(callback: (accumulator: T, word: string, index: number, trie: this) => T, initialValue: T): T {
-    let accumulator = initialValue;
-    let index = 0;
-    for (const word of this) {
-      accumulator = callback(accumulator, word, index, this);
-      index++;
-    }
-    return accumulator;
-  }
-
   print() {
     console.log([...this]);
   }
 
+  protected* _getIterator(): IterableIterator<string> {
+    function* _dfs(node: TrieNode, path: string): IterableIterator<string> {
+      if (node.isEnd) {
+        yield path;
+      }
+      for (const [char, childNode] of node.children) {
+        yield* _dfs(childNode, path + char);
+      }
+    }
+
+    yield* _dfs(this.root, '');
+  }
+
   /**
    * Time Complexity: O(M), where M is the length of the input string.
    * Space Complexity: O(1) - Constant space.

package/src/types/data-structures/base/base.ts

@@ -0,0 +1,6 @@
+import { IterableElementBase, IterablePairBase } from "../../../data-structures";
+
+export type PairCallback<K, V, R> = (value: V, key: K, index: number, container: IterablePairBase<K, V>) => R;
+export type ElementCallback<V, R> = (element: V, index: number, container: IterableElementBase<V>) => R;
+export type ReducePairCallback<K, V, R> = (accumulator: R, value: V, key: K, index: number, container: IterablePairBase<K, V>) => R;
+export type ReduceElementCallback<V, R> = (accumulator: R, element: V, index: number, container: IterableElementBase<V>) => R;

package/src/types/data-structures/base/index.ts

@@ -0,0 +1 @@
+export * from './base';

package/src/types/data-structures/index.ts

@@ -9,3 +9,4 @@ export * from './queue';
 export * from './stack';
 export * from './tree';
 export * from './trie';
+export * from './base';

package/test/unit/data-structures/binary-tree/avl-tree.test.ts

@@ -305,30 +305,30 @@ describe('AVLTree iterative methods test', () => {
 
   test('forEach should iterate over all elements', () => {
     const mockCallback = jest.fn();
-    avl.forEach((entry) => {
-      mockCallback(entry);
+    avl.forEach((value, key) => {
+      mockCallback(value, key);
     });
 
     expect(mockCallback.mock.calls.length).toBe(3);
-    expect(mockCallback.mock.calls[0][0]).toEqual([1, 'a']);
-    expect(mockCallback.mock.calls[1][0]).toEqual([2, 'b']);
-    expect(mockCallback.mock.calls[2][0]).toEqual([3, 'c']);
+    expect(mockCallback.mock.calls[0]).toEqual(['a', 1]);
+    expect(mockCallback.mock.calls[1]).toEqual(['b', 2]);
+    expect(mockCallback.mock.calls[2]).toEqual(['c', 3]);
   });
 
   test('filter should return a new tree with filtered elements', () => {
-    const filteredTree = avl.filter(([key]) => key > 1);
+    const filteredTree = avl.filter((value, key) => key > 1);
     expect(filteredTree.size).toBe(2);
     expect([...filteredTree]).toEqual([[2, 'b'], [3, 'c']]);
   });
 
   test('map should return a new tree with modified elements', () => {
-    const mappedTree = avl.map(([key]) => (key * 2).toString());
+    const mappedTree = avl.map((value, key) => (key * 2).toString());
     expect(mappedTree.size).toBe(3);
     expect([...mappedTree]).toEqual([[1, '2'], [2, '4'], [3, '6']]);
   });
 
   test('reduce should accumulate values', () => {
-    const sum = avl.reduce((acc, [key]) => acc + key, 0);
+    const sum = avl.reduce((acc, value, key) => acc + key, 0);
     expect(sum).toBe(6);
   });
 
@@ -350,11 +350,11 @@ describe('AVLTree iterative methods test', () => {
 
   test('should keys', () => {
     const keys = avl.keys();
-    expect(keys).toEqual([1, 2, 3]);
+    expect([...keys]).toEqual([1, 2, 3]);
   });
 
   test('should values', () => {
     const values = avl.values();
-    expect(values).toEqual(['a', 'b', 'c']);
+    expect([...values]).toEqual(['a', 'b', 'c']);
   });
 });

package/test/unit/data-structures/binary-tree/binary-tree.test.ts

@@ -580,30 +580,30 @@ describe('BinaryTree iterative methods test', () => {
 
   test('forEach should iterate over all elements', () => {
     const mockCallback = jest.fn();
-    binaryTree.forEach((entry) => {
-      mockCallback(entry);
+    binaryTree.forEach((value, key) => {
+      mockCallback(value, key);
     });
 
     expect(mockCallback.mock.calls.length).toBe(3);
-    expect(mockCallback.mock.calls[0][0]).toEqual([2, 'b']);
-    expect(mockCallback.mock.calls[1][0]).toEqual([1, 'a']);
-    expect(mockCallback.mock.calls[2][0]).toEqual([3, 'c']);
+    expect(mockCallback.mock.calls[0]).toEqual(['b', 2]);
+    expect(mockCallback.mock.calls[1]).toEqual(['a', 1]);
+    expect(mockCallback.mock.calls[2]).toEqual(['c', 3]);
   });
 
   test('filter should return a new tree with filtered elements', () => {
-    const filteredTree = binaryTree.filter(([key]) => key > 1);
+    const filteredTree = binaryTree.filter((value, key) => key > 1);
     expect(filteredTree.size).toBe(2);
     expect([...filteredTree]).toEqual([[3, 'c'], [2, 'b']]);
   });
 
   test('map should return a new tree with modified elements', () => {
-    const mappedTree = binaryTree.map(([key]) => (key * 2).toString());
+    const mappedTree = binaryTree.map((value, key) => (key * 2).toString());
     expect(mappedTree.size).toBe(3);
     expect([...mappedTree]).toEqual([[1, '2'], [2, '4'], [3, '6']]);
   });
 
   test('reduce should accumulate values', () => {
-    const sum = binaryTree.reduce((acc, [key]) => acc + key, 0);
+    const sum = binaryTree.reduce((acc, currentValue, currentKey) => acc + currentKey, 0);
     expect(sum).toBe(6);
   });
 
@@ -625,11 +625,11 @@ describe('BinaryTree iterative methods test', () => {
 
   test('should keys', () => {
     const keys = binaryTree.keys();
-    expect(keys).toEqual([2, 1, 3]);
+    expect([...keys]).toEqual([2, 1, 3]);
   });
 
   test('should values', () => {
     const values = binaryTree.values();
-    expect(values).toEqual(['b', 'a', 'c']);
+    expect([...values]).toEqual(['b', 'a', 'c']);
   });
 });

package/test/unit/data-structures/binary-tree/bst.test.ts

@@ -864,30 +864,30 @@ describe('BST iterative methods test', () => {
 
   test('forEach should iterate over all elements', () => {
     const mockCallback = jest.fn();
-    bst.forEach((entry) => {
-      mockCallback(entry);
+    bst.forEach((value, key) => {
+      mockCallback(value, key);
     });
 
     expect(mockCallback.mock.calls.length).toBe(3);
-    expect(mockCallback.mock.calls[0][0]).toEqual([1, 'a']);
-    expect(mockCallback.mock.calls[1][0]).toEqual([2, 'b']);
-    expect(mockCallback.mock.calls[2][0]).toEqual([3, 'c']);
+    expect(mockCallback.mock.calls[0]).toEqual(['a', 1]);
+    expect(mockCallback.mock.calls[1]).toEqual(['b', 2]);
+    expect(mockCallback.mock.calls[2]).toEqual(['c', 3]);
   });
 
   test('filter should return a new tree with filtered elements', () => {
-    const filteredTree = bst.filter(([key]) => key > 1);
+    const filteredTree = bst.filter((value, key) => key > 1);
     expect(filteredTree.size).toBe(2);
     expect([...filteredTree]).toEqual([[2, 'b'], [3, 'c']]);
   });
 
   test('map should return a new tree with modified elements', () => {
-    const mappedTree = bst.map(([key]) => (key * 2).toString());
+    const mappedTree = bst.map((value, key) => (key * 2).toString());
     expect(mappedTree.size).toBe(3);
     expect([...mappedTree]).toEqual([[1, '2'], [2, '4'], [3, '6']]);
   });
 
   test('reduce should accumulate values', () => {
-    const sum = bst.reduce((acc, [key]) => acc + key, 0);
+    const sum = bst.reduce((acc, value, key) => acc + key, 0);
     expect(sum).toBe(6);
   });
 
@@ -909,11 +909,11 @@ describe('BST iterative methods test', () => {
 
   test('should keys', () => {
     const keys = bst.keys();
-    expect(keys).toEqual([1, 2, 3]);
+    expect([...keys]).toEqual([1, 2, 3]);
   });
 
   test('should values', () => {
     const values = bst.values();
-    expect(values).toEqual(['a', 'b', 'c']);
+    expect([...values]).toEqual(['a', 'b', 'c']);
   });
 });