linked-list-typed 2.0.5 → 2.1.1

package/dist/data-structures/linked-list/singly-linked-list.js

@@ -1,33 +1,60 @@
 "use strict";
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SinglyLinkedList = exports.SinglyLinkedListNode = void 0;
 const linear_base_1 = require("../base/linear-base");
+/**
+ * Node of a singly linked list; stores value and the next link.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ */
 class SinglyLinkedListNode extends linear_base_1.LinkedListNode {
     /**
-     * The constructor function initializes an instance of a class with a given value and sets the next property to undefined.
-     * @param {E} value - The "value" parameter is of type E, which means it can be any data type. It represents the value that
-     * will be stored in the node of a linked list.
+     * Create a list node.
+     * @remarks Time O(1), Space O(1)
+     * @param value - Element value to store.
+     * @returns New node instance.
      */
     constructor(value) {
         super(value);
         this._value = value;
         this._next = undefined;
     }
+    /**
+     * Get the next node.
+     * @remarks Time O(1), Space O(1)
+     * @returns Next node or undefined.
+     */
     get next() {
         return this._next;
     }
+    /**
+     * Set the next node.
+     * @remarks Time O(1), Space O(1)
+     * @param value - Next node or undefined.
+     * @returns void
+     */
     set next(value) {
         this._next = value;
     }
 }
 exports.SinglyLinkedListNode = SinglyLinkedListNode;
 /**
+ * Singly linked list with O(1) push/pop-like ends operations and linear scans.
+ * @remarks Time O(1), Space O(1)
+ * @template E
+ * @template R
  * 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 doubly linked lists, singly linked lists can be easily traversed forwards but not backwards.
  * 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.
  * Caution: Although our linked list classes provide methods such as at, setAt, addAt, and indexOf that are based on array indices, their time complexity, like that of the native Array.lastIndexOf, is 𝑂(𝑛). If you need to use these methods frequently, you might want to consider other data structures, such as Deque or Queue (designed for random access). Similarly, since the native Array.shift method has a time complexity of 𝑂(𝑛), using an array to simulate a queue can be inefficient. In such cases, you should use Queue or Deque, as these data structures leverage deferred array rearrangement, effectively reducing the average time complexity to 𝑂(1).
- *
  * @example
  * // implementation of a basic text editor
  *     class TextEditor {
@@ -96,60 +123,88 @@ exports.SinglyLinkedListNode = SinglyLinkedListNode;
  *     console.log(editor.getText()); // 'Haello'
  */
 class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
+    /**
+     * Create a SinglyLinkedList and optionally bulk-insert elements.
+     * @remarks Time O(N), Space O(N)
+     * @param [elements] - Iterable of elements or nodes (or raw records if toElementFn is provided).
+     * @param [options] - Options such as maxLen and toElementFn.
+     * @returns New SinglyLinkedList instance.
+     */
     constructor(elements = [], options) {
         super(options);
+        this._equals = Object.is;
         this._length = 0;
-        if (options) {
-        }
         this.pushMany(elements);
     }
+    /**
+     * Get the head node.
+     * @remarks Time O(1), Space O(1)
+     * @returns Head node or undefined.
+     */
     get head() {
         return this._head;
     }
+    /**
+     * Get the tail node.
+     * @remarks Time O(1), Space O(1)
+     * @returns Tail node or undefined.
+     */
     get tail() {
         return this._tail;
     }
+    /**
+     * Get the number of elements.
+     * @remarks Time O(1), Space O(1)
+     * @returns Current length.
+     */
+    get length() {
+        return this._length;
+    }
+    /**
+     * Get the first element value.
+     * @remarks Time O(1), Space O(1)
+     * @returns First element or undefined.
+     */
     get first() {
         var _a;
         return (_a = this.head) === null || _a === void 0 ? void 0 : _a.value;
     }
+    /**
+     * Get the last element value.
+     * @remarks Time O(1), Space O(1)
+     * @returns Last element or undefined.
+     */
     get last() {
         var _a;
         return (_a = this.tail) === null || _a === void 0 ? void 0 : _a.value;
     }
-    get length() {
-        return this._length;
-    }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `fromArray` function creates a new SinglyLinkedList instance and populates it with the elements from the given
-     * array.
-     * @param {E[]} data - The `data` parameter is an array of elements of type `E`.
-     * @returns The `fromArray` function returns a `SinglyLinkedList` object.
+     * Create a new list from an iterable of elements.
+     * @remarks Time O(N), Space O(N)
+     * @template E
+     * @template R
+     * @template S
+     * @param this - The constructor (subclass) to instantiate.
+     * @param data - Iterable of elements to insert.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A new list populated with the iterable's elements.
      */
