binary-tree-typed 2.3.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/dist/umd/binary-tree-typed.js

@@ -1205,6 +1205,9 @@ var binaryTreeTyped = (() => {
       __publicField(this, "iterationType", "ITERATIVE");
       __publicField(this, "_isMapMode", true);
       __publicField(this, "_isDuplicate", false);
+      // Map mode acceleration store:
+      // - isMapMode=false: unused
+      // - isMapMode=true: key -> node reference (O(1) has/getNode + fast get)
       __publicField(this, "_store", /* @__PURE__ */ new Map());
       __publicField(this, "_root");
       __publicField(this, "_size", 0);
@@ -1300,7 +1303,7 @@ var binaryTreeTyped = (() => {
      * @returns The newly created node.
      */
     createNode(key, value) {
-      return new BinaryTreeNode(key, this._isMapMode ? void 0 : value);
+      return new BinaryTreeNode(key, value);
     }
     /**
      * Creates a new, empty tree of the same type and configuration.
@@ -1447,11 +1450,11 @@ var binaryTreeTyped = (() => {
      * @returns True if the addition was successful, false otherwise.
      */
     set(keyNodeOrEntry, value) {
-      const [newNode, newValue] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
+      const [newNode] = this._keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry, value);
       if (newNode === void 0) return false;
       if (!this._root) {
         this._setRoot(newNode);
-        if (this._isMapMode) this._setValue(newNode == null ? void 0 : newNode.key, newValue);
+        if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
         this._size = 1;
         return true;
       }
@@ -1463,7 +1466,7 @@ var binaryTreeTyped = (() => {
         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;
           }
         }
@@ -1483,7 +1486,7 @@ var binaryTreeTyped = (() => {
         } else if (potentialParent.right === void 0) {
           potentialParent.right = newNode;
         }
-        if (this._isMapMode) this._setValue(newNode == null ? void 0 : newNode.key, newValue);
+        if (this._isMapMode && newNode !== null && newNode !== void 0) this._store.set(newNode.key, newNode);
         this._size++;
         return true;
       }
@@ -1550,13 +1553,13 @@ var binaryTreeTyped = (() => {
      * 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) {
+    delete(keyNodeEntryRawOrPredicate) {
       const deletedResult = [];
       if (!this._root) return deletedResult;
-      const curr = this.getNode(keyNodeOrEntry);
+      const curr = this.getNode(keyNodeEntryRawOrPredicate);
       if (!curr) return deletedResult;
       const parent = curr == null ? void 0 : curr.parent;
       let needBalanced;
@@ -1568,6 +1571,10 @@ var binaryTreeTyped = (() => {
         if (leftSubTreeRightMost) {
           const parentOfLeftSubTreeMax = leftSubTreeRightMost.parent;
           orgCurrent = this._swapProperties(curr, leftSubTreeRightMost);
+          if (this._isMapMode) {
+            this._store.set(curr.key, curr);
+            this._store.set(leftSubTreeRightMost.key, leftSubTreeRightMost);
+          }
           if (parentOfLeftSubTreeMax) {
             if (parentOfLeftSubTreeMax.right === leftSubTreeRightMost)
               parentOfLeftSubTreeMax.right = leftSubTreeRightMost.left;
@@ -1651,6 +1658,13 @@ var binaryTreeTyped = (() => {
      * @returns The first matching node, or undefined if not found.
      */
     getNode(keyNodeEntryOrPredicate, startNode = this._root, iterationType = this.iterationType) {
+      if (this._isMapMode && keyNodeEntryOrPredicate !== null && keyNodeEntryOrPredicate !== void 0) {
+        if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+          const key = this._extractKey(keyNodeEntryOrPredicate);
+          if (key === null || key === void 0) return;
+          return this._store.get(key);
+        }
+      }
       return this.search(keyNodeEntryOrPredicate, true, (node) => node, startNode, iterationType)[0];
     }
     /**
@@ -1663,15 +1677,22 @@ var binaryTreeTyped = (() => {
      * @returns The associated value, or undefined.
      */
     get(keyNodeEntryOrPredicate, startNode = this._root, iterationType = this.iterationType) {
-      var _a;
+      var _a, _b;
       if (this._isMapMode) {
         const key = this._extractKey(keyNodeEntryOrPredicate);
         if (key === null || key === void 0) return;
-        return this._store.get(key);
+        return (_a = this._store.get(key)) == null ? void 0 : _a.value;
       }
-      return (_a = this.getNode(keyNodeEntryOrPredicate, startNode, iterationType)) == null ? void 0 : _a.value;
+      return (_b = this.getNode(keyNodeEntryOrPredicate, startNode, iterationType)) == null ? void 0 : _b.value;
     }
     has(keyNodeEntryOrPredicate, startNode = this._root, iterationType = this.iterationType) {
+      if (this._isMapMode && keyNodeEntryOrPredicate !== void 0 && keyNodeEntryOrPredicate !== null) {
+        if (!this._isPredicate(keyNodeEntryOrPredicate)) {
+          const key = this._extractKey(keyNodeEntryOrPredicate);
+          if (key === null || key === void 0) return false;
+          return this._store.has(key);
+        }
+      }
       return this.search(keyNodeEntryOrPredicate, true, (node) => node, startNode, iterationType).length > 0;
     }
     /**
@@ -1740,7 +1761,7 @@ var binaryTreeTyped = (() => {
           }
           return true;
         };
-        const isStandardBST = checkBST(false);
+        const isStandardBST = checkBST();
         const isInverseBST = checkBST(true);
         return isStandardBST || isInverseBST;
       }
@@ -2416,8 +2437,7 @@ var binaryTreeTyped = (() => {
           }
           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];
             current = current.right;
           }
         }
@@ -2425,8 +2445,7 @@ var binaryTreeTyped = (() => {
         if (node.left && this.isRealNode(node)) {
           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);
         }
@@ -2504,8 +2523,7 @@ var binaryTreeTyped = (() => {
         (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,
@@ -2513,7 +2531,6 @@ var binaryTreeTyped = (() => {
         true
         // Include nulls
       );
-      if (this._isMapMode) cloned._store = this._store;
     }
     /**
      * (Protected) Recursive helper for `toVisual`.
@@ -2676,8 +2693,10 @@ var binaryTreeTyped = (() => {
      */
     _setValue(key, value) {
       if (key === null || key === void 0) return false;
-      if (value === void 0) return false;
-      return this._store.set(key, value);
+      const node = this._store.get(key);
+      if (!node) return false;
+      node.value = value;
+      return true;
     }
     /**
      * (Protected) Clears all nodes from the tree.