@procedures/collections 0.0.0-stage → 0.2.0

package/src/interfaces/queue.ts

@@ -0,0 +1,353 @@
+/**
+ * Queue and Deque interfaces that mirror Java's Queue and Deque.
+ *
+ * Queues are collections designed for holding elements prior to processing.
+ * Deques (double-ended queues) allow efficient insertion/removal at both ends.
+ */
+
+import type { Collection, ReadonlyCollection } from "./collection.js";
+import type { Compare } from "../core/traits.js";
+
+/**
+ * ReadonlyQueue<T> - Readonly FIFO (First-In-First-Out) queue.
+ *
+ * Provides read-only access to queue operations.
+ */
+export interface ReadonlyQueue<T> extends ReadonlyCollection<T> {
+  /**
+   * Retrieves, but does not remove, the head of this queue.
+   *
+   * @returns The head element
+   * @throws Error if queue is empty
+   */
+  peek(): T;
+
+  /**
+   * Returns the head element without throwing if empty.
+   * Returns undefined if queue is empty.
+   */
+  peekOrUndefined(): T | undefined;
+}
+
+/**
+ * Queue<T> - FIFO (First-In-First-Out) queue.
+ *
+ * Mirrors java.util.Queue.
+ * Elements are processed in the order they were added.
+ */
+export interface Queue<T> extends ReadonlyQueue<T>, Collection<T> {
+  /**
+   * Inserts an element into the queue.
+   * For bounded queues with overflow='throw', throws if queue is full.
+   *
+   * @param element The element to add
+   * @returns true if element was added
+   * @throws Error if queue is full (bounded with throw policy)
+   */
+  offer(element: T): boolean;
+
+  /**
+   * Retrieves and removes the head of this queue.
+   *
+   * @returns The head element
+   * @throws Error if queue is empty
+   */
+  poll(): T;
+
+  /**
+   * Retrieves and removes the head of this queue, or returns undefined if empty.
+   */
+  pollOrUndefined(): T | undefined;
+
+  /**
+   * Alias for offer(). Adds element to end of queue.
+   * Included for consistency with standard queue terminology.
+   */
+  enqueue(element: T): boolean;
+
+  /**
+   * Alias for poll(). Removes and returns element from front of queue.
+   * Included for consistency with standard queue terminology.
+   */
+  dequeue(): T;
+}
+
+/**
+ * Deque<T> - Double-ended queue.
+ *
+ * Mirrors java.util.Deque.
+ * Supports insertion and removal at both ends.
+ * Can be used as a queue (FIFO) or stack (LIFO).
+ */
+export interface Deque<T> extends Queue<T> {
+  // First element operations (head of queue)
+
+  /**
+   * Inserts element at the front of this deque.
+   *
+   * @param element The element to add
+   * @throws Error if deque is full (bounded with throw policy)
+   */
+  addFirst(element: T): void;
+
+  /**
+   * Inserts element at the front, returning false if full.
+   */
+  offerFirst(element: T): boolean;
+
+  /**
+   * Retrieves and removes the first element.
+   *
+   * @throws Error if deque is empty
+   */
+  removeFirst(): T;
+
+  /**
+   * Retrieves and removes the first element, or undefined if empty.
+   */
+  pollFirst(): T | undefined;
+
+  /**
+   * Retrieves but does not remove the first element.
+   *
+   * @throws Error if deque is empty
+   */
+  peekFirst(): T;
+
+  /**
+   * Retrieves but does not remove the first element, or undefined if empty.
+   */
+  peekFirstOrUndefined(): T | undefined;
+
+  // Last element operations (tail of queue)
+
+  /**
+   * Inserts element at the end of this deque.
+   *
+   * @param element The element to add
+   * @throws Error if deque is full (bounded with throw policy)
+   */
+  addLast(element: T): void;
+
+  /**
+   * Inserts element at the end, returning false if full.
+   */
+  offerLast(element: T): boolean;
+
+  /**
+   * Retrieves and removes the last element.
+   *
+   * @throws Error if deque is empty
+   */
+  removeLast(): T;
+
+  /**
+   * Retrieves and removes the last element, or undefined if empty.
+   */
+  pollLast(): T | undefined;
+
+  /**
+   * Retrieves but does not remove the last element.
+   *
+   * @throws Error if deque is empty
+   */
+  peekLast(): T;
+
+  /**
+   * Retrieves but does not remove the last element, or undefined if empty.
+   */
+  peekLastOrUndefined(): T | undefined;
+
+  // Stack operations (LIFO). As on a JavaScript array and on every List of this package,
+  // push and pop work at the end. (Java's Deque uses the front.) The top of the stack is peekLast().
+
+  /**
+   * Pushes element onto the stack represented by this deque.
+   * Equivalent to addLast().
+   *
+   * @param element The element to push
+   */
+  push(element: T): void;
+
+  /**
+   * Pops an element from the stack represented by this deque.
+   * Equivalent to removeLast().
+   *
+   * @returns The popped element
+   * @throws Error if deque is empty
+   */
+  pop(): T;
+}
+
+/**
+ * BlockingQueue<T> - Queue that supports blocking operations.
+ *
+ * Mirrors java.util.concurrent.BlockingQueue.
+ * Useful for producer-consumer patterns.
+ */
+export interface BlockingQueue<T> extends Queue<T> {
+  /**
+   * Inserts element, waiting if necessary for space to become available.
+   *
+   * @param element The element to add
+   * @param timeoutMs Optional timeout in milliseconds
+   * @returns Promise that resolves to true when element is added
+   * @throws Error if timeout expires
+   */
+  put(element: T, timeoutMs?: number): Promise<void>;
+
+  /**
+   * Retrieves and removes the head, waiting if necessary until an element is available.
+   *
+   * @param timeoutMs Optional timeout in milliseconds
+   * @returns Promise that resolves to the head element
+   * @throws Error if timeout expires
+   */
+  take(timeoutMs?: number): Promise<T>;
+
+  /**
+   * Returns the remaining capacity.
+   * Returns Infinity for unbounded queues.
+   */
+  readonly remainingCapacity: number;
+
+  /**
+   * Removes all available elements and adds them to the given array.
+   * Returns the number of elements transferred.
+   */
+  drainTo(target: T[], maxElements?: number): number;
+}
+
+/**
+ * PriorityQueue<T> - Queue that orders elements by priority.
+ *
+ * Mirrors java.util.PriorityQueue.
+ * Elements are removed in priority order (not insertion order).
+ * Requires a comparison function to determine priority.
+ */
+export interface PriorityQueue<T> extends Queue<T> {
+  /**
+   * The comparison function used to determine priority.
+   * Elements with lower compare value have higher priority.
+   */
+  readonly compare: Compare<T>;
+
+  /**
+   * Returns the comparator used to order elements, or undefined if natural ordering.
+   */
+  readonly comparator: Compare<T> | undefined;
+}
+
+/**
+ * AsyncQueue<T> - Async iterable queue.
+ *
+ * Designed for async/await patterns and streaming data.
+ * Implements AsyncIterable for use with for-await-of loops.
+ */
+export interface AsyncQueue<T> extends AsyncIterable<T> {
+  /** Number of elements currently in queue */
+  readonly size: number;
+
+  /** True if queue is empty */
+  readonly isEmpty: boolean;
+
+  /**
+   * Adds element to queue.
+   * For bounded queues, may wait for space to become available.
+   */
+  put(element: T): Promise<void>;
+
+  /**
+   * Removes and returns next element.
+   * Waits for an element if queue is empty.
+   */
+  take(): Promise<T>;
+
+  /**
+   * Attempts to add element without waiting.
+   * Returns false if queue is full.
+   */
+  tryPut(element: T): boolean;
+
+  /**
+   * Attempts to remove element without waiting.
+   * Returns undefined if queue is empty.
+   */
+  tryTake(): T | undefined;
+
+  /**
+   * Returns next element without removing it.
+   * Waits for an element if queue is empty.
+   */
+  peek(): Promise<T>;
+
+  /**
+   * Closes the queue, preventing further additions.
+   * Allows existing elements to be consumed.
+   */
+  close(): void;
+
+  /**
+   * Returns true if queue is closed.
+   */
+  readonly isClosed: boolean;
+}
+
+/**
+ * TransferQueue<T> - Queue where producers can wait for consumers.
+ *
+ * Mirrors java.util.concurrent.TransferQueue.
+ * Useful for direct handoff between producer and consumer threads.
+ */
+export interface TransferQueue<T> extends BlockingQueue<T> {
+  /**
+   * Transfers element to consumer, waiting if necessary.
+   * Waits for a consumer to receive the element.
+   *
+   * @param element The element to transfer
+   * @returns Promise that resolves when element is received
+   */
+  transfer(element: T): Promise<void>;
+
+  /**
+   * Attempts to transfer element to waiting consumer.
+   * Returns false immediately if no consumer is waiting.
+   *
+   * @param element The element to transfer
+   * @param timeoutMs Optional timeout in milliseconds
+   */
+  tryTransfer(element: T, timeoutMs?: number): Promise<boolean>;
+
+  /**
+   * Returns true if there are consumers waiting to receive elements.
+   */
+  readonly hasWaitingConsumer: boolean;
+
+  /**
+   * Returns an estimate of the number of consumers waiting to receive elements.
+   */
+  readonly waitingConsumerCount: number;
+}
+
+/**
+ * DelayQueue<T> - Queue where elements become available after a delay.
+ *
+ * Mirrors java.util.concurrent.DelayQueue.
+ * Elements can only be removed once their delay has expired.
+ */
+export interface DelayQueue<T> extends BlockingQueue<T> {
+  /**
+   * Adds element with specified delay.
+   *
+   * @param element The element to add
+   * @param delayMs Delay in milliseconds before element becomes available (defaults to 0)
+   */
+  offer(element: T, delayMs?: number): boolean;
+
+  /**
+   * Returns the delay (in ms) until next element becomes available.
+   * Returns 0 if element is ready now.
+   * Returns Infinity if queue is empty.
+   */
+  readonly nextDelay: number;
+}

