stack-typed 2.4.4 → 2.5.0

package/README.md

@@ -35,42 +35,6 @@ yarn add stack-typed
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
-### basic Stack creation and push operation
-```typescript
- // Create a simple Stack with initial values
-    const stack = new Stack([1, 2, 3, 4, 5]);
-
-    // Verify the stack maintains insertion order (LIFO will be shown in pop)
-    console.log([...stack]); // [1, 2, 3, 4, 5];
-
-    // Check length
-    console.log(stack.size); // 5;
-
-    // Push a new element to the top
-    stack.push(6);
-    console.log(stack.size); // 6;
-```
-
-### Stack pop operation (LIFO - Last In First Out)
-```typescript
- const stack = new Stack<number>([10, 20, 30, 40, 50]);
-
-    // Peek at the top element without removing
-    const top = stack.peek();
-    console.log(top); // 50;
-
-    // Pop removes from the top (LIFO order)
-    const popped = stack.pop();
-    console.log(popped); // 50;
-
-    // Next pop gets the previous element
-    const next = stack.pop();
-    console.log(next); // 40;
-
-    // Verify length decreased
-    console.log(stack.size); // 3;
-```
-
 ### Function Call Stack
 ```typescript
  const functionStack = new Stack<string>();
@@ -190,6 +154,12 @@ yarn add stack-typed
     console.log(stack.elements.join('/')); // 'c';
 ```
 
