data-structure-typed 2.5.0 → 2.5.2

package/dist/esm/stack.mjs

@@ -0,0 +1,905 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/common/error.ts
+function raise(ErrorClass, message) {
+  throw new ErrorClass(message);
+}
+__name(raise, "raise");
+
+// src/data-structures/base/iterable-element-base.ts
+var IterableElementBase = class {
+  static {
+    __name(this, "IterableElementBase");
+  }
+  /**
+   * Create a new iterable base.
+   *
+   * @param options Optional behavior overrides. When provided, a `toElementFn`
+   * is used to convert a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  constructor(options) {
+    if (options) {
+      const { toElementFn } = options;
+      if (typeof toElementFn === "function") this._toElementFn = toElementFn;
+      else if (toElementFn) raise(TypeError, "toElementFn must be a function type");
+    }
+  }
+  /**
+   * The converter used to transform a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  _toElementFn;
+  /**
+   * Exposes the current `toElementFn`, if configured.
+   *
+   * @returns The converter function or `undefined` when not set.
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  get toElementFn() {
+    return this._toElementFn;
+  }
+  /**
+   * Returns an iterator over the structure's elements.
+   *
+   * @param args Optional iterator arguments forwarded to the internal iterator.
+   * @returns An `IterableIterator<E>` that yields the elements in traversal order.
+   *
+   * @remarks
+   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Returns an iterator over the values (alias of the default iterator).
+   *
+   * @returns An `IterableIterator<E>` over all elements.
+   * @remarks
+   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
+   */
+  *values() {
+    for (const item of this) yield item;
+  }
+  /**
+   * Tests whether all elements satisfy the predicate.
+   *
+   * @template TReturn
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if every element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (!predicate(item, index++, this)) return false;
+      } else {
+        const fn = predicate;
+        if (!fn.call(thisArg, item, index++, this)) return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Tests whether at least one element satisfies the predicate.
+   *
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if any element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early on first success. Space O(1).
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return true;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Invokes a callback for each element in iteration order.
+   *
+   * @param callbackfn Function invoked per element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the callback.
+   * @returns `void`.
+   *
+   * @remarks
+   * Time O(n), Space O(1).
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        callbackfn(item, index++, this);
+      } else {
+        const fn = callbackfn;
+        fn.call(thisArg, item, index++, this);
+      }
+    }
+  }
+  // Implementation signature
+  find(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return item;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return item;
+      }
+    }
+    return;
+  }
+  /**
+   * Checks whether a strictly-equal element exists in the structure.
+   *
+   * @param element The element to test with `===` equality.
+   * @returns `true` if an equal element is found; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case. Space O(1).
+   */
+  has(element) {
+    for (const ele of this) if (ele === element) return true;
+    return false;
+  }
+  /**
+   * Reduces all elements to a single accumulated value.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.
+   * @param initialValue The initial accumulator value of type `E`.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @template U The accumulator type when it differs from `E`.
+   * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.
+   * @param initialValue The initial accumulator value of type `U`.
+   * @returns The final accumulated value typed as `U`.
+   *
+   * @remarks
+   * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
+   */
+  reduce(callbackfn, initialValue) {
+    let index = 0;
+    const iter = this[Symbol.iterator]();
+    let acc;
+    if (arguments.length >= 2) {
+      acc = initialValue;
+    } else {
+      const first = iter.next();
+      if (first.done) raise(TypeError, "Reduce of empty structure with no initial value");
+      acc = first.value;
+      index = 1;
+    }
+    for (const value of iter) {
+      acc = callbackfn(acc, value, index++, this);
+    }
+    return acc;
+  }
+  /**
+   * Materializes the elements into a new array.
+   *
+   * @returns A shallow array copy of the iteration order.
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Returns a representation of the structure suitable for quick visualization.
+   * Defaults to an array of elements; subclasses may override to provide richer visuals.
+   *
+   * @returns A visual representation (array by default).
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Prints `toVisual()` to the console. Intended for quick debugging.
+   *
+   * @returns `void`.
+   * @remarks
+   * Time O(n) due to materialization, Space O(n) for the intermediate representation.
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+
+// src/data-structures/stack/stack.ts
+var Stack = class extends IterableElementBase {
+  static {
+    __name(this, "Stack");
+  }
+  _equals = /* @__PURE__ */ __name((a, b) => Object.is(a, b), "_equals");
+  /**
+   * Create a Stack and optionally bulk-push elements.
+   * @remarks Time O(N), Space O(N)
+   * @param [elements] - Iterable of elements (or raw records if toElementFn is set).
+   * @param [options] - Options such as toElementFn and equality function.
+   * @returns New Stack instance.
+   */
+  constructor(elements = [], options) {
+    super(options);
+    this.pushMany(elements);
+  }
+  _elements = [];
+  /**
+   * Get the backing array of elements.
+   * @remarks Time O(1), Space O(1)
+   * @returns Internal elements array.
+   */
+  get elements() {
+    return this._elements;
+  }
+  /**
+    * 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;
+  }
+  /**
+   * Create a stack from an array of elements.
+   * @remarks Time O(N), Space O(N)
+   * @template E
+   * @template R
+   * @param this - The constructor (subclass) to instantiate.
+   * @param elements - Array of elements to push in order.
+   * @param [options] - Options forwarded to the constructor.
+   * @returns A new Stack populated from the array.
+   */
+  static fromArray(elements, options) {
+    return new this(elements, options);
+  }
+  /**
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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();
+  }
+  /**
+   * Push many elements from an iterable.
+   * @remarks Time O(N), Space O(1)
+   * @param elements - Iterable of elements (or raw records if toElementFn is set).
+   * @returns Array of per-element success flags.
+   */
+  pushMany(elements) {
+    const ans = [];
+    for (const el of elements) {
+      if (this.toElementFn) ans.push(this.push(this.toElementFn(el)));
+      else ans.push(this.push(el));
+    }
+    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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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);
+  }
+  /**
+   * Delete the element at an index.
+   * @remarks Time O(N), Space O(1)
+   * @param index - Zero-based index from the bottom.
+   * @returns True if removed.
+   */
+  deleteAt(index) {
+    if (index < 0 || index >= this.elements.length) return false;
+    const spliced = this.elements.splice(index, 1);
+    return spliced.length === 1;
+  }
+  /**
+   * Delete the first element that satisfies a predicate.
+   * @remarks Time O(N), Space O(1)
+   * @param predicate - Function (value, index, stack) → boolean to decide deletion.
+   * @returns True if a match was removed.
+   */
+  deleteWhere(predicate) {
+    for (let i = 0; i < this.elements.length; i++) {
+      if (predicate(this.elements[i], i, this)) {
+        this.elements.splice(i, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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;
+    for (const v of this) {
+      if (predicate.call(thisArg, v, index, this)) out.push(v);
+      index++;
+    }
+    return out;
+  }
+  /**
+   * Map values into a new stack of the same element type.
+   * @remarks Time O(N), Space O(N)
+   * @param callback - Mapping function (value, index, stack) → newValue.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new stack with mapped values.
+   */
+  mapSame(callback, thisArg) {
+    const out = this._createInstance({ toElementFn: this.toElementFn });
+    let index = 0;
+    for (const v of this) {
+      const mv = thisArg === void 0 ? callback(v, index++, this) : callback.call(thisArg, v, index++, this);
+      out.push(mv);
+    }
+    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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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;
+    for (const v of this) {
+      out.push(thisArg === void 0 ? callback(v, index, this) : callback.call(thisArg, v, index, this));
+      index++;
+    }
+    return out;
+  }
+  /**
+   * Set the equality comparator used by delete/search operations.
+   * @remarks Time O(1), Space O(1)
+   * @param equals - Equality predicate (a, b) → boolean.
+   * @returns This stack.
+   */
+  setEquality(equals) {
+    this._equals = equals;
+    return this;
+  }
+  /**
+   * (Protected) Find the index of a target element using the equality function.
+   * @remarks Time O(N), Space O(1)
+   * @param target - Element to search for.
+   * @returns Index or -1 if not found.
+   */
+  _indexOfByEquals(target) {
+    for (let i = 0; i < this.elements.length; i++) if (this._equals(this.elements[i], target)) return i;
+    return -1;
+  }
+  /**
+   * (Protected) Create an empty instance of the same concrete class.
+   * @remarks Time O(1), Space O(1)
+   * @param [options] - Options forwarded to the constructor.
+   * @returns An empty like-kind stack instance.
+   */
+  _createInstance(options) {
+    const Ctor = this.constructor;
+    return new Ctor([], options);
+  }
+  /**
+   * (Protected) Create a like-kind stack and seed it from an iterable.
+   * @remarks Time O(N), Space O(N)
+   * @template T
+   * @template RR
+   * @param [elements] - Iterable used to seed the new stack.
+   * @param [options] - Options forwarded to the constructor.
+   * @returns A like-kind Stack instance.
+   */
+  _createLike(elements = [], options) {
+    const Ctor = this.constructor;
+    return new Ctor(elements, options);
+  }
+  /**
+   * (Protected) Iterate elements from bottom to top.
+   * @remarks Time O(N), Space O(1)
+   * @returns Iterator of elements.
+   */
+  *_getIterator() {
+    for (let i = 0; i < this.elements.length; i++) yield this.elements[i];
+  }
+};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+export { Stack };
+//# sourceMappingURL=stack.mjs.map
+//# sourceMappingURL=stack.mjs.map