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/dist/umd/queue-typed.js

@@ -536,6 +536,12 @@ var queueTyped = (() => {
       }
       return -1;
     }
+    /**
+     * Concatenate lists/elements preserving order.
+     * @param items - Elements or `LinearBase` instances.
+     * @returns New list with combined elements (`this` type).
+     * @remarks Time O(sum(length)), Space O(sum(length))
+     */
     concat(...items) {
       const newList = this.clone();
       for (const item of items) {
@@ -2337,6 +2343,12 @@ var queueTyped = (() => {
      */
     _setBucketSize(size) {
       this._bucketSize = size;
+      if (this._length === 0) {
+        this._buckets = [new Array(this._bucketSize)];
+        this._bucketCount = 1;
+        this._bucketFirst = this._bucketLast = 0;
+        this._firstInBucket = this._lastInBucket = this._bucketSize >> 1;
+      }
     }
     /**
      * (Protected) Iterate elements from front to back.