max-priority-queue-typed 2.4.0 → 2.4.1

package/dist/types/data-structures/binary-tree/tree-set.d.ts

@@ -0,0 +1,181 @@
+/**
+ * TreeSet (ordered set) — a restricted, native-like API backed by RedBlackTree.
+ *
+ * Design goals:
+ * - No node exposure (no node inputs/outputs)
+ * - Native Set-like surface + Java NavigableSet-like helpers
+ * - Strict default comparator (number/string/Date), otherwise require comparator
+ */
+import type { Comparator } from '../../types';
+import type { TreeSetElementCallback, TreeSetOptions, TreeSetRangeOptions, TreeSetReduceCallback } from '../../types';
+/**
+ * An ordered Set backed by a red-black tree.
+ *
+ * - Iteration order is ascending by key.
+ * - No node exposure: all APIs use keys only.
+ */
+export declare class TreeSet<K = any, R = K> implements Iterable<K> {
+    #private;
+    /**
+     * Create a TreeSet from an iterable of keys or raw elements.
+     *
+     * @param elements - Iterable of keys, or raw elements if `toElementFn` is provided.
+     * @param options - Configuration options including optional `toElementFn` to transform raw elements.
+     * @throws {TypeError} When using the default comparator and encountering unsupported key types,
+     * or invalid keys (e.g. `NaN`, invalid `Date`).
+     * @example
+     * // Standard usage with keys
+     * const set = new TreeSet([3, 1, 2]);
+     *
+     * // Using toElementFn to transform raw objects
+     * const users = [{ id: 3, name: 'Alice' }, { id: 1, name: 'Bob' }];
+     * const set = new TreeSet<number, User>(users, { toElementFn: u => u.id });
+     */
+    constructor(elements?: Iterable<R> | Iterable<K>, options?: TreeSetOptions<K, R>);
+    /**
+     * Create the strict default comparator.
+     *
+     * Supports:
+     * - `number` (rejects `NaN`; treats `-0` and `0` as equal)
+     * - `string`
+     * - `Date` (orders by `getTime()`, rejects invalid dates)
+     *
+     * For other key types, a custom comparator must be provided.
+     */
+    static createDefaultComparator<K>(): Comparator<K>;
+    /**
+     * Number of elements in the set.
+     */
+    get size(): number;
+    /**
+     * Whether the set is empty.
+     */
+    isEmpty(): boolean;
+    private _validateKey;
+    /**
+     * Add a key to the set (no-op if already present).
+     * @remarks Expected time O(log n)
+     */
+    add(key: K): this;
+    /**
+     * Test whether a key exists.
+     * @remarks Expected time O(log n)
+     */
+    has(key: K): boolean;
+    /**
+     * Delete a key.
+     * @returns `true` if the key existed; otherwise `false`.
+     * @remarks Expected time O(log n)
+     */
+    delete(key: K): boolean;
+    /**
+     * Remove all keys.
+     */
+    clear(): void;
+    /**
+     * Iterate over keys in ascending order.
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Iterate over values in ascending order.
+     *
+     * Note: for Set-like containers, `values()` is the same as `keys()`.
+     */
+    values(): IterableIterator<K>;
+    /**
+     * Iterate over `[value, value]` pairs (native Set convention).
+     *
+     * Note: TreeSet stores only keys internally; `[k, k]` is created on-the-fly during iteration.
+     */
+    entries(): IterableIterator<[K, K]>;
+    [Symbol.iterator](): IterableIterator<K>;
+    /**
+     * Visit each value in ascending order.
+     *
+     * Callback follows native Set convention: `(value, value2, set)`.
+     */
+    forEach(cb: (value: K, value2: K, set: TreeSet<K>) => void, thisArg?: any): void;
+    /**
+     * Create a new TreeSet by mapping each value to a new key.
+     *
+     * This mirrors `RedBlackTree.map`: mapping produces a new ordered container.
+     * @remarks Time O(n log n) expected, Space O(n)
+     */
+    map<MK>(callbackfn: TreeSetElementCallback<K, MK, TreeSet<K>>, options?: Omit<TreeSetOptions<MK>, 'toElementFn'> & {
+        comparator?: (a: MK, b: MK) => number;
+    }, thisArg?: unknown): TreeSet<MK>;
+    /**
+     * Create a new TreeSet containing only values that satisfy the predicate.
+     * @remarks Time O(n log n) expected, Space O(n)
+     */
+    filter(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): TreeSet<K>;
+    /**
+     * Reduce values into a single accumulator.
+     * @remarks Time O(n), Space O(1)
+     */
+    reduce<A>(callbackfn: TreeSetReduceCallback<K, A, TreeSet<K>>, initialValue: A): A;
+    /**
+     * Test whether all values satisfy a predicate.
+     * @remarks Time O(n), Space O(1)
+     */
+    every(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean;
+    /**
+     * Test whether any value satisfies a predicate.
+     * @remarks Time O(n), Space O(1)
+     */
+    some(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): boolean;
+    /**
+     * Find the first value that satisfies a predicate.
+     * @remarks Time O(n), Space O(1)
+     */
+    find(callbackfn: TreeSetElementCallback<K, boolean, TreeSet<K>>, thisArg?: unknown): K | undefined;
+    /**
+     * Materialize the set into an array of keys.
+     * @remarks Time O(n), Space O(n)
+     */
+    toArray(): K[];
+    /**
+     * Print a human-friendly representation.
+     * @remarks Time O(n), Space O(n)
+     */
+    print(): void;
+    /**
+     * Smallest key in the set.
+     */
+    first(): K | undefined;
+    /**
+     * Largest key in the set.
+     */
+    last(): K | undefined;
+    /**
+     * Remove and return the smallest key.
+     */
+    pollFirst(): K | undefined;
+    /**
+     * Remove and return the largest key.
+     */
+    pollLast(): K | undefined;
+    /**
+     * Smallest key that is >= the given key.
+     */
+    ceiling(key: K): K | undefined;
+    /**
+     * Largest key that is <= the given key.
+     */
+    floor(key: K): K | undefined;
+    /**
+     * Smallest key that is > the given key.
+     */
+    higher(key: K): K | undefined;
+    /**
+     * Largest key that is < the given key.
+     */
+    lower(key: K): K | undefined;
+    /**
+     * Return all keys in a given range.
+     *
+     * @param range `[low, high]`
+     * @param options Inclusive/exclusive bounds (defaults to inclusive).
+     */
+    rangeSearch(range: [K, K], options?: TreeSetRangeOptions): K[];
+}

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

@@ -11,7 +11,7 @@ export interface IBinaryTree<K = any, V = any, R = any> {
     readonly isMapMode: boolean;
     iterationType: IterationType;
     readonly NIL: BinaryTreeNode<K, V>;
-    readonly store: Map<K, V | undefined>;
+    readonly store: Map<K, BinaryTreeNode<K, V>>;
     readonly toEntryFn?: ToEntryFn<K, V, R>;
     readonly isDuplicate: boolean;
     createNode(key: K, value?: BinaryTreeNode<K, V>['value']): BinaryTreeNode<K, V>;
@@ -19,7 +19,7 @@ export interface IBinaryTree<K = any, V = any, R = any> {
     add(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
     set(keyOrNodeOrEntryOrRawElement: BTNRep<K, V, BinaryTreeNode<K, V>>, value?: V, count?: number): boolean;
     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>>[];
+    delete(keyNodeEntryRawOrPredicate: 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;

package/dist/types/types/data-structures/binary-tree/index.d.ts

@@ -2,8 +2,8 @@ export * from './binary-tree';
 export * from './bst';
 export * from './avl-tree';
 export * from './segment-tree';
-export * from './avl-tree-multi-map';
 export * from './red-black-tree';
 export * from './tree-multi-map';
-export * from './tree-counter';
-export * from './avl-tree-counter';
+export * from './tree-set';
+export * from './tree-map';
+export * from './tree-multi-set';

package/dist/types/types/data-structures/binary-tree/tree-map.d.ts

@@ -0,0 +1,33 @@
+import type { Comparator } from '../../common';
+export interface TreeMapOptions<K, V, R = [K, V]> {
+    comparator?: Comparator<K>;
+    /**
+     * Pass-through to the underlying RedBlackTree/BST `isMapMode` option.
+     *
+     * - `true`  (default in core): store values in an internal key→value store.
+     * - `false`: store values on tree nodes (Node Mode).
+     */
+    isMapMode?: boolean;
+    /**
+     * Transform raw elements into `[key, value]` entries.
+     * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<[K, V]>`.
+     */
+    toEntryFn?: (rawElement: R) => [K, V];
+}
+export type TreeMapRangeOptions = {
+    lowInclusive?: boolean;
+    highInclusive?: boolean;
+};
+/**
+ * Callback used by TreeMap entry-wise utilities.
+ *
+ * `SELF` is intentionally generic to avoid type-layer circular imports.
+ * Implementations (e.g. `TreeMap<K, V>`) should bind `SELF` at use sites.
+ */
+export type TreeMapEntryCallback<K, V, R, SELF> = (value: V | undefined, key: K, index: number, map: SELF) => R;
+/**
+ * Reducer callback used by TreeMap.
+ *
+ * `SELF` is intentionally generic to avoid type-layer circular imports.
+ */
+export type TreeMapReduceCallback<K, V, A, SELF> = (acc: A, value: V | undefined, key: K, index: number, map: SELF) => A;

package/dist/types/types/data-structures/binary-tree/tree-multi-set.d.ts

@@ -0,0 +1,16 @@
+import type { Comparator } from '../../common';
+export interface TreeMultiSetOptions<K, R = K> {
+    comparator?: Comparator<K>;
+    /**
+     * Pass-through to the underlying RedBlackTree/BST `isMapMode` option.
+     *
+     * - `true`  (recommended): MapMode store uses key→node index for fast lookups.
+     * - `false`: Node Mode.
+     */
+    isMapMode?: boolean;
+    /**
+     * Transform raw elements into keys.
+     * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<K>`.
+     */
+    toElementFn?: (rawElement: R) => K;
+}

package/dist/types/types/data-structures/binary-tree/tree-set.d.ts

@@ -0,0 +1,33 @@
+import type { Comparator } from '../../common';
+export interface TreeSetOptions<K, R = K> {
+    comparator?: Comparator<K>;
+    /**
+     * Pass-through to the underlying RedBlackTree/BST `isMapMode` option.
+     *
+     * - `true`  (default in core): store values in an internal key→value store.
+     * - `false`: store values on tree nodes (Node Mode).
+     */
+    isMapMode?: boolean;
+    /**
+     * Transform raw elements into keys.
+     * When provided, the constructor accepts `Iterable<R>` instead of `Iterable<K>`.
+     */
+    toElementFn?: (rawElement: R) => K;
+}
+export type TreeSetRangeOptions = {
+    lowInclusive?: boolean;
+    highInclusive?: boolean;
+};
+/**
+ * Callback used by TreeSet element-wise utilities.
+ *
+ * `SELF` is intentionally generic to avoid type-layer circular imports.
+ * Implementations (e.g. `TreeSet<K>`) should bind `SELF` at use sites.
+ */
+export type TreeSetElementCallback<K, R, SELF> = (value: K, index: number, set: SELF) => R;
+/**
+ * Reducer callback used by TreeSet.
+ *
+ * `SELF` is intentionally generic to avoid type-layer circular imports.
+ */
+export type TreeSetReduceCallback<K, A, SELF> = (acc: A, value: K, index: number, set: SELF) => A;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "max-priority-queue-typed",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "Max Priority Queue",
   "browser": "dist/umd/max-priority-queue-typed.min.js",
   "umd:main": "dist/umd/max-priority-queue-typed.min.js",
@@ -165,6 +165,6 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "data-structure-typed": "^2.4.0"
+    "data-structure-typed": "^2.4.1"
   }
 }

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

@@ -75,7 +75,7 @@ export abstract class LinearBase<
    * @param options - `{ maxLen?, ... }` bounds/behavior options.
    * @remarks Time O(1), Space O(1)
    */
-  protected constructor(options?: LinearBaseOptions<E, R>) {
+   constructor(options?: LinearBaseOptions<E, R>) {
     super(options);
     if (options) {
       const { maxLen } = options;
@@ -156,14 +156,6 @@ export abstract class LinearBase<
     return -1;
   }
 
-  /**
-   * 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;
-
   /**
    * Concatenate elements and/or containers.
    * @param items - Elements or other containers.
@@ -412,7 +404,7 @@ export abstract class LinearLinkedBase<
   R = any,
   NODE extends LinkedListNode<E> = LinkedListNode<E>
 > extends LinearBase<E, R, NODE> {
-  protected constructor(options?: LinearBaseOptions<E, R>) {
+   constructor(options?: LinearBaseOptions<E, R>) {
     super(options);
     if (options) {
       const { maxLen } = options;
@@ -478,8 +470,6 @@ export abstract class LinearLinkedBase<
    * @returns New list with combined elements (`this` type).
    * @remarks Time O(sum(length)), Space O(sum(length))
    */
-  override concat(...items: LinearBase<E, R>[]): this;
-
   override concat(...items: (E | LinearBase<E, R>)[]): this {
     const newList = this.clone();
 

package/src/data-structures/binary-tree/avl-tree.ts

@@ -383,7 +383,7 @@ export class AVLTree<K = any, V = any, R = any> extends BST<K, V, R> implements
    * @returns The newly created AVLTreeNode.
    */
   override createNode(key: K, value?: V): AVLTreeNode<K, V> {
-    return new AVLTreeNode<K, V>(key, this._isMapMode ? undefined : value) as AVLTreeNode<K, V>;
+    return new AVLTreeNode<K, V>(key, value) as AVLTreeNode<K, V>;
   }
 
   /**

package/src/data-structures/binary-tree/binary-tree.ts

@@ -10,7 +10,7 @@ import type {
   BinaryTreeDeleteResult,
   BinaryTreeOptions,
   BinaryTreePrintOptions,
-  BTNEntry,
+  BTNEntry, BTNRep,
   DFSOrderPattern,
   DFSStackItem,
   EntryCallback,
@@ -401,7 +401,10 @@ export class BinaryTree<K = any, V = any, R = any>
     return this._isDuplicate;
   }
 
-  protected _store = new Map<K, V | undefined>();
+  // Map mode acceleration store:
+  // - isMapMode=false: unused
+  // - isMapMode=true: key -> node reference (O(1) has/getNode + fast get)
+  protected _store = new Map<K, BinaryTreeNode<K, V>>();
 
   /**
    * Gets the external value store (used in Map mode).
@@ -470,7 +473,7 @@ export class BinaryTree<K = any, V = any, R = any>
    * @returns The newly created node.
    */
   createNode(key: K, value?: V): BinaryTreeNode<K, V> {
-    return new BinaryTreeNode<K, V>(key, this._isMapMode ? undefined : value);
+    return new BinaryTreeNode<K, V>(key, value);
   }
 
   /**
@@ -661,12 +664,12 @@ export class BinaryTree<K = any, V = any, R = any>
     value?: V
   ): boolean {
 
-    const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
+    const [newNode] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
     if (newNode === undefined) return false;
 
     if (!this._root) {
       this._setRoot(newNode);
-      if (this._isMapMode) this._setValue(newNode?.key, newValue);
+      if (this._isMapMode && newNode !== null && newNode !== undefined) this._store.set(newNode.key, newNode);
       this._size = 1;
       return true;
     }
@@ -681,7 +684,7 @@ export class BinaryTree<K = any, V = any, R = any>
       if (!this._isDuplicate) {
         if (newNode !== null && cur.key === newNode.key) {
           this._replaceNode(cur, newNode);
-          if (this._isMapMode) this._setValue(cur.key, newValue);
+          if (this._isMapMode && newNode !== null) this._store.set(cur.key, newNode);
           return true; // Replaced existing node
         }
       }
@@ -704,7 +707,7 @@ export class BinaryTree<K = any, V = any, R = any>
       } else if (potentialParent.right === undefined) {
         potentialParent.right = newNode;
       }
-      if (this._isMapMode) this._setValue(newNode?.key, newValue);
+      if (this._isMapMode && newNode !== null && newNode !== undefined) this._store.set(newNode.key, newNode);
       this._size++;
       return true;
     }
@@ -795,16 +798,16 @@ export class BinaryTree<K = any, V = any, R = any>
    * Deletes a node from the tree.
    * @remarks Time O(log N), For BST, Red-Black Tree, and AVL Tree subclasses, the worst-case time is O(log N). This implementation finds the node, and if it has two children, swaps it with the rightmost node of its left subtree (in-order predecessor) before deleting. Time O(N) in the worst case. O(N) to find the node (`getNode`) and O(H) (which is O(N) worst-case) to find the rightmost node. Space O(1) (if `getNode` is iterative, which it is).
    *
-   * @param keyNodeOrEntry - The node to delete.
+   * @param keyNodeEntryRawOrPredicate - The node to delete.
    * @returns An array containing deletion results (for compatibility with self-balancing trees).
    */
   delete(
-    keyNodeOrEntry: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined
+    keyNodeEntryRawOrPredicate: BTNRep<K, V, BinaryTreeNode<K, V>> | NodePredicate<BinaryTreeNode<K, V> | null>
   ): BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[] {
     const deletedResult: BinaryTreeDeleteResult<BinaryTreeNode<K, V>>[] = [];
     if (!this._root) return deletedResult;
 
-    const curr = this.getNode(keyNodeOrEntry);
+    const curr = this.getNode(keyNodeEntryRawOrPredicate);
     if (!curr) return deletedResult;
 
     const parent: BinaryTreeNode<K, V> | undefined = curr?.parent;
@@ -822,6 +825,13 @@ export class BinaryTree<K = any, V = any, R = any>
         const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
         // Swap properties
         orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
+
+        // Map mode store tracks key -> node reference; after swapping keys we must re-index both nodes.
+        if (this._isMapMode) {
+          this._store.set(curr.key, curr);
+          this._store.set(leftSubTreeRightMost.key, leftSubTreeRightMost);
+        }
+
         // `orgCurrent` is now the node to be physically deleted (which was the rightmost)
         if (parentOfLeftSubTreeMax) {
           // Unlink the rightmost node
@@ -1002,6 +1012,13 @@ export class BinaryTree<K = any, V = any, R = any>
     startNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
     iterationType: IterationType = this.iterationType
   ): BinaryTreeNode<K, V> | null | undefined {
+    if (this._isMapMode && keyNodeEntryOrPredicate !== null && keyNodeEntryOrPredicate !== undefined) {
+      if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+        const key = this._extractKey(keyNodeEntryOrPredicate as any);
+        if (key === null || key === undefined) return;
+        return this._store.get(key);
+      }
+    }
     return this.search(keyNodeEntryOrPredicate, true, node => node, startNode, iterationType)[0];
   }
 
@@ -1022,7 +1039,7 @@ export class BinaryTree<K = any, V = any, R = any>
     if (this._isMapMode) {
       const key = this._extractKey(keyNodeEntryOrPredicate);
       if (key === null || key === undefined) return;
-      return this._store.get(key);
+      return this._store.get(key)?.value;
     }
     return this.getNode(keyNodeEntryOrPredicate, startNode, iterationType)?.value;
   }
@@ -1059,6 +1076,13 @@ export class BinaryTree<K = any, V = any, R = any>
     startNode: K | BinaryTreeNode<K, V> | [K | null | undefined, V | undefined] | null | undefined = this._root,
     iterationType: IterationType = this.iterationType
   ): boolean {
+    if (this._isMapMode && keyNodeEntryOrPredicate !== undefined && keyNodeEntryOrPredicate !== null) {
+      if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+        const key = this._extractKey(keyNodeEntryOrPredicate as any);
+        if (key === null || key === undefined) return false;
+        return this._store.has(key);
+      }
+    }
     return this.search(keyNodeEntryOrPredicate, true, node => node, startNode, iterationType).length > 0;
   }
 
@@ -1139,7 +1163,7 @@ export class BinaryTree<K = any, V = any, R = any>
         }
         return true;
       };
-      const isStandardBST = checkBST(false);
+      const isStandardBST = checkBST();
       const isInverseBST = checkBST(true);
       return isStandardBST || isInverseBST;
     }
