singly-linked-list-typed 2.4.4 → 2.5.0

package/README.md

@@ -34,79 +34,6 @@ yarn add singly-linked-list-typed
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
-### basic SinglyLinkedList creation and push operation
-```typescript
- // Create a simple SinglyLinkedList with initial values
-    const list = new SinglyLinkedList([1, 2, 3, 4, 5]);
-
-    // Verify the list maintains insertion order
-    console.log([...list]); // [1, 2, 3, 4, 5];
-
-    // Check length
-    console.log(list.length); // 5;
-
-    // Push a new element to the end
-    list.push(6);
-    console.log(list.length); // 6;
-    console.log([...list]); // [1, 2, 3, 4, 5, 6];
-```
-
-### SinglyLinkedList pop and shift operations
-```typescript
- const list = new SinglyLinkedList<number>([10, 20, 30, 40, 50]);
-
-    // Pop removes from the end
-    const last = list.pop();
-    console.log(last); // 50;
-
-    // Shift removes from the beginning
-    const first = list.shift();
-    console.log(first); // 10;
-
-    // Verify remaining elements
-    console.log([...list]); // [20, 30, 40];
-    console.log(list.length); // 3;
-```
-
-### SinglyLinkedList unshift and forward traversal
-```typescript
- const list = new SinglyLinkedList<number>([20, 30, 40]);
-
-    // Unshift adds to the beginning
-    list.unshift(10);
-    console.log([...list]); // [10, 20, 30, 40];
-
-    // Access elements (forward traversal only for singly linked)
-    const second = list.at(1);
-    console.log(second); // 20;
-
-    // SinglyLinkedList allows forward iteration only
-    const elements: number[] = [];
-    for (const item of list) {
-      elements.push(item);
-    }
-    console.log(elements); // [10, 20, 30, 40];
-
-    console.log(list.length); // 4;
-```
-
-### SinglyLinkedList filter and map operations
-```typescript
- const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
-
-    // Filter even numbers
-    const filtered = list.filter(value => value % 2 === 0);
-    console.log(filtered.length); // 2;
-
-    // Map to double values
-    const doubled = list.map(value => value * 2);
-    console.log(doubled.length); // 5;
-
-    // Use reduce to sum
-    const sum = list.reduce((acc, value) => acc + value, 0);
-    console.log(sum); // 15;
-```
-
 ### SinglyLinkedList for sequentially processed data stream
 ```typescript
  interface LogEntry {
@@ -228,6 +155,21 @@ yarn add singly-linked-list-typed
     console.log(editor.getText()); // 'Haello';
 ```
 
