undirected-graph-typed 1.51.9 → 1.52.2

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Kirk Qi <qilinaus@gmail.com>
  * @license MIT License
  */
-import type { PriorityQueueOptions } from '../../types';
+import type { Comparator, ElementCallback, PriorityQueueOptions } from '../../types';
 import { Heap } from '../heap';
 
 /**
@@ -16,16 +16,93 @@ import { Heap } from '../heap';
  * 5. Huffman Coding: Used to select the smallest node combination when constructing a Huffman tree.
  * 6. Kth Largest Element in a Data Stream: Used to maintain a min-heap of size K for quickly finding the Kth largest element in stream data
  */
-export class PriorityQueue<E = any> extends Heap<E> {
+export class PriorityQueue<E = any, R = any> extends Heap<E, R> {
   /**
    * The constructor initializes a priority queue with optional elements and options.
    * @param elements - The `elements` parameter is an iterable object that contains the initial
-   * elements to be added to the priority queue. It is an optional parameter and if not provided, the
+   * elements to be added to the priority queue. It is an optional parameter, and if not provided, the
    * priority queue will be initialized as empty.
    * @param [options] - The `options` parameter is an optional object that can be used to customize the
    * behavior of the priority queue. It can contain the following properties:
    */
-  constructor(elements: Iterable<E> = [], options?: PriorityQueueOptions<E>) {
+  constructor(elements: Iterable<E> | Iterable<R> = [], options?: PriorityQueueOptions<E, R>) {
     super(elements, options);
   }
+
+  /**
+   * The `clone` function returns a new instance of the `PriorityQueue` class with the same comparator
+   * and toElementFn as the original instance.
+   * @returns The method is returning a new instance of the `PriorityQueue` class with the same
+   * elements and properties as the current instance.
+   */
+  override clone(): PriorityQueue<E, R> {
+    return new PriorityQueue<E, R>(this, { comparator: this.comparator, toElementFn: this.toElementFn });
+  }
+
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(n)
+   *
+   * The `filter` function creates a new PriorityQueue object containing elements that pass a given callback
+   * function.
+   * @param callback - The `callback` parameter is a function that will be called for each element in
+   * the heap. It takes three arguments: the current element, the index of the current element, and the
+   * heap itself. The callback function should return a boolean value indicating whether the current
+   * element should be included in the filtered list
+   * @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 `filter` method is returning a new `PriorityQueue` object that contains the elements that pass
+   * the filter condition specified by the `callback` function.
+   */
+  override filter(callback: ElementCallback<E, R, boolean, PriorityQueue<E, R>>, thisArg?: any): PriorityQueue<E, R> {
+    const filteredPriorityQueue = new PriorityQueue<E, R>([], {
+      toElementFn: this.toElementFn,
+      comparator: this.comparator
+    });
+    let index = 0;
+    for (const current of this) {
+      if (callback.call(thisArg, current, index, this)) {
+        filteredPriorityQueue.add(current);
+      }
+      index++;
+    }
+    return filteredPriorityQueue;
+  }
+
+  /**
+   * Time Complexity: O(n log n)
+   * Space Complexity: O(n)
+   *
+   * The `map` function creates a new heap by applying a callback function to each element of the
+   * original heap.
+   * @param callback - The `callback` parameter is a function that will be called for each element in
+   * the heap. It takes three arguments: `el` (the current element), `index` (the index of the current
+   * element), and `this` (the heap itself). The callback function should return a value of
+   * @param comparator - The `comparator` parameter is a function that defines the order of the
+   * elements in the heap. It takes two elements `a` and `b` as arguments and returns a negative number
+   * if `a` should be placed before `b`, a positive number if `a` should be placed after
+   * @param [toElementFn] - The `toElementFn` parameter is an optional function that converts the raw
+   * element `RR` to the desired type `T`. It takes a single argument `rawElement` of type `RR` and
+   * returns a value of type `T`. This function is used to transform the elements of the original
+   * @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 instance of the `PriorityQueue` class with the mapped elements.
+   */
+  override map<EM, RM>(
+    callback: ElementCallback<E, R, EM, PriorityQueue<E, R>>,
+    comparator: Comparator<EM>,
+    toElementFn?: (rawElement: RM) => EM,
+    thisArg?: any
+  ): PriorityQueue<EM, RM> {
+    const mappedPriorityQueue: PriorityQueue<EM, RM> = new PriorityQueue<EM, RM>([], { comparator, toElementFn });
+    let index = 0;
+    for (const el of this) {
+      mappedPriorityQueue.add(callback.call(thisArg, el, index, this));
+      index++;
+    }
+    return mappedPriorityQueue;
+  }
 }

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

@@ -16,9 +16,9 @@ import { calcMinUnitsRequired, rangeCheck } from '../../utils';
  * 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
  */
-export class Deque<E> extends IterableElementBase<E> {
+export class Deque<E = any, R = any> extends IterableElementBase<E, R, Deque<E, R>> {
   /**
-   * The constructor initializes a Deque object with an optional iterable of elements and options.
+   * The constructor initializes a Deque object with optional iterable of elements and options.
    * @param elements - An iterable object (such as an array or a Set) that contains the initial
    * elements to be added to the deque. It can also be an object with a `length` or `size` property
    * that represents the number of elements in the iterable object. If no elements are provided, an
@@ -28,12 +28,13 @@ export class Deque<E> extends IterableElementBase<E> {
    * which determines the size of each bucket in the deque. If the `bucketSize` option is not provided
    * or is not a number
    */
-  constructor(elements: IterableWithSizeOrLength<E> = [], options?: DequeOptions) {
-    super();
+  constructor(elements: IterableWithSizeOrLength<E> | IterableWithSizeOrLength<R> = [], options?: DequeOptions<E, R>) {
+    super(options);
 
     if (options) {
-      const { bucketSize } = options;
+      const { bucketSize, maxLen } = options;
       if (typeof bucketSize === 'number') this._bucketSize = bucketSize;
+      if (typeof maxLen === 'number' && maxLen > 0 && maxLen % 1 === 0) this._maxLen = maxLen;
     }
 
     let _size: number;
@@ -53,8 +54,12 @@ export class Deque<E> extends IterableElementBase<E> {
     this._bucketFirst = this._bucketLast = (this._bucketCount >> 1) - (needBucketNum >> 1);
     this._firstInBucket = this._lastInBucket = (this._bucketSize - (_size % this._bucketSize)) >> 1;
 
-    for (const element of elements) {
-      this.push(element);
+    for (const el of elements) {
+      if (this.toElementFn) {
+        this.push(this.toElementFn(el as R));
+      } else {
+        this.push(el as E);
+      }
     }
   }
 
@@ -69,6 +74,17 @@ export class Deque<E> extends IterableElementBase<E> {
     return this._bucketSize;
   }
 
+  protected _maxLen: number = -1;
+
+  /**
+   * The maxLen function returns the max length of the deque.
+   *
+   * @return The max length of the deque
+   */
+  get maxLen() {
+    return this._maxLen;
+  }
+
   protected _bucketFirst = 0;
 
   /**
@@ -189,6 +205,7 @@ export class Deque<E> extends IterableElementBase<E> {
     }
     this._size += 1;
     this._buckets[this._bucketLast][this._lastInBucket] = element;
+    if (this._maxLen > 0 && this._size > this._maxLen) this.shift();
     return true;
   }
 
@@ -253,6 +270,7 @@ export class Deque<E> extends IterableElementBase<E> {
     }
     this._size += 1;
     this._buckets[this._bucketFirst][this._firstInBucket] = element;
+    if (this._maxLen > 0 && this._size > this._maxLen) this.pop();
     return true;
   }
 
@@ -326,7 +344,7 @@ export class Deque<E> extends IterableElementBase<E> {
   /**
    * The below function is a generator that yields elements from a collection one by one.
    */
-  * begin(): Generator<E> {
+  *begin(): Generator<E> {
     let index = 0;
     while (index < this.size) {
       yield this.at(index);
@@ -338,7 +356,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * The function `reverseBegin()` is a generator that yields elements in reverse order starting from
    * the last element.
    */
-  * reverseBegin(): Generator<E> {
+  *reverseBegin(): Generator<E> {
     let index = this.size - 1;
     while (index >= 0) {
       yield this.at(index);
@@ -747,8 +765,8 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns The `clone()` method is returning a new instance of the `Deque` class with the same
    * elements as the original deque (`this`) and the same bucket size.
    */
-  clone(): Deque<E> {
-    return new Deque<E>([...this], { bucketSize: this.bucketSize });
+  clone(): Deque<E, R> {
+    return new Deque<E, R>(this, { bucketSize: this.bucketSize, toElementFn: this.toElementFn });
   }
 
   /**
@@ -772,8 +790,8 @@ export class Deque<E> extends IterableElementBase<E> {
    * @returns The `filter` method is returning a new `Deque` object that contains the elements that
    * satisfy the given predicate function.
    */
-  filter(predicate: ElementCallback<E, boolean>, thisArg?: any): Deque<E> {
-    const newDeque = new Deque<E>([], { bucketSize: this._bucketSize });
+  filter(predicate: ElementCallback<E, R, boolean, Deque<E, R>>, thisArg?: any): Deque<E, R> {
+    const newDeque = new Deque<E, R>([], { bucketSize: this._bucketSize, toElementFn: this.toElementFn });
     let index = 0;
     for (const el of this) {
       if (predicate.call(thisArg, el, index, this)) {
@@ -788,21 +806,28 @@ export class Deque<E> extends IterableElementBase<E> {
    * Time Complexity: O(n)
    * Space Complexity: O(n)
    */
+
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
-   *
-   * The `map` function creates a new Deque by applying a callback function to each element of the
-   * original Deque.
-   * @param callback - The `callback` parameter is a function that will be called for each element in
-   * the deque. 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 a new Deque object with the mapped values.
-   */
-  map<T>(callback: ElementCallback<E, T>, thisArg?: any): Deque<T> {
-    const newDeque = new Deque<T>([], { bucketSize: this._bucketSize });
+   * 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 will be called for each element in the
+   * deque. It takes three arguments: the current element, the index of the element, and the deque
+   * itself. It should return a value of type EM.
+   * @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 adding it to the new deque. If
+   * provided, this function will be called for each raw element in the original deque.
+   * @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 Deque object with elements of type EM and raw elements of type RM.
+   */
+  map<EM, RM>(
+    callback: ElementCallback<E, R, EM, Deque<E, R>>,
+    toElementFn?: (rawElement: RM) => EM,
+    thisArg?: any
+  ): Deque<EM, RM> {
+    const newDeque = new Deque<EM, RM>([], { bucketSize: this._bucketSize, toElementFn });
     let index = 0;
     for (const el of this) {
       newDeque.push(callback.call(thisArg, el, index, this));
@@ -823,7 +848,7 @@ export class Deque<E> extends IterableElementBase<E> {
    * The above function is an implementation of the iterator protocol in TypeScript, allowing the
    * object to be iterated over using a for...of loop.
    */
-  protected* _getIterator(): IterableIterator<E> {
+  protected *_getIterator(): IterableIterator<E> {
     for (let i = 0; i < this.size; ++i) {
       yield this.at(i);
     }

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

@@ -3,7 +3,7 @@
  * @copyright Tyler Zeng <zrwusa@gmail.com>
  * @class
  */
-import type { ElementCallback } from '../../types';
+import type { ElementCallback, QueueOptions } from '../../types';
 import { IterableElementBase } from '../base';
 import { SinglyLinkedList } from '../linked-list';
 
@@ -16,17 +16,20 @@ import { SinglyLinkedList } from '../linked-list';
  * 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.
  */
-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
-   * will be used to initialize the `_elements` property of the class. If not provided, the `_elements` property will be
-   * initialized as an empty array.
-   */
-  constructor(elements: Iterable<E> = []) {
-    super();
+export class Queue<E = any, R = any> extends IterableElementBase<E, R, Queue<E, R>> {
+  constructor(elements: Iterable<E> | Iterable<R> = [], options?: QueueOptions<E, R>) {
+    super(options);
+
+    if (options) {
+      const { autoCompactRatio = 0.5 } = options;
+      this._autoCompactRatio = autoCompactRatio;
+    }
+
     if (elements) {
-      for (const el of elements) this.push(el);
+      for (const el of elements) {
+        if (this.toElementFn) this.push(this.toElementFn(el as R));
+        else this.push(el as E);
+      }
     }
   }
 
@@ -92,6 +95,25 @@ export class Queue<E = any> extends IterableElementBase<E> {
     return this.size > 0 ? this.elements[this.elements.length - 1] : undefined;
   }
 
+  _autoCompactRatio: number = 0.5;
+
+  /**
+   * This function returns the value of the autoCompactRatio property.
+   * @returns The `autoCompactRatio` property of the object, which is a number.
+   */
+  get autoCompactRatio(): number {
+    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: number) {
+    this._autoCompactRatio = v;
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -103,7 +125,6 @@ export class Queue<E = any> extends IterableElementBase<E> {
    *
    * The function "fromArray" creates a new Queue object from an array of elements.Creates a queue from an existing array.
    * @public
-   * @static
    * @param {E[]} elements - The "elements" parameter is an array of elements of type E.
    * @returns The method is returning a new instance of the Queue class, initialized with the elements from the input
    * array.
@@ -149,12 +170,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
     const first = this.first;
     this._offset += 1;
 
-    if (this.offset * 2 < this.elements.length) return first;
-
-    // only delete dequeued elements when reaching half size
-    // to decrease latency of shifting elements.
-    this._elements = this.elements.slice(this.offset);
-    this._offset = 0;
+    if (this.offset / this.elements.length > this.autoCompactRatio) this.compact();
     return first;
   }
 
@@ -190,7 +206,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * @param index
    */
   at(index: number): E | undefined {
-    return this.elements[index];
+    return this.elements[index + this._offset];
   }
 
   /**
@@ -241,6 +257,17 @@ export class Queue<E = any> extends IterableElementBase<E> {
     this._offset = 0;
   }
 
+  /**
+   * The `compact` function in TypeScript slices the elements array based on the offset and resets the
+   * offset to zero.
+   * @returns The `compact()` method is returning a boolean value of `true`.
+   */
+  compact(): boolean {
+    this._elements = this.elements.slice(this.offset);
+    this._offset = 0;
+    return true;
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -254,8 +281,8 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * The `clone()` function returns a new Queue object with the same elements as the original Queue.
    * @returns The `clone()` method is returning a new instance of the `Queue` class.
    */
-  clone(): Queue<E> {
-    return new Queue(this.elements.slice(this.offset));
+  clone(): Queue<E, R> {
+    return new Queue(this.elements.slice(this.offset), { toElementFn: this.toElementFn });
   }
 
   /**
@@ -279,8 +306,8 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * @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>([]);
+  filter(predicate: ElementCallback<E, R, boolean, Queue<E, R>>, thisArg?: any): Queue<E, R> {
+    const newDeque = new Queue<E, R>([], { toElementFn: this.toElementFn });
     let index = 0;
     for (const el of this) {
       if (predicate.call(thisArg, el, index, this)) {
@@ -296,22 +323,12 @@ export class Queue<E = any> extends IterableElementBase<E> {
    * 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 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>([]);
+  map<EM, RM>(
+    callback: ElementCallback<E, R, EM, Queue<E, R>>,
+    toElementFn?: (rawElement: RM) => EM,
+    thisArg?: any
+  ): Queue<EM, RM> {
+    const newDeque = new Queue<EM, RM>([], { toElementFn });
     let index = 0;
     for (const el of this) {
       newDeque.push(callback.call(thisArg, el, index, this));
@@ -331,8 +348,8 @@ export class Queue<E = any> extends IterableElementBase<E> {
    *
    * The function `_getIterator` returns an iterable iterator for the elements in the class.
    */
-  protected* _getIterator(): IterableIterator<E> {
-    for (const item of this.elements) {
+  protected *_getIterator(): IterableIterator<E> {
+    for (const item of this.elements.slice(this.offset)) {
       yield item;
     }
   }
@@ -344,7 +361,7 @@ export class Queue<E = any> extends IterableElementBase<E> {
  * 3. Memory Usage: Since each element requires additional space to store a pointer to the next element, linked lists may use more memory compared to arrays.
  * 4. Frequent Enqueuing and Dequeuing Operations: If your application involves frequent enqueuing and dequeuing operations and is less concerned with random access, then LinkedListQueue is a good choice.
  */
-export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
+export class LinkedListQueue<E = any, R = any> extends SinglyLinkedList<E, R> {
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)
@@ -358,7 +375,7 @@ export class LinkedListQueue<E = any> extends SinglyLinkedList<E> {
    * @returns The `clone()` method is returning a new instance of `LinkedListQueue` with the same
    * values as the original `LinkedListQueue`.
    */
-  override clone(): LinkedListQueue<E> {
-    return new LinkedListQueue<E>(this.values());
+  override clone(): LinkedListQueue<E, R> {
+    return new LinkedListQueue<E, R>(this, { toElementFn: this.toElementFn });
   }
 }

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

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { ElementCallback } from '../../types';
+import type { ElementCallback, StackOptions } from '../../types';
 import { IterableElementBase } from '../base';
 
 /**
@@ -16,17 +16,17 @@ 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.
  */
-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
-   * of elements of type `E`. It is used to initialize the `_elements` property of the class. If the `elements` parameter
-   * is provided and is an array, it is assigned to the `_elements
-   */
-  constructor(elements: Iterable<E> = []) {
-    super();
+export class Stack<E = any, R = any> extends IterableElementBase<E, R, Stack<E, R>> {
+  constructor(elements: Iterable<E> | Iterable<R> = [], options?: StackOptions<E, R>) {
+    super(options);
     if (elements) {
-      for (const el of elements) this.push(el);
+      for (const el of elements) {
+        if (this.toElementFn) {
+          this.push(this.toElementFn(el as R));
+        } else {
+          this.push(el as E);
+        }
+      }
     }
   }
 
@@ -192,8 +192,8 @@ export class Stack<E = any> extends IterableElementBase<E> {
    * 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.
    */
-  clone(): Stack<E> {
-    return new Stack(this.elements.slice());
+  clone(): Stack<E, R> {
+    return new Stack<E, R>(this, { toElementFn: this.toElementFn });
   }
 
   /**
@@ -217,8 +217,8 @@ export class Stack<E = any> extends IterableElementBase<E> {
    * @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>();
+  filter(predicate: ElementCallback<E, R, boolean, Stack<E, R>>, thisArg?: any): Stack<E, R> {
+    const newStack = new Stack<E, R>([], { toElementFn: this.toElementFn });
     let index = 0;
     for (const el of this) {
       if (predicate.call(thisArg, el, index, this)) {
@@ -235,20 +235,25 @@ export class Stack<E = any> extends IterableElementBase<E> {
    */
 
   /**
-   * 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.
+   * @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.
    */
-  map<T>(callback: ElementCallback<E, T>, thisArg?: any): Stack<T> {
-    const newStack = new Stack<T>();
+  map<EM, RM>(
+    callback: ElementCallback<E, R, EM, Stack<E, R>>,
+    toElementFn?: (rawElement: RM) => EM,
+    thisArg?: any
+  ): Stack<EM, RM> {
+    const newStack = new Stack<EM, RM>([], { toElementFn });
     let index = 0;
     for (const el of this) {
       newStack.push(callback.call(thisArg, el, index, this));
@@ -269,7 +274,7 @@ export class Stack<E = any> extends IterableElementBase<E> {
    * Custom iterator for the Stack class.
    * @returns An iterator object.
    */
-  protected* _getIterator(): IterableIterator<E> {
+  protected *_getIterator(): IterableIterator<E> {
     for (let i = 0; i < this.elements.length; i++) {
       yield this.elements[i];
     }