@@ -2086,8 +2110,7 @@ export class BinaryTree<K = any, V = any, R = any>
         current = stack.pop();
 
         if (this.isRealNode(current)) {
-          if (this._isMapMode) yield [current.key, this._store.get(current.key)];
-          else yield [current.key, current.value];
+          yield [current.key, current.value];
           // Move to the right subtree
           current = current.right;
         }
@@ -2098,8 +2121,7 @@ export class BinaryTree<K = any, V = any, R = any>
         yield* this[Symbol.iterator](node.left);
       }
 
-      if (this._isMapMode) yield [node.key, this._store.get(node.key)];
-      else yield [node.key, node.value];
+      yield [node.key, node.value];
 
       if (node.right && this.isRealNode(node)) {
         yield* this[Symbol.iterator](node.right);
@@ -2212,15 +2234,14 @@ export class BinaryTree<K = any, V = any, R = any>
       node => {
         if (node === null) cloned.set(null);
         else {
-          if (this._isMapMode) cloned.set([node.key, this._store.get(node.key)]);
-          else cloned.set([node.key, node.value]);
+          cloned.set([node.key, node.value]);
         }
       },
       this._root,
       this.iterationType,
       true // Include nulls
     );
-    if (this._isMapMode) cloned._store = this._store;
+    // Map mode: store is rebuilt via set() calls above.
   }
 
   /**
@@ -2468,8 +2489,11 @@ export class BinaryTree<K = any, V = any, R = any>
    */
   protected _setValue(key: K | null | undefined, value: V | undefined) {
     if (key === null || key === undefined) return false;
-    if (value === undefined) return false; // Or allow setting undefined?
-    return this._store.set(key, value);
+    // Map mode stores node references; update the node value in-place.
+    const node = this._store.get(key);
+    if (!node) return false;
+    node.value = value as V;
+    return true;
   }
 
   /**