@procedures/collections 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,277 @@
+/**
+ * Collections Framework - A comprehensive Java Collections-inspired library for TypeScript.
+ *
+ * Provides:
+ * - Core collection interfaces (List, Set, Queue, Map, etc.)
+ * - Rich implementations (ArrayList, LinkedList, HashSet, HashMap, PriorityQueue, etc.)
+ * - Composable behaviors (bounded, readonly, safe, evented, synchronized, LRU, TTL)
+ * - Functional error handling (Option, Result)
+ * - Event-driven collections with typed events
+ * - Async/concurrent collections (AsyncQueue, Channels with CSP patterns)
+ * - Lazy functional operations (map, filter, reduce, etc.)
+ * - Stream-style collectors (groupBy, counting, summarizing, etc.)
+ * - Pluggable equality/hashing/comparison
+ *
+ * @example
+ * // Composable behaviors
+ * import { arrayList, compose, boundedList, eventedList } from '@common/collections'
+ *
+ * const list = compose(
+ *   eventedList(),
+ *   boundedList({ capacity: 100, policy: 'drop-oldest' })
+ * )(arrayList<number>())
+ *
+ * list.on('add', ({ value }) => console.log('Added:', value))
+ * list.add(42)
+ *
+ * @example
+ * // Functional operations with lazy evaluation
+ * import { pipe, map, filter, take, collect, toList } from '@common/collections'
+ *
+ * const result = pipe(
+ *   [1, 2, 3, 4, 5],
+ *   (it) => map(it, x => x * 2),
+ *   (it) => filter(it, x => x > 5),
+ *   (it) => take(it, 2),
+ *   (it) => collect(it, toList())
+ * )
+ *
+ * @example
+ * // Async channels with Go-style CSP
+ * import { channel, select, timeout, pipeline } from '@common/collections'
+ *
+ * const ch = channel<number>()
+ * await ch.send(42)
+ * const value = await select(
+ *   ch.case(v => v),
+ *   timeout(1000).case(() => null)
+ * )
+ */
+
+// ============================================================================
+// 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";
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+export * from "./storage/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";
+
+// ============================================================================
+// 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";
+
+// ============================================================================
+// 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 {
+  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";

package/src/interfaces/collection.ts

@@ -0,0 +1,141 @@
+/**
+ * Base collection interfaces that mirror Java Collections Framework.
+ *
+ * These form the root of the collection hierarchy and define the
+ * fundamental operations common to all collections.
+ */
+
+import type { Eq } from "../core/traits.js";
+
+/**
+ * ReadonlyCollection<T> - The root interface for readonly collections.
+ *
+ * Mirrors java.util.Collection but without mutation operations.
+ * All collections should extend this or a more specific readonly interface.
+ */
+export interface ReadonlyCollection<T> extends Iterable<T> {
+  /**
+   * Returns the number of elements in this collection.
+   */
+  readonly size: number;
+
+  /**
+   * Returns true if this collection contains no elements.
+   */
+  readonly isEmpty: boolean;
+
+  /**
+   * Returns true if this collection contains the specified element.
+   * Uses the collection's equality function to compare elements.
+   *
+   * @param element The element to check for
+   */
+  contains(element: T): boolean;
+
+  /**
+   * Returns true if this collection contains all elements in the specified collection.
+   *
+   * @param other The collection whose elements to check for
+   */
+  containsAll(other: Iterable<T>): boolean;
+
+  /**
+   * Returns an array containing all elements in this collection.
+   * The returned array is safe to modify (it's a copy).
+   */
+  toArray(): T[];
+
+  /**
+   * Performs the given action for each element.
+   *
+   * @param action The action to perform for each element
+   */
+  forEach(action: (element: T, index: number) => void): void;
+
+  /**
+   * Returns the equality function used by this collection.
+   */
+  readonly eq: Eq<T>;
+}
+
+/**
+ * Collection<T> - The root interface for mutable collections.
+ *
+ * Mirrors java.util.Collection with mutation operations.
+ * All mutable collections should extend this or a more specific interface.
+ */
+export interface Collection<T> extends ReadonlyCollection<T> {
+  /**
+   * Adds an element to this collection.
+   *
+   * Returns true if the collection was modified as a result of this call.
+   * Some collections (like Set) may return false if the element already exists.
+   *
+   * @param element The element to add
+   * @returns true if the collection changed
+   * @throws Error if collection is full (bounded) and policy is 'throw'
+   */
+  add(element: T): boolean;
+
+  /**
+   * Adds all elements from the specified collection to this collection.
+   *
+   * @param other The collection whose elements to add
+   * @returns true if the collection changed
+   */
+  addAll(other: Iterable<T>): boolean;
+
+  /**
+   * Removes a single instance of the specified element from this collection.
+   *
+   * Returns true if an element was removed as a result of this call.
+   *
+   * @param element The element to remove
+   * @returns true if an element was removed
+   */
+  remove(element: T): boolean;
+
+  /**
+   * Removes all elements from this collection that are also in the specified collection.
+   *
+   * @param other The collection whose elements to remove
+   * @returns true if the collection changed
+   */
+  removeAll(other: Iterable<T>): boolean;
+
+  /**
+   * Retains only the elements in this collection that are in the specified collection.
+   * In other words, removes all elements not in the specified collection.
+   *
+   * @param other The collection of elements to retain
+   * @returns true if the collection changed
+   */
+  retainAll(other: Iterable<T>): boolean;
+
+  /**
+   * Removes all elements from this collection.
+   * The collection will be empty after this call returns.
+   */
+  clear(): void;
+}
+
+/**
+ * Utility type to check if a collection is readonly.
+ */
+export type IsReadonly<C> = C extends ReadonlyCollection<any>
+  ? C extends Collection<any>
+    ? false
+    : true
+  : false;
+
+/**
+ * Extract element type from a collection.
+ */
+export type ElementOf<C> = C extends ReadonlyCollection<infer T> ? T : never;
+
+/**
+ * Make a collection readonly by removing mutation methods.
+ */
+export type Readonly<C extends Collection<any>> = C extends Collection<infer T>
+  ? ReadonlyCollection<T>
+  : never;