package/src/interfaces/set.ts

@@ -0,0 +1,158 @@
+/**
+ * Set interfaces that mirror Java's Set interface hierarchy.
+ *
+ * Sets are collections that contain no duplicate elements.
+ * They provide efficient membership testing.
+ */
+
+import type { Collection, ReadonlyCollection } from "./collection.js";
+import type { Compare } from "../core/traits.js";
+
+/**
+ * ReadonlySet<T> - Readonly set with no duplicates.
+ */
+export interface ReadonlySet<T> extends ReadonlyCollection<T> {
+  /**
+   * Returns true if this set contains the specified element.
+   */
+  contains(element: T): boolean;
+
+  /**
+   * Returns true if this set contains all elements in the specified collection.
+   */
+  containsAll(other: Iterable<T>): boolean;
+}
+
+/**
+ * Set<T> - Mutable set with no duplicates.
+ *
+ * Mirrors java.util.Set.
+ * Elements are unique based on the set's equality function.
+ */
+export interface Set<T> extends ReadonlySet<T>, Collection<T> {
+  /**
+   * Adds the specified element to this set if it is not already present.
+   *
+   * @returns true if this set did not already contain the element
+   */
+  add(element: T): boolean;
+
+  /**
+   * Removes the specified element from this set if it is present.
+   *
+   * @returns true if this set contained the element
+   */
+  remove(element: T): boolean;
+
+  /**
+   * Adds all elements in the specified collection to this set.
+   * This is a union operation.
+   *
+   * @returns true if this set changed
+   */
+  addAll(other: Iterable<T>): boolean;
+
+  /**
+   * Removes from this set all of its elements that are contained in the specified collection.
+   * This is a difference operation.
+   *
+   * @returns true if this set changed
+   */
+  removeAll(other: Iterable<T>): boolean;
+
+  /**
+   * Retains only the elements in this set that are contained in the specified collection.
+   * This is an intersection operation.
+   *
+   * @returns true if this set changed
+   */
+  retainAll(other: Iterable<T>): boolean;
+}
+
+/**
+ * SortedSet<T> - Set that maintains elements in sorted order.
+ *
+ * Mirrors java.util.SortedSet.
+ */
+export interface SortedSet<T> extends Set<T> {
+  /**
+   * Returns the comparator used to order elements in this set.
+   */
+  readonly comparator: Compare<T>;
+
+  /**
+   * Returns the first (lowest) element in this set.
+   *
+   * @throws Error if set is empty
+   */
+  first(): T;
+
+  /**
+   * Returns the last (highest) element in this set.
+   *
+   * @throws Error if set is empty
+   */
+  last(): T;
+
+  /**
+   * Returns a view of the portion of this set whose elements are strictly less than toElement.
+   */
+  headSet(toElement: T): SortedSet<T>;
+
+  /**
+   * Returns a view of the portion of this set whose elements are greater than or equal to fromElement.
+   */
+  tailSet(fromElement: T): SortedSet<T>;
+
+  /**
+   * Returns a view of the portion of this set whose elements range from fromElement to toElement.
+   */
+  subSet(fromElement: T, toElement: T): SortedSet<T>;
+}
+
+/**
+ * NavigableSet<T> - Extended sorted set with navigation methods.
+ *
+ * Mirrors java.util.NavigableSet.
+ */
+export interface NavigableSet<T> extends SortedSet<T> {
+  /**
+   * Returns the greatest element less than or equal to the given element, or undefined if none.
+   */
+  floor(element: T): T | undefined;
+
+  /**
+   * Returns the least element greater than or equal to the given element, or undefined if none.
+   */
+  ceiling(element: T): T | undefined;
+
+  /**
+   * Returns the greatest element strictly less than the given element, or undefined if none.
+   */
+  lower(element: T): T | undefined;
+
+  /**
+   * Returns the least element strictly greater than the given element, or undefined if none.
+   */
+  higher(element: T): T | undefined;
+
+  /**
+   * Retrieves and removes the first (lowest) element, or returns undefined if empty.
+   */
+  pollFirst(): T | undefined;
+
+  /**
+   * Retrieves and removes the last (highest) element, or returns undefined if empty.
+   */
+  pollLast(): T | undefined;
+
+  /**
+   * Returns a reverse order view of this set.
+   */
+  descendingSet(): NavigableSet<T>;
+
+  /**
+   * Returns a reverse order iterator over the elements in this set.
+   */
+  descendingIterator(): Iterator<T>;
+}

