data-structure-typed 2.0.5 → 2.1.0

package/dist/cjs/interfaces/binary-tree.d.ts

@@ -1,9 +1,59 @@
 import { BinaryTreeNode } from '../data-structures';
-import type { BinaryTreeDeleteResult, BinaryTreeOptions, BTNRep, NodePredicate } from '../types';
-export interface IBinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = object> {
-    createNode(key: K, value?: BinaryTreeNode['value']): BinaryTreeNode;
-    createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R, MK, MV, MR>;
+import type { BinaryTreeDeleteResult, BinaryTreeOptions, BTNRep, DFSOrderPattern, EntryCallback, IterationType, NodeCallback, NodePredicate, OptNodeOrNull, ReduceEntryCallback, ToEntryFn } from '../types';
+/**
+ * Public, implementation-agnostic binary tree API.
+ * K = key, V = value, R = raw/record used with toEntryFn (optional).
+ * Transforming methods like `map` use method-level generics MK/MV/MR.
+ */
+export interface IBinaryTree<K = any, V = any, R extends object = object> {
+    readonly size: number;
+    readonly root: BinaryTreeNode<K, V> | null | undefined;
+    readonly isMapMode: boolean;
+    iterationType: IterationType;
+    readonly NIL: BinaryTreeNode<K, V>;
+    readonly store: Map<K, V | undefined>;
+    readonly toEntryFn?: ToEntryFn<K, V, R>;
+    readonly isDuplicate: boolean;
+    _createNode(key: K, value?: BinaryTreeNode<K, V>['value']): BinaryTreeNode<K, V>;
+    createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R>;
     add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
-    addMany(nodes: Iterable<BTNRep<K, V, BinaryTreeNode<K, V>>>, values?: Iterable<V | undefined>): boolean[];
-    delete(predicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V>>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+    addMany(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): boolean[];
+    delete(keyNodeEntryRawOrPredicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+    clear(): void;
+    isEmpty(): boolean;
+    get(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): V | undefined;
+    has(keyNodeEntryOrPredicate?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): boolean;
+    hasValue(value: V): boolean;
+    find(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): [K, V | undefined] | undefined;
+    [Symbol.iterator](): IterableIterator<[K, V | undefined]>;
+    entries(): IterableIterator<[K, V | undefined]>;
+    keys(): IterableIterator<K>;
+    values(): IterableIterator<V | undefined>;
+    forEach(callbackfn: EntryCallback<K, V | undefined, void>, thisArg?: unknown): void;
+    every(callbackfn: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): boolean;
+    some(callbackfn: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): boolean;
+    reduce<U>(reducer: ReduceEntryCallback<K, V | undefined, U>, initialValue: U): U;
+    getNode(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): OptNodeOrNull<BinaryTreeNode<K, V>>;
+    getLeftMost<C extends NodeCallback<OptNodeOrNull<BinaryTreeNode<K, V>>>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>;
+    getRightMost<C extends NodeCallback<BinaryTreeNode<K, V> | undefined>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>;
+    dfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    dfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, pattern?: DFSOrderPattern, onlyOne?: boolean, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: boolean): ReturnType<C>[];
+    bfs<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: false): ReturnType<C>[];
+    bfs<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: true): ReturnType<C>[];
+    morris<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, pattern?: DFSOrderPattern, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): ReturnType<C>[];
+    leaves<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    listLevels<C extends NodeCallback<BinaryTreeNode<K, V>>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: false): ReturnType<C>[][];
+    listLevels<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType, includeNull?: true): ReturnType<C>[][];
+    getPathToRoot<C extends NodeCallback<OptNodeOrNull<BinaryTreeNode<K, V>>>>(beginNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, callback?: C, isReverse?: boolean): ReturnType<C>[];
+    getDepth(dist: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): number;
+    getHeight(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): number;
+    getMinHeight(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): number;
+    isPerfectlyBalanced(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): boolean;
+    isBST(startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): boolean;
+    search<C extends NodeCallback<BinaryTreeNode<K, V> | null>>(keyNodeEntryOrPredicate: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | NodePredicate<BinaryTreeNode<K, V> | null>, onlyOne?: boolean, callback?: C, startNode?: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, iterationType?: IterationType): ReturnType<C>[];
+    clone(): this;
+    filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this;
+    map<MK = K, MV = V, MR extends object = object>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<BinaryTreeOptions<MK, MV, MR>>, thisArg?: unknown): IBinaryTree<MK, MV, MR>;
+    merge(anotherTree: IBinaryTree<K, V, R>): void;
+    refill(keysNodesEntriesOrRaws: Iterable<K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, values?: Iterable<V | undefined>): void;
 }

package/dist/cjs/interfaces/graph.d.ts

