graph-typed 2.0.4 → 2.1.0

package/src/data-structures/base/iterable-element-base.ts

@@ -1,10 +1,25 @@
-import { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';
+import type { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';
 
-export abstract class IterableElementBase<E, R> {
+/**
+ * Base class that makes a data structure iterable and provides common
+ * element-wise utilities (e.g., map/filter/reduce/find).
+ *
+ * @template E The public element type yielded by the structure.
+ * @template R The underlying "raw" element type used internally or by converters.
+ *
+ * @remarks
+ * This class implements the JavaScript iteration protocol (via `Symbol.iterator`)
+ * and offers array-like helpers with predictable time/space complexity.
+ */
+export abstract class IterableElementBase<E, R> implements Iterable<E> {
   /**
-   * The protected constructor initializes the options for the IterableElementBase class, including the
-   * toElementFn function.
-   * @param [options] - An optional object that contains the following properties:
+   * 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).
    */
   protected constructor(options?: IterableElementBaseOptions<E, R>) {
     if (options) {
@@ -14,147 +29,164 @@ export abstract class IterableElementBase<E, R> {
     }
   }
 
+  /**
+   * The converter used to transform a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
   protected _toElementFn?: (rawElement: R) => E;
 
+  /**
+   * Exposes the current `toElementFn`, if configured.
+   *
+   * @returns The converter function or `undefined` when not set.
+   * @remarks
+   * Time O(1), Space O(1).
+   */
   get toElementFn(): ((rawElement: R) => E) | undefined {
     return this._toElementFn;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * 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.
    *
-   * The function is an implementation of the Symbol.iterator method that returns an IterableIterator.
-   * @param {any[]} args - The `args` parameter in the code snippet represents a rest parameter. It
-   * allows the function to accept any number of arguments as an array. In this case, the `args`
-   * parameter is used to pass any number of arguments to the `_getIterator` method.
+   * @remarks
+   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
    */
-  *[Symbol.iterator](...args: any[]): IterableIterator<E> {
+  *[Symbol.iterator](...args: unknown[]): IterableIterator<E> {
     yield* this._getIterator(...args);
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Returns an iterator over the values (alias of the default iterator).
    *
-   * The function returns an iterator that yields all the values in the object.
+   * @returns An `IterableIterator<E>` over all elements.
+   * @remarks
+   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
    */
   *values(): IterableIterator<E> {
-    for (const item of this) {
-      yield item;
-    }
+    for (const item of this) yield item;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Tests whether all elements satisfy the predicate.
    *
-   * The `every` function checks if every element in the array satisfies a given predicate.
-   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-   * the current element being processed, its index, and the array it belongs to. It should return a
-   * boolean value indicating whether the element satisfies a certain condition or not.
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `predicate` function. If `thisArg` is provided, it will be
-   * passed as the `this` value to the `predicate` function. If `thisArg` is
-   * @returns The `every` method is returning a boolean value. It returns `true` if every element in
-   * the array satisfies the provided predicate function, and `false` otherwise.
+   * @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: ElementCallback<E, R, boolean>, thisArg?: any): boolean {
+  every(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {
     let index = 0;
     for (const item of this) {
-      if (!predicate.call(thisArg, item, index++, this)) {
-        return false;
+      if (thisArg === undefined) {
+        if (!predicate(item, index++, this)) return false;
+      } else {
+        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;
+        if (!fn.call(thisArg, item, index++, this)) return false;
       }
     }
     return true;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * 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`.
    *
-   * The "some" function checks if at least one element in a collection satisfies a given predicate.
-   * @param predicate - The `predicate` parameter is a callback function that takes three arguments:
-   * `value`, `index`, and `array`. It should return a boolean value indicating whether the current
-   * element satisfies the condition.
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as the `this` value when executing the `predicate` function. If `thisArg` is provided,
-   * it will be passed as the `this` value to the `predicate` function. If `thisArg
-   * @returns a boolean value. It returns true if the predicate function returns true for any element
-   * in the collection, and false otherwise.
+   * @remarks
+   * Time O(n) in the worst case; may exit early on first success. Space O(1).
    */
-  some(predicate: ElementCallback<E, R, boolean>, thisArg?: any): boolean {
+  some(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean {
     let index = 0;
     for (const item of this) {
-      if (predicate.call(thisArg, item, index++, this)) {
-        return true;
+      if (thisArg === undefined) {
+        if (predicate(item, index++, this)) return true;
+      } else {
+        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;
+        if (fn.call(thisArg, item, index++, this)) return true;
       }
     }
     return false;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * 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`.
    *
-   * The `forEach` function iterates over each element in an array-like object and calls a callback
-   * function for each element.
-   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
-   * the array. It takes three arguments: the current element being processed, the index of the current
-   * element, and the array that forEach was called upon.
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
-   * be passed as the `this` value to the `callbackfn` function. If `thisArg
+   * @remarks
+   * Time O(n), Space O(1).
    */
-  forEach(callbackfn: ElementCallback<E, R, void>, thisArg?: any): void {
+  forEach(callbackfn: ElementCallback<E, R, void>, thisArg?: unknown): void {
     let index = 0;
     for (const item of this) {
-      callbackfn.call(thisArg, item, index++, this);
+      if (thisArg === undefined) {
+        callbackfn(item, index++, this);
+      } else {
+        const fn = callbackfn as (this: unknown, v: E, i: number, self: this) => void;
+        fn.call(thisArg, item, index++, this);
+      }
     }
   }
 
-  find<S extends E>(predicate: ElementCallback<E, R, S>, thisArg?: any): S | undefined;
-  find(predicate: ElementCallback<E, R, unknown>, thisArg?: any): E | undefined;
-
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Finds the first element that satisfies the predicate and returns it.
+   *
+   * @overload
+   * Finds the first element of type `S` (a subtype of `E`) that satisfies the predicate and returns it.
+   * @template S
+   * @param predicate Type-guard predicate: `(value, index, self) => value is S`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns The matched element typed as `S`, or `undefined` if not found.
+   *
+   * @overload
+   * @param predicate Boolean predicate: `(value, index, self) => boolean`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns The first matching element as `E`, or `undefined` if not found.
    *
-   * The `find` function iterates over the elements of an array-like object and returns the first
-   * element that satisfies the provided callback function.
-   * @param predicate - The predicate parameter is a function that will be called for each element in
-   * the array. It takes three arguments: the current element being processed, the index of the current
-   * element, and the array itself. The function should return a boolean value indicating whether the
-   * current element matches the desired condition.
-   * @param {any} [thisArg] - The `thisArg` parameter is an optional argument that specifies the value
-   * to be used as `this` when executing the `callbackfn` function. If `thisArg` is provided, it will
-   * be passed as the `this` value to the `callbackfn` function. If `thisArg
-   * @returns The `find` method returns the first element in the array that satisfies the provided
-   * callback function. If no element satisfies the callback function, `undefined` is returned.
+   * @remarks
+   * Time O(n) in the worst case; may exit early on the first match. Space O(1).
    */
-  find(predicate: ElementCallback<E, R, boolean>, thisArg?: any): E | undefined {
+  find<S extends E>(predicate: ElementCallback<E, R, S>, thisArg?: unknown): S | undefined;
+  find(predicate: ElementCallback<E, R, unknown>, thisArg?: unknown): E | undefined;
+
+  // Implementation signature
+  find(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): E | undefined {
     let index = 0;
     for (const item of this) {
-      if (predicate.call(thisArg, item, index++, this)) return item;
+      if (thisArg === undefined) {
+        if (predicate(item, index++, this)) return item;
+      } else {
+        const fn = predicate as (this: unknown, v: E, i: number, self: this) => boolean;
+        if (fn.call(thisArg, item, index++, this)) return item;
+      }
     }
-
     return;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * Checks whether a strictly-equal element exists in the structure.
    *
-   * The function checks if a given element exists in a collection.
-   * @param {E} element - The parameter "element" is of type E, which means it can be any type. It
-   * represents the element that we want to check for existence in the collection.
-   * @returns a boolean value. It returns true if the element is found in the collection, and false
-   * otherwise.
+   * @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: E): boolean {
-    for (const ele of this) {
-      if (ele === element) return true;
-    }
+    for (const ele of this) if (ele === element) return true;
     return false;
   }
 
@@ -163,67 +195,158 @@ export abstract class IterableElementBase<E, R> {
   reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue: U): U;
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(1)
+   * 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`.
    *
-   * The `reduce` function iterates over the elements of an array-like object and applies a callback
-   * function to reduce them into a single value.
-   * @param callbackfn - The callbackfn parameter is a function that will be called for each element in
-   * the array. It takes four arguments:
-   * @param {U} initialValue - The initialValue parameter is the initial value of the accumulator. It
-   * is the value that the accumulator starts with before the reduction operation begins.
-   * @returns The `reduce` method is returning the final value of the accumulator after iterating over
-   * all the elements in the array and applying the callback function to each element.
+   * @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<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue?: U): U {
-    let accumulator = initialValue ?? (0 as U);
     let index = 0;
-    for (const item of this) {
-      accumulator = callbackfn(accumulator, item, index++, this);
+    const iter = this[Symbol.iterator]();
+    let acc: U;
+
+    if (arguments.length >= 2) {
+      acc = initialValue as U;
+    } else {
+      const first = iter.next();
+      if (first.done) throw new TypeError('Reduce of empty structure with no initial value');
+      acc = first.value as unknown as U;
+      index = 1;
     }
-    return accumulator;
+
+    for (const value of iter as unknown as Iterable<E>) {
+      acc = callbackfn(acc, value, index++, this);
+    }
+    return acc;
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Materializes the elements into a new array.
    *
-   * The `toArray` function converts a linked list into an array.
-   * @returns The `toArray()` method is returning an array of type `E[]`.
+   * @returns A shallow array copy of the iteration order.
+   * @remarks
+   * Time O(n), Space O(n).
    */
   toArray(): E[] {
     return [...this];
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Returns a representation of the structure suitable for quick visualization.
+   * Defaults to an array of elements; subclasses may override to provide richer visuals.
    *
-   * The print function logs the elements of an array to the console.
+   * @returns A visual representation (array by default).
+   * @remarks
+   * Time O(n), Space O(n).
    */
   toVisual(): E[] {
     return [...this];
   }
 
   /**
-   * Time Complexity: O(n)
-   * Space Complexity: O(n)
+   * Prints `toVisual()` to the console. Intended for quick debugging.
    *
-   * The print function logs the elements of an array to the console.
+   * @returns `void`.
+   * @remarks
+   * Time O(n) due to materialization, Space O(n) for the intermediate representation.
    */
   print(): void {
     console.log(this.toVisual());
   }
 
+  /**
+   * Indicates whether the structure currently contains no elements.
+   *
+   * @returns `true` if empty; otherwise `false`.
+   * @remarks
+   * Expected Time O(1), Space O(1) for most implementations.
+   */
   abstract isEmpty(): boolean;
 
+  /**
+   * Removes all elements from the structure.
+   *
+   * @returns `void`.
+   * @remarks
+   * Expected Time O(1) or O(n) depending on the implementation; Space O(1).
+   */
   abstract clear(): void;
 
-  abstract clone(): IterableElementBase<E, R>;
+  /**
+   * Creates a structural copy with the same element values and configuration.
+   *
+   * @returns A clone of the current instance (same concrete type).
+   * @remarks
+   * Expected Time O(n) to copy elements; Space O(n).
+   */
+  abstract clone(): this;
+
+  /**
+   * Maps each element to a new element and returns a new iterable structure.
+   *
+   * @template EM The mapped element type.
+   * @template RM The mapped raw element type used internally by the target structure.
+   * @param callback Function with signature `(value, index, self) => mapped`.
+   * @param options Optional options for the returned structure, including its `toElementFn`.
+   * @param thisArg Optional `this` binding for the callback.
+   * @returns A new `IterableElementBase<EM, RM>` containing mapped elements.
+   *
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  abstract map<EM, RM>(
+    callback: ElementCallback<E, R, EM>,
+    options?: IterableElementBaseOptions<EM, RM>,
+    thisArg?: unknown
+  ): IterableElementBase<EM, RM>;
 
-  abstract map(...args: any[]): any;
+  /**
+   * Maps each element to the same element type and returns the same concrete structure type.
+   *
+   * @param callback Function with signature `(value, index, self) => mappedValue`.
+   * @param thisArg Optional `this` binding for the callback.
+   * @returns A new instance of the same concrete type with mapped elements.
+   *
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  abstract mapSame(callback: ElementCallback<E, R, E>, thisArg?: unknown): this;
 
-  abstract filter(...args: any[]): any;
+  /**
+   * Filters elements using the provided predicate and returns the same concrete structure type.
+   *
+   * @param predicate Function with signature `(value, index, self) => boolean`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns A new instance of the same concrete type containing only elements that pass the predicate.
+   *
+   * @remarks
+   * Time O(n), Space O(k) where `k` is the number of kept elements.
+   */
+  abstract filter(predicate: ElementCallback<E, R, boolean>, thisArg?: unknown): this;
 
-  protected abstract _getIterator(...args: any[]): IterableIterator<E>;
+  /**
+   * Internal iterator factory used by the default iterator.
+   *
+   * @param args Optional iterator arguments.
+   * @returns An iterator over elements.
+   *
+   * @remarks
+   * Implementations should yield in O(1) per element with O(1) extra space when possible.
+   */
+  protected abstract _getIterator(...args: unknown[]): IterableIterator<E>;
 }