-    static fromArray(data) {
-        const singlyLinkedList = new SinglyLinkedList();
-        for (const item of data) {
-            singlyLinkedList.push(item);
-        }
-        return singlyLinkedList;
+    static from(data, options) {
+        const list = new this([], options);
+        for (const x of data)
+            list.push(x);
+        return list;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `push` function adds a new element or node to the end of a singly linked list.
-     * @param {E | SinglyLinkedListNode<E>} elementOrNode - The `elementOrNode` parameter in the `push`
-     * method can accept either an element of type `E` or a `SinglyLinkedListNode<E>` object.
-     * @returns The `push` method is returning a boolean value, specifically `true`.
+     * Append an element/node to the tail.
+     * @remarks Time O(1), Space O(1)
+     * @param elementOrNode - Element or node to append.
+     * @returns True when appended.
      */
     push(elementOrNode) {
         const newNode = this._ensureNode(elementOrNode);
         if (!this.head) {
-            this._head = newNode;
-            this._tail = newNode;
+            this._head = this._tail = newNode;
         }
         else {
             this.tail.next = newNode;
@@ -161,12 +216,9 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `pop` function removes and returns the value of the last element in a linked list.
-     * @returns The method is returning the value of the element that is being popped from the end of the
-     * list.
+     * Remove and return the tail element.
+     * @remarks Time O(N), Space O(1)
+     * @returns Removed element or undefined.
      */
     pop() {
         if (!this.head)
@@ -179,9 +231,8 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
             return value;
         }
         let current = this.head;
-        while (current.next !== this.tail) {
+        while (current.next !== this.tail)
             current = current.next;
-        }
         const value = this.tail.value;
         current.next = undefined;
         this._tail = current;
@@ -189,36 +240,30 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return value;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `shift()` function removes and returns the value of the first element in a linked list.
-     * @returns The value of the removed node.
+     * Remove and return the head element.
+     * @remarks Time O(1), Space O(1)
+     * @returns Removed element or undefined.
      */
     shift() {
         if (!this.head)
             return undefined;
-        const removedNode = this.head;
+        const removed = this.head;
         this._head = this.head.next;
+        if (!this._head)
+            this._tail = undefined;
         this._length--;
-        return removedNode.value;
+        return removed.value;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The unshift function adds a new element or node to the beginning of a singly linked list in
-     * TypeScript.
-     * @param {E | SinglyLinkedListNode<E>} elementOrNode - The `elementOrNode` parameter in the
-     * `unshift` method can be either an element of type `E` or a `SinglyLinkedListNode` containing an
-     * element of type `E`.
-     * @returns The `unshift` method is returning a boolean value, specifically `true`.
+     * Prepend an element/node to the head.
+     * @remarks Time O(1), Space O(1)
+     * @param elementOrNode - Element or node to prepend.
+     * @returns True when prepended.
      */
     unshift(elementOrNode) {
         const newNode = this._ensureNode(elementOrNode);
         if (!this.head) {
-            this._head = newNode;
-            this._tail = newNode;
+            this._head = this._tail = newNode;
         }
         else {
             newNode.next = this.head;
@@ -228,63 +273,42 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         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<SinglyLinkedListNode<E>>} elements - The `elements`
-     * parameter in the `pushMany` function can accept an iterable containing elements of type `E`, `R`,
-     * or `SinglyLinkedListNode<E>`.
-     * @returns The `pushMany` function returns an array of boolean values indicating whether each
-     * element was successfully pushed into the data structure.
+     * Append a sequence of elements/nodes.
+     * @remarks Time O(N), Space O(1)
+     * @param elements - Iterable of elements or nodes (or raw records if toElementFn is provided).
+     * @returns Array of per-element success flags.
      */
     pushMany(elements) {
         const ans = [];
         for (const el of elements) {
-            if (this.toElementFn) {
+            if (this.toElementFn)
                 ans.push(this.push(this.toElementFn(el)));
-                continue;
-            }
-            ans.push(this.push(el));
+            else
+                ans.push(this.push(el));
         }
         return ans;
     }
     /**
-     * Time Complexity: O(k)
-     * Space Complexity: O(k)
-     *
-     * The function `unshiftMany` iterates over elements and adds them to a data structure, optionally
-     * converting them using a provided function.
-     * @param {Iterable<E> | Iterable<R> | Iterable<SinglyLinkedListNode<E>>} elements - The `elements`
-     * parameter in the `unshiftMany` function can accept an iterable containing elements of type `E`,
-     * `R`, or `SinglyLinkedListNode<E>`. The function iterates over each element in the iterable and
-     * performs an `unshift` operation on the linked list for each
-     * @returns The `unshiftMany` function is returning an array of boolean values, where each value
-     * represents the result of calling the `unshift` method on the current instance of the class.
+     * Prepend a sequence of elements/nodes.
+     * @remarks Time O(N), Space O(1)
+     * @param elements - Iterable of elements or nodes (or raw records if toElementFn is provided).
+     * @returns Array of per-element success flags.
      */
     unshiftMany(elements) {
         const ans = [];
         for (const el of elements) {
-            if (this.toElementFn) {
+            if (this.toElementFn)
                 ans.push(this.unshift(this.toElementFn(el)));
-                continue;
-            }
-            ans.push(this.unshift(el));
+            else
+                ans.push(this.unshift(el));
         }
         return ans;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * This function searches for a specific element in a singly linked list based on a given node or
-     * predicate.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter in the `get` method can be one of
-     * the following types:
-     * @returns The `get` method returns the value of the first node in the singly linked list that
-     * satisfies the provided predicate function. If no such node is found, it returns `undefined`.
+     * Find the first value matching a predicate (by node).
+     * @remarks Time O(N), Space O(1)
+     * @param elementNodeOrPredicate - Element, node, or node predicate to match.
+     * @returns Matched value or undefined.
      */
     search(elementNodeOrPredicate) {
         const predicate = this._ensurePredicate(elementNodeOrPredicate);
@@ -297,97 +321,67 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return undefined;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `at` returns the value at a specified index in a linked list, or undefined if the index is out of range.
-     * @param {number} index - The index parameter is a number that represents the position of the element we want to
-     * retrieve from the list.
-     * @returns The method `at(index: number): E | undefined` returns the value at the specified index in the linked list, or
-     * `undefined` if the index is out of bounds.
+     * Get the element at a given index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index.
+     * @returns Element or undefined.
      */
     at(index) {
         if (index < 0 || index >= this._length)
             return undefined;
         let current = this.head;
-        for (let i = 0; i < index; i++) {
+        for (let i = 0; i < index; i++)
             current = current.next;
-        }
         return current.value;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function `isNode` in TypeScript checks if the input is an instance of `SinglyLinkedListNode`.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter in the `isNode` function can be
-     * one of the following types:
-     * @returns The `isNode` function is checking if the `elementNodeOrPredicate` parameter is an
-     * instance of `SinglyLinkedListNode<E>`. If it is, the function returns `true`, indicating that the
-     * parameter is a `SinglyLinkedListNode<E>`. If it is not an instance of `SinglyLinkedListNode<E>`,
-     * the function returns `false`.
+     * Type guard: check whether the input is a SinglyLinkedListNode.
+     * @remarks Time O(1), Space O(1)
+     * @param elementNodeOrPredicate - Element, node, or predicate.
+     * @returns True if the value is a SinglyLinkedListNode.
      */
     isNode(elementNodeOrPredicate) {
         return elementNodeOrPredicate instanceof SinglyLinkedListNode;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `getNodeAt` returns the node at a given index in a singly linked list.
-     * @param {number} index - The `index` parameter is a number that represents the position of the node we want to
-     * retrieve from the linked list. It indicates the zero-based index of the node we want to access.
-     * @returns The method `getNodeAt(index: number)` returns a `SinglyLinkedListNode<E>` object if the node at the
-     * specified index exists, or `undefined` if the index is out of bounds.
+     * Get the node reference at a given index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index.
+     * @returns Node or undefined.
      */
     getNodeAt(index) {
+        if (index < 0 || index >= this._length)
+            return undefined;
         let current = this.head;
-        for (let i = 0; i < index; i++) {
+        for (let i = 0; i < index; i++)
             current = current.next;
-        }
         return current;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `deleteAt` function removes an element at a specified index from a linked list and returns the removed element.
-     * @param {number} index - The index parameter represents the position of the element that needs to be deleted in the
-     * data structure. It is of type number.
-     * @returns The method `deleteAt` returns the value of the node that was deleted, or `undefined` if the index is out of
-     * bounds.
+     * Delete the element at an index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index.
+     * @returns Removed element or undefined.
      */
     deleteAt(index) {
         if (index < 0 || index >= this._length)
-            return;
-        let deleted;
-        if (index === 0) {
-            deleted = this.first;
-            this.shift();
-            return deleted;
-        }
+            return undefined;
+        if (index === 0)
+            return this.shift();
         const targetNode = this.getNodeAt(index);
         const prevNode = this._getPrevNode(targetNode);
-        if (prevNode && targetNode) {
-            deleted = targetNode.value;
-            prevNode.next = targetNode.next;
-            if (targetNode === this.tail)
-                this._tail = prevNode;
-            this._length--;
-            return deleted;
-        }
-        return;
+        const value = targetNode.value;
+        prevNode.next = targetNode.next;
+        if (targetNode === this.tail)
+            this._tail = prevNode;
+        this._length--;
+        return value;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The delete function removes a node with a specific value from a singly linked list.
-     * @param {E | SinglyLinkedListNode<E>} elementOrNode - The `elementOrNode` parameter can accept either a value of type `E`
-     * or a `SinglyLinkedListNode<E>` object.
-     * @returns The `delete` method returns a boolean value. It returns `true` if the value or node is found and
-     * successfully deleted from the linked list, and `false` if the value or node is not found in the linked list.
+     * Delete the first match by value/node.
+     * @remarks Time O(N), Space O(1)
+     * @param [elementOrNode] - Element or node to remove; if omitted/undefined, nothing happens.
+     * @returns True if removed.
      */
     delete(elementOrNode) {
         if (elementOrNode === undefined || !this.head)
@@ -397,7 +391,6 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
             return false;
         const prevNode = this._getPrevNode(node);
         if (!prevNode) {
-            // The node is the head
             this._head = node.next;
             if (node === this.tail)
                 this._tail = undefined;
@@ -411,31 +404,19 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `addAt` function inserts a new element or node at a specified index in a singly linked list.
-     * @param {number} index - The `index` parameter represents the position at which you want to add a
-     * new element or node in the linked list. It is a number that indicates the index where the new
-     * element or node should be inserted.
-     * @param {E | SinglyLinkedListNode<E>} newElementOrNode - The `newElementOrNode` parameter in the
-     * `addAt` method can be either a value of type `E` or a `SinglyLinkedListNode<E>` object. This
-     * parameter represents the element or node that you want to add to the linked list at the specified
-     * index.
-     * @returns The `addAt` method returns a boolean value - `true` if the element or node was
-     * successfully added at the specified index, and `false` if the index is out of bounds.
+     * Insert a new element/node at an index, shifting following nodes.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index.
+     * @param newElementOrNode - Element or node to insert.
+     * @returns True if inserted.
      */
     addAt(index, newElementOrNode) {
         if (index < 0 || index > this._length)
             return false;
-        if (index === 0) {
-            this.unshift(newElementOrNode);
-            return true;
-        }
-        if (index === this._length) {
-            this.push(newElementOrNode);
-            return true;
-        }
+        if (index === 0)
+            return this.unshift(newElementOrNode);
+        if (index === this._length)
+            return this.push(newElementOrNode);
         const newNode = this._ensureNode(newElementOrNode);
         const prevNode = this.getNodeAt(index - 1);
         newNode.next = prevNode.next;
@@ -444,43 +425,31 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function setAt(index, value) updates the value at a specified index in a data structure if the
-     * index exists.
-     * @param {number} index - The `index` parameter in the `setAt` method refers to the position in the
-     * data structure where you want to set a new value.
-     * @param {E} value - The `value` parameter in the `setAt` method represents the new value that you
-     * want to set at the specified index in the data structure.
-     * @returns The `setAt` method returns a boolean value - `true` if the value at the specified index
-     * is successfully updated, and `false` if the index is out of bounds (i.e., the node at that index
-     * does not exist).
+     * Set the element value at an index.
+     * @remarks Time O(N), Space O(1)
+     * @param index - Zero-based index.
+     * @param value - New value.
+     * @returns True if updated.
      */
     setAt(index, value) {
         const node = this.getNodeAt(index);
-        if (node) {
-            node.value = value;
-            return true;
-        }
-        return false;
+        if (!node)
+            return false;
+        node.value = value;
+        return true;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The function checks if the length of a data structure is equal to zero and returns a boolean value indicating
-     * whether it is empty or not.
-     * @returns A boolean value indicating whether the length of the object is equal to 0.
+     * Check whether the list is empty.
+     * @remarks Time O(1), Space O(1)
+     * @returns True if length is 0.
      */
     isEmpty() {
         return this._length === 0;
     }
     /**
-     * Time Complexity: O(1)
-     * Space Complexity: O(1)
-     *
-     * The `clear` function resets the linked list by setting the head, tail, and length to undefined and 0 respectively.
+     * Remove all nodes and reset length.
+     * @remarks Time O(N), Space O(1)
+     * @returns void
      */
     clear() {
         this._head = undefined;
@@ -488,18 +457,16 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         this._length = 0;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `reverse` function reverses the order of the nodes in a singly linked list.
-     * @returns The reverse() method does not return anything. It has a return type of void.
+     * Reverse the list in place.
+     * @remarks Time O(N), Space O(1)
+     * @returns This list.
      */
     reverse() {
         if (!this.head || this.head === this.tail)
             return this;
-        let prev = undefined;
+        let prev;
         let current = this.head;
-        let next = undefined;
+        let next;
         while (current) {
             next = current.next;
             current.next = prev;
@@ -510,17 +477,10 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return this;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `getNode` in TypeScript searches for a node in a singly linked list based on a given
-     * element, node, or predicate.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean) | undefined} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter in the `getNode` method can be one
-     * of the following types:
-     * @returns The `getNode` method returns either a `SinglyLinkedListNode<E>` if a matching node is
-     * found based on the provided predicate, or it returns `undefined` if no matching node is found or
-     * if the input parameter is `undefined`.
+     * Find a node by value, reference, or predicate.
+     * @remarks Time O(N), Space O(1)
+     * @param [elementNodeOrPredicate] - Element, node, or node predicate to match.
+     * @returns Matching node or undefined.
      */
     getNode(elementNodeOrPredicate) {
         if (elementNodeOrPredicate === undefined)
@@ -530,28 +490,18 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         const predicate = this._ensurePredicate(elementNodeOrPredicate);
         let current = this.head;
         while (current) {
-            if (predicate(current)) {
+            if (predicate(current))
                 return current;
-            }
             current = current.next;
         }
         return undefined;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `addBefore` in TypeScript adds a new element or node before an existing element or
-     * node in a singly linked list.
-     * @param {E | SinglyLinkedListNode<E>} existingElementOrNode - existingElementOrNode represents the
-     * element or node in the linked list before which you want to add a new element or node.
-     * @param {E | SinglyLinkedListNode<E>} newElementOrNode - The `newElementOrNode` parameter in the
-     * `addBefore` method represents the element or node that you want to insert before the existing
-     * element or node in the linked list. This new element can be of type `E` or a
-     * `SinglyLinkedListNode<E>`.
-     * @returns The `addBefore` method returns a boolean value - `true` if the new element or node was
-     * successfully added before the existing element or node, and `false` if the operation was
-     * unsuccessful.
+     * Insert a new element/node before an existing one.
+     * @remarks Time O(N), Space O(1)
+     * @param existingElementOrNode - Existing element or node.
+     * @param newElementOrNode - Element or node to insert.
+     * @returns True if inserted.
      */
     addBefore(existingElementOrNode, newElementOrNode) {
         const existingNode = this.getNode(existingElementOrNode);
@@ -560,8 +510,11 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         const prevNode = this._getPrevNode(existingNode);
         const newNode = this._ensureNode(newElementOrNode);
         if (!prevNode) {
-            // Add at the head
-            this.unshift(newNode);
+            newNode.next = this._head;
+            this._head = newNode;
+            if (!this._tail)
+                this._tail = newNode;
+            this._length++;
         }
         else {
             prevNode.next = newNode;
@@ -571,299 +524,327 @@ class SinglyLinkedList extends linear_base_1.LinearLinkedBase {
         return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The `addAfter` function in TypeScript adds a new element or node after an existing element or node
-     * in a singly linked list.
-     * @param {E | SinglyLinkedListNode<E>} existingElementOrNode - existingElementOrNode can be either
-     * an element of type E or a SinglyLinkedListNode of type E.
-     * @param {E | SinglyLinkedListNode<E>} newElementOrNode - The `newElementOrNode` parameter in the
-     * `addAfter` method represents the element or node that you want to add after the existing element
-     * or node in a singly linked list. This parameter can be either the value of the new element or a
-     * reference to a `SinglyLinkedListNode` containing
-     * @returns The `addAfter` method returns a boolean value - `true` if the new element or node was
-     * successfully added after the existing element or node, and `false` if the existing element or node
-     * was not found.
+     * Insert a new element/node after an existing one.
+     * @remarks Time O(N), Space O(1)
+     * @param existingElementOrNode - Existing element or node.
+     * @param newElementOrNode - Element or node to insert.
+     * @returns True if inserted.
      */
     addAfter(existingElementOrNode, newElementOrNode) {
         const existingNode = this.getNode(existingElementOrNode);
-        if (existingNode) {
-            const newNode = this._ensureNode(newElementOrNode);
-            newNode.next = existingNode.next;
-            existingNode.next = newNode;
-            if (existingNode === this.tail) {
-                this._tail = newNode;
-            }
-            this._length++;
-            return true;
-        }
-        return false;
+        if (!existingNode)
+            return false;
+        const newNode = this._ensureNode(newElementOrNode);
+        newNode.next = existingNode.next;
+        existingNode.next = newNode;
+        if (existingNode === this.tail)
+            this._tail = newNode;
+        this._length++;
+        return true;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `splice` in TypeScript overrides the default behavior to remove and insert elements
-     * in a singly linked list while handling boundary cases.
-     * @param {number} start - The `start` parameter in the `splice` method indicates the index at which
-     * to start modifying the list. It specifies the position where elements will be added or removed.
-     * @param {number} [deleteCount=0] - The `deleteCount` parameter in the `splice` method specifies the
-     * number of elements to remove from the array starting at the specified `start` index. If
-     * `deleteCount` is not provided, it defaults to 0, meaning no elements will be removed but new
-     * elements can still be inserted at
-     * @param {E[]} items - The `items` parameter in the `splice` method represents the elements to be
-     * inserted into the list at the specified `start` index. These elements will be inserted in place of
-     * the elements that are removed from the list. The `splice` method allows you to add new elements to
-     * the list while
-     * @returns The `splice` method is returning a `SinglyLinkedList` containing the elements that were
-     * removed from the original list during the splice operation.
+     * Remove and/or insert elements at a position (array-like behavior).
+     * @remarks Time O(N + M), Space O(M)
+     * @param start - Start index (clamped to [0, length]).
+     * @param [deleteCount] - Number of elements to remove (default 0).
+     * @param [items] - Elements to insert after `start`.
+     * @returns A new list containing the removed elements (typed as `this`).
      */
     splice(start, deleteCount = 0, ...items) {
-        const removedList = this._createInstance({ toElementFn: this._toElementFn, maxLen: this._maxLen });
-        // If `start` is out of range, perform boundary processing
         start = Math.max(0, Math.min(start, this.length));
         deleteCount = Math.max(0, deleteCount);
-        // Find the predecessor node of `start`
+        const removedList = this._createInstance();
         const prevNode = start === 0 ? undefined : this.getNodeAt(start - 1);
-        const startNode = prevNode ? prevNode.next : this.head;
-        let current = startNode;
-        for (let i = 0; i < deleteCount && current; i++) {
-            removedList.push(current.value);
-            current = current.next;
-        }
-        const nextNode = current;
-        let lastInsertedNode = undefined;
-        for (const item of items) {
-            const newNode = this._ensureNode(item);
-            if (!lastInsertedNode) {
-                if (prevNode) {
-                    prevNode.next = newNode;
-                }
-                else {
-                    this._head = newNode;
-                }
-            }
-            else {
-                lastInsertedNode.next = newNode;
-            }
-            lastInsertedNode = newNode;
+        let cur = prevNode ? prevNode.next : this.head;
+        let removedCount = 0;
+        while (removedCount < deleteCount && cur) {
+            removedList.push(cur.value);
+            cur = cur.next;
+            removedCount++;
         }
-        // Connect new node to `nextNode`
-        if (lastInsertedNode) {
-            lastInsertedNode.next = nextNode;
+        const afterNode = cur;
+        if (prevNode) {
+            prevNode.next = afterNode;
         }
-        else if (prevNode) {
-            prevNode.next = nextNode;
-        }
-        // Update tail node and length
-        if (!nextNode) {
-            this._tail = lastInsertedNode || prevNode;
+        else {
+            this._head = afterNode;
+        }
+        if (!afterNode)
+            this._tail = prevNode;
+        if (items.length > 0) {
+            let firstInserted;
+            let lastInserted;
+            for (const it of items) {
+                const node = this._ensureNode(it);
+                if (!firstInserted)
+                    firstInserted = node;
+                if (lastInserted)
+                    lastInserted.next = node;
+                lastInserted = node;
+            }
+            if (prevNode)
+                prevNode.next = firstInserted;
+            else
+                this._head = firstInserted;
+            lastInserted.next = afterNode;
+            if (!afterNode)
+                this._tail = lastInserted;
+        }
+        this._length += items.length - removedCount;
+        if (this._length === 0) {
+            this._head = undefined;
+            this._tail = undefined;
         }
-        this._length += items.length - removedList.length;
         return removedList;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * The function `countOccurrences` iterates through a singly linked list and counts the occurrences
-     * of a specified element or nodes that satisfy a given predicate.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<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 singly linked list.
+     * Count how many nodes match a value/node/predicate.
+     * @remarks Time O(N), Space O(1)
+     * @param elementOrNode - Element, node, or node predicate to match.
+     * @returns Number of matches in the list.
      */
     countOccurrences(elementOrNode) {
-        const predicate = this._ensurePredicate(elementOrNode);
+        const predicate = elementOrPredicate(elementOrNode, this._equals);
         let count = 0;
         let current = this.head;
         while (current) {
-            if (predicate(current)) {
+            if (predicate(current))
                 count++;
-            }
             current = current.next;
         }
         return count;
     }
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `clone` function returns a new instance of the `SinglyLinkedList` class with the same values
-     * as the original list.
-     * @returns The `clone()` method is returning a new instance of the `SinglyLinkedList` class, which
-     * is a clone of the original list.
+     * Set the equality comparator used to compare values.
+     * @remarks Time O(1), Space O(1)
+     * @param equals - Equality predicate (a, b) → boolean.
+     * @returns This list.
      */
-    clone() {
-        return new SinglyLinkedList(this, { toElementFn: this.toElementFn, maxLen: this._maxLen });
-    }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `filter` function creates a new SinglyLinkedList by iterating over the elements of the current
-     * list and applying a callback function to each element to determine if it should be included in the
-     * filtered list.
-     * @param callback - The callback parameter is a function that will be called for each element in the
-     * list. It takes three arguments: the current element, the index of the current element, and the
-     * list itself. The callback function should return a boolean value indicating whether the current
-     * element should be included in the filtered list or not
-     * @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 `SinglyLinkedList` object that contains the
-     * elements that pass the filter condition specified by the `callback` function.
+    setEquality(equals) {
+        this._equals = equals;
+        return this;
+    }
+    /**
+     * Delete the first node whose value matches a predicate.
+     * @remarks Time O(N), Space O(1)
+     * @param predicate - Predicate (value, index, list) → boolean to decide deletion.
+     * @returns True if a node was removed.
      */
-    filter(callback, thisArg) {
-        const filteredList = this._createInstance({ toElementFn: this.toElementFn, maxLen: this._maxLen });
-        let index = 0;
-        for (const current of this) {
-            if (callback.call(thisArg, current, index, this)) {
-                filteredList.push(current);
+    deleteWhere(predicate) {
+        let prev;
+        let current = this.head;
+        let i = 0;
+        while (current) {
+            if (predicate(current.value, i++, this)) {
+                if (!prev) {
+                    this._head = current.next;
+                    if (current === this._tail)
+                        this._tail = undefined;
+                }
+                else {
+                    prev.next = current.next;
+                    if (current === this._tail)
+                        this._tail = prev;
+                }
+                this._length--;
+                return true;
             }
-            index++;
-        }
-        return filteredList;
-    }
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(n)
-     *
-     * The `map` function takes a callback function and returns a new SinglyLinkedList with the results
-     * of applying the callback to each element in the original list.
-     * @param callback - The `callback` parameter is a function that will be called for each element in
-     * the original list. It takes three arguments: `current` (the current element being processed),
-     * `index` (the index of the current element), and `this` (the original list). It should return a
-     * value
-     * @param [toElementFn] - The `toElementFn` parameter is an optional function that can be used to
-     * convert the raw element (`RR`) to the desired element type (`T`). It takes the raw element as
-     * input and returns the converted element. If this parameter is not provided, the raw element will
-     * be used as is.
-     * @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 `SinglyLinkedList` class with the mapped elements.
-     */
-    map(callback, toElementFn, thisArg) {
-        const mappedList = new SinglyLinkedList([], { toElementFn, maxLen: this._maxLen });
-        let index = 0;
-        for (const current of this) {
-            mappedList.push(callback.call(thisArg, current, index, this));
-            index++;
+            prev = current;
+            current = current.next;
         }
-        return mappedList;
+        return false;
     }
     /**
-     * The function `_createInstance` returns a new instance of `SinglyLinkedList` with the specified
-     * options.
-     * @param [options] - The `options` parameter in the `_createInstance` method is of type
-     * `SinglyLinkedListOptions<E, R>`, which is used to configure the behavior of the `SinglyLinkedList`
-     * instance being created. It is an optional parameter, meaning it can be omitted when calling the
-     * method.
-     * @returns An instance of the `SinglyLinkedList` class with an empty array and the provided options
-     * is being returned.
+     * Deep clone this list (values are copied by reference).
+     * @remarks Time O(N), Space O(N)
+     * @returns A new list with the same element sequence.
      */
-    _createInstance(options) {
-        return new SinglyLinkedList([], options);
+    clone() {
+        const out = this._createInstance();
+        for (const v of this)
+            out.push(v);
+        return out;
     }
     /**
-     * The function `_getIterator` returns an iterable iterator that yields the values of a linked list.
+     * Filter values into a new list of the same class.
+     * @remarks Time O(N), Space O(N)
+     * @param callback - Predicate (value, index, list) → boolean to keep value.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new list with kept values.
      */
-    *_getIterator() {
-        let current = this.head;
-        while (current) {
-            yield current.value;
-            current = current.next;
-        }
+    filter(callback, thisArg) {
+        const out = this._createInstance();
+        let index = 0;
+        for (const value of this)
+            if (callback.call(thisArg, value, index++, this))
+                out.push(value);
+        return out;
     }
     /**
-     * The function returns an iterator that iterates over the elements of a collection in reverse order.
+     * Map values into a new list of the same class.
+     * @remarks Time O(N), Space O(N)
+     * @param callback - Mapping function (value, index, list) → newValue.
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new list with mapped values.
      */
-    *_getReverseIterator() {
-        const reversedArr = [...this].reverse();
-        for (const item of reversedArr) {
-            yield item;
+    mapSame(callback, thisArg) {
+        const out = this._createInstance();
+        let index = 0;
+        for (const value of this) {
+            const mv = thisArg === undefined ? callback(value, index++, this) : callback.call(thisArg, value, index++, this);
+            out.push(mv);
         }
+        return out;
     }
     /**
-     * The function `_getNodeIterator` returns an iterator that iterates over the nodes of a singly
-     * linked list.
+     * Map values into a new list (possibly different element type).
+     * @remarks Time O(N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param callback - Mapping function (value, index, list) → newElement.
+     * @param [options] - Options for the output list (e.g., maxLen, toElementFn).
+     * @param [thisArg] - Value for `this` inside the callback.
+     * @returns A new SinglyLinkedList with mapped values.
      */
-    *_getNodeIterator() {
-        let current = this.head;
-        while (current) {
-            yield current;
-            current = current.next;
-        }
+    map(callback, options, thisArg) {
+        const out = this._createLike([], Object.assign(Object.assign({}, (options !== null && options !== void 0 ? options : {})), { maxLen: this._maxLen }));
+        let index = 0;
+        for (const value of this)
+            out.push(callback.call(thisArg, value, index++, this));
+        return out;
+    }
+    /**
+     * (Protected) Create a node from a value.
+     * @remarks Time O(1), Space O(1)
+     * @param value - Value to wrap in a node.
+     * @returns A new SinglyLinkedListNode instance.
+     */
+    _createNode(value) {
+        return new SinglyLinkedListNode(value);
     }
-    // protected *_getReverseNodeIterator(): IterableIterator<SinglyLinkedListNode<E>> {
-    //   const reversedArr = [...this._getNodeIterator()].reverse();
-    //
-    //   for (const item of reversedArr) {
-    //     yield item;
-    //   }
-    // }
-    /**
-     * The _isPredicate function in TypeScript checks if the input is a function that takes a
-     * SinglyLinkedListNode as an argument and returns a boolean.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter can be one of the following types:
-     * @returns The _isPredicate method is returning a boolean value based on whether the
-     * elementNodeOrPredicate parameter is a function or not. If the elementNodeOrPredicate is a
-     * function, the method will return true, indicating that it is a predicate function. If it is not a
-     * function, the method will return false.
+    /**
+     * (Protected) Check if input is a node predicate function.
+     * @remarks Time O(1), Space O(1)
+     * @param elementNodeOrPredicate - Element, node, or node predicate.
+     * @returns True if input is a predicate function.
      */
     _isPredicate(elementNodeOrPredicate) {
         return typeof elementNodeOrPredicate === 'function';
     }
     /**
-     * The function `_ensureNode` ensures that the input is a valid node and returns it, creating a new
-     * node if necessary.
-     * @param {E | SinglyLinkedListNode<E>} elementOrNode - The `elementOrNode` parameter can be either
-     * an element of type `E` or a `SinglyLinkedListNode` containing an element of type `E`.
-     * @returns A SinglyLinkedListNode<E> object is being returned.
+     * (Protected) Normalize input into a node instance.
+     * @remarks Time O(1), Space O(1)
+     * @param elementOrNode - Element or node.
+     * @returns A SinglyLinkedListNode for the provided input.
      */
     _ensureNode(elementOrNode) {
         if (this.isNode(elementOrNode))
             return elementOrNode;
-        return new SinglyLinkedListNode(elementOrNode);
+        return this._createNode(elementOrNode);
     }
     /**
-     * The function `_ensurePredicate` in TypeScript ensures that the input is either a node, a predicate
-     * function, or a value to compare with the node's value.
-     * @param {E | SinglyLinkedListNode<E> | ((node: SinglyLinkedListNode<E>) => boolean)} elementNodeOrPredicate
-     * elementNodeOrPredicate - The `elementNodeOrPredicate` parameter can be one of the following types:
-     * @returns A function is being returned. If the input `elementNodeOrPredicate` is already a node, a
-     * function is returned that checks if a given node is equal to the input node. If the input is a
-     * predicate function, it is returned as is. If the input is neither a node nor a predicate function,
-     * a function is returned that checks if a given node's value is equal to the input
+     * (Protected) Normalize input into a node predicate.
+     * @remarks Time O(1), Space O(1)
+     * @param elementNodeOrPredicate - Element, node, or predicate.
+     * @returns A predicate taking a node and returning true/false.
      */
     _ensurePredicate(elementNodeOrPredicate) {
         if (this.isNode(elementNodeOrPredicate))
             return (node) => node === elementNodeOrPredicate;
         if (this._isPredicate(elementNodeOrPredicate))
             return elementNodeOrPredicate;
-        return (node) => node.value === elementNodeOrPredicate;
+        const value = elementNodeOrPredicate;
+        return (node) => this._equals(node.value, value);
     }
     /**
-     * The function `_getPrevNode` returns the node before a given node in a singly linked list.
-     * @param node - The `node` parameter in the `_getPrevNode` method is a reference to a node in a
-     * singly linked list. The method is used to find the node that comes before the given node in the
-     * linked list.
-     * @returns The `_getPrevNode` method returns either the previous node of the input node in a singly
-     * linked list or `undefined` if the input node is the head of the list or if the input node is not
-     * found in the list.
+     * (Protected) Get the previous node of a given node.
+     * @remarks Time O(N), Space O(1)
+     * @param node - A node in the list.
+     * @returns Previous node or undefined.
      */
     _getPrevNode(node) {
         if (!this.head || this.head === node)
             return undefined;
         let current = this.head;
-        while (current.next && current.next !== node) {
+        while (current.next && current.next !== node)
             current = current.next;
-        }
         return current.next === node ? current : undefined;
     }
+    /**
+     * (Protected) Iterate values from head to tail.
+     * @remarks Time O(N), Space O(1)
+     * @returns Iterator of values (E).
+     */
+    *_getIterator() {
+        let current = this.head;
+        while (current) {
+            yield current.value;
+            current = current.next;
+        }
+    }
+    /**
+     * (Protected) Iterate values from tail to head.
+     * @remarks Time O(N), Space O(N)
+     * @returns Iterator of values (E).
+     */
+    *_getReverseIterator() {
+        const reversedArr = [...this].reverse();
+        for (const item of reversedArr)
+            yield item;
+    }
+    /**
+     * (Protected) Iterate nodes from head to tail.
+     * @remarks Time O(N), Space O(1)
+     * @returns Iterator of nodes.
+     */
+    *_getNodeIterator() {
+        let current = this.head;
+        while (current) {
+            yield current;
+            current = current.next;
+        }
+    }
+    /**
+     * (Protected) Create an empty instance of the same concrete class.
+     * @remarks Time O(1), Space O(1)
+     * @param [options] - Options forwarded to the constructor.
+     * @returns An empty like-kind list instance.
+     */
+    _createInstance(options) {
+        const Ctor = this.constructor;
+        return new Ctor([], options);
+    }
+    /**
+     * (Protected) Create a like-kind instance and seed it from an iterable.
+     * @remarks Time O(N), Space O(N)
+     * @template EM
+     * @template RM
+     * @param [elements] - Iterable used to seed the new list.
+     * @param [options] - Options forwarded to the constructor.
+     * @returns A like-kind SinglyLinkedList instance.
+     */
+    _createLike(elements = [], options) {
+        const Ctor = this.constructor;
+        return new Ctor(elements, options);
+    }
+    /**
+     * (Protected) Spawn an empty like-kind list instance.
+     * @remarks Time O(1), Space O(1)
+     * @template EM
+     * @template RM
+     * @param [options] - Options forwarded to the constructor.
+     * @returns An empty like-kind SinglyLinkedList instance.
+     */
+    _spawnLike(options) {
+        return this._createLike([], options);
+    }
 }
 exports.SinglyLinkedList = SinglyLinkedList;
+function elementOrPredicate(input, equals) {
+    if (input instanceof SinglyLinkedListNode)
+        return (node) => node === input;
+    if (typeof input === 'function')
+        return input;
+    const value = input;
+    return (node) => equals(node.value, value);
+}