data-structure-typed 2.0.5 → 2.1.1

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

@@ -0,0 +1,219 @@
+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>;
+}

package/dist/types/data-structures/base/iterable-entry-base.d.ts

@@ -0,0 +1,144 @@
+import type { EntryCallback, ReduceEntryCallback } from '../../types';
+/**
+ * Iterable view over key-value entries.
+ * @template K - Key type.
+ * @template V - Value type.
+ * @remarks Time O(1), Space O(1)
+ */
+export declare abstract class IterableEntryBase<K = any, V = any> {
+    /**
+     * Total number of entries.
+     * @returns Entry count.
+     * @remarks Time O(1), Space O(1)
+     */
+    abstract get size(): number;
+    /**
+     * Default iterator yielding `[key, value]` entries.
+     * @returns Iterator of `[K, V]`.
+     * @remarks Time O(n) to iterate, Space O(1)
+     */
+    [Symbol.iterator](...args: any[]): IterableIterator<[K, V]>;
+    /**
+     * Iterate over `[key, value]` pairs (may yield `undefined` values).
+     * @returns Iterator of `[K, V | undefined]`.
+     * @remarks Time O(n), Space O(1)
+     */
+    entries(): IterableIterator<[K, V | undefined]>;
+    /**
+     * Iterate over keys only.
+     * @returns Iterator of keys.
+     * @remarks Time O(n), Space O(1)
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Iterate over values only.
+     * @returns Iterator of values.
+     * @remarks Time O(n), Space O(1)
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Test whether all entries satisfy the predicate.
+     * @param predicate - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns `true` if all pass; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
+     */
+    every(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean;
+    /**
+     * Test whether any entry satisfies the predicate.
+     * @param predicate - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns `true` if any passes; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
+     */
+    some(predicate: EntryCallback<K, V, boolean>, thisArg?: any): boolean;
+    /**
+     * Visit each entry, left-to-right.
+     * @param callbackfn - `(key, value, index, self) => void`.
+     * @param thisArg - Optional `this` for callback.
+     * @remarks Time O(n), Space O(1)
+     */
+    forEach(callbackfn: EntryCallback<K, V, void>, thisArg?: any): void;
+    /**
+     * Find the first entry that matches a predicate.
+     * @param callbackfn - `(key, value, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns Matching `[key, value]` or `undefined`.
+     * @remarks Time O(n), Space O(1)
+     */
+    find(callbackfn: EntryCallback<K, V, boolean>, thisArg?: any): [K, V] | undefined;
+    /**
+     * Whether the given key exists.
+     * @param key - Key to test.
+     * @returns `true` if found; otherwise `false`.
+     * @remarks Time O(n) generic, Space O(1)
+     */
+    has(key: K): boolean;
+    /**
+     * Whether there exists an entry with the given value.
+     * @param value - Value to test.
+     * @returns `true` if found; otherwise `false`.
+     * @remarks Time O(n), Space O(1)
+     */
+    hasValue(value: V): boolean;
+    /**
+     * Get the value under a key.
+     * @param key - Key to look up.
+     * @returns Value or `undefined`.
+     * @remarks Time O(n) generic, Space O(1)
+     */
+    get(key: K): V | undefined;
+    /**
+     * Reduce entries into a single accumulator.
+     * @param callbackfn - `(acc, value, key, index, self) => acc`.
+     * @param initialValue - Initial accumulator.
+     * @returns Final accumulator.
+     * @remarks Time O(n), Space O(1)
+     */
+    reduce<U>(callbackfn: ReduceEntryCallback<K, V, U>, initialValue: U): U;
+    /**
+     * Visualize the iterable as an array of `[key, value]` pairs (or a custom string).
+     * @returns Array of entries (default) or a string.
+     * @remarks Time O(n), Space O(n)
+     */
+    toVisual(): [K, V][] | string;
+    /**
+     * Print a human-friendly representation to the console.
+     * @remarks Time O(n), Space O(n)
+     */
+    print(): void;
+    /**
+     * Whether there are no entries.
+     * @returns `true` if empty; `false` otherwise.
+     * @remarks Time O(1) typical, Space O(1)
+     */
+    abstract isEmpty(): boolean;
+    /**
+     * Remove all entries.
+     * @remarks Time O(n) typical, Space O(1)
+     */
+    abstract clear(): void;
+    /**
+     * Deep clone preserving the concrete subtype.
+     * @returns A new instance of the same concrete class (`this` type).
+     * @remarks Time O(n) typical, Space O(n)
+     */
+    abstract clone(): this;
+    /**
+     * Map entries using an implementation-specific strategy.
+     * @remarks Time O(n), Space O(n)
+     */
+    abstract map(...args: any[]): any;
+    /**
+     * Filter entries and return the same-species structure.
+     * @returns A new instance of the same concrete class (`this` type).
+     * @remarks Time O(n), Space O(n)
+     */
+    abstract filter(...args: any[]): this;
+    /**
+     * Underlying iterator for the default iteration protocol.
+     * @returns Iterator of `[K, V]`.
+     * @remarks Time O(n), Space O(1)
+     */
+    protected abstract _getIterator(...args: any[]): IterableIterator<[K, V]>;
+}

package/dist/types/data-structures/base/linear-base.d.ts

@@ -0,0 +1,335 @@
+import type { ElementCallback, LinearBaseOptions, ReduceLinearCallback } from '../../types';
+import { IterableElementBase } from './iterable-element-base';
+/**
+ * Singly-linked list node.
+ * @template E - Element type.
+ * @remarks Time O(1), Space O(1)
+ */
+export declare class LinkedListNode<E = any> {
+    /**
+     * Initialize a node.
+     * @param value - Element value.
+     * @remarks Time O(1), Space O(1)
+     */
+    constructor(value: E);
+    protected _value: E;
+    /**
+     * Element payload getter.
+     * @returns Element value.
+     * @remarks Time O(1), Space O(1)
+     */
+    get value(): E;
+    /**
+     * Element payload setter.
+     * @param value - New value.
+     * @remarks Time O(1), Space O(1)
+     */
+    set value(value: E);
+    protected _next: LinkedListNode<E> | undefined;
+    /**
+     * Next node getter.
+     * @returns Next node or `undefined`.
+     * @remarks Time O(1), Space O(1)
+     */
+    get next(): LinkedListNode<E> | undefined;
+    /**
+     * Next node setter.
+     * @param value - Next node or `undefined`.
+     * @remarks Time O(1), Space O(1)
+     */
+    set next(value: LinkedListNode<E> | undefined);
+}
+/**
+ * Abstract linear container with array-like utilities.
+ * @template E - Element type.
+ * @template R - Return type for mapped/derived views.
+ * @template NODE - Linked node type used by some implementations.
+ * @remarks Time O(1), Space O(1)
+ */
+export declare abstract class LinearBase<E, R = any, NODE extends LinkedListNode<E> = LinkedListNode<E>> extends IterableElementBase<E, R> {
+    /**
+     * Construct a linear container with runtime options.
+     * @param options - `{ maxLen?, ... }` bounds/behavior options.
+     * @remarks Time O(1), Space O(1)
+     */
+    protected constructor(options?: LinearBaseOptions<E, R>);
+    /**
+     * Element count.
+     * @returns Number of elements.
+     * @remarks Time O(1), Space O(1)
+     */
+    abstract get length(): number;
+    protected _maxLen: number;
+    /**
+     * Upper bound for length (if positive), or `-1` when unbounded.
+     * @returns Maximum allowed length.
+     * @remarks Time O(1), Space O(1)
+     */
+    get maxLen(): number;
+    /**
+     * First index of a value from the left.
+     * @param searchElement - Value to match.
+     * @param fromIndex - Start position (supports negative index).
+     * @returns Index or `-1` if not found.
+     * @remarks Time O(n), Space O(1)
+     */
+    indexOf(searchElement: E, fromIndex?: number): number;
+    /**
+     * Last index of a value from the right.
+     * @param searchElement - Value to match.
+     * @param fromIndex - Start position (supports negative index).
+     * @returns Index or `-1` if not found.
+     * @remarks Time O(n), Space O(1)
+     */
+    lastIndexOf(searchElement: E, fromIndex?: number): number;
+    /**
+     * Find the first index matching a predicate.
+     * @param predicate - `(element, index, self) => boolean`.
+     * @param thisArg - Optional `this` for callback.
+     * @returns Index or `-1`.
+     * @remarks Time O(n), Space O(1)
+     */
+    findIndex(predicate: ElementCallback<E, R, boolean>, thisArg?: any): number;
+    /**
+     * Concatenate multiple containers of the same species.
+     * @param items - Other lists to append.
+     * @returns New container with combined elements (`this` type).
+     * @remarks Time O(sum(length)), Space O(sum(length))
+     */
+    concat(...items: this[]): this;
+    /**
+     * In-place stable order via array sort semantics.
+     * @param compareFn - Comparator `(a, b) => number`.
+     * @returns This container.
+     * @remarks Time O(n log n), Space O(n) (materializes to array temporarily)
+     */
+    sort(compareFn?: (a: E, b: E) => number): this;
+    /**
+     * Remove and/or insert elements at a position (array-compatible).
+     * @param start - Start index (supports negative index).
+     * @param deleteCount - How many to remove.
+     * @param items - Elements to insert.
+     * @returns Removed elements as a new list (`this` type).
+     * @remarks Time O(n + m), Space O(min(n, m)) where `m = items.length`
+     */
+    splice(start: number, deleteCount?: number, ...items: E[]): this;
+    /**
+     * Join all elements into a string.
+     * @param separator - Separator string.
+     * @returns Concatenated string.
+     * @remarks Time O(n), Space O(n)
+     */
+    join(separator?: string): string;
+    /**
+     * Snapshot elements into a reversed array.
+     * @returns New reversed array.
+     * @remarks Time O(n), Space O(n)
+     */
+    toReversedArray(): E[];
+    reduceRight(callbackfn: ReduceLinearCallback<E>): E;
+    reduceRight(callbackfn: ReduceLinearCallback<E>, initialValue: E): E;
+    /**
+     * Right-to-left reduction over elements.
+     * @param callbackfn - `(acc, element, index, self) => acc`.
+     * @param initialValue - Initial accumulator (optional generic overloads supported).
+     * @returns Final accumulator.
+     * @remarks Time O(n), Space O(1)
+     */
+    reduceRight<U>(callbackfn: ReduceLinearCallback<E, U>, initialValue: U): U;
+    /**
+     * Create a shallow copy of a subrange.
+     * @param start - Inclusive start (supports negative index).
+     * @param end - Exclusive end (supports negative index).
+     * @returns New list with the range (`this` type).
+     * @remarks Time O(n), Space O(n)
+     */
+    slice(start?: number, end?: number): this;
+    /**
+     * Fill a range with a value.
+     * @param value - Value to set.
+     * @param start - Inclusive start.
+     * @param end - Exclusive end.
+     * @returns This list.
+     * @remarks Time O(n), Space O(1)
+     */
+    fill(value: E, start?: number, end?: number): this;
+    /**
+     * Set the value at an index.
+     * @param index - Position (0-based).
+     * @param value - New value.
+     * @returns `true` if updated.
+     * @remarks Time O(1) typical, Space O(1)
+     */
+    abstract setAt(index: number, value: E): boolean;
+    /**
+     * Deep clone while preserving concrete subtype.
+     * @returns New list of the same species (`this` type).
+     * @remarks Time O(n), Space O(n)
+     */
+    abstract clone(): this;
+    /**
+     * Reverse the order of elements in-place (or equivalent).
+     * @returns This list.
+     * @remarks Time O(n), Space O(1)
+     */
+    abstract reverse(): this;
+    /**
+     * Append one element or node to the tail.
+     * @param elementOrNode - Element or node.
+     * @returns `true` if appended.
+     * @remarks Time O(1) amortized typical, Space O(1)
+     */
+    abstract push(elementOrNode: E | NODE): boolean;
+    /**
+     * Append many elements/nodes at once.
+     * @param elements - Iterable of elements or nodes.
+     * @returns Array of booleans indicating append success.
+     * @remarks Time O(n), Space O(1)
+     */
+    abstract pushMany(elements: Iterable<E> | Iterable<R> | Iterable<NODE>): boolean[];
+    /**
+     * Remove one element or node if present.
+     * @param elementOrNode - Element or node to delete.
+     * @returns `true` if removed.
+     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
+     */
+    abstract delete(elementOrNode: E | NODE | undefined): boolean;
+    /**
+     * Get element at an index.
+     * @param index - Position (0-based).
+     * @returns Element or `undefined`.
+     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
+     */
+    abstract at(index: number): E | undefined;
+    /**
+     * Remove element at a position.
+     * @param pos - Position (0-based).
+     * @returns Removed element or `undefined`.
+     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
+     */
+    abstract deleteAt(pos: number): E | undefined;
+    /**
+     * Insert an element/node at a position.
+     * @param index - Position (0-based).
+     * @param newElementOrNode - Element or node to insert.
+     * @returns `true` if inserted.
+     * @remarks Time O(1)~O(n) depending on implementation, Space O(1)
+     */
+    abstract addAt(index: number, newElementOrNode: E | NODE): boolean;
+    /**
+     * Create an empty list of the same species.
+     * @param options - Runtime options to carry.
+     * @returns Empty list (`this` type).
+     * @remarks Time O(1), Space O(1)
+     */
+    protected abstract _createInstance(options?: LinearBaseOptions<E, R>): this;
+    /**
+     * Reverse-direction iterator over elements.
+     * @returns Iterator of elements from tail to head.
+     * @remarks Time O(n), Space O(1)
+     */
+    protected abstract _getReverseIterator(...args: any[]): IterableIterator<E>;
+}
+/**
+ * Linked-list specialized linear container.
+ * @template E - Element type.
+ * @template R - Return type for mapped/derived views.
+ * @template NODE - Linked node type.
+ * @remarks Time O(1), Space O(1)
+ */
+export declare abstract class LinearLinkedBase<E, R = any, NODE extends LinkedListNode<E> = LinkedListNode<E>> extends LinearBase<E, R, NODE> {
+    protected constructor(options?: LinearBaseOptions<E, R>);
+    /**
+     * Linked-list optimized `indexOf` (forwards scan).
+     * @param searchElement - Value to match.
+     * @param fromIndex - Start position.
+     * @returns Index or `-1`.
+     * @remarks Time O(n), Space O(1)
+     */
+    indexOf(searchElement: E, fromIndex?: number): number;
+    /**
+     * Linked-list optimized `lastIndexOf` (reverse scan).
+     * @param searchElement - Value to match.
+     * @param fromIndex - Start position.
+     * @returns Index or `-1`.
+     * @remarks Time O(n), Space O(1)
+     */
+    lastIndexOf(searchElement: E, fromIndex?: number): number;
+    /**
+     * Concatenate lists/elements preserving order.
+     * @param items - Elements or `LinearBase` instances.
+     * @returns New list with combined elements (`this` type).
+     * @remarks Time O(sum(length)), Space O(sum(length))
+     */
+    concat(...items: LinearBase<E, R>[]): this;
+    /**
+     * Slice via forward iteration (no random access required).
+     * @param start - Inclusive start (supports negative index).
+     * @param end - Exclusive end (supports negative index).
+     * @returns New list (`this` type).
+     * @remarks Time O(n), Space O(n)
+     */
+    slice(start?: number, end?: number): this;
+    /**
+     * Splice by walking node iterators from the start index.
+     * @param start - Start index.
+     * @param deleteCount - How many elements to remove.
+     * @param items - Elements to insert after the splice point.
+     * @returns Removed elements as a new list (`this` type).
+     * @remarks Time O(n + m), Space O(min(n, m)) where `m = items.length`
+     */
+    splice(start: number, deleteCount?: number, ...items: E[]): this;
+    reduceRight(callbackfn: ReduceLinearCallback<E>): E;
+    reduceRight(callbackfn: ReduceLinearCallback<E>, initialValue: E): E;
+    /**
+     * Right-to-left reduction using reverse iterator.
+     * @param callbackfn - `(acc, element, index, self) => acc`.
+     * @param initialValue - Initial accumulator.
+     * @returns Final accumulator.
+     * @remarks Time O(n), Space O(1)
+     */
+    reduceRight<U>(callbackfn: ReduceLinearCallback<E, U>, initialValue: U): U;
+    /**
+     * Delete by element or node in a linked list.
+     * @param elementOrNode - Element or node.
+     * @returns `true` if removed.
+     * @remarks Time O(1)~O(n) depending on availability of links, Space O(1)
+     */
+    abstract delete(elementOrNode: E | NODE | undefined): boolean;
+    /**
+     * Insert new element/node before an existing node.
+     * @param existingElementOrNode - Reference element/node.
+     * @param newElementOrNode - Element/node to insert.
+     * @returns `true` if inserted.
+     * @remarks Time O(1)~O(n) depending on reference access, Space O(1)
+     */
+    abstract addBefore(existingElementOrNode: E | NODE, newElementOrNode: E | NODE): boolean;
+    /**
+     * Insert new element/node after an existing node.
+     * @param existingElementOrNode - Reference element/node.
+     * @param newElementOrNode - Element/node to insert.
+     * @returns `true` if inserted.
+     * @remarks Time O(1)~O(n) depending on reference access, Space O(1)
+     */
+    abstract addAfter(existingElementOrNode: E | NODE, newElementOrNode: E | NODE): boolean;
+    /**
+     * Node at index (for random-access emulation).
+     * @param index - Position (0-based).
+     * @returns Node or `undefined`.
+     * @remarks Time O(n), Space O(1)
+     */
+    abstract getNodeAt(index: number): NODE | undefined;
+    /**
+     * Iterate linked nodes from head to tail.
+     * @returns Iterator over nodes.
+     * @remarks Time O(n), Space O(1)
+     */
+    protected abstract _getNodeIterator(...args: any[]): IterableIterator<NODE>;
+    /**
+     * Get previous node of a given node.
+     * @param node - Current node.
+     * @returns Previous node or `undefined`.
+     * @remarks Time O(1)~O(n) depending on list variant (singly vs doubly), Space O(1)
+     */
+    protected abstract _getPrevNode(node: NODE): NODE | undefined;
+}