@@ -2,4 +2,20 @@ import { VertexKey } from '../types';
 export interface IGraph<V, E, VO, EO> {
     createVertex(key: VertexKey, value?: V): VO;
     createEdge(srcOrV1: VertexKey, destOrV2: VertexKey, weight?: number, value?: E): EO;
+    getVertex(vertexKey: VertexKey): VO | undefined;
+    hasVertex(vertexOrKey: VO | VertexKey): boolean;
+    addVertex(vertex: VO): boolean;
+    addVertex(key: VertexKey, value?: V): boolean;
+    deleteVertex(vertexOrKey: VO | VertexKey): boolean;
+    deleteEdge(edge: EO): EO | undefined;
+    getEdge(srcOrKey: VO | VertexKey, destOrKey: VO | VertexKey): EO | undefined;
+    degreeOf(vertexOrKey: VO | VertexKey): number;
+    edgeSet(): EO[];
+    edgesOf(vertexOrKey: VO | VertexKey): EO[];
+    getNeighbors(vertexOrKey: VO | VertexKey): VO[];
+    getEndsOfEdge(edge: EO): [VO, VO] | undefined;
+    isEmpty(): boolean;
+    clear(): void;
+    clone(): this;
+    filter(...args: any[]): this;
 }

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

@@ -3,7 +3,7 @@ import { LinearBase } from '../../../data-structures/base/linear-base';
 export type EntryCallback<K, V, R> = (key: K, value: V, index: number, original: IterableEntryBase<K, V>) => R;
 export type ElementCallback<E, R, RT> = (element: E, index: number, original: IterableElementBase<E, R>) => RT;
 export type ReduceEntryCallback<K, V, R> = (accumulator: R, value: V, key: K, index: number, original: IterableEntryBase<K, V>) => R;
