heap-typed 2.0.5 → 2.1.1

package/src/interfaces/binary-tree.ts

@@ -1,16 +1,250 @@
 import { BinaryTreeNode } from '../data-structures';
-import type { BinaryTreeDeleteResult, BinaryTreeOptions, BTNRep, NodePredicate } from '../types';
+import type {
+  BinaryTreeDeleteResult,
+  BinaryTreeOptions,
+  BTNRep,
+  DFSOrderPattern,
+  EntryCallback,
+  IterationType,
+  NodeCallback,
+  NodePredicate,
+  OptNodeOrNull,
+  ReduceEntryCallback,
+  ToEntryFn
+} from '../types';
 
-export interface IBinaryTree<K = any, V = any, R = object, MK = any, MV = any, MR = object> {
-  createNode(key: K, value?: BinaryTreeNode['value']): BinaryTreeNode;
+/**
+ * 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 = any> {
+  // ---- state ----
+  readonly size: number;
+  readonly root: BinaryTreeNode<K, V> | null | undefined;
+  readonly isMapMode: boolean;
+  // NOTE: iterationType is mutable on the class; remove readonly here to match
+  iterationType: IterationType;
+  // Extra public state/getters implemented by BinaryTree (useful to callers)
+  readonly NIL: BinaryTreeNode<K, V>;
+  readonly store: Map<K, V | undefined>;
+  readonly toEntryFn?: ToEntryFn<K, V, R>;
+  readonly isDuplicate: boolean;
 
-  createTree(options?: Partial<BinaryTreeOptions<K, V, R>>): IBinaryTree<K, V, R, MK, MV, MR>;
+  // ---- construction / mutation ----
+  _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[];
+  // Accept raw R as well (when toEntryFn is configured)
+  addMany(
+    keysNodesEntriesOrRaws: Iterable<
+      K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R
+    >,
+    values?: Iterable<V | undefined>
+  ): boolean[];
 
+  // Accept BTNRep, predicate, or raw R for deletion
   delete(
-    predicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V>>
+    keyNodeEntryRawOrPredicate: R | BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
   ): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[];
+
+  clear(): void;
+
+  isEmpty(): boolean;
+
+  // ---- query / read ----
+
+  // Widen `get` to support entry and optional traversal context (matches impl)
+  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` also supports node/entry/predicate and optional traversal context
+  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;
+
+  // ---- iteration ----
+  [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;
+
+  // ---- node access / extremes ----
+  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>;
+
+  // ---- traversal ----
+  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>[];
+
+  // ---- metrics & validation ----
+  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 helpers ----
+  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>[];
+
+  // ---- immutable transforms ----
+  clone(): this;
+
+  filter(predicate: EntryCallback<K, V | undefined, boolean>, thisArg?: unknown): this;
+
+  map<MK = K, MV = V, MR = any>(
+    callback: EntryCallback<K, V | undefined, [MK, MV]>,
+    options?: Partial<BinaryTreeOptions<MK, MV, MR>>,
+    thisArg?: unknown
+  ): IBinaryTree<MK, MV, MR>;
+
+  // ---- bulk / interop ----
+  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/src/interfaces/graph.ts

@@ -1,7 +1,44 @@
 import { VertexKey } from '../types';
 
 export interface IGraph<V, E, VO, EO> {
+  // Vertex factories
   createVertex(key: VertexKey, value?: V): VO;
 
+  // Edge factories
   createEdge(srcOrV1: VertexKey, destOrV2: VertexKey, weight?: number, value?: E): EO;
+
+  // Core vertex ops
+  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;
+
+  // Core edge ops
+  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;
+
+  // Container-like ops
+  isEmpty(): boolean;
+
+  clear(): void;
+
+  clone(): this;
+
+  filter(...args: any[]): this;
 }

package/src/types/data-structures/base/base.ts

@@ -11,12 +11,12 @@ export type ReduceEntryCallback<K, V, R> = (
   original: IterableEntryBase<K, V>
 ) => R;
 
-export type ReduceElementCallback<E, R, RT = E> = (
-  accumulator: RT,
-  element: E,
+export type ReduceElementCallback<E, R, U = E> = (
+  accumulator: U,
+  value: E,
   index: number,
-  original: IterableElementBase<E, R>
-) => RT;
+  self: IterableElementBase<E, R>
+) => U;
 
 export type ReduceLinearCallback<E, RT = E> = (
   accumulator: RT,

package/src/types/data-structures/graph/abstract-graph.ts

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

package/src/types/utils/utils.ts

@@ -4,6 +4,8 @@ export type Any = string | number | bigint | boolean | symbol | undefined | obje
 
 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 {

package/src/utils/utils.ts

@@ -5,7 +5,7 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-import type { Comparable, ComparablePrimitive, TrampolineThunk, Trampoline } from '../types';
+import type { Comparable, ComparablePrimitive, Trampoline, TrampolineThunk } from '../types';
 
 /**
  * The function generates a random UUID (Universally Unique Identifier) in TypeScript.
@@ -209,9 +209,7 @@ export function isComparable(value: unknown, isForceObjectComparable = false): v
  * @param computation - A function that, when executed, returns the next trampoline step.
  * @returns A TrampolineThunk object containing the deferred computation.
  */
-export const makeTrampolineThunk = <T>(
-  computation: () => Trampoline<T>
-): TrampolineThunk<T> => ({
+export const makeTrampolineThunk = <T>(computation: () => Trampoline<T>): TrampolineThunk<T> => ({
   isThunk: true, // Marker indicating this is a thunk
   fn: computation // The deferred computation function
 });
@@ -226,13 +224,11 @@ export const makeTrampolineThunk = <T>(
  * @param value - The value to test.
  * @returns True if the value is a valid TrampolineThunk, false otherwise.
  */
-export const isTrampolineThunk = <T>(
-  value: Trampoline<T>
-): value is TrampolineThunk<T> =>
+export const isTrampolineThunk = <T>(value: Trampoline<T>): value is TrampolineThunk<T> =>
   typeof value === 'object' && // Must be an object
-  value !== null &&            // Must not be null
-  'isThunk' in value &&        // Must have the 'isThunk' property
-  value.isThunk;               // The flag must be true
+  value !== null && // Must not be null
+  'isThunk' in value && // Must have the 'isThunk' property
+  value.isThunk; // The flag must be true
 
 /**
  * Executes a trampoline computation until a final (non-thunk) result is obtained.
@@ -247,7 +243,8 @@ export const isTrampolineThunk = <T>(
  */
 export function trampoline<T>(initial: Trampoline<T>): T {
   let current = initial; // Start with the initial trampoline value
-  while (isTrampolineThunk(current)) { // Keep unwrapping while we have thunks
+  while (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
@@ -302,9 +299,7 @@ export function makeTrampoline<Args extends any[], Result>(
  * @param initial - The initial Trampoline or Promise of Trampoline to start execution from.
  * @returns A Promise that resolves to the final result (a non-thunk value).
  */
-export async function asyncTrampoline<T>(
-  initial: Trampoline<T> | Promise<Trampoline<T>>
-): Promise<T> {
+export async function asyncTrampoline<T>(initial: Trampoline<T> | Promise<Trampoline<T>>): Promise<T> {
   let current = await initial; // Wait for the initial step to resolve if it's a Promise
 
   // Keep executing thunks until we reach a non-thunk (final) value