@procedures/collections 0.46.0 → 0.47.2

package/src/interfaces/queue.ts

@@ -1,353 +0,0 @@
-/**
- * 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

@@ -1,158 +0,0 @@
-/**
- * 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/order/index.ts

@@ -1,6 +0,0 @@
-/**
- * The order of a list as data (Graph's split, wave 2, W1). Each item keeps a string key, and the list
- * sorts by it. An item that moves between two others gets a key between theirs, so a move writes one
- * item and no other.
- */
-export { KEY_DIGITS, keyBetween, keysBetween, keysForDrop, compareKeys, isValidKey, dropIndex, type KeyCheckOptions, type KeyedItem, type Point } from "./rank.js";