data-structure-typed 2.3.0 → 2.4.0

package/test/unit/data-structures/binary-tree/tree-set.test.ts

@@ -0,0 +1,187 @@
+import { TreeSet } from '../../../../src';
+
+describe('TreeSet (RedBlackTree-backed, no node exposure)', () => {
+  test('basic operations: add/has/delete/size/isEmpty/clear', () => {
+    const s = new TreeSet<number>();
+    expect(s.isEmpty()).toBe(true);
+    expect(s.size).toBe(0);
+
+    expect(s.add(2)).toBe(s);
+    expect(s.add(1)).toBe(s);
+    expect(s.add(3)).toBe(s);
+    expect(s.size).toBe(3);
+    expect(s.isEmpty()).toBe(false);
+
+    expect(s.has(2)).toBe(true);
+    expect(s.has(999)).toBe(false);
+
+    expect(s.delete(2)).toBe(true);
+    expect(s.delete(2)).toBe(false);
+    expect(s.size).toBe(2);
+
+    s.clear();
+    expect(s.size).toBe(0);
+    expect(s.isEmpty()).toBe(true);
+  });
+
+  test('iteration: keys/values/entries and ordering', () => {
+    const s = new TreeSet<number>([3, 1, 2, 2]);
+    expect([...s]).toEqual([1, 2, 3]);
+    expect([...s.keys()]).toEqual([1, 2, 3]);
+    expect([...s.values()]).toEqual([1, 2, 3]);
+    expect([...s.entries()]).toEqual([
+      [1, 1],
+      [2, 2],
+      [3, 3]
+    ]);
+
+    const seen: number[] = [];
+    const ctx = { ok: true };
+    s.forEach(function (this: typeof ctx, v) {
+      expect(this).toBe(ctx);
+      seen.push(v);
+    }, ctx);
+    expect(seen).toEqual([1, 2, 3]);
+  });
+
+  test('default comparator: NaN throws (even on empty tree)', () => {
+    const s = new TreeSet<number>();
+    expect(() => s.add(Number.NaN)).toThrow(TypeError);
+    expect(() => s.has(Number.NaN)).toThrow(TypeError);
+    expect(() => s.delete(Number.NaN)).toThrow(TypeError);
+    expect(() => s.ceiling(Number.NaN)).toThrow(TypeError);
+  });
+
+  test('constructor throws when encountering invalid keys under default comparator', () => {
+    expect(() => new TreeSet<number>([1, Number.NaN, 2])).toThrow(TypeError);
+
+    const bad = new Date('not-a-date');
+    expect(() => new TreeSet<Date>([bad])).toThrow(TypeError);
+
+    type Obj = { n: number };
+    expect(() => new TreeSet<Obj>([{ n: 1 }])).toThrow(TypeError);
+  });
+
+  test('default comparator: -0 and 0 are the same key', () => {
+    const s = new TreeSet<number>();
+    s.add(-0);
+    expect(s.size).toBe(1);
+    expect(s.has(0)).toBe(true);
+    expect(s.has(-0)).toBe(true);
+
+    s.add(0);
+    expect(s.size).toBe(1);
+  });
+
+  test('default comparator: Date supported; invalid Date throws', () => {
+    const d1 = new Date('2020-01-01T00:00:00.000Z');
+    const d2 = new Date('2021-01-01T00:00:00.000Z');
+    const s = new TreeSet<Date>([d2, d1]);
+    expect([...s]).toEqual([d1, d2]);
+
+    const bad = new Date('not-a-date');
+    const s2 = new TreeSet<Date>();
+    expect(() => s2.add(bad)).toThrow(TypeError);
+  });
+
+  test('default comparator: string key ordering is supported', () => {
+    const s = new TreeSet<string>(['b', 'a', 'c']);
+    expect([...s]).toEqual(['a', 'b', 'c']);
+    expect(s.higher('b')).toBe('c');
+  });
+
+  test('default comparator: non-primitive/non-Date requires custom comparator', () => {
+    type Obj = { n: number };
+    const o1: Obj = { n: 1 };
+
+    expect(() => new TreeSet<Obj>([o1])).toThrow(TypeError);
+
+    const byN = (a: Obj, b: Obj) => a.n - b.n;
+    const s = new TreeSet<Obj>([o1, { n: 2 }], { comparator: byN });
+    expect(s.size).toBe(2);
+  });
+
+  test('createDefaultComparator throws for unsupported key types', () => {
+    const cmp = TreeSet.createDefaultComparator<object>();
+    expect(() => cmp({} as unknown as object, {} as unknown as object)).toThrow(TypeError);
+  });
+
+  test('navigable operations: first/last/pollFirst/pollLast', () => {
+    const s = new TreeSet<number>();
+    expect(s.first()).toBe(undefined);
+    expect(s.last()).toBe(undefined);
+    expect(s.pollFirst()).toBe(undefined);
+    expect(s.pollLast()).toBe(undefined);
+
+    s.add(2).add(1).add(3);
+    expect(s.first()).toBe(1);
+    expect(s.last()).toBe(3);
+
+    expect(s.pollFirst()).toBe(1);
+    expect([...s]).toEqual([2, 3]);
+
+    expect(s.pollLast()).toBe(3);
+    expect([...s]).toEqual([2]);
+  });
+
+  test('navigable operations: ceiling/floor/higher/lower', () => {
+    const s = new TreeSet<number>([1, 3, 5]);
+
+    expect(s.ceiling(0)).toBe(1);
+    expect(s.ceiling(1)).toBe(1);
+    expect(s.ceiling(2)).toBe(3);
+    expect(s.ceiling(6)).toBe(undefined);
+
+    expect(s.floor(0)).toBe(undefined);
+    expect(s.floor(1)).toBe(1);
+    expect(s.floor(2)).toBe(1);
+    expect(s.floor(6)).toBe(5);
+
+    expect(s.higher(1)).toBe(3);
+    expect(s.higher(5)).toBe(undefined);
+
+    expect(s.lower(1)).toBe(undefined);
+    expect(s.lower(5)).toBe(3);
+  });
+
+  test('rangeSearch supports inclusive/exclusive bounds', () => {
+    const s = new TreeSet<number>([1, 2, 3, 4, 5]);
+
+    expect(s.rangeSearch([2, 4])).toEqual([2, 3, 4]);
+    expect(s.rangeSearch([2, 4], { lowInclusive: true, highInclusive: false })).toEqual([2, 3]);
+    expect(s.rangeSearch([2, 4], { lowInclusive: false, highInclusive: true })).toEqual([3, 4]);
+    expect(s.rangeSearch([2, 4], { lowInclusive: false, highInclusive: false })).toEqual([3]);
+  });
+
+  test('map/filter/reduce/every/some/find/toArray/print', () => {
+    const s = new TreeSet<number>([3, 1, 2]);
+
+    expect(s.map(v => v * 2).toArray()).toEqual([2, 4, 6]);
+
+    const ctx = { mul: 3 };
+    expect(
+      s.map(function (this: typeof ctx, v) {
+        return v * this.mul;
+      }, {}, ctx).toArray()
+    ).toEqual([3, 6, 9]);
+
+    expect(s.filter(v => v % 2 === 1).toArray()).toEqual([1, 3]);
+    expect(s.reduce((acc, v) => acc + v, 0)).toBe(6);
+
+    expect(s.every(v => v > 0)).toBe(true);
+    expect(s.every(v => v > 2)).toBe(false);
+
+    expect(s.some(v => v === 2)).toBe(true);
+    expect(s.some(v => v === 999)).toBe(false);
+
+    expect(s.find(v => v >= 2)).toBe(2);
+    expect(s.find(v => v >= 999)).toBe(undefined);
+
+    expect(s.toArray()).toEqual([1, 2, 3]);
+
+    const spy = jest.spyOn(console, 'log').mockImplementation(() => undefined);
+    s.print();
+    expect(spy).toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});

package/test/unit/unrestricted-interconversion.test.ts

@@ -168,19 +168,21 @@ describe('conversions', () => {
   });
 
   it('Entry Array to TreeMultiMap', () => {
-    const treeMulti = new TreeMultiMap<number>(entries);
+    // TreeMultiMap uses bucket semantics: [key, values[]]
+    const bucketEntries: [number, string[]][] = entries.map(([k, v]) => [k, [v]]);
+    const treeMulti = new TreeMultiMap<number, string>(bucketEntries);
     expect(treeMulti.size).toBe(9);
     if (isDebug) treeMulti.print();
     expect([...treeMulti]).toEqual([
-      [1, '1'],
-      [2, '2'],
-      [3, '3'],
-      [4, '4'],
-      [5, '5'],
-      [6, '6'],
-      [7, '7'],
-      [8, '8'],
-      [9, '9']
+      [1, ['1']],
+      [2, ['2']],
+      [3, ['3']],
+      [4, ['4']],
+      [5, ['5']],
+      [6, ['6']],
+      [7, ['7']],
+      [8, ['8']],
+      [9, ['9']]
     ]);
   });
 

package/test/utils/patch.ts

@@ -4,9 +4,9 @@ export async function withMutedConsole<T>(fn: () => T | Promise<T>): Promise<T>
   const originalError = console.error;
 
   // Keep it minimal: silence during the callback, always restore.
-  console.log = (message?: any, ...optionalParams: any[]) => undefined;
-  console.warn = (message?: any, ...optionalParams: any[]) => undefined;
-  console.error = (message?: any, ...optionalParams: any[]) => undefined;
+  console.log = (_message?: any, ..._optionalParams: any[]) => undefined;
+  console.warn = (_message?: any, ..._optionalParams: any[]) => undefined;
+  console.error = (_message?: any, ..._optionalParams: any[]) => undefined;
 
   try {
     return await fn();

package/test/utils/perf.mjs

@@ -0,0 +1,34 @@
+// Re-export utilities for performance tests (ESM)
+export const magnitude = {
+  MILLION: 1000000,
+  HUNDRED_THOUSAND: 100000,
+  TEN_THOUSAND: 10000,
+  THOUSAND: 1000,
+  HUNDRED: 100
+};
+
+export function getRandomInt(min = 0, max = 1000) {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export function getRandomIntArray(length, min = 0, max = 1000) {
+  return Array.from({ length }, () => getRandomInt(min, max));
+}
+
+export function getRandomIndex(length) {
+  return Math.floor(Math.random() * length);
+}
+
+export function getRandomWords(count, minLength = 3, maxLength = 10) {
+  const words = [];
+  const chars = 'abcdefghijklmnopqrstuvwxyz';
+  for (let i = 0; i < count; i++) {
+    const length = getRandomInt(minLength, maxLength);
+    let word = '';
+    for (let j = 0; j < length; j++) {
+      word += chars[Math.floor(Math.random() * chars.length)];
+    }
+    words.push(word);
+  }
+  return words;
+}

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

@@ -1,236 +0,0 @@
-/**
- * data-structure-typed
- *
- * @author Pablo Zeng
- * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
- * @license MIT License
- */
-import type { AVLTreeCounterOptions, BinaryTreeDeleteResult, BSTNOptKeyOrNode, EntryCallback, FamilyPosition, IterationType, RBTNColor } from '../../types';
-import { IBinaryTree } from '../../interfaces';
-import { AVLTree } from './avl-tree';
-/**
- * AVL node with an extra 'count' field; keeps parent/child links.
- * @remarks Time O(1), Space O(1)
- * @template K
- * @template V
- */
-export declare class AVLTreeCounterNode<K = any, V = any> {
-    key: K;
-    value?: V;
-    parent?: AVLTreeCounterNode<K, V>;
-    /**
-     * Create an AVL counter node.
-     * @remarks Time O(1), Space O(1)
-     * @param key - Key of the node.
-     * @param [value] - Associated value (ignored in map mode).
-     * @param [count] - Initial count for this node (default 1).
-     * @returns New AVLTreeCounterNode instance.
-     */
-    constructor(key: K, value?: V, count?: number);
-    _left?: AVLTreeCounterNode<K, V> | null | undefined;
-    /**
-     * Get the left child pointer.
-     * @remarks Time O(1), Space O(1)
-     * @returns Left child node, or null/undefined.
-     */
-    get left(): AVLTreeCounterNode<K, V> | null | undefined;
-    /**
-     * Set the left child and update its parent pointer.
-     * @remarks Time O(1), Space O(1)
-     * @param v - New left child node, or null/undefined.
-     * @returns void
-     */
-    set left(v: AVLTreeCounterNode<K, V> | null | undefined);
-    _right?: AVLTreeCounterNode<K, V> | null | undefined;
-    /**
-     * Get the right child pointer.
-     * @remarks Time O(1), Space O(1)
-     * @returns Right child node, or null/undefined.
-     */
-    get right(): AVLTreeCounterNode<K, V> | null | undefined;
-    /**
-     * Set the right child and update its parent pointer.
-     * @remarks Time O(1), Space O(1)
-     * @param v - New right child node, or null/undefined.
-     * @returns void
-     */
-    set right(v: AVLTreeCounterNode<K, V> | null | undefined);
-    _height: number;
-    /**
-     * Gets the height of the node (used in self-balancing trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The height.
-     */
-    get height(): number;
-    /**
-     * Sets the height of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new height.
-     */
-    set height(value: number);
-    _color: RBTNColor;
-    /**
-     * Gets the color of the node (used in Red-Black trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The node's color.
-     */
-    get color(): RBTNColor;
-    /**
-     * Sets the color of the node.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new color.
-     */
-    set color(value: RBTNColor);
-    _count: number;
-    /**
-     * Gets the count of nodes in the subtree rooted at this node (used in order-statistic trees).
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The subtree node count.
-     */
-    get count(): number;
-    /**
-     * Sets the count of nodes in the subtree.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @param value - The new count.
-     */
-    set count(value: number);
-    /**
-     * Gets the position of the node relative to its parent.
-     * @remarks Time O(1), Space O(1)
-     *
-     * @returns The family position (e.g., 'ROOT', 'LEFT', 'RIGHT').
-     */
-    get familyPosition(): FamilyPosition;
-}
-/**
- * AVL tree that tracks an aggregate 'count' across nodes; supports balanced insert/delete and map-like mode.
- * @remarks Time O(1), Space O(1)
- * @template K
- * @template V
- * @template R
- */
-export declare class AVLTreeCounter<K = any, V = any, R = any> extends AVLTree<K, V, R> implements IBinaryTree<K, V, R> {
-    /**
-     * Create a AVLTreeCounter instance
-     * @remarks Time O(n), Space O(n)
-     * @param keysNodesEntriesOrRaws
-     * @param options
-     * @returns New AVLTreeCounterNode instance.
-     */
-    constructor(keysNodesEntriesOrRaws?: Iterable<K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined | R>, options?: AVLTreeCounterOptions<K, V, R>);
-    protected _count: number;
-    get count(): number;
-    /**
-     * Compute the total count by traversing the tree (sums node.count).
-     * @remarks Time O(N), Space O(H)
-     * @returns Total count recomputed from nodes.
-     */
-    getComputedCount(): number;
-    createNode(key: K, value?: V, count?: number): AVLTreeCounterNode<K, V>;
-    /**
-     * Type guard: check whether the input is an AVLTreeCounterNode.
-     * @remarks Time O(1), Space O(1)
-     * @returns True if the value is an AVLTreeCounterNode.
-     */
-    isNode(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined): keyNodeOrEntry is AVLTreeCounterNode<K, V>;
-    /**
-     * Insert or increment a node and update aggregate count.
-     * @remarks Time O(log N), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry to insert.
-     * @param [value] - Value when a bare key is provided (ignored in map mode).
-     * @param [count] - How much to increase the node's count (default 1).
-     * @returns True if inserted/updated; false if ignored.
-     */
-    set(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): boolean;
-    /**
-     * Delete a node (or decrement its count) and rebalance if needed.
-     * @remarks Time O(log N), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry identifying the node.
-     * @param [ignoreCount] - If true, remove the node regardless of its count.
-     * @returns Array of deletion results including deleted node and a rebalance hint when present.
-     */
-    delete(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, ignoreCount?: boolean): BinaryTreeDeleteResult<AVLTreeCounterNode<K, V>>[];
-    /**
-     * Remove all nodes and reset aggregate counters.
-     * @remarks Time O(N), Space O(1)
-     * @returns void
-     */
-    clear(): void;
-    /**
-     * Rebuild the tree into a perfectly balanced form using in-order nodes.
-     * @remarks Time O(N), Space O(N)
-     * @param [iterationType] - Traversal style to use when constructing the balanced tree.
-     * @returns True if rebalancing succeeded (tree not empty).
-     */
-    perfectlyBalance(iterationType?: IterationType): boolean;
-    /**
-     * Deep copy this tree, preserving map mode and aggregate counts.
-     * @remarks Time O(N), Space O(N)
-     * @returns A deep copy of this tree.
-     */
-    clone(): this;
-    /**
-     * Create a new AVLTreeCounter by mapping each [key, value] entry.
-     * @remarks Time O(N log N), Space O(N)
-     * @template MK
-     * @template MV
-     * @template MR
-     * @param callback - Function mapping (key, value, index, tree) → [newKey, newValue].
-     * @param [options] - Options for the output tree.
-     * @param [thisArg] - Value for `this` inside the callback.
-     * @returns A new AVLTreeCounter with mapped entries.
-     */
-    map<MK = K, MV = V, MR = any>(callback: EntryCallback<K, V | undefined, [MK, MV]>, options?: Partial<AVLTreeCounterOptions<MK, MV, MR>>, thisArg?: unknown): AVLTreeCounter<MK, MV, MR>;
-    /**
-     * (Protected) Create an empty instance of the same concrete class.
-     * @remarks Time O(1), Space O(1)
-     * @template TK
-     * @template TV
-     * @template TR
-     * @param [options] - Optional constructor options for the like-kind instance.
-     * @returns An empty like-kind instance.
-     */
-    protected _createInstance<TK = K, TV = V, TR = R>(options?: Partial<AVLTreeCounterOptions<TK, TV, TR>>): this;
-    /**
-     * (Protected) Create a like-kind instance and seed it from an iterable.
-     * @remarks Time O(N log N), Space O(N)
-     * @template TK
-     * @template TV
-     * @template TR
-     * @param iter - Iterable used to seed the new tree.
-     * @param [options] - Options merged with the current snapshot.
-     * @returns A like-kind AVLTreeCounter built from the iterable.
-     */
-    protected _createLike<TK = K, TV = V, TR = R>(iter?: Iterable<TK | AVLTreeCounterNode<TK, TV> | [TK | null | undefined, TV | undefined] | null | undefined | TR>, options?: Partial<AVLTreeCounterOptions<TK, TV, TR>>): AVLTreeCounter<TK, TV, TR>;
-    /**
-     * (Protected) Normalize input into a node plus its effective value and count.
-     * @remarks Time O(1), Space O(1)
-     * @param keyNodeOrEntry - Key, node, or [key, value] entry.
-     * @param [value] - Value used when a bare key is provided.
-     * @param [count] - Count increment to apply (default 1).
-     * @returns Tuple [node, value] where node may be undefined.
-     */
-    protected _keyValueNodeOrEntryToNodeAndValue(keyNodeOrEntry: K | AVLTreeCounterNode<K, V> | [K | null | undefined, V | undefined] | null | undefined, value?: V, count?: number): [AVLTreeCounterNode<K, V> | undefined, V | undefined];
-    /**
-     * (Protected) Swap keys/values/counters between the source and destination nodes.
-     * @remarks Time O(1), Space O(1)
-     * @param srcNode - Source node (or key) whose properties will be moved.
-     * @param destNode - Destination node (or key) to receive properties.
-     * @returns Destination node after swap, or undefined.
-     */
-    protected _swapProperties(srcNode: BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>, destNode: BSTNOptKeyOrNode<K, AVLTreeCounterNode<K, V>>): AVLTreeCounterNode<K, V> | undefined;
-    /**
-     * (Protected) Replace one node by another and adjust counters accordingly.
-     * @remarks Time O(1), Space O(1)
-     * @param oldNode - Node being replaced.
-     * @param newNode - Replacement node.
-     * @returns The new node after replacement.
-     */
-    protected _replaceNode(oldNode: AVLTreeCounterNode<K, V>, newNode: AVLTreeCounterNode<K, V>): AVLTreeCounterNode<K, V>;
-}