+### Convert stack to array
+```typescript
+ const stack = new Stack<number>([1, 2, 3]);
+    console.log(stack.toArray()); // [1, 2, 3];
+```
+
 [//]: # (No deletion!!! End of Example Replace Section)
 
 

package/dist/cjs/index.cjs

@@ -253,10 +253,23 @@ var Stack = class extends IterableElementBase {
     return this._elements;
   }
   /**
-   * Get the number of stored elements.
-   * @remarks Time O(1), Space O(1)
-   * @returns Current size.
-   */
+    * Get the number of stored elements.
+    * @remarks Time O(1), Space O(1)
+    * @returns Current size.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Get number of elements
+  *  const stack = new Stack<number>([1, 2, 3]);
+  *     console.log(stack.size); // 3;
+    */
   get size() {
     return this.elements.length;
   }
@@ -274,36 +287,123 @@ var Stack = class extends IterableElementBase {
     return new this(elements, options);
   }
   /**
-   * Check whether the stack is empty.
-   * @remarks Time O(1), Space O(1)
-   * @returns True if size is 0.
-   */
+    * Check whether the stack is empty.
+    * @remarks Time O(1), Space O(1)
+    * @returns True if size is 0.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Check if stack has elements
+  *  const stack = new Stack<number>();
+  *     console.log(stack.isEmpty()); // true;
+  *     stack.push(1);
+  *     console.log(stack.isEmpty()); // false;
+    */
   isEmpty() {
     return this.elements.length === 0;
   }
   /**
-   * Get the top element without removing it.
-   * @remarks Time O(1), Space O(1)
-   * @returns Top element or undefined.
-   */
+    * Get the top element without removing it.
+    * @remarks Time O(1), Space O(1)
+    * @returns Top element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // View the top element without removing it
+  *  const stack = new Stack<string>(['a', 'b', 'c']);
+  *     console.log(stack.peek()); // 'c';
+  *     console.log(stack.size); // 3;
+    */
   peek() {
     return this.isEmpty() ? void 0 : this.elements[this.elements.length - 1];
   }
   /**
-   * Push one element onto the top.
-   * @remarks Time O(1), Space O(1)
-   * @param element - Element to push.
-   * @returns True when pushed.
-   */
+    * Push one element onto the top.
+    * @remarks Time O(1), Space O(1)
+    * @param element - Element to push.
+    * @returns True when pushed.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // basic Stack creation and push operation
+  *  // Create a simple Stack with initial values
+  *     const stack = new Stack([1, 2, 3, 4, 5]);
+  *
+  *     // Verify the stack maintains insertion order (LIFO will be shown in pop)
+  *     console.log([...stack]); // [1, 2, 3, 4, 5];
+  *
+  *     // Check length
+  *     console.log(stack.size); // 5;
+  *
+  *     // Push a new element to the top
+  *     stack.push(6);
+  *     console.log(stack.size); // 6;
+    */
   push(element) {
     this.elements.push(element);
     return true;
   }
   /**
-   * Pop and return the top element.
-   * @remarks Time O(1), Space O(1)
-   * @returns Removed element or undefined.
-   */
+    * Pop and return the top element.
+    * @remarks Time O(1), Space O(1)
+    * @returns Removed element or undefined.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Stack pop operation (LIFO - Last In First Out)
+  *  const stack = new Stack<number>([10, 20, 30, 40, 50]);
+  *
+  *     // Peek at the top element without removing
+  *     const top = stack.peek();
+  *     console.log(top); // 50;
+  *
+  *     // Pop removes from the top (LIFO order)
+  *     const popped = stack.pop();
+  *     console.log(popped); // 50;
+  *
+  *     // Next pop gets the previous element
+  *     const next = stack.pop();
+  *     console.log(next); // 40;
+  *
+  *     // Verify length decreased
+  *     console.log(stack.size); // 3;
+    */
   pop() {
     return this.isEmpty() ? void 0 : this.elements.pop();
   }
@@ -322,11 +422,24 @@ var Stack = class extends IterableElementBase {
     return ans;
   }
   /**
-   * Delete the first occurrence of a specific element.
-   * @remarks Time O(N), Space O(1)
-   * @param element - Element to remove (using the configured equality).
-   * @returns True if an element was removed.
-   */
+    * Delete the first occurrence of a specific element.
+    * @remarks Time O(N), Space O(1)
+    * @param element - Element to remove (using the configured equality).
+    * @returns True if an element was removed.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove element
+  *  const stack = new Stack<number>([1, 2, 3]);
+  *     stack.delete(2);
+  *     console.log(stack.toArray()); // [1, 3];
+    */
   delete(element) {
     const idx = this._indexOfByEquals(element);
     return this.deleteAt(idx);
@@ -358,30 +471,74 @@ var Stack = class extends IterableElementBase {
     return false;
   }
   /**
-   * Remove all elements and reset storage.
-   * @remarks Time O(1), Space O(1)
-   * @returns void
-   */
+    * Remove all elements and reset storage.
+    * @remarks Time O(1), Space O(1)
+    * @returns void
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Remove all elements
+  *  const stack = new Stack<number>([1, 2, 3]);
+  *     stack.clear();
+  *     console.log(stack.isEmpty()); // true;
+    */
   clear() {
     this._elements = [];
   }
   /**
-   * Deep clone this stack.
-   * @remarks Time O(N), Space O(N)
-   * @returns A new stack with the same content.
-   */
+    * Deep clone this stack.
+    * @remarks Time O(N), Space O(N)
+    * @returns A new stack with the same content.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Create independent copy
+  *  const stack = new Stack<number>([1, 2, 3]);
+  *     const copy = stack.clone();
+  *     copy.pop();
+  *     console.log(stack.size); // 3;
+  *     console.log(copy.size); // 2;
+    */
   clone() {
     const out = this._createInstance({ toElementFn: this.toElementFn });
     for (const v of this) out.push(v);
     return out;
   }
   /**
-   * Filter elements into a new stack of the same class.
-   * @remarks Time O(N), Space O(N)
-   * @param predicate - Predicate (value, index, stack) → boolean to keep value.
-   * @param [thisArg] - Value for `this` inside the predicate.
-   * @returns A new stack with kept values.
-   */
+    * Filter elements into a new stack of the same class.
+    * @remarks Time O(N), Space O(N)
+    * @param predicate - Predicate (value, index, stack) → boolean to keep value.
+    * @param [thisArg] - Value for `this` inside the predicate.
+    * @returns A new stack with kept values.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Filter elements
+  *  const stack = new Stack<number>([1, 2, 3, 4, 5]);
+  *     const evens = stack.filter(x => x % 2 === 0);
+  *     console.log(evens.toArray()); // [2, 4];
+    */
   filter(predicate, thisArg) {
     const out = this._createInstance({ toElementFn: this.toElementFn });
     let index = 0;
@@ -408,15 +565,28 @@ var Stack = class extends IterableElementBase {
     return out;
   }
   /**
-   * Map values into a new stack (possibly different element type).
-   * @remarks Time O(N), Space O(N)
-   * @template EM
-   * @template RM
-   * @param callback - Mapping function (value, index, stack) → newElement.
-   * @param [options] - Options for the output stack (e.g., toElementFn).
-   * @param [thisArg] - Value for `this` inside the callback.
-   * @returns A new Stack with mapped elements.
-   */
+    * Map values into a new stack (possibly different element type).
+    * @remarks Time O(N), Space O(N)
+    * @template EM
+    * @template RM
+    * @param callback - Mapping function (value, index, stack) → newElement.
+    * @param [options] - Options for the output stack (e.g., toElementFn).
+    * @param [thisArg] - Value for `this` inside the callback.
+    * @returns A new Stack with mapped elements.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @example
+  * // Transform elements
+  *  const stack = new Stack<number>([1, 2, 3]);
+  *     const doubled = stack.map(x => x * 2);
+  *     console.log(doubled.toArray()); // [2, 4, 6];
+    */
   map(callback, options, thisArg) {
     const out = this._createLike([], { ...options ?? {} });
     let index = 0;
@@ -479,6 +649,31 @@ var Stack = class extends IterableElementBase {
   }
 };
 
+// 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";
@@ -511,6 +706,7 @@ var Range = class {
  */
 
 exports.DFSOperation = DFSOperation;
+exports.ERR = ERR;
 exports.Range = Range;
 exports.Stack = Stack;
 //# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/data-structures/base/iterable-element-base.ts","../../src/data-structures/stack/stack.ts","../../src/common/index.ts"],"names":["DFSOperation"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';\n\n/**\n * Base class that makes a data structure iterable and provides common\n * element-wise utilities (e.g., map/filter/reduce/find).\n *\n * @template E The public element type yielded by the structure.\n * @template R The underlying \"raw\" element type used internally or by converters.\n *\n * @remarks\n * This class implements the JavaScript iteration protocol (via `Symbol.iterator`)\n * and offers array-like helpers with predictable time/space complexity.\n */\nexport abstract class IterableElementBase<E, R> implements Iterable<E> {\n  /**\n   * Create a new iterable base.\n   *\n   * @param options Optional behavior overrides. When provided, a `toElementFn`\n   * is used to convert a raw element (`R`) into a public element (`E`).\n   *\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  protected constructor(options?: IterableElementBaseOptions<E, R>) {\n    if (options) {\n      const { toElementFn } = options;\n      if (typeof toElementFn === 'function') this._toElementFn = toElementFn;\n      else if (toElementFn) throw new TypeError('toElementFn must be a function type');\n    }\n  }\n\n  /**\n   * The converter used to transform a raw element (`R`) into a public element (`E`).\n   *\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  protected readonly _toElementFn?: (rawElement: R) => E;\n\n  /**\n   * Exposes the current `toElementFn`, if configured.\n   *\n   * @returns The converter function or `undefined` when not set.\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  get toElementFn(): ((rawElement: R) => E) | undefined {\n    return this._toElementFn;\n  }\n\n  /**\n   * Returns an iterator over the structure's elements.\n   *\n   * @param args Optional iterator arguments forwarded to the internal iterator.\n   * @returns An `IterableIterator<E>` that yields the elements in traversal order.\n   *\n   * @remarks\n   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.\n   */\n  *[Symbol.iterator](...args: unknown[]): IterableIterator<E> {\n    yield* this._getIterator(...args);\n  }\n\n  /**\n   * Returns an iterator over the values (alias of the default iterator).\n   *\n   * @returns An `IterableIterator<E>` over all elements.\n   * @remarks\n   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).\n   */\n  *values(): IterableIterator<E> {\n    for (const item of this) yield item;\n  }\n\n  /**\n   * Tests whether all elements satisfy the predicate.\n   *\n   * @template TReturn\n   * @param predicate Function invoked for each element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns `true` if every element passes; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).\n   */\n  every(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (!predicate(item, index++, this)) return false;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (!fn.call(thisArg, item, index++, this)) return false;\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Tests whether at least one element satisfies the predicate.\n   *\n   * @param predicate Function invoked for each element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns `true` if any element passes; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early on first success. Space O(1).\n   */\n  some(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (predicate(item, index++, this)) return true;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (fn.call(thisArg, item, index++, this)) return true;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Invokes a callback for each element in iteration order.\n   *\n   * @param callbackfn Function invoked per element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns `void`.\n   *\n   * @remarks\n   * Time O(n), Space O(1).\n   */\n  forEach(callbackfn: ElementCallback<E, R, void>, thisArg?: unknown): void {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        callbackfn(item, index++, this);\n      } else {\n        const fn = callbackfn as (this: unknown, v: E, i: number, self: this) => void;\n        fn.call(thisArg, item, index++, this);\n      }\n    }\n  }\n\n  /**\n   * Finds the first element that satisfies the predicate and returns it.\n   *\n   * @overload\n   * Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.\n   * @template S\n   * @param predicate Type-guard predicate: `(value, index, self) => value is S`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns The matched element typed as `S`, or `undefined` if not found.\n   *\n   * @overload\n   * @param predicate Boolean predicate: `(value, index, self) => boolean`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns The first matching element as `E`, or `undefined` if not found.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early on the first match. Space O(1).\n   */\n  find<S extends E>(predicate: ElementCallback<E, R, S>, thisArg?: unknown): S | undefined;\n  find(predicate: ElementCallback<E, R, unknown>, thisArg?: unknown): E | undefined;\n\n  // Implementation signature\n  find(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): E | undefined {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (predicate(item, index++, this)) return item;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (fn.call(thisArg, item, index++, this)) return item;\n      }\n    }\n    return;\n  }\n\n  /**\n   * Checks whether a strictly-equal element exists in the structure.\n   *\n   * @param element The element to test with `===` equality.\n   * @returns `true` if an equal element is found; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case. Space O(1).\n   */\n  has(element: E): boolean {\n    for (const ele of this) if (ele === element) return true;\n    return false;\n  }\n\n  reduce(callbackfn: ReduceElementCallback<E, R>): E;\n  reduce(callbackfn: ReduceElementCallback<E, R>, initialValue: E): E;\n  reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue: U): U;\n\n  /**\n   * Reduces all elements to a single accumulated value.\n   *\n   * @overload\n   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.\n   * @returns The final accumulated value typed as `E`.\n   *\n   * @overload\n   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.\n   * @param initialValue The initial accumulator value of type `E`.\n   * @returns The final accumulated value typed as `E`.\n   *\n   * @overload\n   * @template U The accumulator type when it differs from `E`.\n   * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.\n   * @param initialValue The initial accumulator value of type `U`.\n   * @returns The final accumulated value typed as `U`.\n   *\n   * @remarks\n   * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.\n   */\n  reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue?: U): U {\n    let index = 0;\n    const iter = this[Symbol.iterator]();\n    let acc: U;\n\n    if (arguments.length >= 2) {\n      acc = initialValue as U;\n    } else {\n      const first = iter.next();\n      if (first.done) throw new TypeError('Reduce of empty structure with no initial value');\n      acc = first.value as unknown as U;\n      index = 1;\n    }\n\n    for (const value of iter) {\n      acc = callbackfn(acc, value, index++, this);\n    }\n    return acc;\n  }\n\n  /**\n   * Materializes the elements into a new array.\n   *\n   * @returns A shallow array copy of the iteration order.\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  toArray(): E[] {\n    return [...this];\n  }\n\n  /**\n   * Returns a representation of the structure suitable for quick visualization.\n   * Defaults to an array of elements; subclasses may override to provide richer visuals.\n   *\n   * @returns A visual representation (array by default).\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  toVisual(): E[] {\n    return [...this];\n  }\n\n  /**\n   * Prints `toVisual()` to the console. Intended for quick debugging.\n   *\n   * @returns `void`.\n   * @remarks\n   * Time O(n) due to materialization, Space O(n) for the intermediate representation.\n   */\n  print(): void {\n    console.log(this.toVisual());\n  }\n\n  /**\n   * Indicates whether the structure currently contains no elements.\n   *\n   * @returns `true` if empty; otherwise `false`.\n   * @remarks\n   * Expected Time O(1), Space O(1) for most implementations.\n   */\n  abstract isEmpty(): boolean;\n\n  /**\n   * Removes all elements from the structure.\n   *\n   * @returns `void`.\n   * @remarks\n   * Expected Time O(1) or O(n) depending on the implementation; Space O(1).\n   */\n  abstract clear(): void;\n\n  /**\n   * Creates a structural copy with the same element values and configuration.\n   *\n   * @returns A clone of the current instance (same concrete type).\n   * @remarks\n   * Expected Time O(n) to copy elements; Space O(n).\n   */\n  abstract clone(): this;\n\n  /**\n   * Maps each element to a new element and returns a new iterable structure.\n   *\n   * @template EM The mapped element type.\n   * @template RM The mapped raw element type used internally by the target structure.\n   * @param callback Function with signature `(value, index, self) => mapped`.\n   * @param options Optional options for the returned structure, including its `toElementFn`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns A new `IterableElementBase<EM, RM>` containing mapped elements.\n   *\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  abstract map<EM, RM>(\n    callback: ElementCallback<E, R, EM>,\n    options?: IterableElementBaseOptions<EM, RM>,\n    thisArg?: unknown\n  ): IterableElementBase<EM, RM>;\n\n  /**\n   * Maps each element to the same element type and returns the same concrete structure type.\n   *\n   * @param callback Function with signature `(value, index, self) => mappedValue`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns A new instance of the same concrete type with mapped elements.\n   *\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  abstract mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;\n\n  /**\n   * Filters elements using the provided predicate and returns the same concrete structure type.\n   *\n   * @param predicate Function with signature `(value, index, self) => boolean`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns A new instance of the same concrete type containing only elements that pass the predicate.\n   *\n   * @remarks\n   * Time O(n), Space O(k) where `k` is the number of kept elements.\n   */\n  abstract filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;\n\n  /**\n   * Internal iterator factory used by the default iterator.\n   *\n   * @param args Optional iterator arguments.\n   * @returns An iterator over elements.\n   *\n   * @remarks\n   * Implementations should yield in O(1) per element with O(1) extra space when possible.\n   */\n  protected abstract _getIterator(...args: unknown[]): IterableIterator<E>;\n}\n","/**\n * data-structure-typed\n *\n * @author Pablo Zeng\n * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>\n * @license MIT License\n */\n\nimport type { ElementCallback, IterableElementBaseOptions, StackOptions } from '../../types';\nimport { IterableElementBase } from '../base';\n\n/**\n * LIFO stack with array storage and optional record→element conversion.\n * @remarks Time O(1), Space O(1)\n * @template E\n * @template R\n * 1. Last In, First Out (LIFO): The core characteristic of a stack is its last in, first out nature, meaning the last element added to the stack will be the first to be removed.\n * 2. Uses: Stacks are commonly used for managing a series of tasks or elements that need to be processed in a last in, first out manner. They are widely used in various scenarios, such as in function calls in programming languages, evaluation of arithmetic expressions, and backtracking algorithms.\n * 3. Performance: Stack operations are typically O(1) in time complexity, meaning that regardless of the stack's size, adding, removing, and viewing the top element are very fast operations.\n * 4. Function Calls: In most modern programming languages, the records of function calls are managed through a stack. When a function is called, its record (including parameters, local variables, and return address) is 'pushed' into the stack. When the function returns, its record is 'popped' from the stack.\n * 5. Expression Evaluation: Used for the evaluation of arithmetic or logical expressions, especially when dealing with parenthesis matching and operator precedence.\n * 6. Backtracking Algorithms: In problems where multiple branches need to be explored but only one branch can be explored at a time, stacks can be used to save the state at each branching point.\n * @example\n * // basic Stack creation and push operation\n *  // Create a simple Stack with initial values\n *     const stack = new Stack([1, 2, 3, 4, 5]);\n *\n *     // Verify the stack maintains insertion order (LIFO will be shown in pop)\n *     console.log([...stack]); // [1, 2, 3, 4, 5];\n *\n *     // Check length\n *     console.log(stack.size); // 5;\n *\n *     // Push a new element to the top\n *     stack.push(6);\n *     console.log(stack.size); // 6;\n * @example\n * // Stack pop operation (LIFO - Last In First Out)\n *  const stack = new Stack<number>([10, 20, 30, 40, 50]);\n *\n *     // Peek at the top element without removing\n *     const top = stack.peek();\n *     console.log(top); // 50;\n *\n *     // Pop removes from the top (LIFO order)\n *     const popped = stack.pop();\n *     console.log(popped); // 50;\n *\n *     // Next pop gets the previous element\n *     const next = stack.pop();\n *     console.log(next); // 40;\n *\n *     // Verify length decreased\n *     console.log(stack.size); // 3;\n * @example\n * // Function Call Stack\n *  const functionStack = new Stack<string>();\n *     functionStack.push('main');\n *     functionStack.push('foo');\n *     functionStack.push('bar');\n *     console.log(functionStack.pop()); // 'bar';\n *     console.log(functionStack.pop()); // 'foo';\n *     console.log(functionStack.pop()); // 'main';\n * @example\n * // Balanced Parentheses or Brackets\n *  type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';\n *\n *     const stack = new Stack<string>();\n *     const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];\n *     const matches: { [key in ValidCharacters]?: ValidCharacters } = { ')': '(', ']': '[', '}': '{' };\n *     for (const char of input) {\n *       if ('([{'.includes(char)) {\n *         stack.push(char);\n *       } else if (')]}'.includes(char)) {\n *         if (stack.pop() !== matches[char]) {\n *           fail('Parentheses are not balanced');\n *         }\n *       }\n *     }\n *     console.log(stack.isEmpty()); // true;\n * @example\n * // Expression Evaluation and Conversion\n *  const stack = new Stack<number>();\n *     const expression = [5, 3, '+']; // Equivalent to 5 + 3\n *     expression.forEach(token => {\n *       if (typeof token === 'number') {\n *         stack.push(token);\n *       } else {\n *         const b = stack.pop()!;\n *         const a = stack.pop()!;\n *         stack.push(token === '+' ? a + b : 0); // Only handling '+' here\n *       }\n *     });\n *     console.log(stack.pop()); // 8;\n * @example\n * // Backtracking Algorithms\n *  const stack = new Stack<[number, number]>();\n *     const maze = [\n *       ['S', ' ', 'X'],\n *       ['X', ' ', 'X'],\n *       [' ', ' ', 'E']\n *     ];\n *     const start: [number, number] = [0, 0];\n *     const end = [2, 2];\n *     const directions = [\n *       [0, 1], // To the right\n *       [1, 0], // down\n *       [0, -1], // left\n *       [-1, 0] // up\n *     ];\n *\n *     const visited = new Set<string>(); // Used to record visited nodes\n *     stack.push(start);\n *     const path: number[][] = [];\n *\n *     while (!stack.isEmpty()) {\n *       const [x, y] = stack.pop()!;\n *       if (visited.has(`${x},${y}`)) continue; // Skip already visited nodes\n *       visited.add(`${x},${y}`);\n *\n *       path.push([x, y]);\n *\n *       if (x === end[0] && y === end[1]) {\n *         break; // Find the end point and exit\n *       }\n *\n *       for (const [dx, dy] of directions) {\n *         const nx = x + dx;\n *         const ny = y + dy;\n *         if (\n *           maze[nx]?.[ny] === ' ' || // feasible path\n *           maze[nx]?.[ny] === 'E' // destination\n *         ) {\n *           stack.push([nx, ny]);\n *         }\n *       }\n *     }\n *\n *     console.log(path); // contains end;\n * @example\n * // Stock Span Problem\n *  const stack = new Stack<number>();\n *     const prices = [100, 80, 60, 70, 60, 75, 85];\n *     const spans: number[] = [];\n *     prices.forEach((price, i) => {\n *       while (!stack.isEmpty() && prices[stack.peek()!] <= price) {\n *         stack.pop();\n *       }\n *       spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);\n *       stack.push(i);\n *     });\n *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6];\n * @example\n * // Simplify File Paths\n *  const stack = new Stack<string>();\n *     const path = '/a/./b/../../c';\n *     path.split('/').forEach(segment => {\n *       if (segment === '..') stack.pop();\n *       else if (segment && segment !== '.') stack.push(segment);\n *     });\n *     console.log(stack.elements.join('/')); // 'c';\n */\nexport class Stack<E = any, R = any> extends IterableElementBase<E, R> {\n  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);\n\n  /**\n   * Create a Stack and optionally bulk-push elements.\n   * @remarks Time O(N), Space O(N)\n   * @param [elements] - Iterable of elements (or raw records if toElementFn is set).\n   * @param [options] - Options such as toElementFn and equality function.\n   * @returns New Stack instance.\n   */\n\n  constructor(elements: Iterable<E> | Iterable<R> = [], options?: StackOptions<E, R>) {\n    super(options);\n    this.pushMany(elements);\n  }\n\n  protected _elements: E[] = [];\n\n  /**\n   * Get the backing array of elements.\n   * @remarks Time O(1), Space O(1)\n   * @returns Internal elements array.\n   */\n\n  get elements(): E[] {\n    return this._elements;\n  }\n\n  /**\n   * Get the number of stored elements.\n   * @remarks Time O(1), Space O(1)\n   * @returns Current size.\n   */\n\n  get size(): number {\n    return this.elements.length;\n  }\n\n  /**\n   * Create a stack from an array of elements.\n   * @remarks Time O(N), Space O(N)\n   * @template E\n   * @template R\n   * @param this - The constructor (subclass) to instantiate.\n   * @param elements - Array of elements to push in order.\n   * @param [options] - Options forwarded to the constructor.\n   * @returns A new Stack populated from the array.\n   */\n\n  static fromArray<E, R = any>(\n    this: new (elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>) => any,\n    elements: E[],\n    options?: StackOptions<E, R>\n  ) {\n    return new this(elements, options);\n  }\n\n  /**\n   * Check whether the stack is empty.\n   * @remarks Time O(1), Space O(1)\n   * @returns True if size is 0.\n   */\n\n  isEmpty(): boolean {\n    return this.elements.length === 0;\n  }\n\n  /**\n   * Get the top element without removing it.\n   * @remarks Time O(1), Space O(1)\n   * @returns Top element or undefined.\n   */\n\n  peek(): E | undefined {\n    return this.isEmpty() ? undefined : this.elements[this.elements.length - 1];\n  }\n\n  /**\n   * Push one element onto the top.\n   * @remarks Time O(1), Space O(1)\n   * @param element - Element to push.\n   * @returns True when pushed.\n   */\n\n  push(element: E): boolean {\n    this.elements.push(element);\n    return true;\n  }\n\n  /**\n   * Pop and return the top element.\n   * @remarks Time O(1), Space O(1)\n   * @returns Removed element or undefined.\n   */\n\n  pop(): E | undefined {\n    return this.isEmpty() ? undefined : this.elements.pop();\n  }\n\n  /**\n   * Push many elements from an iterable.\n   * @remarks Time O(N), Space O(1)\n   * @param elements - Iterable of elements (or raw records if toElementFn is set).\n   * @returns Array of per-element success flags.\n   */\n\n  pushMany(elements: Iterable<E> | Iterable<R>): boolean[] {\n    const ans: boolean[] = [];\n    for (const el of elements) {\n      if (this.toElementFn) ans.push(this.push(this.toElementFn(el as R)));\n      else ans.push(this.push(el as E));\n    }\n    return ans;\n  }\n\n  /**\n   * Delete the first occurrence of a specific element.\n   * @remarks Time O(N), Space O(1)\n   * @param element - Element to remove (using the configured equality).\n   * @returns True if an element was removed.\n   */\n\n  delete(element: E): boolean {\n    const idx = this._indexOfByEquals(element);\n    return this.deleteAt(idx);\n  }\n\n  /**\n   * Delete the element at an index.\n   * @remarks Time O(N), Space O(1)\n   * @param index - Zero-based index from the bottom.\n   * @returns True if removed.\n   */\n\n  deleteAt(index: number): boolean {\n    if (index < 0 || index >= this.elements.length) return false;\n    const spliced = this.elements.splice(index, 1);\n    return spliced.length === 1;\n  }\n\n  /**\n   * Delete the first element that satisfies a predicate.\n   * @remarks Time O(N), Space O(1)\n   * @param predicate - Function (value, index, stack) → boolean to decide deletion.\n   * @returns True if a match was removed.\n   */\n\n  deleteWhere(predicate: (value: E, index: number, stack: this) => boolean): boolean {\n    for (let i = 0; i < this.elements.length; i++) {\n      if (predicate(this.elements[i], i, this)) {\n        this.elements.splice(i, 1);\n        return true;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Remove all elements and reset storage.\n   * @remarks Time O(1), Space O(1)\n   * @returns void\n   */\n\n  clear(): void {\n    this._elements = [];\n  }\n\n  /**\n   * Deep clone this stack.\n   * @remarks Time O(N), Space O(N)\n   * @returns A new stack with the same content.\n   */\n\n  clone(): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    for (const v of this) out.push(v);\n    return out;\n  }\n\n  /**\n   * Filter elements into a new stack of the same class.\n   * @remarks Time O(N), Space O(N)\n   * @param predicate - Predicate (value, index, stack) → boolean to keep value.\n   * @param [thisArg] - Value for `this` inside the predicate.\n   * @returns A new stack with kept values.\n   */\n\n  filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    let index = 0;\n    for (const v of this) {\n      if (predicate.call(thisArg, v, index, this)) out.push(v);\n      index++;\n    }\n    return out;\n  }\n\n  /**\n   * Map values into a new stack of the same element type.\n   * @remarks Time O(N), Space O(N)\n   * @param callback - Mapping function (value, index, stack) → newValue.\n   * @param [thisArg] - Value for `this` inside the callback.\n   * @returns A new stack with mapped values.\n   */\n\n  mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    let index = 0;\n    for (const v of this) {\n      const mv = thisArg === undefined ? callback(v, index++, this) : callback.call(thisArg, v, index++, this);\n      out.push(mv);\n    }\n    return out;\n  }\n\n  /**\n   * Map values into a new stack (possibly different element type).\n   * @remarks Time O(N), Space O(N)\n   * @template EM\n   * @template RM\n   * @param callback - Mapping function (value, index, stack) → newElement.\n   * @param [options] - Options for the output stack (e.g., toElementFn).\n   * @param [thisArg] - Value for `this` inside the callback.\n   * @returns A new Stack with mapped elements.\n   */\n\n  map<EM, RM>(\n    callback: ElementCallback<E, R, EM>,\n    options?: IterableElementBaseOptions<EM, RM>,\n    thisArg?: unknown\n  ): Stack<EM, RM> {\n    const out = this._createLike<EM, RM>([], { ...(options ?? {}) });\n    let index = 0;\n    for (const v of this) {\n      out.push(thisArg === undefined ? callback(v, index, this) : callback.call(thisArg, v, index, this));\n      index++;\n    }\n    return out;\n  }\n\n  /**\n   * Set the equality comparator used by delete/search operations.\n   * @remarks Time O(1), Space O(1)\n   * @param equals - Equality predicate (a, b) → boolean.\n   * @returns This stack.\n   */\n\n  setEquality(equals: (a: E, b: E) => boolean): this {\n    this._equals = equals;\n    return this;\n  }\n\n  /**\n   * (Protected) Find the index of a target element using the equality function.\n   * @remarks Time O(N), Space O(1)\n   * @param target - Element to search for.\n   * @returns Index or -1 if not found.\n   */\n\n  protected _indexOfByEquals(target: E): number {\n    for (let i = 0; i < this.elements.length; i++) if (this._equals(this.elements[i], target)) return i;\n    return -1;\n  }\n\n  /**\n   * (Protected) Create an empty instance of the same concrete class.\n   * @remarks Time O(1), Space O(1)\n   * @param [options] - Options forwarded to the constructor.\n   * @returns An empty like-kind stack instance.\n   */\n\n  protected _createInstance(options?: StackOptions<E, R>): this {\n    const Ctor = this.constructor as new (elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>) => this;\n    return new Ctor([], options);\n  }\n\n  /**\n   * (Protected) Create a like-kind stack and seed it from an iterable.\n   * @remarks Time O(N), Space O(N)\n   * @template T\n   * @template RR\n   * @param [elements] - Iterable used to seed the new stack.\n   * @param [options] - Options forwarded to the constructor.\n   * @returns A like-kind Stack instance.\n   */\n\n  protected _createLike<T = E, RR = R>(\n    elements: Iterable<T> | Iterable<RR> = [],\n    options?: StackOptions<T, RR>\n  ): Stack<T, RR> {\n    const Ctor = this.constructor as new (\n      elements?: Iterable<T> | Iterable<RR>,\n      options?: StackOptions<T, RR>\n    ) => Stack<T, RR>;\n    return new Ctor(elements, options);\n  }\n\n  /**\n   * (Protected) Iterate elements from bottom to top.\n   * @remarks Time O(N), Space O(1)\n   * @returns Iterator of elements.\n   */\n\n  protected *_getIterator(): IterableIterator<E> {\n    for (let i = 0; i < this.elements.length; i++) yield this.elements[i];\n  }\n}\n","export enum DFSOperation {\n  VISIT = 0,\n  PROCESS = 1\n}\n\nexport class Range<K> {\n  constructor(\n    public low: K,\n    public high: K,\n    public includeLow: boolean = true,\n    public includeHigh: boolean = true\n  ) {\n    // if (!(isComparable(low) && isComparable(high))) throw new RangeError('low or high is not comparable');\n    // if (low > high) throw new RangeError('low must be less than or equal to high');\n  }\n\n  // Determine whether a key is within the range\n  isInRange(key: K, comparator: (a: K, b: K) => number): boolean {\n    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;\n    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;\n    return lowCheck && highCheck;\n  }\n}\n"]}
+{"version":3,"sources":["../../src/data-structures/base/iterable-element-base.ts","../../src/data-structures/stack/stack.ts","../../src/common/error.ts","../../src/common/index.ts"],"names":["DFSOperation"],"mappings":";;;;;;AAaO,IAAe,sBAAf,MAAgE;AAAA,EAbvE;AAauE,IAAA,MAAA,CAAA,IAAA,EAAA,qBAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAU3D,YAAY,OAAA,EAA4C;AAChE,IAAA,IAAI,OAAA,EAAS;AACX,MAAA,MAAM,EAAE,aAAY,GAAI,OAAA;AACxB,MAAA,IAAI,OAAO,WAAA,KAAgB,UAAA,EAAY,IAAA,CAAK,YAAA,GAAe,WAAA;AAAA,WAAA,IAClD,WAAA,EAAa,MAAM,IAAI,SAAA,CAAU,qCAAqC,CAAA;AAAA,IACjF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQU,YAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASV,IAAI,WAAA,GAAkD;AACpD,IAAA,OAAO,IAAA,CAAK,YAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,EAAE,MAAA,CAAO,QAAQ,CAAA,CAAA,GAAK,IAAA,EAAsC;AAC1D,IAAA,OAAO,IAAA,CAAK,YAAA,CAAa,GAAG,IAAI,CAAA;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,CAAC,MAAA,GAA8B;AAC7B,IAAA,KAAA,MAAW,IAAA,IAAQ,MAAM,MAAM,IAAA;AAAA,EACjC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,KAAA,CAAM,WAA2C,OAAA,EAA4B;AAC3E,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACvB,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,IAAI,CAAC,SAAA,CAAU,IAAA,EAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,KAAA;AAAA,MAC9C,CAAA,MAAO;AACL,QAAA,MAAM,EAAA,GAAK,SAAA;AACX,QAAA,IAAI,CAAC,GAAG,IAAA,CAAK,OAAA,EAAS,MAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,KAAA;AAAA,MACrD;AAAA,IACF;AACA,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,IAAA,CAAK,WAA2C,OAAA,EAA4B;AAC1E,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACvB,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,IAAI,SAAA,CAAU,IAAA,EAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,IAAA;AAAA,MAC7C,CAAA,MAAO;AACL,QAAA,MAAM,EAAA,GAAK,SAAA;AACX,QAAA,IAAI,GAAG,IAAA,CAAK,OAAA,EAAS,MAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,IAAA;AAAA,MACpD;AAAA,IACF;AACA,IAAA,OAAO,KAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,OAAA,CAAQ,YAAyC,OAAA,EAAyB;AACxE,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACvB,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,UAAA,CAAW,IAAA,EAAM,SAAS,IAAI,CAAA;AAAA,MAChC,CAAA,MAAO;AACL,QAAA,MAAM,EAAA,GAAK,UAAA;AACX,QAAA,EAAA,CAAG,IAAA,CAAK,OAAA,EAAS,IAAA,EAAM,KAAA,EAAA,EAAS,IAAI,CAAA;AAAA,MACtC;AAAA,IACF;AAAA,EACF;AAAA;AAAA,EAwBA,IAAA,CAAK,WAA2C,OAAA,EAAkC;AAChF,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACvB,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,IAAI,SAAA,CAAU,IAAA,EAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,IAAA;AAAA,MAC7C,CAAA,MAAO;AACL,QAAA,MAAM,EAAA,GAAK,SAAA;AACX,QAAA,IAAI,GAAG,IAAA,CAAK,OAAA,EAAS,MAAM,KAAA,EAAA,EAAS,IAAI,GAAG,OAAO,IAAA;AAAA,MACpD;AAAA,IACF;AACA,IAAA;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,IAAI,OAAA,EAAqB;AACvB,IAAA,KAAA,MAAW,GAAA,IAAO,IAAA,EAAM,IAAI,GAAA,KAAQ,SAAS,OAAO,IAAA;AACpD,IAAA,OAAO,KAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA2BA,MAAA,CAAU,YAA4C,YAAA,EAAqB;AACzE,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,MAAM,IAAA,GAAO,IAAA,CAAK,MAAA,CAAO,QAAQ,CAAA,EAAE;AACnC,IAAA,IAAI,GAAA;AAEJ,IAAA,IAAI,SAAA,CAAU,UAAU,CAAA,EAAG;AACzB,MAAA,GAAA,GAAM,YAAA;AAAA,IACR,CAAA,MAAO;AACL,MAAA,MAAM,KAAA,GAAQ,KAAK,IAAA,EAAK;AACxB,MAAA,IAAI,KAAA,CAAM,IAAA,EAAM,MAAM,IAAI,UAAU,iDAAiD,CAAA;AACrF,MAAA,GAAA,GAAM,KAAA,CAAM,KAAA;AACZ,MAAA,KAAA,GAAQ,CAAA;AAAA,IACV;AAEA,IAAA,KAAA,MAAW,SAAS,IAAA,EAAgC;AAClD,MAAA,GAAA,GAAM,UAAA,CAAW,GAAA,EAAK,KAAA,EAAO,KAAA,EAAA,EAAS,IAAI,CAAA;AAAA,IAC5C;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAA,GAAe;AACb,IAAA,OAAO,CAAC,GAAG,IAAI,CAAA;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,QAAA,GAAgB;AACd,IAAA,OAAO,CAAC,GAAG,IAAI,CAAA;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,KAAA,GAAc;AACZ,IAAA,OAAA,CAAQ,GAAA,CAAI,IAAA,CAAK,QAAA,EAAU,CAAA;AAAA,EAC7B;AAkFF,CAAA;;;ACzNO,IAAM,KAAA,GAAN,cAAsC,mBAAA,CAA0B;AAAA,EAtIvE;AAsIuE,IAAA,MAAA,CAAA,IAAA,EAAA,OAAA,CAAA;AAAA;AAAA,EAC3D,OAAA,2BAAoC,CAAA,EAAG,CAAA,KAAM,OAAO,EAAA,CAAG,CAAA,EAAG,CAAC,CAAA,EAAxB,SAAA,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAU7C,WAAA,CAAY,QAAA,GAAsC,EAAC,EAAG,OAAA,EAA8B;AAClF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,SAAS,QAAQ,CAAA;AAAA,EACxB;AAAA,EAEU,YAAiB,EAAC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQ5B,IAAI,QAAA,GAAgB;AAClB,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqBA,IAAI,IAAA,GAAe;AACjB,IAAA,OAAO,KAAK,QAAA,CAAS,MAAA;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,OAAO,SAAA,CAEL,QAAA,EACA,OAAA,EACA;AACA,IAAA,OAAO,IAAI,IAAA,CAAK,QAAA,EAAU,OAAO,CAAA;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAyBA,OAAA,GAAmB;AACjB,IAAA,OAAO,IAAA,CAAK,SAAS,MAAA,KAAW,CAAA;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,IAAA,GAAsB;AACpB,IAAA,OAAO,IAAA,CAAK,SAAQ,GAAI,MAAA,GAAY,KAAK,QAAA,CAAS,IAAA,CAAK,QAAA,CAAS,MAAA,GAAS,CAAC,CAAA;AAAA,EAC5E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkCA,KAAK,OAAA,EAAqB;AACxB,IAAA,IAAA,CAAK,QAAA,CAAS,KAAK,OAAO,CAAA;AAC1B,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAqCA,GAAA,GAAqB;AACnB,IAAA,OAAO,KAAK,OAAA,EAAQ,GAAI,MAAA,GAAY,IAAA,CAAK,SAAS,GAAA,EAAI;AAAA,EACxD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,SAAS,QAAA,EAAgD;AACvD,IAAA,MAAM,MAAiB,EAAC;AACxB,IAAA,KAAA,MAAW,MAAM,QAAA,EAAU;AACzB,MAAA,IAAI,IAAA,CAAK,WAAA,EAAa,GAAA,CAAI,IAAA,CAAK,IAAA,CAAK,KAAK,IAAA,CAAK,WAAA,CAAY,EAAO,CAAC,CAAC,CAAA;AAAA,WAC9D,GAAA,CAAI,IAAA,CAAK,IAAA,CAAK,IAAA,CAAK,EAAO,CAAC,CAAA;AAAA,IAClC;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,OAAO,OAAA,EAAqB;AAC1B,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,gBAAA,CAAiB,OAAO,CAAA;AACzC,IAAA,OAAO,IAAA,CAAK,SAAS,GAAG,CAAA;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,SAAS,KAAA,EAAwB;AAC/B,IAAA,IAAI,QAAQ,CAAA,IAAK,KAAA,IAAS,IAAA,CAAK,QAAA,CAAS,QAAQ,OAAO,KAAA;AACvD,IAAA,MAAM,OAAA,GAAU,IAAA,CAAK,QAAA,CAAS,MAAA,CAAO,OAAO,CAAC,CAAA;AAC7C,IAAA,OAAO,QAAQ,MAAA,KAAW,CAAA;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAAY,SAAA,EAAuE;AACjF,IAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAA,EAAK;AAC7C,MAAA,IAAI,UAAU,IAAA,CAAK,QAAA,CAAS,CAAC,CAAA,EAAG,CAAA,EAAG,IAAI,CAAA,EAAG;AACxC,QAAA,IAAA,CAAK,QAAA,CAAS,MAAA,CAAO,CAAA,EAAG,CAAC,CAAA;AACzB,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,IACF;AACA,IAAA,OAAO,KAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAsBA,KAAA,GAAc;AACZ,IAAA,IAAA,CAAK,YAAY,EAAC;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,KAAA,GAAc;AACZ,IAAA,MAAM,MAAM,IAAA,CAAK,eAAA,CAAgB,EAAE,WAAA,EAAa,IAAA,CAAK,aAAa,CAAA;AAClE,IAAA,KAAA,MAAW,CAAA,IAAK,IAAA,EAAM,GAAA,CAAI,IAAA,CAAK,CAAC,CAAA;AAChC,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBA,MAAA,CAAO,WAA2C,OAAA,EAAyB;AACzE,IAAA,MAAM,MAAM,IAAA,CAAK,eAAA,CAAgB,EAAE,WAAA,EAAa,IAAA,CAAK,aAAa,CAAA;AAClE,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,KAAK,IAAA,EAAM;AACpB,MAAA,IAAI,SAAA,CAAU,KAAK,OAAA,EAAS,CAAA,EAAG,OAAO,IAAI,CAAA,EAAG,GAAA,CAAI,IAAA,CAAK,CAAC,CAAA;AACvD,MAAA,KAAA,EAAA;AAAA,IACF;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,OAAA,CAAQ,UAAoC,OAAA,EAAyB;AACnE,IAAA,MAAM,MAAM,IAAA,CAAK,eAAA,CAAgB,EAAE,WAAA,EAAa,IAAA,CAAK,aAAa,CAAA;AAClE,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,KAAK,IAAA,EAAM;AACpB,MAAA,MAAM,EAAA,GAAK,OAAA,KAAY,MAAA,GAAY,QAAA,CAAS,CAAA,EAAG,KAAA,EAAA,EAAS,IAAI,CAAA,GAAI,QAAA,CAAS,IAAA,CAAK,OAAA,EAAS,CAAA,EAAG,SAAS,IAAI,CAAA;AACvG,MAAA,GAAA,CAAI,KAAK,EAAE,CAAA;AAAA,IACb;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EA0BA,GAAA,CACE,QAAA,EACA,OAAA,EACA,OAAA,EACe;AACf,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,WAAA,CAAoB,EAAC,EAAG,EAAE,GAAI,OAAA,IAAW,EAAC,EAAI,CAAA;AAC/D,IAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,IAAA,KAAA,MAAW,KAAK,IAAA,EAAM;AACpB,MAAA,GAAA,CAAI,IAAA,CAAK,OAAA,KAAY,MAAA,GAAY,QAAA,CAAS,GAAG,KAAA,EAAO,IAAI,CAAA,GAAI,QAAA,CAAS,IAAA,CAAK,OAAA,EAAS,CAAA,EAAG,KAAA,EAAO,IAAI,CAAC,CAAA;AAClG,MAAA,KAAA,EAAA;AAAA,IACF;AACA,IAAA,OAAO,GAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,YAAY,MAAA,EAAuC;AACjD,IAAA,IAAA,CAAK,OAAA,GAAU,MAAA;AACf,IAAA,OAAO,IAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASU,iBAAiB,MAAA,EAAmB;AAC5C,IAAA,KAAA,IAAS,IAAI,CAAA,EAAG,CAAA,GAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAA,EAAK,IAAI,IAAA,CAAK,OAAA,CAAQ,KAAK,QAAA,CAAS,CAAC,CAAA,EAAG,MAAM,GAAG,OAAO,CAAA;AAClG,IAAA,OAAO,EAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASU,gBAAgB,OAAA,EAAoC;AAC5D,IAAA,MAAM,OAAO,IAAA,CAAK,WAAA;AAClB,IAAA,OAAO,IAAI,IAAA,CAAK,EAAC,EAAG,OAAO,CAAA;AAAA,EAC7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYU,WAAA,CACR,QAAA,GAAuC,EAAC,EACxC,OAAA,EACc;AACd,IAAA,MAAM,OAAO,IAAA,CAAK,WAAA;AAIlB,IAAA,OAAO,IAAI,IAAA,CAAK,QAAA,EAAU,OAAO,CAAA;AAAA,EACnC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,CAAW,YAAA,GAAoC;AAC7C,IAAA,KAAA,IAAS,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,IAAA,CAAK,QAAA,CAAS,QAAQ,CAAA,EAAA,EAAK,MAAM,IAAA,CAAK,QAAA,CAAS,CAAC,CAAA;AAAA,EACtE;AACF;;;AC9lBO,IAAM,GAAA,GAAM;AAAA;AAAA,EAEjB,iCAAiB,MAAA,CAAA,CAAC,KAAA,EAAe,GAAA,EAAa,GAAA,EAAa,QACzD,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,MAAA,EAAS,KAAK,qBAAqB,GAAG,CAAA,EAAA,EAAK,GAAG,CAAA,EAAA,CAAA,EADvD,iBAAA,CAAA;AAAA,EAGjB,YAAA,0BAAe,GAAA,KACb,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,yBAAA,CAAA,EADZ,cAAA,CAAA;AAAA;AAAA,EAId,eAAA,kBAAiB,MAAA,CAAA,CAAC,MAAA,EAAgB,GAAA,KAChC,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,EAAG,MAAM,CAAA,CAAA,EADlB,iBAAA,CAAA;AAAA,EAGjB,kBAAA,0BAAqB,GAAA,KACnB,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,+DAAA,CAAA,EADN,oBAAA,CAAA;AAAA,EAGpB,UAAA,kBAAY,MAAA,CAAA,CAAC,MAAA,EAAgB,GAAA,KAC3B,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,EAAG,MAAM,CAAA,CAAA,EADvB,YAAA,CAAA;AAAA,EAGZ,YAAA,kBAAc,MAAA,CAAA,CAAC,IAAA,EAAc,GAAA,KAC3B,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,EAAG,IAAI,CAAA,oBAAA,CAAA,EADnB,cAAA,CAAA;AAAA,EAGd,YAAA,0BAAe,GAAA,KACb,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,wCAAA,CAAA,EADZ,cAAA,CAAA;AAAA,EAGd,UAAA,0BAAa,GAAA,KACX,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,uBAAA,CAAA,EADd,YAAA,CAAA;AAAA,EAGZ,WAAA,0BAAc,GAAA,KACZ,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,iBAAA,CAAA,EADb,aAAA,CAAA;AAAA,EAGb,WAAA,0BAAc,GAAA,KACZ,CAAA,EAAG,MAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,gDAAA,CAAA,EADb,aAAA,CAAA;AAAA,EAGb,kBAAA,kBAAoB,MAAA,CAAA,CAAC,QAAA,EAAkB,GAAA,EAAa,QAClD,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,qBAAA,EAAwB,QAAQ,CAAA,MAAA,EAAS,GAAG,CAAA,CAAA,CAAA,EADlD,oBAAA,CAAA;AAAA;AAAA,EAIpB,gBAAA,kBAAkB,MAAA,CAAA,CAAC,MAAA,EAAgB,GAAA,KACjC,CAAA,EAAG,GAAA,GAAM,GAAA,GAAM,IAAA,GAAO,EAAE,CAAA,EAAG,MAAM,CAAA,CAAA,EADjB,kBAAA,CAAA;AAAA;AAAA,EAIlB,uBAAA,kBAAyB,MAAA,CAAA,CAAC,EAAA,KACxB,CAAA,0CAAA,EAA6C,EAAE,CAAA,CAAA,CAAA,EADxB,yBAAA,CAAA;AAAA,EAGzB,cAAA,+BACE,kDAAA,EADc,gBAAA,CAAA;AAAA,EAGhB,eAAA,+BACE,uCAAA,EADe,iBAAA,CAAA;AAAA,EAGjB,oBAAA,+BACE,gDAAA,EADoB,sBAAA,CAAA;AAAA,EAGtB,iBAAA,0BAAoB,QAAA,EAAkB,GAAA,KACpC,+BAA+B,QAAQ,CAAA,UAAA,EAAa,GAAG,CAAA,CAAA,CAAA,EADtC,mBAAA;AAErB;;;ACzDO,IAAK,YAAA,qBAAAA,aAAAA,KAAL;AACL,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,WAAQ,CAAA,CAAA,GAAR,OAAA;AACA,EAAAA,aAAAA,CAAAA,aAAAA,CAAA,aAAU,CAAA,CAAA,GAAV,SAAA;AAFU,EAAA,OAAAA,aAAAA;AAAA,CAAA,EAAA,YAAA,IAAA,EAAA;AAKL,IAAM,QAAN,MAAe;AAAA,EACpB,YACS,GAAA,EACA,IAAA,EACA,UAAA,GAAsB,IAAA,EACtB,cAAuB,IAAA,EAC9B;AAJO,IAAA,IAAA,CAAA,GAAA,GAAA,GAAA;AACA,IAAA,IAAA,CAAA,IAAA,GAAA,IAAA;AACA,IAAA,IAAA,CAAA,UAAA,GAAA,UAAA;AACA,IAAA,IAAA,CAAA,WAAA,GAAA,WAAA;AAAA,EAIT;AAAA,EAhBF;AAOsB,IAAA,MAAA,CAAA,IAAA,EAAA,OAAA,CAAA;AAAA;AAAA;AAAA,EAYpB,SAAA,CAAU,KAAQ,UAAA,EAA6C;AAC7D,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,UAAA,GAAa,UAAA,CAAW,GAAA,EAAK,IAAA,CAAK,GAAG,CAAA,IAAK,CAAA,GAAI,UAAA,CAAW,GAAA,EAAK,IAAA,CAAK,GAAG,CAAA,GAAI,CAAA;AAChG,IAAA,MAAM,SAAA,GAAY,IAAA,CAAK,WAAA,GAAc,UAAA,CAAW,GAAA,EAAK,IAAA,CAAK,IAAI,CAAA,IAAK,CAAA,GAAI,UAAA,CAAW,GAAA,EAAK,IAAA,CAAK,IAAI,CAAA,GAAI,CAAA;AACpG,IAAA,OAAO,QAAA,IAAY,SAAA;AAAA,EACrB;AACF","file":"index.cjs","sourcesContent":["import type { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';\n\n/**\n * Base class that makes a data structure iterable and provides common\n * element-wise utilities (e.g., map/filter/reduce/find).\n *\n * @template E The public element type yielded by the structure.\n * @template R The underlying \"raw\" element type used internally or by converters.\n *\n * @remarks\n * This class implements the JavaScript iteration protocol (via `Symbol.iterator`)\n * and offers array-like helpers with predictable time/space complexity.\n */\nexport abstract class IterableElementBase<E, R> implements Iterable<E> {\n  /**\n   * Create a new iterable base.\n   *\n   * @param options Optional behavior overrides. When provided, a `toElementFn`\n   * is used to convert a raw element (`R`) into a public element (`E`).\n   *\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  protected constructor(options?: IterableElementBaseOptions<E, R>) {\n    if (options) {\n      const { toElementFn } = options;\n      if (typeof toElementFn === 'function') this._toElementFn = toElementFn;\n      else if (toElementFn) throw new TypeError('toElementFn must be a function type');\n    }\n  }\n\n  /**\n   * The converter used to transform a raw element (`R`) into a public element (`E`).\n   *\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  protected _toElementFn?: (rawElement: R) => E;\n\n  /**\n   * Exposes the current `toElementFn`, if configured.\n   *\n   * @returns The converter function or `undefined` when not set.\n   * @remarks\n   * Time O(1), Space O(1).\n   */\n  get toElementFn(): ((rawElement: R) => E) | undefined {\n    return this._toElementFn;\n  }\n\n  /**\n   * Returns an iterator over the structure's elements.\n   *\n   * @param args Optional iterator arguments forwarded to the internal iterator.\n   * @returns An `IterableIterator<E>` that yields the elements in traversal order.\n   *\n   * @remarks\n   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.\n   */\n  *[Symbol.iterator](...args: unknown[]): IterableIterator<E> {\n    yield* this._getIterator(...args);\n  }\n\n  /**\n   * Returns an iterator over the values (alias of the default iterator).\n   *\n   * @returns An `IterableIterator<E>` over all elements.\n   * @remarks\n   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).\n   */\n  *values(): IterableIterator<E> {\n    for (const item of this) yield item;\n  }\n\n  /**\n   * Tests whether all elements satisfy the predicate.\n   *\n   * @template TReturn\n   * @param predicate Function invoked for each element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns `true` if every element passes; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).\n   */\n  every(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (!predicate(item, index++, this)) return false;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (!fn.call(thisArg, item, index++, this)) return false;\n      }\n    }\n    return true;\n  }\n\n  /**\n   * Tests whether at least one element satisfies the predicate.\n   *\n   * @param predicate Function invoked for each element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns `true` if any element passes; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early on first success. Space O(1).\n   */\n  some(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (predicate(item, index++, this)) return true;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (fn.call(thisArg, item, index++, this)) return true;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Invokes a callback for each element in iteration order.\n   *\n   * @param callbackfn Function invoked per element with signature `(value, index, self)`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns `void`.\n   *\n   * @remarks\n   * Time O(n), Space O(1).\n   */\n  forEach(callbackfn: ElementCallback<E, R, void>, thisArg?: unknown): void {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        callbackfn(item, index++, this);\n      } else {\n        const fn = callbackfn as (this: unknown, v: E, i: number, self: this) => void;\n        fn.call(thisArg, item, index++, this);\n      }\n    }\n  }\n\n  /**\n   * Finds the first element that satisfies the predicate and returns it.\n   *\n   * @overload\n   * Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.\n   * @template S\n   * @param predicate Type-guard predicate: `(value, index, self) => value is S`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns The matched element typed as `S`, or `undefined` if not found.\n   *\n   * @overload\n   * @param predicate Boolean predicate: `(value, index, self) => boolean`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns The first matching element as `E`, or `undefined` if not found.\n   *\n   * @remarks\n   * Time O(n) in the worst case; may exit early on the first match. Space O(1).\n   */\n  find<S extends E>(predicate: ElementCallback<E, R, S>, thisArg?: unknown): S | undefined;\n  find(predicate: ElementCallback<E, R, unknown>, thisArg?: unknown): E | undefined;\n\n  // Implementation signature\n  find(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): E | undefined {\n    let index = 0;\n    for (const item of this) {\n      if (thisArg === undefined) {\n        if (predicate(item, index++, this)) return item;\n      } else {\n        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;\n        if (fn.call(thisArg, item, index++, this)) return item;\n      }\n    }\n    return;\n  }\n\n  /**\n   * Checks whether a strictly-equal element exists in the structure.\n   *\n   * @param element The element to test with `===` equality.\n   * @returns `true` if an equal element is found; otherwise `false`.\n   *\n   * @remarks\n   * Time O(n) in the worst case. Space O(1).\n   */\n  has(element: E): boolean {\n    for (const ele of this) if (ele === element) return true;\n    return false;\n  }\n\n  reduce(callbackfn: ReduceElementCallback<E, R>): E;\n  reduce(callbackfn: ReduceElementCallback<E, R>, initialValue: E): E;\n  reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue: U): U;\n\n  /**\n   * Reduces all elements to a single accumulated value.\n   *\n   * @overload\n   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.\n   * @returns The final accumulated value typed as `E`.\n   *\n   * @overload\n   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.\n   * @param initialValue The initial accumulator value of type `E`.\n   * @returns The final accumulated value typed as `E`.\n   *\n   * @overload\n   * @template U The accumulator type when it differs from `E`.\n   * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.\n   * @param initialValue The initial accumulator value of type `U`.\n   * @returns The final accumulated value typed as `U`.\n   *\n   * @remarks\n   * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.\n   */\n  reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue?: U): U {\n    let index = 0;\n    const iter = this[Symbol.iterator]();\n    let acc: U;\n\n    if (arguments.length >= 2) {\n      acc = initialValue as U;\n    } else {\n      const first = iter.next();\n      if (first.done) throw new TypeError('Reduce of empty structure with no initial value');\n      acc = first.value as unknown as U;\n      index = 1;\n    }\n\n    for (const value of iter as unknown as Iterable<E>) {\n      acc = callbackfn(acc, value, index++, this);\n    }\n    return acc;\n  }\n\n  /**\n   * Materializes the elements into a new array.\n   *\n   * @returns A shallow array copy of the iteration order.\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  toArray(): E[] {\n    return [...this];\n  }\n\n  /**\n   * Returns a representation of the structure suitable for quick visualization.\n   * Defaults to an array of elements; subclasses may override to provide richer visuals.\n   *\n   * @returns A visual representation (array by default).\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  toVisual(): E[] {\n    return [...this];\n  }\n\n  /**\n   * Prints `toVisual()` to the console. Intended for quick debugging.\n   *\n   * @returns `void`.\n   * @remarks\n   * Time O(n) due to materialization, Space O(n) for the intermediate representation.\n   */\n  print(): void {\n    console.log(this.toVisual());\n  }\n\n  /**\n   * Indicates whether the structure currently contains no elements.\n   *\n   * @returns `true` if empty; otherwise `false`.\n   * @remarks\n   * Expected Time O(1), Space O(1) for most implementations.\n   */\n  abstract isEmpty(): boolean;\n\n  /**\n   * Removes all elements from the structure.\n   *\n   * @returns `void`.\n   * @remarks\n   * Expected Time O(1) or O(n) depending on the implementation; Space O(1).\n   */\n  abstract clear(): void;\n\n  /**\n   * Creates a structural copy with the same element values and configuration.\n   *\n   * @returns A clone of the current instance (same concrete type).\n   * @remarks\n   * Expected Time O(n) to copy elements; Space O(n).\n   */\n  abstract clone(): this;\n\n  /**\n   * Maps each element to a new element and returns a new iterable structure.\n   *\n   * @template EM The mapped element type.\n   * @template RM The mapped raw element type used internally by the target structure.\n   * @param callback Function with signature `(value, index, self) => mapped`.\n   * @param options Optional options for the returned structure, including its `toElementFn`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns A new `IterableElementBase<EM, RM>` containing mapped elements.\n   *\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  abstract map<EM, RM>(\n    callback: ElementCallback<E, R, EM>,\n    options?: IterableElementBaseOptions<EM, RM>,\n    thisArg?: unknown\n  ): IterableElementBase<EM, RM>;\n\n  /**\n   * Maps each element to the same element type and returns the same concrete structure type.\n   *\n   * @param callback Function with signature `(value, index, self) => mappedValue`.\n   * @param thisArg Optional `this` binding for the callback.\n   * @returns A new instance of the same concrete type with mapped elements.\n   *\n   * @remarks\n   * Time O(n), Space O(n).\n   */\n  abstract mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;\n\n  /**\n   * Filters elements using the provided predicate and returns the same concrete structure type.\n   *\n   * @param predicate Function with signature `(value, index, self) => boolean`.\n   * @param thisArg Optional `this` binding for the predicate.\n   * @returns A new instance of the same concrete type containing only elements that pass the predicate.\n   *\n   * @remarks\n   * Time O(n), Space O(k) where `k` is the number of kept elements.\n   */\n  abstract filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;\n\n  /**\n   * Internal iterator factory used by the default iterator.\n   *\n   * @param args Optional iterator arguments.\n   * @returns An iterator over elements.\n   *\n   * @remarks\n   * Implementations should yield in O(1) per element with O(1) extra space when possible.\n   */\n  protected abstract _getIterator(...args: unknown[]): IterableIterator<E>;\n}\n","/**\n * data-structure-typed\n *\n * @author Pablo Zeng\n * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>\n * @license MIT License\n */\n\nimport type { ElementCallback, IterableElementBaseOptions, StackOptions } from '../../types';\nimport { IterableElementBase } from '../base';\n\n/**\n * LIFO stack with array storage and optional record→element conversion.\n * @remarks Time O(1), Space O(1)\n * @template E\n * @template R\n * 1. Last In, First Out (LIFO): The core characteristic of a stack is its last in, first out nature, meaning the last element added to the stack will be the first to be removed.\n * 2. Uses: Stacks are commonly used for managing a series of tasks or elements that need to be processed in a last in, first out manner. They are widely used in various scenarios, such as in function calls in programming languages, evaluation of arithmetic expressions, and backtracking algorithms.\n * 3. Performance: Stack operations are typically O(1) in time complexity, meaning that regardless of the stack's size, adding, removing, and viewing the top element are very fast operations.\n * 4. Function Calls: In most modern programming languages, the records of function calls are managed through a stack. When a function is called, its record (including parameters, local variables, and return address) is 'pushed' into the stack. When the function returns, its record is 'popped' from the stack.\n * 5. Expression Evaluation: Used for the evaluation of arithmetic or logical expressions, especially when dealing with parenthesis matching and operator precedence.\n * 6. Backtracking Algorithms: In problems where multiple branches need to be explored but only one branch can be explored at a time, stacks can be used to save the state at each branching point.\n * @example\n * // Function Call Stack\n *  const functionStack = new Stack<string>();\n *     functionStack.push('main');\n *     functionStack.push('foo');\n *     functionStack.push('bar');\n *     console.log(functionStack.pop()); // 'bar';\n *     console.log(functionStack.pop()); // 'foo';\n *     console.log(functionStack.pop()); // 'main';\n * @example\n * // Balanced Parentheses or Brackets\n *  type ValidCharacters = ')' | '(' | ']' | '[' | '}' | '{';\n *\n *     const stack = new Stack<string>();\n *     const input: ValidCharacters[] = '[({})]'.split('') as ValidCharacters[];\n *     const matches: { [key in ValidCharacters]?: ValidCharacters } = { ')': '(', ']': '[', '}': '{' };\n *     for (const char of input) {\n *       if ('([{'.includes(char)) {\n *         stack.push(char);\n *       } else if (')]}'.includes(char)) {\n *         if (stack.pop() !== matches[char]) {\n *           fail('Parentheses are not balanced');\n *         }\n *       }\n *     }\n *     console.log(stack.isEmpty()); // true;\n * @example\n * // Expression Evaluation and Conversion\n *  const stack = new Stack<number>();\n *     const expression = [5, 3, '+']; // Equivalent to 5 + 3\n *     expression.forEach(token => {\n *       if (typeof token === 'number') {\n *         stack.push(token);\n *       } else {\n *         const b = stack.pop()!;\n *         const a = stack.pop()!;\n *         stack.push(token === '+' ? a + b : 0); // Only handling '+' here\n *       }\n *     });\n *     console.log(stack.pop()); // 8;\n * @example\n * // Backtracking Algorithms\n *  const stack = new Stack<[number, number]>();\n *     const maze = [\n *       ['S', ' ', 'X'],\n *       ['X', ' ', 'X'],\n *       [' ', ' ', 'E']\n *     ];\n *     const start: [number, number] = [0, 0];\n *     const end = [2, 2];\n *     const directions = [\n *       [0, 1], // To the right\n *       [1, 0], // down\n *       [0, -1], // left\n *       [-1, 0] // up\n *     ];\n *\n *     const visited = new Set<string>(); // Used to record visited nodes\n *     stack.push(start);\n *     const path: number[][] = [];\n *\n *     while (!stack.isEmpty()) {\n *       const [x, y] = stack.pop()!;\n *       if (visited.has(`${x},${y}`)) continue; // Skip already visited nodes\n *       visited.add(`${x},${y}`);\n *\n *       path.push([x, y]);\n *\n *       if (x === end[0] && y === end[1]) {\n *         break; // Find the end point and exit\n *       }\n *\n *       for (const [dx, dy] of directions) {\n *         const nx = x + dx;\n *         const ny = y + dy;\n *         if (\n *           maze[nx]?.[ny] === ' ' || // feasible path\n *           maze[nx]?.[ny] === 'E' // destination\n *         ) {\n *           stack.push([nx, ny]);\n *         }\n *       }\n *     }\n *\n *     console.log(path); // contains end;\n * @example\n * // Stock Span Problem\n *  const stack = new Stack<number>();\n *     const prices = [100, 80, 60, 70, 60, 75, 85];\n *     const spans: number[] = [];\n *     prices.forEach((price, i) => {\n *       while (!stack.isEmpty() && prices[stack.peek()!] <= price) {\n *         stack.pop();\n *       }\n *       spans.push(stack.isEmpty() ? i + 1 : i - stack.peek()!);\n *       stack.push(i);\n *     });\n *     console.log(spans); // [1, 1, 1, 2, 1, 4, 6];\n * @example\n * // Simplify File Paths\n *  const stack = new Stack<string>();\n *     const path = '/a/./b/../../c';\n *     path.split('/').forEach(segment => {\n *       if (segment === '..') stack.pop();\n *       else if (segment && segment !== '.') stack.push(segment);\n *     });\n *     console.log(stack.elements.join('/')); // 'c';\n * @example\n * // Convert stack to array\n *  const stack = new Stack<number>([1, 2, 3]);\n *     console.log(stack.toArray()); // [1, 2, 3];\n */\nexport class Stack<E = any, R = any> extends IterableElementBase<E, R> {\n  protected _equals: (a: E, b: E) => boolean = (a, b) => Object.is(a, b);\n\n  /**\n   * Create a Stack and optionally bulk-push elements.\n   * @remarks Time O(N), Space O(N)\n   * @param [elements] - Iterable of elements (or raw records if toElementFn is set).\n   * @param [options] - Options such as toElementFn and equality function.\n   * @returns New Stack instance.\n   */\n\n  constructor(elements: Iterable<E> | Iterable<R> = [], options?: StackOptions<E, R>) {\n    super(options);\n    this.pushMany(elements);\n  }\n\n  protected _elements: E[] = [];\n\n  /**\n   * Get the backing array of elements.\n   * @remarks Time O(1), Space O(1)\n   * @returns Internal elements array.\n   */\n\n  get elements(): E[] {\n    return this._elements;\n  }\n\n  /**\n   * Get the number of stored elements.\n   * @remarks Time O(1), Space O(1)\n   * @returns Current size.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Get number of elements\n *  const stack = new Stack<number>([1, 2, 3]);\n *     console.log(stack.size); // 3;\n   */\n\n  get size(): number {\n    return this.elements.length;\n  }\n\n  /**\n   * Create a stack from an array of elements.\n   * @remarks Time O(N), Space O(N)\n   * @template E\n   * @template R\n   * @param this - The constructor (subclass) to instantiate.\n   * @param elements - Array of elements to push in order.\n   * @param [options] - Options forwarded to the constructor.\n   * @returns A new Stack populated from the array.\n   */\n\n  static fromArray<E, R = any>(\n    this: new (elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>) => any,\n    elements: E[],\n    options?: StackOptions<E, R>\n  ) {\n    return new this(elements, options);\n  }\n\n  /**\n   * Check whether the stack is empty.\n   * @remarks Time O(1), Space O(1)\n   * @returns True if size is 0.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Check if stack has elements\n *  const stack = new Stack<number>();\n *     console.log(stack.isEmpty()); // true;\n *     stack.push(1);\n *     console.log(stack.isEmpty()); // false;\n   */\n\n  isEmpty(): boolean {\n    return this.elements.length === 0;\n  }\n\n  /**\n   * Get the top element without removing it.\n   * @remarks Time O(1), Space O(1)\n   * @returns Top element or undefined.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // View the top element without removing it\n *  const stack = new Stack<string>(['a', 'b', 'c']);\n *     console.log(stack.peek()); // 'c';\n *     console.log(stack.size); // 3;\n   */\n\n  peek(): E | undefined {\n    return this.isEmpty() ? undefined : this.elements[this.elements.length - 1];\n  }\n\n  /**\n   * Push one element onto the top.\n   * @remarks Time O(1), Space O(1)\n   * @param element - Element to push.\n   * @returns True when pushed.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // basic Stack creation and push operation\n *  // Create a simple Stack with initial values\n *     const stack = new Stack([1, 2, 3, 4, 5]);\n *\n *     // Verify the stack maintains insertion order (LIFO will be shown in pop)\n *     console.log([...stack]); // [1, 2, 3, 4, 5];\n *\n *     // Check length\n *     console.log(stack.size); // 5;\n *\n *     // Push a new element to the top\n *     stack.push(6);\n *     console.log(stack.size); // 6;\n   */\n\n  push(element: E): boolean {\n    this.elements.push(element);\n    return true;\n  }\n\n  /**\n   * Pop and return the top element.\n   * @remarks Time O(1), Space O(1)\n   * @returns Removed element or undefined.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Stack pop operation (LIFO - Last In First Out)\n *  const stack = new Stack<number>([10, 20, 30, 40, 50]);\n *\n *     // Peek at the top element without removing\n *     const top = stack.peek();\n *     console.log(top); // 50;\n *\n *     // Pop removes from the top (LIFO order)\n *     const popped = stack.pop();\n *     console.log(popped); // 50;\n *\n *     // Next pop gets the previous element\n *     const next = stack.pop();\n *     console.log(next); // 40;\n *\n *     // Verify length decreased\n *     console.log(stack.size); // 3;\n   */\n\n  pop(): E | undefined {\n    return this.isEmpty() ? undefined : this.elements.pop();\n  }\n\n  /**\n   * Push many elements from an iterable.\n   * @remarks Time O(N), Space O(1)\n   * @param elements - Iterable of elements (or raw records if toElementFn is set).\n   * @returns Array of per-element success flags.\n   */\n\n  pushMany(elements: Iterable<E> | Iterable<R>): boolean[] {\n    const ans: boolean[] = [];\n    for (const el of elements) {\n      if (this.toElementFn) ans.push(this.push(this.toElementFn(el as R)));\n      else ans.push(this.push(el as E));\n    }\n    return ans;\n  }\n\n  /**\n   * Delete the first occurrence of a specific element.\n   * @remarks Time O(N), Space O(1)\n   * @param element - Element to remove (using the configured equality).\n   * @returns True if an element was removed.\n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Remove element\n *  const stack = new Stack<number>([1, 2, 3]);\n *     stack.delete(2);\n *     console.log(stack.toArray()); // [1, 3];\n   */\n\n  delete(element: E): boolean {\n    const idx = this._indexOfByEquals(element);\n    return this.deleteAt(idx);\n  }\n\n  /**\n   * Delete the element at an index.\n   * @remarks Time O(N), Space O(1)\n   * @param index - Zero-based index from the bottom.\n   * @returns True if removed.\n   */\n\n  deleteAt(index: number): boolean {\n    if (index < 0 || index >= this.elements.length) return false;\n    const spliced = this.elements.splice(index, 1);\n    return spliced.length === 1;\n  }\n\n  /**\n   * Delete the first element that satisfies a predicate.\n   * @remarks Time O(N), Space O(1)\n   * @param predicate - Function (value, index, stack) → boolean to decide deletion.\n   * @returns True if a match was removed.\n   */\n\n  deleteWhere(predicate: (value: E, index: number, stack: this) => boolean): boolean {\n    for (let i = 0; i < this.elements.length; i++) {\n      if (predicate(this.elements[i], i, this)) {\n        this.elements.splice(i, 1);\n        return true;\n      }\n    }\n    return false;\n  }\n\n  /**\n   * Remove all elements and reset storage.\n   * @remarks Time O(1), Space O(1)\n   * @returns void\n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Remove all elements\n *  const stack = new Stack<number>([1, 2, 3]);\n *     stack.clear();\n *     console.log(stack.isEmpty()); // true;\n   */\n\n  clear(): void {\n    this._elements = [];\n  }\n\n  /**\n   * Deep clone this stack.\n   * @remarks Time O(N), Space O(N)\n   * @returns A new stack with the same content.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Create independent copy\n *  const stack = new Stack<number>([1, 2, 3]);\n *     const copy = stack.clone();\n *     copy.pop();\n *     console.log(stack.size); // 3;\n *     console.log(copy.size); // 2;\n   */\n\n  clone(): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    for (const v of this) out.push(v);\n    return out;\n  }\n\n  /**\n   * Filter elements into a new stack of the same class.\n   * @remarks Time O(N), Space O(N)\n   * @param predicate - Predicate (value, index, stack) → boolean to keep value.\n   * @param [thisArg] - Value for `this` inside the predicate.\n   * @returns A new stack with kept values.\n   \n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Filter elements\n *  const stack = new Stack<number>([1, 2, 3, 4, 5]);\n *     const evens = stack.filter(x => x % 2 === 0);\n *     console.log(evens.toArray()); // [2, 4];\n   */\n\n  filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    let index = 0;\n    for (const v of this) {\n      if (predicate.call(thisArg, v, index, this)) out.push(v);\n      index++;\n    }\n    return out;\n  }\n\n  /**\n   * Map values into a new stack of the same element type.\n   * @remarks Time O(N), Space O(N)\n   * @param callback - Mapping function (value, index, stack) → newValue.\n   * @param [thisArg] - Value for `this` inside the callback.\n   * @returns A new stack with mapped values.\n   */\n\n  mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this {\n    const out = this._createInstance({ toElementFn: this.toElementFn });\n    let index = 0;\n    for (const v of this) {\n      const mv = thisArg === undefined ? callback(v, index++, this) : callback.call(thisArg, v, index++, this);\n      out.push(mv);\n    }\n    return out;\n  }\n\n  /**\n   * Map values into a new stack (possibly different element type).\n   * @remarks Time O(N), Space O(N)\n   * @template EM\n   * @template RM\n   * @param callback - Mapping function (value, index, stack) → newElement.\n   * @param [options] - Options for the output stack (e.g., toElementFn).\n   * @param [thisArg] - Value for `this` inside the callback.\n   * @returns A new Stack with mapped elements.\n   \n   \n   \n   \n   \n   \n   \n   \n    * @example\n * // Transform elements\n *  const stack = new Stack<number>([1, 2, 3]);\n *     const doubled = stack.map(x => x * 2);\n *     console.log(doubled.toArray()); // [2, 4, 6];\n   */\n\n  map<EM, RM>(\n    callback: ElementCallback<E, R, EM>,\n    options?: IterableElementBaseOptions<EM, RM>,\n    thisArg?: unknown\n  ): Stack<EM, RM> {\n    const out = this._createLike<EM, RM>([], { ...(options ?? {}) });\n    let index = 0;\n    for (const v of this) {\n      out.push(thisArg === undefined ? callback(v, index, this) : callback.call(thisArg, v, index, this));\n      index++;\n    }\n    return out;\n  }\n\n  /**\n   * Set the equality comparator used by delete/search operations.\n   * @remarks Time O(1), Space O(1)\n   * @param equals - Equality predicate (a, b) → boolean.\n   * @returns This stack.\n   */\n\n  setEquality(equals: (a: E, b: E) => boolean): this {\n    this._equals = equals;\n    return this;\n  }\n\n  /**\n   * (Protected) Find the index of a target element using the equality function.\n   * @remarks Time O(N), Space O(1)\n   * @param target - Element to search for.\n   * @returns Index or -1 if not found.\n   */\n\n  protected _indexOfByEquals(target: E): number {\n    for (let i = 0; i < this.elements.length; i++) if (this._equals(this.elements[i], target)) return i;\n    return -1;\n  }\n\n  /**\n   * (Protected) Create an empty instance of the same concrete class.\n   * @remarks Time O(1), Space O(1)\n   * @param [options] - Options forwarded to the constructor.\n   * @returns An empty like-kind stack instance.\n   */\n\n  protected _createInstance(options?: StackOptions<E, R>): this {\n    const Ctor = this.constructor as new (elements?: Iterable<E> | Iterable<R>, options?: StackOptions<E, R>) => this;\n    return new Ctor([], options);\n  }\n\n  /**\n   * (Protected) Create a like-kind stack and seed it from an iterable.\n   * @remarks Time O(N), Space O(N)\n   * @template T\n   * @template RR\n   * @param [elements] - Iterable used to seed the new stack.\n   * @param [options] - Options forwarded to the constructor.\n   * @returns A like-kind Stack instance.\n   */\n\n  protected _createLike<T = E, RR = R>(\n    elements: Iterable<T> | Iterable<RR> = [],\n    options?: StackOptions<T, RR>\n  ): Stack<T, RR> {\n    const Ctor = this.constructor as new (\n      elements?: Iterable<T> | Iterable<RR>,\n      options?: StackOptions<T, RR>\n    ) => Stack<T, RR>;\n    return new Ctor(elements, options);\n  }\n\n  /**\n   * (Protected) Iterate elements from bottom to top.\n   * @remarks Time O(N), Space O(1)\n   * @returns Iterator of elements.\n   */\n\n  protected *_getIterator(): IterableIterator<E> {\n    for (let i = 0; i < this.elements.length; i++) yield this.elements[i];\n  }\n}\n","/**\n * Centralized error message templates.\n * Keep using native Error/TypeError/RangeError — this only standardizes messages.\n */\nexport const ERR = {\n  // Range / index\n  indexOutOfRange: (index: number, min: number, max: number, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Index ${index} is out of range [${min}, ${max}].`,\n\n  invalidIndex: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Index must be an integer.`,\n\n  // Type / argument\n  invalidArgument: (reason: string, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}${reason}`,\n\n  comparatorRequired: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Comparator is required for non-number/non-string/non-Date keys.`,\n\n  invalidKey: (reason: string, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}${reason}`,\n\n  notAFunction: (name: string, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}${name} must be a function.`,\n\n  invalidEntry: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Each entry must be a [key, value] tuple.`,\n\n  invalidNaN: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}NaN is not a valid key.`,\n\n  invalidDate: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Invalid Date key.`,\n\n  reduceEmpty: (ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Reduce of empty structure with no initial value.`,\n\n  callbackReturnType: (expected: string, got: string, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}Callback must return ${expected}; got ${got}.`,\n\n  // State / operation\n  invalidOperation: (reason: string, ctx?: string) =>\n    `${ctx ? ctx + ': ' : ''}${reason}`,\n\n  // Matrix\n  matrixDimensionMismatch: (op: string) =>\n    `Matrix: Dimensions must be compatible for ${op}.`,\n\n  matrixSingular: () =>\n    'Matrix: Singular matrix, inverse does not exist.',\n\n  matrixNotSquare: () =>\n    'Matrix: Must be square for inversion.',\n\n  matrixNotRectangular: () =>\n    'Matrix: Must be rectangular for transposition.',\n\n  matrixRowMismatch: (expected: number, got: number) =>\n    `Matrix: Expected row length ${expected}, but got ${got}.`\n} as const;\n","export { ERR } from './error';\n\nexport enum DFSOperation {\n  VISIT = 0,\n  PROCESS = 1\n}\n\nexport class Range<K> {\n  constructor(\n    public low: K,\n    public high: K,\n    public includeLow: boolean = true,\n    public includeHigh: boolean = true\n  ) {\n    // if (!(isComparable(low) && isComparable(high))) throw new RangeError('low or high is not comparable');\n    // if (low > high) throw new RangeError('low must be less than or equal to high');\n  }\n\n  // Determine whether a key is within the range\n  isInRange(key: K, comparator: (a: K, b: K) => number): boolean {\n    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;\n    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;\n    return lowCheck && highCheck;\n  }\n}\n"]}