-export type ReduceElementCallback<E, R, RT = E> = (accumulator: RT, element: E, index: number, original: IterableElementBase<E, R>) => RT;
+export type ReduceElementCallback<E, R, U = E> = (accumulator: U, value: E, index: number, self: IterableElementBase<E, R>) => U;
 export type ReduceLinearCallback<E, RT = E> = (accumulator: RT, element: E, index: number, original: LinearBase<E>) => RT;
 export type IterableElementBaseOptions<E, R> = {
     toElementFn?: (rawElement: R) => E;

package/dist/cjs/types/data-structures/graph/abstract-graph.d.ts

@@ -8,3 +8,7 @@ export type DijkstraResult<V> = {
     minDist: number;
     minPath: V[];
 } | undefined;
+export type GraphOptions<V = any> = {
+    vertexValueInitializer?: (key: VertexKey) => V;
+    defaultEdgeWeight?: number;
+};

package/dist/cjs/types/utils/utils.d.ts

@@ -1,6 +1,7 @@
 export type SpecifyOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 export type Any = string | number | bigint | boolean | symbol | undefined | object;
 export type Arithmetic = number | bigint;
+export type ElemOf<T> = T extends (infer U)[] ? U : never;
 export type ComparablePrimitive = number | bigint | string | boolean;
 export interface BaseComparableObject {
     [key: string]: unknown;

package/dist/cjs/utils/utils.d.ts

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { Comparable, TrampolineThunk, Trampoline } from '../types';
+import type { Comparable, Trampoline, TrampolineThunk } from '../types';
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
  * @returns A randomly generated UUID (Universally Unique Identifier) in the format

package/dist/cjs/utils/utils.js

@@ -252,7 +252,8 @@ exports.isTrampolineThunk = isTrampolineThunk;
  */
 function trampoline(initial) {
     let current = initial; // Start with the initial trampoline value
-    while ((0, exports.isTrampolineThunk)(current)) { // Keep unwrapping while we have thunks
+    while ((0, exports.isTrampolineThunk)(current)) {
+        // Keep unwrapping while we have thunks
         current = current.fn(); // Execute the deferred function to get the next step
     }
     return current; // Once no thunks remain, return the final result

package/dist/cjs/utils/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/utils/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/utils/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;AA2LA,oCAWC;AA6CD,gCAOC;AA+BD,wCAKC;AAeD,0CAUC;AA+BD,kDAOC;AApVD;;;;;GAKG;AACI,MAAM,MAAM,GAAG;IACpB,OAAO,sCAAsC,CAAC,OAAO,CAAC,MAAM,EAAE,UAAU,CAAC;QACvE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,EAChC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QACrC,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AANW,QAAA,MAAM,UAMjB;AAEF;;;;;;;;GAQG;AACI,MAAM,WAAW,GAAG,UAAa,KAAU,EAAE,SAA0D;IAC5G,IAAI,CAAC,GAAG,CAAC,CAAC,EACR,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,EAAE,CAAC;IAElB,OAAO,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC;QACjB,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;YAC3C,GAAG,EAAE,CAAC;QACR,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAfW,QAAA,WAAW,eAetB;AAEF;;;;;;;;GAQG;AACI,MAAM,MAAM,GAAG,CAAC,KAAa,EAAU,EAAE;IAC9C,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACf,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACvC,CAAC,CAAC;AALW,QAAA,MAAM,UAKjB;AAEF;;;;;;;;;;;;;GAaG;AACI,MAAM,UAAU,GAAG,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW,EAAE,OAAO,GAAG,sBAAsB,EAAQ,EAAE;IAC5G,IAAI,KAAK,GAAG,GAAG,IAAI,KAAK,GAAG,GAAG;QAAE,MAAM,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AAChE,CAAC,CAAC;AAFW,QAAA,UAAU,cAErB;AAEF;;;;;GAKG;AACI,MAAM,eAAe,GAAG,CAAC,OAAO,GAAG,0BAA0B,EAAQ,EAAE;IAC5E,MAAM,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC,CAAC;AAFW,QAAA,eAAe,mBAE1B;AAEF;;;;;;;GAOG;AACI,MAAM,SAAS,GAAG,CAAC,KAAc,EAAmB,EAAE;IAC3D,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAC/B,OAAO,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,IAAI,SAAS,KAAK,UAAU,CAAC;AAChF,CAAC,CAAC;AAHW,QAAA,SAAS,aAGpB;AAEF;;;;;;;;GAQG;AACI,MAAM,oBAAoB,GAAG,CAAC,aAAqB,EAAE,QAAgB,EAAE,EAAE,CAC9E,IAAI,CAAC,KAAK,CAAC,CAAC,aAAa,GAAG,QAAQ,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;AAD3C,QAAA,oBAAoB,wBACuB;AAExD;;;;;;;;GAQG;AACI,MAAM,UAAU,GAAG,CAAC,GAAW,EAAE,QAAgB,EAAE,EAAE,EAAE;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IACvC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,UAAU,CAAC,GAAG,UAAU,CAAC;AACnD,CAAC,CAAC;AAHW,QAAA,UAAU,cAGrB;AAEF;;;;;;;;GAQG;AACH,SAAS,qBAAqB,CAAC,KAAc;IAC3C,MAAM,SAAS,GAAG,OAAO,KAAK,CAAC;IAC/B,IAAI,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxC,2DAA2D;IAC3D,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,SAAS,CAAC;AACrF,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,oBAAoB,CAAC,GAAW;IACvC,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACtC,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,aAAa,KAAK,GAAG,EAAE,CAAC;YAC1B,IAAI,qBAAqB,CAAC,aAAa,CAAC;gBAAE,OAAO,aAAa,CAAC;YAC/D,IAAI,OAAO,aAAa,KAAK,QAAQ,IAAI,aAAa,KAAK,IAAI;gBAAE,OAAO,oBAAoB,CAAC,aAAa,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,YAAY,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,YAAY,KAAK,iBAAiB;YAAE,OAAO,YAAY,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,YAAY,CAAC,KAAc,EAAE,uBAAuB,GAAG,KAAK;IAC1E,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,qBAAqB,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE9C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,IAAI,CAAC;IACvC,oEAAoE;IACpE,IAAI,uBAAuB;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,eAAe,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC5E,OAAO,qBAAqB,CAAC,eAAe,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;GAUG;AACI,MAAM,mBAAmB,GAAG,CAAI,WAAgC,EAAsB,EAAE,CAAC,CAAC;IAC/F,OAAO,EAAE,IAAI,EAAE,oCAAoC;IACnD,EAAE,EAAE,WAAW,CAAC,oCAAoC;CACrD,CAAC,CAAC;AAHU,QAAA,mBAAmB,uBAG7B;AAEH;;;;;;;;;GASG;AACI,MAAM,iBAAiB,GAAG,CAAI,KAAoB,EAA+B,EAAE,CACxF,OAAO,KAAK,KAAK,QAAQ,IAAI,oBAAoB;IACjD,KAAK,KAAK,IAAI,IAAI,mBAAmB;IACrC,SAAS,IAAI,KAAK,IAAI,mCAAmC;IACzD,KAAK,CAAC,OAAO,CAAC,CAAC,wBAAwB;AAJ5B,QAAA,iBAAiB,qBAId;AAEhB;;;;;;;;;;GAUG;AACH,SAAgB,UAAU,CAAI,OAAsB;IAClD,IAAI,OAAO,GAAG,OAAO,CAAC,CAAC,0CAA0C;IACjE,OAAO,IAAA,yBAAiB,EAAC,OAAO,CAAC,EAAE,CAAC;QAClC,uCAAuC;QACvC,OAAO,GAAG,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,qDAAqD;IAC/E,CAAC;IACD,OAAO,OAAO,CAAC,CAAC,iDAAiD;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,SAAgB,cAAc,CAC5B,EAAyC,CAAC,4CAA4C;;IAEtF,kFAAkF;IAClF,OAAO,CAAC,GAAG,IAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAsB,eAAe,CAAI,OAA+C;;QACtF,IAAI,OAAO,GAAG,MAAM,OAAO,CAAC,CAAC,yDAAyD;QAEtF,iEAAiE;QACjE,OAAO,IAAA,yBAAiB,EAAC,OAAO,CAAC,EAAE,CAAC;YAClC,OAAO,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,4CAA4C;QAC5E,CAAC;QAED,6CAA6C;QAC7C,OAAO,OAAO,CAAC;IACjB,CAAC;CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,SAAgB,mBAAmB,CACjC,EAAuE;IAEvE,8EAA8E;IAC9E,OAAO,CAAO,GAAG,IAAU,EAAmB,EAAE;QAC9C,OAAO,eAAe,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC,CAAA,CAAC;AACJ,CAAC"}

package/dist/esm/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>;
 }