sorted-collections 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,431 @@
+/**
+ * A standard JS/TS comparator: negative if `a` sorts before `b`, positive if
+ * after, zero if equal.
+ */
+type Comparator<T> = (a: T, b: T) => number;
+interface SortedOptions<T> {
+    comparator?: Comparator<T>;
+}
+interface SortedOptionsRequired<T> {
+    comparator: Comparator<T>;
+}
+/** Types with a natural order (`<`/`>`) usable without an explicit comparator. */
+type NaturallyOrderable = number | string;
+/**
+ * Rest-tuple used in constructors so TypeScript enforces a comparator at
+ * compile time for any `T` that isn't naturally orderable, while keeping it
+ * optional for `number`/`string`.
+ */
+type ComparatorArg<T> = T extends NaturallyOrderable ? [options?: SortedOptions<T>] : [options: SortedOptionsRequired<T>];
+
+/**
+ * A list that keeps its elements in sorted order as they're inserted.
+ *
+ * A thin public wrapper around the internal {@link BucketEngine} — see there
+ * for the actual "list of lists" (sqrt-decomposition) implementation and its
+ * complexity notes.
+ *
+ * @example
+ * ```ts
+ * const scores = new SortedList<number>([42, 7, 99]);
+ * scores.add(15);
+ * [...scores]; // [7, 15, 42, 99]
+ * ```
+ */
+declare class SortedList<T> implements Iterable<T> {
+    private readonly engine;
+    /**
+     * @example
+     * ```ts
+     * new SortedList<number>(); // empty
+     * new SortedList<number>([3, 1, 2]); // [1, 2, 3]
+     * new SortedList<Person>([...], { comparator: (a, b) => a.age - b.age });
+     * ```
+     */
+    constructor(iterable?: Iterable<T>, ...options: ComparatorArg<T>);
+    /** Safe to call from subclasses/clone: both `ComparatorArg<T>` branches accept `{ comparator }`. */
+    protected comparatorArg(): ComparatorArg<T>;
+    /**
+     * O(√n) amortized.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>();
+     * scores.add(42);
+     * scores.add(7);
+     * [...scores]; // [7, 42]
+     * ```
+     */
+    add(value: T): void;
+    /**
+     * Bulk-inserts every value from `iterable`, one {@link add} at a time.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([3, 1]);
+     * scores.update([2, 5, 4]);
+     * [...scores]; // [1, 2, 3, 4, 5]
+     * ```
+     */
+    update(iterable: Iterable<T>): void;
+    /**
+     * Removes the first occurrence of `value`. Returns `false` if it wasn't present.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([1, 2, 2, 3]);
+     * scores.remove(2); // true — removes one occurrence
+     * scores.remove(99); // false — not present
+     * ```
+     */
+    remove(value: T): boolean;
+    /**
+     * Like {@link remove}, but never throws (or returns anything) if `value` isn't present.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([1, 2, 3]);
+     * scores.discard(99); // no-op, no error
+     * ```
+     */
+    discard(value: T): void;
+    /**
+     * Removes and returns the element at `index` (default: the last element).
+     * Negative indices count from the end, same as {@link at}.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([10, 20, 30]);
+     * scores.pop(); // 30 — last element
+     * scores.pop(0); // 10 — first element
+     * ```
+     */
+    pop(index?: number): T;
+    /**
+     * O(√n): walks bucket lengths to find the element at `index` (negative indices count from the end).
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([10, 20, 30]);
+     * scores.at(0); // 10
+     * scores.at(-1); // 30 — same as Array.prototype.at
+     * scores.at(99); // undefined — out of range
+     * ```
+     */
+    at(index: number): T | undefined;
+    /**
+     * The index of the first occurrence of `value`, or `-1` if absent.
+     *
+     * @example
+     * ```ts
+     * new SortedList<number>([1, 2, 2, 3]).indexOf(2); // 1
+     * new SortedList<number>([1, 2, 3]).indexOf(99); // -1
+     * ```
+     */
+    indexOf(value: T): number;
+    /**
+     * O(log n): binary search for the bucket, then binary search within it.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([1, 2, 3]);
+     * scores.has(2); // true
+     * scores.has(99); // false
+     * ```
+     */
+    has(value: T): boolean;
+    /**
+     * The leftmost index where `value` could be inserted while keeping the list sorted.
+     *
+     * @example
+     * ```ts
+     * new SortedList<number>([1, 2, 2, 2, 3]).bisectLeft(2); // 1
+     * ```
+     */
+    bisectLeft(value: T): number;
+    /**
+     * The rightmost index where `value` could be inserted while keeping the list sorted.
+     *
+     * @example
+     * ```ts
+     * new SortedList<number>([1, 2, 2, 2, 3]).bisectRight(2); // 4
+     * ```
+     */
+    bisectRight(value: T): number;
+    /**
+     * O(log n) to locate both bounds by value + O(k) to iterate the k results.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([1, 2, 3, 4, 5]);
+     * [...scores.irange(2, 4)]; // [2, 3, 4] — inclusive by default
+     * [...scores.irange(2, 4, { inclusive: [false, true] })]; // [3, 4]
+     * ```
+     */
+    irange(min?: T, max?: T, options?: {
+        inclusive?: [boolean, boolean];
+    }): IterableIterator<T>;
+    /**
+     * O(√n) to locate both positional bounds + O(k) to iterate the k results.
+     *
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([10, 20, 30, 40, 50]);
+     * [...scores.islice(1, 4)]; // [20, 30, 40] — like Array.prototype.slice
+     * ```
+     */
+    islice(start?: number, end?: number): IterableIterator<T>;
+    /**
+     * @example
+     * ```ts
+     * new SortedList<number>([1, 2, 3]).length; // 3
+     * ```
+     */
+    get length(): number;
+    /**
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([1, 2, 3]);
+     * scores.clear();
+     * scores.length; // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * An independent copy — mutating the clone never affects the original.
+     *
+     * @example
+     * ```ts
+     * const original = new SortedList<number>([1, 2, 3]);
+     * const copy = original.clone();
+     * copy.add(4);
+     * original.length; // 3
+     * copy.length; // 4
+     * ```
+     */
+    clone(): SortedList<T>;
+    /**
+     * @example
+     * ```ts
+     * const scores = new SortedList<number>([3, 1, 2]);
+     * for (const value of scores) console.log(value); // 1, 2, 3
+     * ```
+     */
+    [Symbol.iterator](): IterableIterator<T>;
+}
+
+/**
+ * Like {@link SortedList}, but rejects duplicates (compared via the
+ * comparator, not reference identity). Adds set-theory operations.
+ *
+ * Reuses `SortedList`'s bucket structure entirely: the only behavioral
+ * difference is that `add` is a no-op for values already present.
+ *
+ * @example
+ * ```ts
+ * const tags = new SortedSet<string>(['b', 'a', 'c', 'a']);
+ * [...tags]; // ['a', 'b', 'c'] — the duplicate 'a' was dropped
+ * ```
+ */
+declare class SortedSet<T> extends SortedList<T> {
+    /**
+     * O(log n) `has` check + O(√n) amortized insert if the value is new.
+     *
+     * @example
+     * ```ts
+     * const tags = new SortedSet<string>(['a']);
+     * tags.add('a'); // no-op, already present
+     * tags.length; // 1
+     * ```
+     */
+    add(value: T): void;
+    /**
+     * @example
+     * ```ts
+     * const original = new SortedSet<number>([1, 2, 3]);
+     * const copy = original.clone();
+     * copy.add(4);
+     * original.length; // 3
+     * ```
+     */
+    clone(): SortedSet<T>;
+    /**
+     * O(m log n + m) for a set of size m being merged in.
+     *
+     * @example
+     * ```ts
+     * const a = new SortedSet<number>([1, 2, 3]);
+     * const b = new SortedSet<number>([3, 4]);
+     * [...a.union(b)]; // [1, 2, 3, 4]
+     * ```
+     */
+    union(other: SortedSet<T>): SortedSet<T>;
+    /**
+     * @example
+     * ```ts
+     * const a = new SortedSet<number>([1, 2, 3]);
+     * const b = new SortedSet<number>([2, 3, 4]);
+     * [...a.intersection(b)]; // [2, 3]
+     * ```
+     */
+    intersection(other: SortedSet<T>): SortedSet<T>;
+    /**
+     * @example
+     * ```ts
+     * const a = new SortedSet<number>([1, 2, 3]);
+     * const b = new SortedSet<number>([2, 3]);
+     * [...a.difference(b)]; // [1] — in a, not in b
+     * ```
+     */
+    difference(other: SortedSet<T>): SortedSet<T>;
+    /**
+     * @example
+     * ```ts
+     * new SortedSet<number>([2, 3]).isSubsetOf(new SortedSet<number>([1, 2, 3, 4])); // true
+     * new SortedSet<number>([1, 5]).isSubsetOf(new SortedSet<number>([1, 2, 3])); // false
+     * ```
+     */
+    isSubsetOf(other: SortedSet<T>): boolean;
+}
+
+/**
+ * A dictionary ordered by key.
+ *
+ * Uses the internal {@link BucketEngine} directly (on `[K, V]` tuples, with a
+ * comparator that only looks at the key) rather than composing over
+ * `SortedList`'s public API. Two reasons: `set` needs the engine's O(log n)
+ * in-place replace-or-insert (`SortedList#bisectLeft` + `#at` would pay for a
+ * positional index it doesn't need), and `get`/`has`/`delete` use the `*By`
+ * lookup methods with a closure over the bare key — that compares the key
+ * only once per candidate (not twice, since the search side needs no
+ * `entry[0]` unwrapping) and avoids allocating a throwaway `[key, undefined]`
+ * search tuple per call.
+ *
+ * @example
+ * ```ts
+ * const byPrice = new SortedMap<number, string>([[101.5, 'order-1'], [99.75, 'order-2']]);
+ * [...byPrice.keys()]; // [99.75, 101.5]
+ * ```
+ */
+declare class SortedMap<K, V> implements Iterable<[K, V]> {
+    private readonly engine;
+    private readonly keyComparator;
+    /**
+     * @example
+     * ```ts
+     * new SortedMap<number, string>(); // empty
+     * new SortedMap<number, string>([[2, 'b'], [1, 'a']]); // ordered by key: 1, 2
+     * ```
+     */
+    constructor(entries?: Iterable<[K, V]>, ...options: ComparatorArg<K>);
+    /**
+     * O(log n) to locate + O(1) to replace in place, or O(√n) amortized to insert.
+     *
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>();
+     * byPrice.set(101.5, 'order-1');
+     * byPrice.set(101.5, 'order-1-updated'); // overwrites, doesn't grow size
+     * ```
+     */
+    set(key: K, value: V): void;
+    /**
+     * O(log n): binary search for the bucket, then binary search within it.
+     *
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[101.5, 'order-1']]);
+     * byPrice.get(101.5); // 'order-1'
+     * byPrice.get(1); // undefined
+     * ```
+     */
+    get(key: K): V | undefined;
+    /**
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[101.5, 'order-1']]);
+     * byPrice.delete(101.5); // true
+     * byPrice.delete(101.5); // false — already gone
+     * ```
+     */
+    delete(key: K): boolean;
+    /**
+     * @example
+     * ```ts
+     * new SortedMap<number, string>([[1, 'a']]).has(1); // true
+     * ```
+     */
+    has(key: K): boolean;
+    /**
+     * A snapshot `SortedSet` of the current keys — not a live view.
+     *
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[2, 'b'], [1, 'a']]);
+     * [...byPrice.keys()]; // [1, 2]
+     * ```
+     */
+    keys(): SortedSet<K>;
+    private keysGenerator;
+    /**
+     * @example
+     * ```ts
+     * [...new SortedMap<number, string>([[2, 'b'], [1, 'a']]).values()]; // ['a', 'b']
+     * ```
+     */
+    values(): IterableIterator<V>;
+    /**
+     * @example
+     * ```ts
+     * [...new SortedMap<number, string>([[2, 'b'], [1, 'a']]).entries()]; // [[1, 'a'], [2, 'b']]
+     * ```
+     */
+    entries(): IterableIterator<[K, V]>;
+    /**
+     * Iterates `[key, value]` pairs with keys in `[minKey, maxKey]`.
+     *
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[95, 'a'], [100, 'b'], [105, 'c']]);
+     * [...byPrice.irange(95, 100)]; // [[95, 'a'], [100, 'b']]
+     * ```
+     */
+    irange(minKey?: K, maxKey?: K): IterableIterator<[K, V]>;
+    /**
+     * O(√n). Entry at ordinal position `index` in key order.
+     *
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[2, 'b'], [1, 'a']]);
+     * byPrice.at(0); // [1, 'a']
+     * ```
+     */
+    at(index: number): [K, V] | undefined;
+    /**
+     * @example
+     * ```ts
+     * new SortedMap<number, string>([[1, 'a'], [2, 'b']]).size; // 2
+     * ```
+     */
+    get size(): number;
+    /**
+     * @example
+     * ```ts
+     * const byPrice = new SortedMap<number, string>([[1, 'a']]);
+     * byPrice.clear();
+     * byPrice.size; // 0
+     * ```
+     */
+    clear(): void;
+    /**
+     * @example
+     * ```ts
+     * for (const [key, value] of new SortedMap([[2, 'b'], [1, 'a']])) {
+     *   console.log(key, value); // 1 'a', then 2 'b'
+     * }
+     * ```
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+}
+
+export { type Comparator, type NaturallyOrderable, SortedList, SortedMap, type SortedOptions, type SortedOptionsRequired, SortedSet };