package/src/interfaces/list.ts

@@ -0,0 +1,281 @@
+/**
+ * List interfaces that mirror Java's List interface.
+ *
+ * Lists are ordered collections that allow duplicate elements
+ * and provide positional (indexed) access to elements.
+ */
+
+import type { Collection, ReadonlyCollection } from "./collection.js";
+import type { Compare } from "../core/traits.js";
+
+/**
+ * ReadonlyList<T> - Readonly ordered collection with indexed access.
+ *
+ * Mirrors java.util.List but without mutation operations.
+ * Elements maintain their insertion order and can be accessed by index.
+ */
+export interface ReadonlyList<T> extends ReadonlyCollection<T> {
+  /**
+   * Returns the element at the specified position.
+   *
+   * @param index The index of the element to return (0-based)
+   * @returns The element at the specified position
+   * @throws RangeError if index is out of bounds
+   */
+  get(index: number): T;
+
+  /**
+   * Returns the index of the first occurrence of the specified element,
+   * or -1 if not found.
+   *
+   * @param element The element to search for
+   * @param fromIndex Optional starting index for the search
+   */
+  indexOf(element: T, fromIndex?: number): number;
+
+  /**
+   * Returns the index of the last occurrence of the specified element,
+   * or -1 if not found.
+   *
+   * @param element The element to search for
+   * @param fromIndex Optional starting index for backwards search
+   */
+  lastIndexOf(element: T, fromIndex?: number): number;
+
+  /**
+   * Returns a view of the portion of this list between fromIndex (inclusive)
+   * and toIndex (exclusive).
+   *
+   * Changes to the sublist are reflected in the original list.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  subList(fromIndex: number, toIndex: number): ReadonlyList<T>;
+
+  /**
+   * Returns the first element in the list.
+   *
+   * @throws Error if list is empty
+   */
+  first(): T;
+
+  /**
+   * Returns the last element in the list.
+   *
+   * @throws Error if list is empty
+   */
+  last(): T;
+}
+
+/**
+ * List<T> - Mutable ordered collection with indexed access.
+ *
+ * Mirrors java.util.List with full mutation capabilities.
+ * Provides methods to insert, replace, and remove elements by index.
+ */
+export interface List<T> extends ReadonlyList<T>, Collection<T> {
+  /**
+   * Replaces the element at the specified position.
+   *
+   * @param index The index of the element to replace
+   * @param element The new element
+   * @returns The element previously at the specified position
+   * @throws RangeError if index is out of bounds
+   */
+  set(index: number, element: T): T;
+
+  /**
+   * Inserts an element at the specified position.
+   * Shifts elements at and after the position to the right.
+   *
+   * @param index The index at which to insert
+   * @param element The element to insert
+   * @throws RangeError if index is out of bounds (0 to size inclusive)
+   */
+  insert(index: number, element: T): void;
+
+  /**
+   * Inserts all elements from the specified collection at the specified position.
+   *
+   * @param index The index at which to insert
+   * @param other The collection whose elements to insert
+   * @returns true if the list changed
+   */
+  insertAll(index: number, other: Iterable<T>): boolean;
+
+  /**
+   * Removes the element at the specified position.
+   * Shifts elements after the position to the left.
+   *
+   * @param index The index of the element to remove
+   * @returns The element that was removed
+   * @throws RangeError if index is out of bounds
+   */
+  removeAt(index: number): T;
+
+  /**
+   * Removes elements in the specified index range.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  removeRange(fromIndex: number, toIndex: number): void;
+
+  /**
+   * Sorts this list according to the specified comparator.
+   *
+   * @param compare The comparison function
+   */
+  sort(compare?: Compare<T>): void;
+
+  /**
+   * Reverses the order of elements in this list.
+   */
+  reverse(): void;
+
+  /**
+   * Returns a mutable sublist view.
+   *
+   * @param fromIndex Start index (inclusive)
+   * @param toIndex End index (exclusive)
+   */
+  subList(fromIndex: number, toIndex: number): List<T>;
+
+  // Stack-like operations
+
+  /**
+   * Appends an element to the end of this list.
+   * Equivalent to add() but doesn't return boolean.
+   *
+   * @param element The element to append
+   */
+  push(element: T): void;
+
+  /**
+   * Removes and returns the last element in this list.
+   *
+   * @returns The last element
+   * @throws Error if list is empty
+   */
+  pop(): T;
+
+  /**
+   * Removes and returns the first element in this list.
+   *
+   * @returns The first element
+   * @throws Error if list is empty
+   */
+  shift(): T;
+
+  /**
+   * Prepends an element to the beginning of this list.
+   *
+   * @param element The element to prepend
+   */
+  unshift(element: T): void;
+}
+
+/**
+ * RandomAccess - Marker interface for lists with O(1) indexed access.
+ *
+ * Indicates that the list provides fast (constant-time) random access.
+ * Examples: ArrayList (yes), LinkedList (no).
+ */
+export interface RandomAccess {
+  /**
+   * Marker property to indicate random access capability.
+   * Always true for collections implementing this interface.
+   */
+  readonly supportsRandomAccess: true;
+}
+
+/**
+ * Stack<T> - LIFO (Last-In-First-Out) collection.
+ *
+ * A stack of elements with push/pop operations.
+ * Can be implemented as a specialized list or standalone.
+ */
+export interface Stack<T> extends Iterable<T> {
+  /** Number of elements */
+  readonly size: number;
+
+  /** True if empty */
+  readonly isEmpty: boolean;
+
+  /**
+   * Pushes an element onto the stack.
+   */
+  push(element: T): void;
+
+  /**
+   * Removes and returns the top element.
+   *
+   * @throws Error if stack is empty
+   */
+  pop(): T;
+
+  /**
+   * Returns the top element without removing it.
+   *
+   * @throws Error if stack is empty
+   */
+  peek(): T;
+
+  /**
+   * Removes all elements.
+   */
+  clear(): void;
+
+  /**
+   * Searches for an element and returns its distance from the top.
+   * Returns -1 if not found.
+   */
+  search(element: T): number;
+}
+
+/**
+ * Vector<T> - Synchronized growable array.
+ *
+ * Like ArrayList but with synchronized access.
+ * Legacy interface from Java; in our framework, use compose(synchronized())(arrayList()) instead.
+ */
+export interface Vector<T> extends List<T> {
+  /**
+   * Current capacity of the underlying array.
+   */
+  readonly capacity: number;
+
+  /**
+   * Trims capacity to current size to minimize memory usage.
+   */
+  trimToSize(): void;
+
+  /**
+   * Increases capacity to ensure it can hold at least the specified number of elements.
+   */
+  ensureCapacity(minCapacity: number): void;
+}
+
+/**
+ * CircularList<T> - List with circular/ring buffer behavior.
+ *
+ * When capacity is reached, oldest elements are overwritten.
+ * Useful for fixed-size buffers like logs or history.
+ */
+export interface CircularList<T> extends List<T> {
+  /**
+   * Maximum capacity of the circular list.
+   */
+  readonly capacity: number;
+
+  /**
+   * Returns true if the list has reached capacity.
+   */
+  readonly isFull: boolean;
+
+  /**
+   * Number of elements that have been overwritten.
+   */
+  readonly overwriteCount: number;
+}