data-structure-typed 2.3.0 → 2.4.0

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

@@ -0,0 +1,263 @@
+/**
+ * TreeMultiSet (ordered multiset) — a restricted, native-like API backed by RedBlackTree.
+ *
+ * Design goals:
+ * - No node exposure
+ * - Strict default comparator (number/string/Date), otherwise require comparator
+ * - Default iteration is expanded (each element yielded `count(x)` times)
+ * - `delete(x)` removes one occurrence by default
+ */
+import type { Comparator, TreeMultiSetOptions } from '../../types';
+export declare class TreeMultiSet<K = any> implements Iterable<K> {
+    #private;
+    private _size;
+    /**
+     * Creates a new TreeMultiSet.
+     * @param elements - Initial elements to add
+     * @param options - Configuration options
+     * @remarks Time O(m log m), Space O(m) where m is the number of initial elements
+     */
+    constructor(elements?: Iterable<K>, options?: TreeMultiSetOptions<K>);
+    /**
+     * Validates the key against the default comparator rules.
+     * @remarks Time O(1), Space O(1)
+     */
+    private _validateKey;
+    /**
+     * Validates that count is a non-negative safe integer.
+     * @remarks Time O(1), Space O(1)
+     */
+    private _validateCount;
+    /**
+     * Total occurrences (sumCounts).
+     * @remarks Time O(1), Space O(1)
+     */
+    get size(): number;
+    /**
+     * Number of distinct keys.
+     * @remarks Time O(1), Space O(1)
+     */
+    get distinctSize(): number;
+    /**
+     * Whether the multiset is empty.
+     * @remarks Time O(1), Space O(1)
+     */
+    isEmpty(): boolean;
+    /**
+     * Whether the multiset contains the given key.
+     * @remarks Time O(log n), Space O(1)
+     */
+    has(key: K): boolean;
+    /**
+     * Returns the count of occurrences for the given key.
+     * @remarks Time O(log n), Space O(1)
+     */
+    count(key: K): number;
+    /**
+     * Add `n` occurrences of `key`.
+     * @returns True if the multiset changed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    add(key: K, n?: number): boolean;
+    /**
+     * Set count for `key` to exactly `n`.
+     * @returns True if changed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    setCount(key: K, n: number): boolean;
+    /**
+     * Delete `n` occurrences of `key` (default 1).
+     * @returns True if any occurrence was removed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    delete(key: K, n?: number): boolean;
+    /**
+     * Delete all occurrences of the given key.
+     * @returns True if any occurrence was removed.
+     * @remarks Time O(log n), Space O(1)
+     */
+    deleteAll(key: K): boolean;
+    /**
+     * Iterates over distinct keys (each key yielded once).
+     * @remarks Time O(n), Space O(1)
+     */
+    keysDistinct(): IterableIterator<K>;
+    /**
+     * Iterates over entries as [key, count] pairs.
+     * @remarks Time O(n), Space O(1)
+     */
+    entries(): IterableIterator<[K, number]>;
+    /**
+     * Expanded iteration (default). Each key is yielded `count(key)` times.
+     * @remarks Time O(size), Space O(1) where size is total occurrences
+     */
+    [Symbol.iterator](): Iterator<K>;
+    /**
+     * Returns an array with all elements (expanded).
+     * @remarks Time O(size), Space O(size)
+     */
+    toArray(): K[];
+    /**
+     * Returns an array with distinct keys only.
+     * @remarks Time O(n), Space O(n)
+     */
+    toDistinctArray(): K[];
+    /**
+     * Returns an array of [key, count] entries.
+     * @remarks Time O(n), Space O(n)
+     */
+    toEntries(): Array<[K, number]>;
+    /**
+     * Expose comparator for advanced usage/testing (read-only).
+     * @remarks Time O(1), Space O(1)
+     */
+    get comparator(): Comparator<K>;
+    /**
+     * Remove all elements from the multiset.
+     * @remarks Time O(1), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 2, 3]);
+     * ms.clear();
+     * ms.size;  // 0
+     */
+    clear(): void;
+    /**
+     * Returns the smallest key, or undefined if empty.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([3, 1, 4]);
+     * ms.first();  // 1
+     */
+    first(): K | undefined;
+    /**
+     * Returns the largest key, or undefined if empty.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([3, 1, 4]);
+     * ms.last();  // 4
+     */
+    last(): K | undefined;
+    /**
+     * Removes all occurrences of the smallest key and returns it.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3]);
+     * ms.pollFirst();  // 1
+     * ms.has(1);       // false
+     */
+    pollFirst(): K | undefined;
+    /**
+     * Removes all occurrences of the largest key and returns it.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 3, 3]);
+     * ms.pollLast();  // 3
+     * ms.has(3);      // false
+     */
+    pollLast(): K | undefined;
+    /**
+     * Returns the smallest key >= given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.ceiling(15);  // 20
+     * ms.ceiling(20);  // 20
+     */
+    ceiling(key: K): K | undefined;
+    /**
+     * Returns the largest key <= given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.floor(25);  // 20
+     * ms.floor(20);  // 20
+     */
+    floor(key: K): K | undefined;
+    /**
+     * Returns the smallest key > given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.higher(10);  // 20
+     * ms.higher(15);  // 20
+     */
+    higher(key: K): K | undefined;
+    /**
+     * Returns the largest key < given key, or undefined.
+     * @remarks Time O(log n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30]);
+     * ms.lower(20);  // 10
+     * ms.lower(15);  // 10
+     */
+    lower(key: K): K | undefined;
+    /**
+     * Iterates over distinct keys with their counts.
+     * @remarks Time O(n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * ms.forEach((key, count) => console.log(`${key}: ${count}`));
+     * // 1: 2, 2: 1, 3: 3
+     */
+    forEach(callback: (key: K, count: number) => void): void;
+    /**
+     * Creates a new TreeMultiSet with entries that match the predicate.
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const filtered = ms.filter((key, count) => count >= 2);
+     * // TreeMultiSet { 1: 2, 3: 3 }
+     */
+    filter(predicate: (key: K, count: number) => boolean): TreeMultiSet<K>;
+    /**
+     * Reduces the multiset to a single value.
+     * @remarks Time O(n), Space O(1)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const total = ms.reduce((acc, key, count) => acc + count, 0);  // 6
+     */
+    reduce<U>(callback: (accumulator: U, key: K, count: number) => U, initialValue: U): U;
+    /**
+     * Maps keys and counts to a new TreeMultiSet.
+     * When multiple keys map to the same new key, counts are merged (added).
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2, 3, 3, 3]);
+     * const mapped = ms.map((key, count) => [key * 10, count]);
+     * // TreeMultiSet { 10: 2, 20: 1, 30: 3 }
+     * @example
+     * // Collision: counts merge
+     * const ms = new TreeMultiSet([1, 2, 3]);
+     * const merged = ms.map((key, count) => [key % 2, count]);
+     * // { 0: 1, 1: 2 }  (1 and 3 both map to 1, counts add)
+     */
+    map<K2>(mapper: (key: K, count: number) => [K2, number], options?: {
+        comparator?: Comparator<K2>;
+    }): TreeMultiSet<K2>;
+    /**
+     * Creates an independent copy of this multiset.
+     * @remarks Time O(n log n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 1, 2]);
+     * const copy = ms.clone();
+     * copy.add(3);
+     * ms.has(3);  // false (original unchanged)
+     */
+    clone(): TreeMultiSet<K>;
+    /**
+     * Returns keys within the given range.
+     * @remarks Time O(log n + k), Space O(k) where k is result size
+     * @example
+     * const ms = new TreeMultiSet([10, 20, 30, 40, 50]);
+     * ms.rangeSearch([15, 45]);  // [20, 30, 40]
+     */
+    rangeSearch<C extends (key: K) => any>(range: [K, K], callback?: C): (C extends undefined ? K : ReturnType<C>)[];
+    /**
+     * Prints the internal tree structure (for debugging).
+     * @remarks Time O(n), Space O(n)
+     * @example
+     * const ms = new TreeMultiSet([1, 2, 3]);
+     * ms.print();
+     */
+    print(): void;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * 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> implements Iterable<K> {
+    #private;
+    /**
+     * Create a TreeSet from an iterable of keys.
+     *
+     * @throws {TypeError} When using the default comparator and encountering unsupported key types,
+     * or invalid keys (e.g. `NaN`, invalid `Date`).
+     */
+    constructor(elements?: Iterable<K>, options?: TreeSetOptions<K>);
+    /**
+     * 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?: TreeSetOptions<MK>, 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>;

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,28 @@
+import type { Comparator } from '../../common';
+export interface TreeMapOptions<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;
+}
+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,11 @@
+import type { Comparator } from '../../common';
+export interface TreeMultiSetOptions<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;
+}

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

@@ -0,0 +1,28 @@
+import type { Comparator } from '../../common';
+export interface TreeSetOptions<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;
+}
+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;