trie-typed
Version:
Trie, prefix tree
220 lines (219 loc) • 8.86 kB
TypeScript
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> {
/**
* 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;
/**
* 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: unknown[]): IterableIterator<E>;
/**
* 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(): IterableIterator<E>;
/**
* 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;
/**
* Materializes the elements into a new array.
*
* @returns A shallow array copy of the iteration order.
* @remarks
* Time O(n), Space O(n).
*/
toArray(): E[];
/**
* 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(): E[];
/**
* 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(): 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;
/**
* 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>;
}