linked-list-typed 1.53.5 → 1.53.7

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,105 +415,115 @@ 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>> {
+  /**
+   * 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> = [], options?: DoublyLinkedListOptions<E, R>) {
     super(options);
     this._head = undefined;
@@ -819,13 +829,9 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     existingElementOrNode: E | DoublyLinkedListNode<E>,
     newElementOrNode: E | DoublyLinkedListNode<E>
   ): boolean {
-    let existingNode;
-
-    if (existingElementOrNode instanceof DoublyLinkedListNode) {
-      existingNode = existingElementOrNode;
-    } else {
-      existingNode = this.getNode(existingElementOrNode);
-    }
+    const existingNode: DoublyLinkedListNode<E> | undefined = this.isNode(existingElementOrNode)
+      ? existingElementOrNode
+      : this.getNode(existingElementOrNode);
 
     if (existingNode) {
       const newNode = this._ensureNode(newElementOrNode);
@@ -862,13 +868,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 {
-    let existingNode;
-
-    if (existingElementOrNode instanceof DoublyLinkedListNode) {
-      existingNode = existingElementOrNode;
-    } else {
-      existingNode = this.getNode(existingElementOrNode);
-    }
+    const existingNode: DoublyLinkedListNode<E> | undefined = this.isNode(existingElementOrNode)
+      ? existingElementOrNode
+      : this.getNode(existingElementOrNode);
 
     if (existingNode) {
       const newNode = this._ensureNode(newElementOrNode);
@@ -978,17 +980,15 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
-   * The indexOf function in TypeScript returns the index of a specified element or node in a Doubly
-   * Linked List.
-   * @param {E | DoublyLinkedListNode<E>} elementOrNode - The `elementOrNode` parameter in the
-   * `indexOf` method can be either an element of type `E` or a `DoublyLinkedListNode` containing an
-   * element of type `E`.
-   * @returns The `indexOf` method is returning the index of the element or node in the doubly linked
-   * list. If the element or node is found in the list, the method returns the index of that element or
-   * node. If the element or node is not found in the list, the method returns -1.
+   * This function finds the index of a specified element, node, or predicate in a doubly linked list.
+   * @param {E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
+   * elementNodeOrPredicate - The `indexOf` method takes in a parameter `elementNodeOrPredicate`, which
+   * can be one of the following:
+   * @returns The `indexOf` method returns the index of the element in the doubly linked list that
+   * matches the provided element, node, or predicate. If no match is found, it returns -1.
    */
-  indexOf(elementOrNode: E | DoublyLinkedListNode<E>): number {
-    const predicate = this._ensurePredicate(elementOrNode);
+  indexOf(elementNodeOrPredicate: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)): number {
+    const predicate = this._ensurePredicate(elementNodeOrPredicate);
     let index = 0;
     let current = this.head;
     while (current) {
@@ -1005,8 +1005,6 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
    * Time Complexity: O(n)
    * Space Complexity: O(1)
    *
-   */
-  /**
    * This function retrieves an element from a doubly linked list based on a given element
    * node or predicate.
    * @param {E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
@@ -1015,7 +1013,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);
@@ -1180,6 +1178,26 @@ export class DoublyLinkedList<E = any, R = any> extends IterableElementBase<E, R
     return mappedList;
   }
 
+  /**
+   * Time Complexity: O(n)
+   * Space Complexity: O(1)
+   *
+   */
+  countOccurrences(elementOrNode: E | DoublyLinkedListNode<E> | ((node: DoublyLinkedListNode<E>) => boolean)): number {
+    const predicate = this._ensurePredicate(elementOrNode);
+    let count = 0;
+    let current = this.head;
+
+    while (current) {
+      if (predicate(current)) {
+        count++;
+      }
+      current = current.next;
+    }
+
+    return count;
+  }
+
   /**
    * Time Complexity: O(n)
    * Space Complexity: O(n)