queue-typed 1.53.6 → 1.53.8

package/src/data-structures/linked-list/doubly-linked-list.ts

@@ -82,52 +82,52 @@ export class DoublyLinkedListNode<E = any> {
 }
 
 /**
- * 1. Node Structure: Each node contains three parts: a data field, a pointer (or reference) to the previous node, and a pointer to the next node. This structure allows traversal of the linked list in both directions.
+ *1. Node Structure: Each node contains three parts: a data field, a pointer (or reference) to the previous node, and a pointer to the next node. This structure allows traversal of the linked list in both directions.
  * 2. Bidirectional Traversal: Unlike singly linked lists, doubly linked lists can be easily traversed forwards or backwards. This makes insertions and deletions in the list more flexible and efficient.
  * 3. No Centralized Index: Unlike arrays, elements in a linked list are not stored contiguously, so there is no centralized index. Accessing elements in a linked list typically requires traversing from the head or tail node.
  * 4. High Efficiency in Insertion and Deletion: Adding or removing elements in a linked list does not require moving other elements, making these operations more efficient than in arrays.
- * @example 
- * // text editor operation history 
- * const actions = [
+ * @example
+ * // text editor operation history
+ *     const actions = [
  *       { type: 'insert', content: 'first line of text' },
  *       { type: 'insert', content: 'second line of text' },
  *       { type: 'delete', content: 'delete the first line' }
  *     ];
  *     const editorHistory = new DoublyLinkedList<{ type: string; content: string }>(actions);
- * 
+ *
  *     console.log(editorHistory.last?.type); // 'delete'
  *     console.log(editorHistory.pop()?.content); // 'delete the first line'
  *     console.log(editorHistory.last?.type); // 'insert'
- * @example 
- * // Browser history 
- * const browserHistory = new DoublyLinkedList<string>();
- * 
+ * @example
+ * // Browser history
+ *     const browserHistory = new DoublyLinkedList<string>();
+ *
  *     browserHistory.push('home page');
  *     browserHistory.push('search page');
  *     browserHistory.push('details page');
- * 
+ *
  *     console.log(browserHistory.last); // 'details page'
  *     console.log(browserHistory.pop()); // 'details page'
  *     console.log(browserHistory.last); // 'search page'
- * @example 
- * // Use DoublyLinkedList to implement music player 
- * // Define the Song interface
+ * @example
+ * // Use DoublyLinkedList to implement music player
+ *     // Define the Song interface
  *     interface Song {
  *       title: string;
  *       artist: string;
  *       duration: number; // duration in seconds
  *     }
- * 
+ *
  *     class Player {
  *       private playlist: DoublyLinkedList<Song>;
  *       private currentSong: ReturnType<typeof this.playlist.getNodeAt> | undefined;
- * 
+ *
  *       constructor(songs: Song[]) {
  *         this.playlist = new DoublyLinkedList<Song>();
  *         songs.forEach(song => this.playlist.push(song));
  *         this.currentSong = this.playlist.head;
  *       }
- * 
+ *
  *       // Play the next song in the playlist
  *       playNext(): Song | undefined {
  *         if (!this.currentSong?.next) {
@@ -137,7 +137,7 @@ export class DoublyLinkedListNode<E = any> {
  *         }
  *         return this.currentSong?.value;
  *       }
- * 
+ *
  *       // Play the previous song in the playlist
  *       playPrevious(): Song | undefined {
  *         if (!this.currentSong?.prev) {
@@ -147,29 +147,29 @@ export class DoublyLinkedListNode<E = any> {
  *         }
  *         return this.currentSong?.value;
  *       }
- * 
+ *
  *       // Get the current song
  *       getCurrentSong(): Song | undefined {
  *         return this.currentSong?.value;
  *       }
- * 
+ *
  *       // Loop through the playlist twice
  *       loopThroughPlaylist(): Song[] {
  *         const playedSongs: Song[] = [];
  *         const initialNode = this.currentSong;
- * 
+ *
  *         // Loop through the playlist twice
  *         for (let i = 0; i < this.playlist.size * 2; i++) {
  *           playedSongs.push(this.currentSong!.value);
  *           this.currentSong = this.currentSong!.next || this.playlist.head; // Loop back to the start if needed
  *         }
- * 
+ *
  *         // Reset the current song to the initial song
  *         this.currentSong = initialNode;
  *         return playedSongs;
  *       }
  *     }
- * 
+ *
  *     const songs = [
  *       { title: 'Bohemian Rhapsody', artist: 'Queen', duration: 354 },
  *       { title: 'Hotel California', artist: 'Eagles', duration: 391 },
@@ -181,48 +181,48 @@ export class DoublyLinkedListNode<E = any> {
  *     player = new Player(songs);
  *     const firstSong = player.getCurrentSong();
  *     const nextSong = player.playNext();
- * 
+ *
  *     // Expect the next song to be "Hotel California by Eagles"
  *     console.log(nextSong); // { title: 'Hotel California', artist: 'Eagles', duration: 391 }
  *     console.log(firstSong); // { title: 'Bohemian Rhapsody', artist: 'Queen', duration: 354 }
- * 
+ *
  *     // should play the previous song
  *     player = new Player(songs);
  *     player.playNext(); // Move to the second song
  *     const currentSong = player.getCurrentSong();
  *     const previousSong = player.playPrevious();
- * 
+ *
  *     // Expect the previous song to be "Bohemian Rhapsody by Queen"
  *     console.log(previousSong); // { title: 'Bohemian Rhapsody', artist: 'Queen', duration: 354 }
  *     console.log(currentSong); // { title: 'Hotel California', artist: 'Eagles', duration: 391 }
- * 
+ *
  *     // should loop to the first song when playing next from the last song
  *     player = new Player(songs);
  *     player.playNext(); // Move to the second song
  *     player.playNext(); // Move to the third song
  *     player.playNext(); // Move to the fourth song
- * 
+ *
  *     const nextSongToFirst = player.playNext(); // Should loop to the first song
- * 
+ *
  *     // Expect the next song to be "Bohemian Rhapsody by Queen"
  *     console.log(nextSongToFirst); // { title: 'Bohemian Rhapsody', artist: 'Queen', duration: 354 }
- * 
+ *
  *     // should loop to the last song when playing previous from the first song
  *     player = new Player(songs);
  *     player.playNext(); // Move to the first song
  *     player.playNext(); // Move to the second song
  *     player.playNext(); // Move to the third song
  *     player.playNext(); // Move to the fourth song
- * 
+ *
  *     const previousToLast = player.playPrevious(); // Should loop to the last song
- * 
+ *
  *     // Expect the previous song to be "Billie Jean by Michael Jackson"
  *     console.log(previousToLast); // { title: 'Billie Jean', artist: 'Michael Jackson', duration: 294 }
- * 
+ *
  *     // should loop through the entire playlist
  *     player = new Player(songs);
  *     const playedSongs = player.loopThroughPlaylist();
- * 
+ *
  *     // The expected order of songs for two loops
  *     console.log(playedSongs); // [
  *  //      { title: 'Bohemian Rhapsody', artist: 'Queen', duration: 354 },
@@ -234,18 +234,18 @@ export class DoublyLinkedListNode<E = any> {
  *  //      { title: 'Shape of You', artist: 'Ed Sheeran', duration: 233 },
  *  //      { title: 'Billie Jean', artist: 'Michael Jackson', duration: 294 }
  *  //    ]
- * @example 
- * // Use DoublyLinkedList to implement LRU cache 
- * interface CacheEntry<K, V> {
+ * @example
+ * // Use DoublyLinkedList to implement LRU cache
+ *     interface CacheEntry<K, V> {
  *       key: K;
  *       value: V;
  *     }
- * 
+ *
  *     class LRUCache<K = string, V = any> {
  *       private readonly capacity: number;
  *       private list: DoublyLinkedList<CacheEntry<K, V>>;
  *       private map: Map<K, DoublyLinkedListNode<CacheEntry<K, V>>>;
- * 
+ *
  *       constructor(capacity: number) {
  *         if (capacity <= 0) {
  *           throw new Error('lru cache capacity must be greater than 0');
@@ -254,31 +254,31 @@ export class DoublyLinkedListNode<E = any> {
  *         this.list = new DoublyLinkedList<CacheEntry<K, V>>();
  *         this.map = new Map<K, DoublyLinkedListNode<CacheEntry<K, V>>>();
  *       }
- * 
+ *
  *       // Get cached value
  *       get(key: K): V | undefined {
  *         const node = this.map.get(key);
- * 
+ *
  *         if (!node) return undefined;
- * 
+ *
  *         // Move the visited node to the head of the linked list (most recently used)
  *         this.moveToFront(node);
- * 
+ *
  *         return node.value.value;
  *       }
- * 
+ *
  *       // Set cache value
  *       set(key: K, value: V): void {
  *         // Check if it already exists
  *         const node = this.map.get(key);
- * 
+ *
  *         if (node) {
  *           // Update value and move to head
  *           node.value.value = value;
  *           this.moveToFront(node);
  *           return;
  *         }
- * 
+ *
  *         // Check capacity
  *         if (this.list.size >= this.capacity) {
  *           // Delete the least recently used element (the tail of the linked list)
@@ -288,119 +288,119 @@ export class DoublyLinkedListNode<E = any> {
  *             this.list.pop();
  *           }
  *         }
- * 
+ *
  *         // Create new node and add to head
  *         const newEntry: CacheEntry<K, V> = { key, value };
  *         this.list.unshift(newEntry);
- * 
+ *
  *         // Save node reference in map
  *         const newNode = this.list.head;
  *         if (newNode) {
  *           this.map.set(key, newNode);
  *         }
  *       }
- * 
+ *
  *       // Move the node to the head of the linked list
  *       private moveToFront(node: DoublyLinkedListNode<CacheEntry<K, V>>): void {
  *         this.list.delete(node);
  *         this.list.unshift(node.value);
  *       }
- * 
+ *
  *       // Delete specific key
  *       delete(key: K): boolean {
  *         const node = this.map.get(key);
  *         if (!node) return false;
- * 
+ *
  *         // Remove from linked list
  *         this.list.delete(node);
  *         // Remove from map
  *         this.map.delete(key);
- * 
+ *
  *         return true;
  *       }
- * 
+ *
  *       // Clear cache
  *       clear(): void {
  *         this.list.clear();
  *         this.map.clear();
  *       }
- * 
+ *
  *       // Get the current cache size
  *       get size(): number {
  *         return this.list.size;
  *       }
- * 
+ *
  *       // Check if it is empty
  *       get isEmpty(): boolean {
  *         return this.list.isEmpty();
  *       }
  *     }
- * 
+ *
  *     // should set and get values correctly
  *     const cache = new LRUCache<string, number>(3);
  *     cache.set('a', 1);
  *     cache.set('b', 2);
  *     cache.set('c', 3);
- * 
+ *
  *     console.log(cache.get('a')); // 1
  *     console.log(cache.get('b')); // 2
  *     console.log(cache.get('c')); // 3
- * 
+ *
  *     // The least recently used element should be evicted when capacity is exceeded
  *     cache.clear();
  *     cache.set('a', 1);
  *     cache.set('b', 2);
  *     cache.set('c', 3);
  *     cache.set('d', 4); // This will eliminate 'a'
- * 
+ *
  *     console.log(cache.get('a')); // undefined
  *     console.log(cache.get('b')); // 2
  *     console.log(cache.get('c')); // 3
  *     console.log(cache.get('d')); // 4
- * 
+ *
  *     // The priority of an element should be updated when it is accessed
  *     cache.clear();
  *     cache.set('a', 1);
  *     cache.set('b', 2);
  *     cache.set('c', 3);
- * 
+ *
  *     cache.get('a'); // access 'a'
  *     cache.set('d', 4); // This will eliminate 'b'
- * 
+ *
  *     console.log(cache.get('a')); // 1
  *     console.log(cache.get('b')); // undefined
  *     console.log(cache.get('c')); // 3
  *     console.log(cache.get('d')); // 4
- * 
+ *
  *     // Should support updating existing keys
  *     cache.clear();
  *     cache.set('a', 1);
  *     cache.set('a', 10);
- * 
+ *
  *     console.log(cache.get('a')); // 10
- * 
+ *
  *     // Should support deleting specified keys
  *     cache.clear();
  *     cache.set('a', 1);
  *     cache.set('b', 2);
- * 
+ *
  *     console.log(cache.delete('a')); // true
  *     console.log(cache.get('a')); // undefined
  *     console.log(cache.size); // 1
- * 
+ *
  *     // Should support clearing cache
  *     cache.clear();
  *     cache.set('a', 1);
  *     cache.set('b', 2);
  *     cache.clear();
- * 
+ *
  *     console.log(cache.size); // 0
  *     console.log(cache.isEmpty); // true
- * @example 
- * // finding lyrics by timestamp in Coldplay's "Fix You" 
- * // Create a DoublyLinkedList to store song lyrics with timestamps
+ * @example
+ * // finding lyrics by timestamp in Coldplay's "Fix You"
+ *     // Create a DoublyLinkedList to store song lyrics with timestamps
  *     const lyricsList = new DoublyLinkedList<{ time: number; text: string }>();
- * 
+ *
  *     // Detailed lyrics with precise timestamps (in milliseconds)
  *     const lyrics = [
  *       { time: 0, text: "When you try your best, but you don't succeed" },
@@ -415,117 +415,124 @@ export class DoublyLinkedListNode<E = any> {
  *       { time: 36000, text: 'And ignite your bones' },
  *       { time: 40000, text: 'And I will try to fix you' }
  *     ];
- * 
+ *
  *     // Populate the DoublyLinkedList with lyrics
  *     lyrics.forEach(lyric => lyricsList.push(lyric));
- * 
+ *
  *     // Test different scenarios of lyric synchronization
- * 
+ *
  *     // 1. Find lyric at exact timestamp
  *     const exactTimeLyric = lyricsList.getBackward(lyric => lyric.value.time <= 36000);
  *     console.log(exactTimeLyric?.text); // 'And ignite your bones'
- * 
+ *
  *     // 2. Find lyric between timestamps
  *     const betweenTimeLyric = lyricsList.getBackward(lyric => lyric.value.time <= 22000);
  *     console.log(betweenTimeLyric?.text); // "When you lose something you can't replace"
- * 
+ *
  *     // 3. Find first lyric when timestamp is less than first entry
  *     const earlyTimeLyric = lyricsList.getBackward(lyric => lyric.value.time <= -1000);
  *     console.log(earlyTimeLyric); // undefined
- * 
+ *
  *     // 4. Find last lyric when timestamp is after last entry
  *     const lateTimeLyric = lyricsList.getBackward(lyric => lyric.value.time <= 50000);
  *     console.log(lateTimeLyric?.text); // 'And I will try to fix you'
- * @example 
- * // cpu process schedules 
- * class Process {
+ * @example
+ * // cpu process schedules
+ *     class Process {
  *       constructor(
  *         public id: number,
  *         public priority: number
  *       ) {}
- * 
+ *
  *       execute(): string {
  *         return `Process ${this.id} executed.`;
  *       }
  *     }
- * 
+ *
  *     class Scheduler {
  *       private queue: DoublyLinkedList<Process>;
- * 
+ *
  *       constructor() {
  *         this.queue = new DoublyLinkedList<Process>();
  *       }
- * 
+ *
  *       addProcess(process: Process): void {
  *         // Insert processes into a queue based on priority, keeping priority in descending order
  *         let current = this.queue.head;
  *         while (current && current.value.priority >= process.priority) {
  *           current = current.next;
  *         }
- * 
+ *
  *         if (!current) {
  *           this.queue.push(process);
  *         } else {
  *           this.queue.addBefore(current, process);
  *         }
  *       }
- * 
+ *
  *       executeNext(): string | undefined {
  *         // Execute tasks at the head of the queue in order
  *         const process = this.queue.shift();
  *         return process ? process.execute() : undefined;
  *       }
- * 
+ *
  *       listProcesses(): string[] {
  *         return this.queue.toArray().map(process => `Process ${process.id} (Priority: ${process.priority})`);
  *       }
- * 
+ *
  *       clear(): void {
  *         this.queue.clear();
  *       }
  *     }
- * 
+ *
  *     // should add processes based on priority
  *     let scheduler = new Scheduler();
  *     scheduler.addProcess(new Process(1, 10));
  *     scheduler.addProcess(new Process(2, 20));
  *     scheduler.addProcess(new Process(3, 15));
- * 
+ *
  *     console.log(scheduler.listProcesses()); // [
  *  //      'Process 2 (Priority: 20)',
  *  //      'Process 3 (Priority: 15)',
  *  //      'Process 1 (Priority: 10)'
  *  //    ]
- * 
+ *
  *     // should execute the highest priority process
  *     scheduler = new Scheduler();
  *     scheduler.addProcess(new Process(1, 10));
  *     scheduler.addProcess(new Process(2, 20));
- * 
+ *
  *     console.log(scheduler.executeNext()); // 'Process 2 executed.'
  *     console.log(scheduler.listProcesses()); // ['Process 1 (Priority: 10)']
- * 
+ *
  *     // should clear all processes
  *     scheduler = new Scheduler();
  *     scheduler.addProcess(new Process(1, 10));
  *     scheduler.addProcess(new Process(2, 20));
- * 
+ *
  *     scheduler.clear();
  *     console.log(scheduler.listProcesses()); // []
  */
 export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R, DoublyLinkedList<E, R>> {
-  constructor(elements: Iterable<E> | Iterable<R> = [], options?: DoublyLinkedListOptions<E, R>) {
+  /**
+   * This TypeScript constructor initializes a DoublyLinkedList with optional elements and options.
+   * @param {Iterable<E> | Iterable<R>} elements - The `elements` parameter in the constructor is an
+   * iterable collection of elements of type `E` or `R`. It is used to initialize the DoublyLinkedList
+   * with the elements provided in the iterable. If no elements are provided, the default value is an
+   * empty iterable.
+   * @param [options] - The `options` parameter in the constructor is of type
+   * `DoublyLinkedListOptions<E, R>`. It is an optional parameter that allows you to pass additional
+   * configuration options to customize the behavior of the DoublyLinkedList.
+   */
+  constructor(
+    elements: Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>> = [],
+    options?: DoublyLinkedListOptions<E, R>
+  ) {
     super(options);
     this._head = undefined;
     this._tail = undefined;
     this._size = 0;
-    if (elements) {
-      for (const el of elements) {
-        if (this.toElementFn) {
-          this.push(this.toElementFn(el as R));
-        } else this.push(el as E);
-      }
-    }
+    this.pushMany(elements);
   }
 
   protected _head: DoublyLinkedListNode<E> | undefined;
@@ -690,6 +697,57 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     return true;
   }
 
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The function `pushMany` iterates over elements and pushes them into a data structure, applying a
+   * transformation function if provided.
+   * @param {Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `pushMany` function can accept an iterable containing elements of type `E`, `R`,
+   * or `DoublyLinkedListNode<E>`. The function iterates over each element in the iterable and pushes
+   * it onto the linked list. If a transformation function `to
+   * @returns The `pushMany` function is returning an array of boolean values (`ans`) which indicate
+   * the success or failure of pushing each element into the data structure.
+   */
+  pushMany(elements: Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.push(this.toElementFn(el as R)));
+        continue;
+      }
+      ans.push(this.push(el as E | DoublyLinkedListNode<E>));
+    }
+    return ans;
+  }
+
+  /**
+   * Time Complexity: O(k)
+   * Space Complexity: O(k)
+   *
+   * The function `unshiftMany` iterates through a collection of elements and adds them to the
+   * beginning of a Doubly Linked List, returning an array of boolean values indicating the success of
+   * each insertion.
+   * @param {Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>} elements - The `elements`
+   * parameter in the `unshiftMany` function can accept an iterable containing elements of type `E`,
+   * `R`, or `DoublyLinkedListNode<E>`. The function iterates over each element in the iterable and
+   * performs an `unshift` operation on the doubly linked list
+   * @returns The `unshiftMany` function returns an array of boolean values indicating the success of
+   * each unshift operation performed on the elements passed as input.
+   */
+  unshiftMany(elements: Iterable<E> | Iterable<R> | Iterable<DoublyLinkedListNode<E>>) {
+    const ans: boolean[] = [];
+    for (const el of elements) {
+      if (this.toElementFn) {
+        ans.push(this.unshift(this.toElementFn(el as R)));
+        continue;
+      }
+      ans.push(this.unshift(el as E | DoublyLinkedListNode<E>));
+    }
+    return ans;
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(1)
@@ -819,7 +877,9 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     existingElementOrNode: E | DoublyLinkedListNode<E>,
     newElementOrNode: E | DoublyLinkedListNode<E>
   ): boolean {
-    const existingNode: DoublyLinkedListNode<E> | undefined = this.getNode(existingElementOrNode);
+    const existingNode: DoublyLinkedListNode<E> | undefined = this.isNode(existingElementOrNode)
+      ? existingElementOrNode
+      : this.getNode(existingElementOrNode);
 
     if (existingNode) {
       const newNode = this._ensureNode(newElementOrNode);
@@ -856,7 +916,9 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * was not found in the linked list.
    */
   addAfter(existingElementOrNode: E | DoublyLinkedListNode<E>, newElementOrNode: E | DoublyLinkedListNode<E>): boolean {
-    const existingNode: DoublyLinkedListNode<E> | undefined = this.getNode(existingElementOrNode);
+    const existingNode: DoublyLinkedListNode<E> | undefined = this.isNode(existingElementOrNode)
+      ? existingElementOrNode
+      : this.getNode(existingElementOrNode);
 
     if (existingNode) {
       const newNode = this._ensureNode(newElementOrNode);
@@ -999,7 +1061,7 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * @returns The `get` method returns the value of the first node in the doubly linked list that
    * satisfies the provided predicate function. If no such node is found, it returns `undefined`.
    */
-  get(
+  search(
     elementNodeOrPredicate: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)
   ): E | undefined {
     const predicate = this._ensurePredicate(elementNodeOrPredicate);
@@ -1168,6 +1230,12 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
+   * The function `countOccurrences` iterates through a doubly linked list and counts the occurrences
+   * of a specified element or nodes that satisfy a given predicate.
+   * @param {E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)} elementOrNode
+   * - The `elementOrNode` parameter in the `countOccurrences` method can accept three types of values:
+   * @returns The `countOccurrences` method returns the number of occurrences of the specified element,
+   * node, or predicate function in the doubly linked list.
    */
   countOccurrences(elementOrNode: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)): number {
     const predicate = this._ensurePredicate(elementOrNode);