stack-typed 2.0.5 → 2.1.0

package/dist/data-structures/base/iterable-element-base.d.ts

@@ -1,116 +1,219 @@
-import { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';
-export declare abstract class IterableElementBase<E, R> {
+import type { ElementCallback, IterableElementBaseOptions, ReduceElementCallback } from '../../types';
+/**
+ * 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 declare 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>);
+    /**
+     * 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;
     /**
-     * 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>;
     /**
-     * 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>;
     /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * 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.
-     */
-    every(predicate: ElementCallback<E, R, boolean>, thisArg?: any): boolean;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * 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.
-     */
-    some(predicate: ElementCallback<E, R, boolean>, thisArg?: any): boolean;
-    /**
-     * Time Complexity: O(n)
-     * Space Complexity: O(1)
-     *
-     * 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
-     */
-    forEach(callbackfn: ElementCallback<E, R, void>, thisArg?: any): void;
-    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)
-     *
-     * 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.
+     * 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: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean;
+    /**
+     * 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: ElementCallback<E, R, boolean>, thisArg?: unknown): boolean;
+    /**
+     * 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: ElementCallback<E, R, void>, thisArg?: unknown): void;
+    /**
+     * 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.
+     *
+     * @remarks
+     * Time O(n) in the worst case; may exit early on the first match. Space O(1).
+     */
+    find<S extends E>(predicate: ElementCallback<E, R, S>, thisArg?: unknown): S | undefined;
+    find(predicate: ElementCallback<E, R, unknown>, thisArg?: unknown): E | undefined;
+    /**
+     * 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: E): boolean;
     reduce(callbackfn: ReduceElementCallback<E, R>): E;
     reduce(callbackfn: ReduceElementCallback<E, R>, initialValue: E): E;
     reduce<U>(callbackfn: ReduceElementCallback<E, R, U>, initialValue: U): U;
     /**
-     * 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[];
     /**
-     * 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[];
     /**
-     * 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;
+    /**
+     * 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>;
-    abstract map(...args: any[]): any;
-    abstract filter(...args: any[]): any;
-    protected abstract _getIterator(...args: any[]): IterableIterator<E>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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>;
 }