@mark1russell7/collections 0.0.0-stage → 0.1.0

package/src/impl/tree-set.ts

@@ -0,0 +1,469 @@
+/**
+ * TreeSet - Red-black tree based sorted set implementation.
+ *
+ * This module implements a sorted set using TreeMap as the backing structure.
+ * Mirrors java.util.TreeSet.
+ *
+ * Key features:
+ * - O(log n) add, remove, contains
+ * - Elements maintained in sorted order (natural or custom comparator)
+ * - Navigation methods (floor, ceiling, lower, higher)
+ * - Range view operations (subSet, headSet, tailSet)
+ *
+ * @example
+ * const set = treeSet<string>()
+ * set.add('c')
+ * set.add('a')
+ * set.add('b')
+ * // Iteration order: a, b, c (sorted)
+ *
+ * @example
+ * // Custom comparator for descending order
+ * const set = treeSet<number>({
+ *   compare: (a, b) => b - a
+ * })
+ */
+
+import type { SortedSet, NavigableSet } from "../interfaces/set.js";
+import type { Eq, Compare } from "../core/traits.js";
+import { TreeMap } from "./tree-map.js";
+import { defaultEq, defaultCompare } from "../utils/defaults.js";
+
+/**
+ * Dummy value used for TreeMap backing.
+ */
+const PRESENT = true;
+
+/**
+ * Options for making a TreeSet.
+ */
+export interface TreeSetOptions<T> {
+  /**
+   * Comparison function for elements.
+   * @default defaultCompare
+   */
+  compare?: Compare<T>;
+
+  /**
+   * Equality function for elements.
+   * @default defaultEq
+   */
+  eq?: Eq<T>;
+}
+
+/**
+ * TreeSet<T> - Red-black tree based sorted set.
+ *
+ * Maintains elements in sorted order using a TreeMap as backing structure.
+ * This class gives O(log n) operations and navigation methods.
+ */
+export class TreeSet<T> implements NavigableSet<T> {
+  private readonly _map: TreeMap<T, boolean>;
+  private readonly _compare: Compare<T>;
+  private readonly _eq: Eq<T>;
+
+  constructor(options: TreeSetOptions<T> = {}) {
+    const {
+      compare = defaultCompare,
+      eq = defaultEq,
+    } = options;
+
+    this._compare = compare;
+    this._eq = eq;
+    this._map = new TreeMap<T, boolean>({
+      compare,
+      eq,
+    });
+  }
+
+  // ========================================================================
+  // Size and state
+  // ========================================================================
+
+  get size(): number {
+    return this._map.size;
+  }
+
+  get isEmpty(): boolean {
+    return this._map.isEmpty;
+  }
+
+  get comparator(): Compare<T> {
+    return this._compare;
+  }
+
+  get eq(): Eq<T> {
+    return this._eq;
+  }
+
+  // ========================================================================
+  // Membership operations
+  // ========================================================================
+
+  has(element: T): boolean {
+    return this._map.has(element);
+  }
+
+  contains(element: T): boolean {
+    return this.has(element);
+  }
+
+  containsAll(other: Iterable<T>): boolean {
+    for (const element of other) {
+      if (!this.has(element)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  // ========================================================================
+  // Modification operations
+  // ========================================================================
+
+  add(element: T): boolean {
+    const oldValue = this._map.set(element, PRESENT);
+    return oldValue === undefined; // Returns true if element was added (not already present)
+  }
+
+  remove(element: T): boolean {
+    const removed = this._map.delete(element);
+    return removed !== undefined;
+  }
+
+  clear(): void {
+    this._map.clear();
+  }
+
+  // ========================================================================
+  // Bulk operations
+  // ========================================================================
+
+  addAll(elements: Iterable<T>): boolean {
+    let modified = false;
+    for (const element of elements) {
+      if (this.add(element)) {
+        modified = true;
+      }
+    }
+    return modified;
+  }
+
+  removeAll(elements: Iterable<T>): boolean {
+    let modified = false;
+    for (const element of elements) {
+      if (this.remove(element)) {
+        modified = true;
+      }
+    }
+    return modified;
+  }
+
+  retainAll(elements: Iterable<T>): boolean {
+    const toRetain = new Set<T>();
+    for (const element of elements) {
+      toRetain.add(element);
+    }
+
+    let modified = false;
+    for (const element of Array.from(this)) {
+      if (!toRetain.has(element)) {
+        this.remove(element);
+        modified = true;
+      }
+    }
+    return modified;
+  }
+
+  // ========================================================================
+  // Set operations
+  // ========================================================================
+
+  union(other: Iterable<T>): TreeSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    for (const element of this) {
+      result.add(element);
+    }
+    for (const element of other) {
+      result.add(element);
+    }
+
+    return result;
+  }
+
+  intersection(other: Iterable<T>): TreeSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    const otherSet = new Set<T>();
+    for (const element of other) {
+      otherSet.add(element);
+    }
+
+    for (const element of this) {
+      if (otherSet.has(element)) {
+        result.add(element);
+      }
+    }
+
+    return result;
+  }
+
+  difference(other: Iterable<T>): TreeSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    const otherSet = new Set<T>();
+    for (const element of other) {
+      otherSet.add(element);
+    }
+
+    for (const element of this) {
+      if (!otherSet.has(element)) {
+        result.add(element);
+      }
+    }
+
+    return result;
+  }
+
+  symmetricDifference(other: Iterable<T>): TreeSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    // Add all elements from this set
+    for (const element of this) {
+      result.add(element);
+    }
+
+    // Toggle elements from other set
+    for (const element of other) {
+      if (result.has(element)) {
+        result.remove(element);
+      } else {
+        result.add(element);
+      }
+    }
+
+    return result;
+  }
+
+  isSubsetOf(other: Iterable<T>): boolean {
+    const otherSet = new Set<T>();
+    for (const element of other) {
+      otherSet.add(element);
+    }
+
+    for (const element of this) {
+      if (!otherSet.has(element)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  isSupersetOf(other: Iterable<T>): boolean {
+    for (const element of other) {
+      if (!this.has(element)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  isDisjointFrom(other: Iterable<T>): boolean {
+    for (const element of other) {
+      if (this.has(element)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  // ========================================================================
+  // SortedSet operations
+  // ========================================================================
+
+  first(): T {
+    const key = this._map.firstKey();
+    return key;
+  }
+
+  last(): T {
+    const key = this._map.lastKey();
+    return key;
+  }
+
+  headSet(toElement: T): SortedSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    for (const element of this) {
+      if (this._compare(element, toElement) < 0) {
+        result.add(element);
+      } else {
+        break; // Elements are sorted
+      }
+    }
+
+    return result;
+  }
+
+  tailSet(fromElement: T): SortedSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    let started = false;
+    for (const element of this) {
+      if (!started && this._compare(element, fromElement) < 0) {
+        continue;
+      }
+      started = true;
+      result.add(element);
+    }
+
+    return result;
+  }
+
+  subSet(fromElement: T, toElement: T): SortedSet<T> {
+    const result = new TreeSet<T>({
+      compare: this._compare,
+      eq: this._eq,
+    });
+
+    for (const element of this) {
+      const cmpFrom = this._compare(element, fromElement);
+      const cmpTo = this._compare(element, toElement);
+
+      if (cmpFrom >= 0 && cmpTo < 0) {
+        result.add(element);
+      } else if (cmpTo >= 0) {
+        break; // Past the range
+      }
+    }
+
+    return result;
+  }
+
+  // ========================================================================
+  // NavigableSet operations
+  // ========================================================================
+
+  floor(element: T): T | undefined {
+    return this._map.floorKey(element);
+  }
+
+  ceiling(element: T): T | undefined {
+    return this._map.ceilingKey(element);
+  }
+
+  lower(element: T): T | undefined {
+    return this._map.lowerKey(element);
+  }
+
+  higher(element: T): T | undefined {
+    return this._map.higherKey(element);
+  }
+
+  pollFirst(): T | undefined {
+    const entry = this._map.pollFirstEntry();
+    return entry?.key;
+  }
+
+  pollLast(): T | undefined {
+    const entry = this._map.pollLastEntry();
+    return entry?.key;
+  }
+
+  descendingSet(): NavigableSet<T> {
+    const reversed = new TreeSet<T>({
+      compare: (a, b) => this._compare(b, a),
+      eq: this._eq,
+    });
+
+    for (const element of this) {
+      reversed.add(element);
+    }
+
+    return reversed;
+  }
+
+  *descendingIterator(): IterableIterator<T> {
+    yield* this._map.descendingKeys();
+  }
+
+  // ========================================================================
+  // View operations
+  // ========================================================================
+
+  *[Symbol.iterator](): Iterator<T> {
+    yield* this._map.keys();
+  }
+
+  forEach(action: (element: T, index: number) => void): void {
+    let index = 0;
+    for (const element of this) {
+      action(element, index++);
+    }
+  }
+
+  toArray(): T[] {
+    return Array.from(this);
+  }
+
+  // ========================================================================
+  // Utility methods
+  // ========================================================================
+
+  toString(): string {
+    const elements = Array.from(this).join(', ');
+    return `TreeSet{${elements}}`;
+  }
+}
+
+/**
+ * Factory function to make a TreeSet.
+ *
+ * @example
+ * const set = treeSet<string>()
+ * set.add('c')
+ * set.add('a')
+ * set.add('b')
+ * // Iteration order: a, b, c
+ *
+ * @example
+ * // With initial elements
+ * const set = treeSet(['c', 'a', 'b'])
+ * // Iteration order: a, b, c
+ *
+ * @example
+ * // Custom comparator for descending order
+ * const set = treeSet<number>({ compare: (a, b) => b - a })
+ */
+export function treeSet<T>(
+  optionsOrElements?: TreeSetOptions<T> | Iterable<T>
+): TreeSet<T> {
+  if (optionsOrElements && Symbol.iterator in optionsOrElements) {
+    const set = new TreeSet<T>();
+    for (const element of optionsOrElements as Iterable<T>) {
+      set.add(element);
+    }
+    return set;
+  }
+
+  return new TreeSet<T>(optionsOrElements as TreeSetOptions<T>);
+}

package/src/index.ts

@@ -0,0 +1,237 @@
+/**
+ * `@mark1russell7/collections`: collections with no dependencies.
+ *
+ * This entry gives the lists, sets, maps, queues, the summary tree, the behaviors, the channels and the lazy
+ * operations. The entries `./dag` and `./graph` give the graph code. The entry `./testing` gives the checks.
+ */
+
+// ============================================================================
+// Core types and utilities
+// ============================================================================
+
+export * from "./core/traits.js";
+export * from "./core/effects.js";
+export * from "./core/policies.js";
+export * from "./core/middleware.js";
+export * from "./core/events.js";
+// ============================================================================
+// Interfaces
+// ============================================================================
+
+export * from "./interfaces/collection.js";
+export * from "./interfaces/list.js";
+export * from "./interfaces/map.js";
+export * from "./interfaces/set.js";
+
+// The listeners of a storage
+export { StorageListeners, reportListenerError, type ListenerErrorHandler } from "./storage/listeners.js";
+
+// The order of a list as data: a rank between two neighbors, and the index of a drop
+export * from "./order/index.js";
+
+// Export queue interfaces with disambiguation for PriorityQueue
+export type {
+  ReadonlyQueue,
+  Queue,
+  Deque,
+  BlockingQueue,
+  PriorityQueue as IPriorityQueue,
+  AsyncQueue as IAsyncQueue,
+  TransferQueue,
+  DelayQueue,
+} from "./interfaces/queue.js";
+
+// ============================================================================
+// Implementations
+// ============================================================================
+
+export * from "./impl/array-list.js";
+export * from "./impl/array-deque.js";
+export * from "./impl/hash-map.js";
+export * from "./impl/linked-hash-map.js";
+export * from "./impl/tree-map.js";
+export * from "./impl/tree-set.js";
+export * from "./impl/linked-list.js";
+export * from "./impl/hash-set.js";
+export * from "./impl/priority-queue.js";
+export { SummaryTree, summaryTree, type SummaryLocation, type SummaryMonoid, type SummarySearch, type SummarySpec } from "./impl/summary-tree.js";
+
+// ============================================================================
+// Behaviors
+// ============================================================================
+
+// Export bounded behaviors (excluding duplicate BoundedCollection interface)
+export {
+  type BoundedOptions,
+  boundedList,
+  boundedQueue,
+  boundedDeque,
+  boundedMap,
+  bounded,
+} from "./behaviors/bounded.js";
+
+export * from "./behaviors/readonly.js";
+export * from "./behaviors/safe.js";
+export * from "./behaviors/evented.js";
+export * from "./behaviors/synchronized.js";
+export * from "./behaviors/lru.js";
+export * from "./behaviors/ttl.js";
+
+// ============================================================================
+// Async/Concurrent
+// ============================================================================
+
+export * from "./async/async-queue.js";
+export * from "./async/channels.js";
+export * from "./async/settled.js";
+
+// ============================================================================
+// Functional Operations
+// ============================================================================
+
+export * from "./fx/iter.js";
+export * from "./fx/collectors.js";
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+export * from "./utils/defaults.js";
+export * from "./utils/factories.js";
+export * from "./utils/helpers.js";
+
+// ============================================================================
+// Re-exports for convenience
+// ============================================================================
+
+// Most commonly used exports
+export { compose, bundle } from "./core/middleware.js";
+export { arrayList } from "./impl/array-list.js";
+export { arrayDeque } from "./impl/array-deque.js";
+export { hashMap } from "./impl/hash-map.js";
+export { linkedHashMap } from "./impl/linked-hash-map.js";
+export { treeMap } from "./impl/tree-map.js";
+export { treeSet } from "./impl/tree-set.js";
+export { linkedList } from "./impl/linked-list.js";
+export { hashSet } from "./impl/hash-set.js";
+export { priorityQueue } from "./impl/priority-queue.js";
+// Common behaviors
+export { readonly, readonlyList, readonlyMap } from "./behaviors/readonly.js";
+export { safeList, safeQueue, safeMap } from "./behaviors/safe.js";
+export { eventedList, eventedQueue, eventedMap } from "./behaviors/evented.js";
+export { synchronized } from "./behaviors/synchronized.js";
+export { lruMap, lruCache, LRUCache } from "./behaviors/lru.js";
+export { ttlMap, ttlCache, TTLCache, ttlCollection } from "./behaviors/ttl.js";
+
+// Async/Concurrent
+export { asyncQueue, AsyncQueue } from "./async/async-queue.js";
+export { asSettled, type Settled } from "./async/settled.js";
+export {
+  channel,
+  Channel,
+  select,
+  timeout,
+  ticker,
+  pipeline,
+  fanOut,
+  fanIn,
+  merge,
+  workerPool,
+} from "./async/channels.js";
+
+// Functional operations
+export {
+  map,
+  filter,
+  flatMap,
+  flatten,
+  take,
+  skip,
+  takeWhile,
+  skipWhile,
+  concat,
+  zip,
+  enumerate,
+  chunk,
+  window,
+  partition,
+  reduce,
+  scan,
+  sort,
+  reverse,
+  distinct,
+  distinctConsecutive,
+  tap,
+  some,
+  every,
+  none,
+  find,
+  count,
+  min,
+  max,
+  sum,
+  average,
+  toArray,
+  toSet,
+  toMap as iterToMap,
+  pipe,
+} from "./fx/iter.js";
+
+export {
+  collect,
+  toList as collectToList,
+  toArray as collectToArray,
+  toSet as collectToSet,
+  toMap as collectToMap,
+  groupingBy,
+  groupingByWith,
+  partitioningBy,
+  counting,
+  summingNumber,
+  averagingNumber,
+  minBy,
+  maxBy,
+  joining,
+  mapping,
+  filtering,
+  flatMapping,
+  reducing,
+  reducingWith,
+  teeing,
+  first,
+  last,
+  summarizingNumber,
+} from "./fx/collectors.js";
+
+// Common factories
+export {
+  emptyList,
+  emptyMap,
+  emptyQueue,
+  singletonList,
+  singletonMap,
+  nCopies,
+  listOf,
+  mapOf,
+  range,
+  rangeTo,
+  toList,
+  toMap,
+  groupBy,
+} from "./utils/factories.js";
+
+// Effects
+export {
+  None,
+  Some,
+  type Option,
+  Ok,
+  Err,
+  type Result,
+  isSome,
+  isNone,
+  isOk,
+  isErr,
+  getOrElse,
+  unwrap,
+} from "./core/effects.js";