+### Find first matching element
+```typescript
+ const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
+    console.log(list.find(n => n > 3)); // 4;
+    console.log(list.find(n => n > 10)); // undefined;
+```
+
+### Iterate over elements
+```typescript
+ const list = new SinglyLinkedList<number>([10, 20, 30]);
+    const result: number[] = [];
+    list.forEach(n => result.push(n));
+    console.log(result); // [10, 20, 30];
+```
+
 [//]: # (No deletion!!! End of Example Replace Section)
 
 

package/dist/cjs/index.cjs

@@ -725,11 +725,37 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return list;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // basic SinglyLinkedList creation and push operation
+  *  // Create a simple SinglyLinkedList with initial values
+  *     const list = new SinglyLinkedList([1, 2, 3, 4, 5]);
+  *
+  *     // Verify the list maintains insertion order
+  *     console.log([...list]); // [1, 2, 3, 4, 5];
+  *
+  *     // Check length
+  *     console.log(list.length); // 5;
+  *
+  *     // Push a new element to the end
+  *     list.push(6);
+  *     console.log(list.length); // 6;
+  *     console.log([...list]); // [1, 2, 3, 4, 5, 6];
+    */
   push(elementOrNode) {
     const newNode = this._ensureNode(elementOrNode);
     if (!this.head) {
@@ -743,10 +769,36 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return true;
   }
   /**
-   * Remove and return the tail element.
-   * @remarks Time O(N), Space O(1)
-   * @returns Removed element or undefined.
-   */
+    * Remove and return the tail element.
+    * @remarks Time O(N), Space O(1)
+    * @returns Removed element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // SinglyLinkedList pop and shift operations
+  *  const list = new SinglyLinkedList<number>([10, 20, 30, 40, 50]);
+  *
+  *     // Pop removes from the end
+  *     const last = list.pop();
+  *     console.log(last); // 50;
+  *
+  *     // Shift removes from the beginning
+  *     const first = list.shift();
+  *     console.log(first); // 10;
+  *
+  *     // Verify remaining elements
+  *     console.log([...list]); // [20, 30, 40];
+  *     console.log(list.length); // 3;
+    */
   pop() {
     if (!this.head) return void 0;
     if (this.head === this.tail) {
@@ -765,10 +817,26 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return value;
   }
   /**
-   * Remove and return the head element.
-   * @remarks Time O(1), Space O(1)
-   * @returns Removed element or undefined.
-   */
+    * Remove and return the head element.
+    * @remarks Time O(1), Space O(1)
+    * @returns Removed element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove from the front
+  *  const list = new SinglyLinkedList<number>([10, 20, 30]);
+  *     console.log(list.shift()); // 10;
+  *     console.log(list.length); // 2;
+    */
   shift() {
     if (!this.head) return void 0;
     const removed = this.head;
@@ -778,11 +846,42 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return removed.value;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // SinglyLinkedList unshift and forward traversal
+  *  const list = new SinglyLinkedList<number>([20, 30, 40]);
+  *
+  *     // Unshift adds to the beginning
+  *     list.unshift(10);
+  *     console.log([...list]); // [10, 20, 30, 40];
+  *
+  *     // Access elements (forward traversal only for singly linked)
+  *     const second = list.at(1);
+  *     console.log(second); // 20;
+  *
+  *     // SinglyLinkedList allows forward iteration only
+  *     const elements: number[] = [];
+  *     for (const item of list) {
+  *       elements.push(item);
+  *     }
+  *     console.log(elements); // [10, 20, 30, 40];
+  *
+  *     console.log(list.length); // 4;
+    */
   unshift(elementOrNode) {
     const newNode = this._ensureNode(elementOrNode);
     if (!this.head) {
@@ -838,11 +937,28 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return void 0;
   }
   /**
-   * Get the element at a given index.
-   * @remarks Time O(N), Space O(1)
-   * @param index - Zero-based index.
-   * @returns Element or undefined.
-   */
+    * Get the element at a given index.
+    * @remarks Time O(N), Space O(1)
+    * @param index - Zero-based index.
+    * @returns Element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Access element by index
+  *  const list = new SinglyLinkedList<string>(['a', 'b', 'c', 'd']);
+  *     console.log(list.at(0)); // 'a';
+  *     console.log(list.at(2)); // 'c';
+  *     console.log(list.at(3)); // 'd';
+    */
   at(index) {
     if (index < 0 || index >= this._length) return void 0;
     let current = this.head;
@@ -859,11 +975,23 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return elementNodeOrPredicate instanceof SinglyLinkedListNode;
   }
   /**
-   * Get the node reference at a given index.
-   * @remarks Time O(N), Space O(1)
-   * @param index - Zero-based index.
-   * @returns Node or undefined.
-   */
+    * Get the node reference at a given index.
+    * @remarks Time O(N), Space O(1)
+    * @param index - Zero-based index.
+    * @returns Node or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Get node at index
+  *  const list = new SinglyLinkedList<string>(['a', 'b', 'c']);
+  *     console.log(list.getNodeAt(1)?.value); // 'b';
+    */
   getNodeAt(index) {
     if (index < 0 || index >= this._length) return void 0;
     let current = this.head;
@@ -871,11 +999,24 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return current;
   }
   /**
-   * Delete the element at an index.
-   * @remarks Time O(N), Space O(1)
-   * @param index - Zero-based index.
-   * @returns Removed element or undefined.
-   */
+    * Delete the element at an index.
+    * @remarks Time O(N), Space O(1)
+    * @param index - Zero-based index.
+    * @returns Removed element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove by index
+  *  const list = new SinglyLinkedList<string>(['a', 'b', 'c']);
+  *     list.deleteAt(1);
+  *     console.log(list.toArray()); // ['a', 'c'];
+    */
   deleteAt(index) {
     if (index < 0 || index >= this._length) return void 0;
     if (index === 0) return this.shift();
@@ -888,11 +1029,24 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return value;
   }
   /**
-   * 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 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.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove first occurrence
+  *  const list = new SinglyLinkedList<number>([1, 2, 3, 2]);
+  *     list.delete(2);
+  *     console.log(list.toArray()); // [1, 3, 2];
+    */
   delete(elementOrNode) {
     if (elementOrNode === void 0 || !this.head) return false;
     const node = this.isNode(elementOrNode) ? elementOrNode : this.getNode(elementOrNode);
@@ -909,12 +1063,25 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return true;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Insert at index
+  *  const list = new SinglyLinkedList<number>([1, 3]);
+  *     list.addAt(1, 2);
+  *     console.log(list.toArray()); // [1, 2, 3];
+    */
   addAt(index, newElementOrNode) {
     if (index < 0 || index > this._length) return false;
     if (index === 0) return this.unshift(newElementOrNode);
@@ -940,28 +1107,70 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return true;
   }
   /**
-   * Check whether the list is empty.
-   * @remarks Time O(1), Space O(1)
-   * @returns True if length is 0.
-   */
+    * Check whether the list is empty.
+    * @remarks Time O(1), Space O(1)
+    * @returns True if length is 0.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Check empty
+  *  console.log(new SinglyLinkedList().isEmpty()); // true;
+    */
   isEmpty() {
     return this._length === 0;
   }
   /**
-   * Remove all nodes and reset length.
-   * @remarks Time O(N), Space O(1)
-   * @returns void
-   */
+    * Remove all nodes and reset length.
+    * @remarks Time O(N), Space O(1)
+    * @returns void
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove all
+  *  const list = new SinglyLinkedList<number>([1, 2, 3]);
+  *     list.clear();
+  *     console.log(list.isEmpty()); // true;
+    */
   clear() {
     this._head = void 0;
     this._tail = void 0;
     this._length = 0;
   }
   /**
-   * Reverse the list in place.
-   * @remarks Time O(N), Space O(1)
-   * @returns This list.
-   */
+    * Reverse the list in place.
+    * @remarks Time O(N), Space O(1)
+    * @returns This list.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Reverse the list in-place
+  *  const list = new SinglyLinkedList<number>([1, 2, 3, 4]);
+  *     list.reverse();
+  *     console.log([...list]); // [4, 3, 2, 1];
+    */
   reverse() {
     if (!this.head || this.head === this.tail) return this;
     let prev;
@@ -1136,22 +1345,64 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return false;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Deep copy
+  *  const list = new SinglyLinkedList<number>([1, 2, 3]);
+  *     const copy = list.clone();
+  *     copy.pop();
+  *     console.log(list.length); // 3;
+  *     console.log(copy.length); // 2;
+    */
   clone() {
     const out = this._createInstance();
     for (const v of this) out.push(v);
     return out;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // SinglyLinkedList filter and map operations
+  *  const list = new SinglyLinkedList<number>([1, 2, 3, 4, 5]);
+  *
+  *     // Filter even numbers
+  *     const filtered = list.filter(value => value % 2 === 0);
+  *     console.log(filtered.length); // 2;
+  *
+  *     // Map to double values
+  *     const doubled = list.map(value => value * 2);
+  *     console.log(doubled.length); // 5;
+  *
+  *     // Use reduce to sum
+  *     const sum = list.reduce((acc, value) => acc + value, 0);
+  *     console.log(sum); // 15;
+    */
   filter(callback, thisArg) {
     const out = this._createInstance();
     let index = 0;
@@ -1175,15 +1426,31 @@ var SinglyLinkedList = class extends LinearLinkedBase {
     return out;
   }
   /**
-   * 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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Transform elements
+  *  const list = new SinglyLinkedList<number>([1, 2, 3]);
+  *     const doubled = list.map(n => n * 2);
+  *     console.log([...doubled]); // [2, 4, 6];
+    */
   map(callback, options, thisArg) {
     const out = this._createLike([], { ...options ?? {}, maxLen: this._maxLen });
     let index = 0;
@@ -1318,6 +1585,31 @@ function elementOrPredicate(input, equals) {
 }
 __name(elementOrPredicate, "elementOrPredicate");
 
+// src/common/error.ts
+var ERR = {
+  // Range / index
+  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
+  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
+  // Type / argument
+  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
+  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
+  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
+  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
+  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
+  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
+  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
+  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
+  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
+  // State / operation
+  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
+  // Matrix
+  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
+  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
+  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
+  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
+  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch")
+};
+
 // src/common/index.ts
 var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
   DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
@@ -1350,6 +1642,7 @@ var Range = class {
  */
 
 exports.DFSOperation = DFSOperation;
+exports.ERR = ERR;
 exports.Range = Range;
 exports.SinglyLinkedList = SinglyLinkedList;
 exports.SinglyLinkedListNode = SinglyLinkedListNode;