package/src/register.ts

@@ -0,0 +1,8 @@
+/**
+ * Registration Entry Point for client-collections
+ *
+ * This package provides collection interfaces and storage abstractions.
+ * No procedures to register - just re-exports the main module.
+ */
+
+export * from "./index.js";

package/src/storage/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Collection Storage Backends
+ *
+ * Abstract storage layer enabling collections to be backed by:
+ * - In-memory (fast, volatile)
+ *
+ * The backends that need an RPC Client (ApiStorage: remote API, HybridStorage: local
+ * cache + remote sync) live in @procedures/client and are exported from
+ * "@procedures/client/collections". Keeping them there means this package
+ * does not depend on the client package.
+ */
+
+export type { CollectionStorage, StorageMetadata } from "./interface.js";
+export { normalizeStorageResult } from "./interface.js";
+
+export { InMemoryStorage } from "./memory.js";

package/src/storage/interface.ts

@@ -0,0 +1,179 @@
+/**
+ * Collection Storage Interface
+ *
+ * Abstract storage layer for collections, enabling different backends:
+ * - InMemoryStorage: Fast, volatile storage using Map
+ * - ApiStorage: Remote persistence via universal client
+ * - HybridStorage: Local cache + remote sync with conflict resolution
+ * - SyncedStorage: Periodic background sync with offline support
+ *
+ * IMPORTANT: All methods return Promise to ensure client code is
+ * transport-agnostic (cannot distinguish local from remote storage).
+ */
+
+/**
+ * Storage backend interface for collections.
+ *
+ * All methods return Promise<T> to ensure consistent async behavior.
+ * This guarantees client code remains agnostic to the storage backend,
+ * enabling seamless switching between local and remote storage.
+ */
+export interface CollectionStorage<T> {
+  //
+  // ═══ Read Operations ═══
+  //
+
+  /**
+   * Get item by ID.
+   *
+   * @param id - Item identifier
+   * @returns Promise resolving to item or undefined if not found
+   */
+  get(id: string): Promise<T | undefined>;
+
+  /**
+   * Get all items in collection.
+   *
+   * @returns Promise resolving to array of all items
+   */
+  getAll(): Promise<T[]>;
+
+  /**
+   * Find items matching predicate.
+   *
+   * @param predicate - Filter function
+   * @returns Promise resolving to array of matching items
+   */
+  find(predicate: (item: T) => boolean): Promise<T[]>;
+
+  /**
+   * Check if item exists.
+   *
+   * @param id - Item identifier
+   * @returns Promise resolving to true if item exists
+   */
+  has(id: string): Promise<boolean>;
+
+  /**
+   * Get number of items in collection.
+   *
+   * @returns Promise resolving to count of items
+   */
+  size(): Promise<number>;
+
+  //
+  // ═══ Write Operations ═══
+  //
+
+  /**
+   * Set/update item by ID.
+   *
+   * @param id - Item identifier
+   * @param value - Item to store
+   * @returns Promise resolving when operation completes
+   */
+  set(id: string, value: T): Promise<void>;
+
+  /**
+   * Delete item by ID.
+   *
+   * @param id - Item identifier
+   * @returns Promise resolving to true if item was deleted, false if not found
+   */
+  delete(id: string): Promise<boolean>;
+
+  /**
+   * Clear all items from collection.
+   *
+   * @returns Promise resolving when operation completes
+   */
+  clear(): Promise<void>;
+
+  //
+  // ═══ Bulk Operations ═══
+  //
+
+  /**
+   * Set multiple items at once (more efficient than individual sets).
+   *
+   * @param items - Array of [id, value] tuples
+   * @returns Promise resolving when operation completes
+   */
+  setBatch(items: Array<[string, T]>): Promise<void>;
+
+  /**
+   * Delete multiple items at once.
+   *
+   * @param ids - Array of item identifiers
+   * @returns Promise resolving to number of items actually deleted
+   */
+  deleteBatch(ids: string[]): Promise<number>;
+
+  /**
+   * Get multiple items by ID at once.
+   *
+   * @param ids - Array of item identifiers
+   * @returns Promise resolving to Map of found items (missing IDs are omitted)
+   */
+  getBatch(ids: string[]): Promise<Map<string, T>>;
+
+  //
+  // ═══ Lifecycle & Metadata ═══
+  //
+
+  /**
+   * Close storage and cleanup resources.
+   * Should be called when collection is no longer needed.
+   *
+   * @returns Promise resolving when cleanup completes
+   */
+  close(): Promise<void>;
+
+  /**
+   * Get storage metadata/stats (optional).
+   * Useful for monitoring and debugging.
+   *
+   * @returns Promise resolving to storage-specific metadata
+   */
+  getMetadata?(): Promise<StorageMetadata>;
+}
+
+/**
+ * Optional storage metadata for monitoring.
+ */
+export interface StorageMetadata {
+  /** Storage backend type */
+  type: "memory" | "api" | "hybrid" | "synced" | "custom";
+
+  /** Number of items */
+  size: number;
+
+  /** Storage-specific stats */
+  stats?: {
+    /** Cache hit rate (for hybrid/synced storage) */
+    hitRate?: number;
+
+    /** Last sync timestamp (for synced storage) */
+    lastSync?: number;
+
+    /** Pending sync operations (for synced storage) */
+    pendingOps?: number;
+
+    /** Memory usage in bytes (for memory storage) */
+    memoryUsage?: number;
+
+    /** Custom stats */
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * @deprecated All storage methods now return Promise.
+ * This helper is kept for backward compatibility but is no longer needed.
+ *
+ * @param value - Promise value
+ * @returns The same Promise
+ */
+export function normalizeStorageResult<T>(value: Promise<T>): Promise<T> {
+  return value;
+}