@mark1russell7/collections 0.9.3 → 0.9.5

package/build/index.d.ts

@@ -287,11 +287,11 @@ export type MergeFunction<T> = (current: T, incoming: T) => T;
  * Policy for when to compact internal storage.
  */
 export interface CompactionPolicy {
-  /** Compact when the used part of the capacity drops below this ratio (0-1). */
+  /** The collection compacts when the used part of its capacity is less than this ratio, from 0 to 1. */
   readonly minLoadFactor?: number;
-  /** Compact when wasted space exceeds this many elements. */
+  /** The collection compacts when its wasted space is more than this number of elements. */
   readonly maxWastedSpace?: number;
-  /** Automatically compact on every removal. */
+  /** When it is true, the collection compacts at each removal. */
   readonly autoCompact?: boolean;
 }
 /**
@@ -463,11 +463,11 @@ export interface Collection<T> extends ReadonlyCollection<T> {
  */
 export type IsReadonly<C> = C extends ReadonlyCollection<any> ? C extends Collection<any> ? false : true : false;
 /**
- * Extract element type from a collection.
+ * This type gives the element type of a collection.
  */
 export type ElementOf<C> = C extends ReadonlyCollection<infer T> ? T : never;
 /**
- * Make a collection readonly by removing mutation methods.
+ * This type makes a collection readonly: it removes the methods that change the collection.
  */
 export type Readonly<C extends Collection<any>> = C extends Collection<infer T> ? ReadonlyCollection<T> : never;
 /**
@@ -532,7 +532,7 @@ export declare const hasCapability: <C extends Collection<any>, K extends keyof
  */
 export interface Evented<E extends Record<string, any>> {
   /**
-   * Subscribe to an event.
+   * This method subscribes a listener to an event.
    * @returns Unsubscribe function
    */
   on<K extends keyof E>(event: K, handler: (payload: E[K]) => void): () => void;
@@ -567,7 +567,7 @@ export interface SafeCollection {
   readonly safe: unknown;
 }
 /**
- * Type helper to extract the element type from a collection.
+ * This type gives the element type of a collection.
  */
 export type ElementType<C> = C extends {
   [Symbol.iterator](): Iterator<infer T>;
@@ -577,7 +577,7 @@ export type ElementType<C> = C extends {
   peek(): infer T;
 } ? T : never;
 /**
- * Type helper to make all methods of a type return their async equivalents.
+ * This type changes each method of a type so that it gives its async equivalent.
  */
 export type Asyncify<C> = { [K in keyof C]: C[K] extends ((...args: infer Args) => infer R) ? (...args: Args) => Promise<R> : C[K]; };
 /**
@@ -634,11 +634,11 @@ export type WithCapability<C, Cap> = C & Cap;
 export declare abstract class CollectionBuilder<C> {
   protected middleware: Middleware<C>[];
   /**
-   * Apply a custom middleware.
+   * This method applies a custom middleware.
    */
   use(middleware: Middleware<C>): this;
   /**
-   * Build the final collection by composing all middleware with the base.
+   * This method builds the final collection: it composes all middleware with the base.
    */
   abstract build(): C;
 }
@@ -720,7 +720,7 @@ export type EventMap = Record<string, any>;
 export declare class Emitter<E extends EventMap> {
   private listeners;
   /**
-   * Subscribe to an event.
+   * This method subscribes a listener to an event.
    *
    * @param event The event name
    * @param listener The callback to invoke when event is emitted
@@ -728,7 +728,7 @@ export declare class Emitter<E extends EventMap> {
    */
   on<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe;
   /**
-   * Subscribe to an event, but automatically unsubscribe after first emission.
+   * This method subscribes a listener to an event, and unsubscribes it after the first emission.
    *
    * @param event The event name
    * @param listener The callback to invoke once
@@ -736,40 +736,40 @@ export declare class Emitter<E extends EventMap> {
    */
   once<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe;
   /**
-   * Emit an event to all registered listeners.
+   * This method emits an event to all registered listeners.
    *
    * @param event The event name
    * @param payload The event payload
    */
   emit<K extends keyof E>(event: K, payload: E[K]): void;
   /**
-   * Remove all listeners for a specific event, or all events if no event specified.
+   * This method removes all listeners of an event, or of all events when the call gives no event.
    *
    * @param event Optional event name to clear listeners for
    */
   off<K extends keyof E>(event?: K): void;
   /**
-   * Get the number of listeners for a specific event.
+   * This method gives the number of listeners of an event.
    *
    * @param event The event name
    * @returns Number of registered listeners
    */
   listenerCount<K extends keyof E>(event: K): number;
   /**
-   * Get all event names that have at least one listener.
+   * This method gives the names of the events that have one or more listeners.
    */
   eventNames(): (keyof E)[];
   /**
-   * Check if there are any listeners for a specific event.
+   * This method gives true when an event has one or more listeners.
    */
   hasListeners<K extends keyof E>(event: K): boolean;
   /**
-   * Remove all listeners and clean up resources.
+   * This method removes all listeners and releases the resources.
    */
   dispose(): void;
 }
 /**
- * Make an event emitter for a specific event map.
+ * This function makes an event emitter for an event map.
  *
  * This is a convenience factory function.
  *
@@ -795,15 +795,15 @@ export declare class EventBatcher<E extends EventMap, K extends keyof E> {
   private timer;
   constructor(emitter: Emitter<E & { [P in `batch-${K & string}`]: E[K][]; }>, event: K, delayMs: number);
   /**
-   * Add an event to the current batch.
+   * This method adds an event to the current batch.
    */
   queue(payload: E[K]): void;
   /**
-   * Immediately emit all batched events.
+   * This method emits all batched events at once.
    */
   flush(): void;
   /**
-   * Clean up resources.
+   * This method sends the events of the batch and releases the resources.
    */
   dispose(): void;
 }
@@ -824,7 +824,7 @@ export declare class AsyncEmitter<E extends EventMap> {
   private listeners;
   on<K extends keyof E>(event: K, listener: Listener<E[K]>): Unsubscribe;
   /**
-   * Emit an event and wait for all async listeners to complete.
+   * This method emits an event and waits until all async listeners complete.
    *
    * @param event The event name
    * @param payload The event payload
@@ -848,7 +848,7 @@ export declare class AsyncEmitter<E extends EventMap> {
  */
 export declare const forwardEvent: <E1 extends EventMap, E2 extends EventMap, K1 extends keyof E1, K2 extends keyof E2>(source: Emitter<E1>, target: Emitter<E2>, sourceEvent: K1, targetEvent: K2, transform?: (payload: E1[K1]) => E2[K2]) => Unsubscribe;
 /**
- * Make a filtered event subscription that only fires when predicate is true.
+ * This function makes a filtered event subscription that fires only when the predicate is true.
  *
  * @example
  * const emitter = new Emitter<{ change: { value: number } }>()
@@ -1025,14 +1025,14 @@ export interface List<T> extends ReadonlyList<T>, Collection<T> {
    */
   push(element: T): void;
   /**
-   * Removes and gives the last element in this list.
+   * This method removes the last element of this list and gives it.
    *
    * @returns The last element
    * @throws Error if list is empty
    */
   pop(): T;
   /**
-   * Removes and gives the first element in this list.
+   * This method removes the first element of this list and gives it.
    *
    * @returns The first element
    * @throws Error if list is empty
@@ -1074,7 +1074,7 @@ export interface Stack<T> extends Iterable<T> {
    */
   push(element: T): void;
   /**
-   * Removes and gives the top element.
+   * This method removes the top element and gives it.
    *
    * @throws Error if stack is empty
    */
@@ -1373,11 +1373,11 @@ export interface NavigableMap<K, V> extends SortedMap<K, V> {
    */
   lastEntry(): Entry<K, V> | undefined;
   /**
-   * Removes and gives the first (lowest) entry, or undefined if empty.
+   * This method removes the first (lowest) entry and gives it, or gives undefined when the map is empty.
    */
   pollFirstEntry(): Entry<K, V> | undefined;
   /**
-   * Removes and gives the last (highest) entry, or undefined if empty.
+   * This method removes the last (highest) entry and gives it, or gives undefined when the map is empty.
    */
   pollLastEntry(): Entry<K, V> | undefined;
   /**
@@ -1582,11 +1582,11 @@ export interface NavigableSet<T> extends SortedSet<T> {
    */
   higher(element: T): T | undefined;
   /**
-   * Retrieves and removes the first (lowest) element, or gives undefined if empty.
+   * This method removes the first (lowest) element and gives it, or gives undefined when the set is empty.
    */
   pollFirst(): T | undefined;
   /**
-   * Retrieves and removes the last (highest) element, or gives undefined if empty.
+   * This method removes the last (highest) element and gives it, or gives undefined when the set is empty.
    */
   pollLast(): T | undefined;
   /**
@@ -1742,7 +1742,7 @@ export declare function dropIndex(point: Point, centers: readonly Point[], rowTo
  */
 interface ReadonlyQueue<T> extends ReadonlyCollection<T> {
   /**
-   * Retrieves, but does not remove, the head of this queue.
+   * This method gives the head of this queue, and does not remove it.
    *
    * @returns The head element
    * @throws Error if queue is empty
@@ -1771,14 +1771,14 @@ interface Queue<T> extends ReadonlyQueue<T>, Collection<T> {
    */
   offer(element: T): boolean;
   /**
-   * Retrieves and removes the head of this queue.
+   * This method removes the head of this queue and gives it.
    *
    * @returns The head element
    * @throws Error if queue is empty
    */
   poll(): T;
   /**
-   * Retrieves and removes the head of this queue, or gives undefined if empty.
+   * This method removes the head of this queue and gives it, or gives undefined when the queue is empty.
    */
   pollOrUndefined(): T | undefined;
   /**
@@ -1787,7 +1787,7 @@ interface Queue<T> extends ReadonlyQueue<T>, Collection<T> {
    */
   enqueue(element: T): boolean;
   /**
-   * Alias for poll(). Removes and gives element from front of queue.
+   * This method is an alias for poll(). It removes the element at the front of the queue and gives it.
    * This method is here for consistency with standard queue terminology.
    */
   dequeue(): T;
@@ -1812,13 +1812,13 @@ interface Deque<T> extends Queue<T> {
    */
   offerFirst(element: T): boolean;
   /**
-   * Retrieves and removes the first element.
+   * This method removes the first element and gives it.
    *
    * @throws Error if deque is empty
    */
   removeFirst(): T;
   /**
-   * Retrieves and removes the first element, or undefined if empty.
+   * This method removes the first element and gives it, or gives undefined when the deque is empty.
    */
   pollFirst(): T | undefined;
   /**
@@ -1843,13 +1843,13 @@ interface Deque<T> extends Queue<T> {
    */
   offerLast(element: T): boolean;
   /**
-   * Retrieves and removes the last element.
+   * This method removes the last element and gives it.
    *
    * @throws Error if deque is empty
    */
   removeLast(): T;
   /**
-   * Retrieves and removes the last element, or undefined if empty.
+   * This method removes the last element and gives it, or gives undefined when the deque is empty.
    */
   pollLast(): T | undefined;
   /**
@@ -1895,7 +1895,7 @@ interface BlockingQueue<T> extends Queue<T> {
    */
   put(element: T, timeoutMs?: number): Promise<void>;
   /**
-   * Retrieves and removes the head, waiting if necessary until an element is available.
+   * This method removes the head and gives it. It waits until an element is available.
    *
    * @param timeoutMs Optional timeout in milliseconds
    * @returns Promise that resolves to the head element
@@ -1948,7 +1948,7 @@ interface AsyncQueue$1<T> extends AsyncIterable<T> {
    */
   put(element: T): Promise<void>;
   /**
-   * Removes and gives next element.
+   * This method removes the next element and gives it.
    * Waits for an element if queue is empty.
    */
   take(): Promise<T>;
@@ -2222,7 +2222,7 @@ export interface HashMapOptions<K, V> {
    */
   initialCapacity?: number;
   /**
-   * Load factor threshold for resizing (0-1).
+   * This option is the load factor threshold for a resize, from 0 to 1.
    * When size > capacity * loadFactor, the map resizes.
    * @default 0.75
    */
@@ -2247,7 +2247,7 @@ export interface HashMapOptions<K, V> {
  * HashMap<K, V> - Hash table implementation with custom equality/hashing.
  *
  * This class uses separate chaining for collision resolution.
- * Automatically resizes when load factor is exceeded.
+ * The map resizes when its load factor is more than the threshold.
  *
  * Not thread-safe. Use synchronized() behavior for concurrent access.
  */
@@ -2350,7 +2350,7 @@ export interface LinkedHashMapOptions<K, V> {
    */
   initialCapacity?: number;
   /**
-   * Load factor before resizing.
+   * This option is the load factor before a resize.
    * @default 0.75
    */
   loadFactor?: number;
@@ -2768,7 +2768,7 @@ export interface HashSetOptions<T> {
    */
   initialCapacity?: number;
   /**
-   * Load factor threshold for resizing.
+   * This option is the load factor threshold for a resize.
    * @default 0.75
    */
   loadFactor?: number;
@@ -3194,23 +3194,23 @@ export declare const unmodifiableCollection: typeof readonlyCollection;
  */
 export interface SafeListOperations<T> {
   /**
-   * Get element at index, as an optional.
+   * This method gives the element at an index, as an optional.
    */
   get(index: number): Optional<T>;
   /**
-   * Set element at index, giving Result with old value or error.
+   * This method sets the element at an index. It gives a Result with the old value or an error.
    */
   set(index: number, element: T): Result<T, string>;
   /**
-   * Remove element at index, giving Result with removed value or error.
+   * This method removes the element at an index. It gives a Result with the removed value or an error.
    */
   removeAt(index: number): Result<T, string>;
   /**
-   * Get first element as an optional.
+   * This method gives the first element, as an optional.
    */
   first(): Optional<T>;
   /**
-   * Get last element as an optional.
+   * This method gives the last element, as an optional.
    */
   last(): Optional<T>;
   /**
@@ -3227,15 +3227,15 @@ export interface SafeListOperations<T> {
  */
 export interface SafeQueueOperations<T> {
   /**
-   * Peek at head element as an optional.
+   * This method gives the head element as an optional, and does not remove it.
    */
   peek(): Optional<T>;
   /**
-   * Poll element as an optional.
+   * This method removes the head element and gives it as an optional.
    */
   poll(): Optional<T>;
   /**
-   * Dequeue element as an optional.
+   * This method dequeues the head element and gives it as an optional.
    */
   dequeue(): Optional<T>;
 }
@@ -3244,23 +3244,23 @@ export interface SafeQueueOperations<T> {
  */
 export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
   /**
-   * Peek at first element as an optional.
+   * This method gives the first element as an optional, and does not remove it.
    */
   peekFirst(): Optional<T>;
   /**
-   * Peek at last element as an optional.
+   * This method gives the last element as an optional, and does not remove it.
    */
   peekLast(): Optional<T>;
   /**
-   * Poll first element as an optional.
+   * This method removes the first element and gives it as an optional.
    */
   pollFirst(): Optional<T>;
   /**
-   * Poll last element as an optional.
+   * This method removes the last element and gives it as an optional.
    */
   pollLast(): Optional<T>;
   /**
-   * Pop element as an optional.
+   * This method pops the top element and gives it as an optional.
    */
   pop(): Optional<T>;
 }
@@ -3269,15 +3269,15 @@ export interface SafeDequeOperations<T> extends SafeQueueOperations<T> {
  */
 export interface SafeMapOperations<K, V> {
   /**
-   * Get value for key as an optional.
+   * This method gives the value of a key, as an optional.
    */
   get(key: K): Optional<V>;
   /**
-   * Set value for key, giving Result with old value or success.
+   * This method sets the value of a key. It gives a Result with the old value or a success.
    */
   set(key: K, value: V): Result<V | undefined, string>;
   /**
-   * Delete key, giving Result with deleted value or error.
+   * This method deletes a key. It gives a Result with the deleted value or an error.
    */
   delete(key: K): Result<V | undefined, string>;
 }
@@ -3674,21 +3674,21 @@ export declare class TTLCache<K, V> {
   delete(key: K): boolean;
   clear(): void;
   /**
-   * Manually trigger cleanup of expired entries.
+   * This method removes the expired entries at once.
    */
   cleanup(): void;
   /**
-   * Get remaining TTL for a key in milliseconds.
+   * This method gives the remaining TTL of a key, in milliseconds.
    * This method gives undefined if key doesn't exist or is expired.
    */
   getTTL(key: K): number | undefined;
   /**
-   * Update TTL for an existing key.
+   * This method updates the TTL of a key that is in the map.
    */
   touch(key: K, customTTL?: number): boolean;
   private startExpirationCheck;
   /**
-   * Stop the background expiration checker and clean up.
+   * This method stops the background expiration checker and cleans up.
    */
   dispose(): void;
   keys(): IterableIterator<K>;
@@ -3707,7 +3707,8 @@ export declare function ttlCache<K, V>(ttl: number, options?: {
  */
 export interface AsyncQueueOptions {
   /**
-   * Maximum capacity. Infinity for unbounded queue.
+   * The maximum number of elements: a whole number of 0 or more, or `Infinity` for no bound.
+   * Any other value gives a `RangeError`.
    * @default Infinity
    */
   capacity?: number;
@@ -3758,7 +3759,7 @@ export declare class AsyncQueue<T> implements AsyncQueue$1<T> {
    */
   put(element: T, timeout?: number): Promise<void>;
   /**
-   * Removes and gives an element from the queue.
+   * This method removes an element from the queue and gives it.
    * If the queue is empty, waits until an element is available.
    *
    * @throws Error if queue is closed and empty
@@ -3843,6 +3844,8 @@ export declare class AsyncQueue<T> implements AsyncQueue$1<T> {
 /**
  * Factory function to make an AsyncQueue.
  *
+ * @throws RangeError if the capacity is not a whole number of 0 or more, or `Infinity`
+ *
  * @example
  * const queue = asyncQueue<number>({ capacity: 100 })
  * await queue.put(42)
@@ -3863,14 +3866,14 @@ export declare class Channel<T> {
   constructor(bufferSize?: number);
   /**
    * This method sends a value through the channel.
-   * Blocks if channel buffer is full.
+   * The call blocks while the buffer of the channel is full.
    *
    * @throws Error if channel is closed
    */
   send(value: T): Promise<void>;
   /**
    * This method receives a value from the channel.
-   * Blocks if no value is available.
+   * The call blocks while no value is available.
    *
    * @throws Error if channel is closed and empty
    */
@@ -4001,7 +4004,7 @@ export declare function pipeline<T, U>(input: Channel<T>, transform: (value: T)
  */
 export declare function fanOut<T>(input: Channel<T>, count: number, bufferSize?: number): Channel<T>[];
 /**
- * Fan-in: merges multiple input channels into one output channel.
+ * Fan-in: this function merges multiple input channels into one output channel.
  *
  * @example
  * const ch1 = channel<number>()
@@ -4086,6 +4089,35 @@ export type Settled<T> = {
  * their rejections are not reported as unhandled.
  */
 export declare function asSettled<T>(promises: Iterable<Promise<T>>): AsyncGenerator<Settled<T>, void, undefined>;
+/**
+ * semaphore - A bound on the tasks that run at the same time.
+ *
+ * @example
+ * const writes = semaphore(4);
+ * // At most 4 writes run at once. The others wait in the order that they came.
+ * await Promise.all(items.map((item) => writes.run(() => store.set(item.id, item))));
+ */
+/** A semaphore: a count of permits, and a queue of the callers that wait for one. */
+export interface Semaphore {
+  /** The permits of the semaphore. */
+  readonly permits: number;
+  /** The permits that no caller holds. */
+  readonly available: number;
+  /** The callers that wait for a permit. */
+  readonly waiting: number;
+  /**
+   * This method gives a permit. It waits while all permits are held. The waiting callers get the permits in the order
+   * that they came. The result is the release of the permit. A second call of the release does nothing.
+   */
+  acquire(): Promise<() => void>;
+  /** This method starts a task with a permit. The permit goes back when the task ends, also when it throws. */
+  run<R>(task: () => R | PromiseLike<R>): Promise<R>;
+}
+/**
+ * This function makes a semaphore with `permits` permits. The value is a whole number of 1 or more, or `Infinity`
+ * for no bound. Another value throws a `RangeError`.
+ */
+export declare function semaphore(permits: number): Semaphore;
 /**
  * Functional operations for iterables (lazy sync transforms).
  *
@@ -4310,7 +4342,7 @@ declare function toMap<T, K, V>(keyExtractor: (element: T) => K, valueExtractor:
  */
 export declare function groupingBy<T, K>(classifier: (element: T) => K): Collector<T, HashMap<K, ArrayList<T>>, HashMap<K, ArrayList<T>>>;
 /**
- * Groups and transforms with a downstream collector.
+ * This function groups the elements and transforms each group with a downstream collector.
  *
  * @example
  * const countByAge = collect(
@@ -4488,7 +4520,7 @@ export declare const hashString: (str: string) => number;
  */
 export declare const hashNumber: (num: number) => number;
 /**
- * Combine multiple hash values.
+ * This function combines hash values into one hash.
  * Useful for hashing objects with multiple fields.
  *
  * @example
@@ -4497,7 +4529,7 @@ export declare const hashNumber: (num: number) => number;
  */
 export declare const combineHashes: (...hashes: number[]) => number;
 /**
- * Make a hash function that hashes by a specific property.
+ * This function makes a hash function that hashes by a property.
  *
  * @example
  * const userHash = hashBy<User>((u) => u.id)
@@ -4709,7 +4741,7 @@ declare function toMap$2<T, K, V>(iterable: Iterable<T>, keyExtractor: (value: T
  */
 export declare function groupBy<T, K>(iterable: Iterable<T>, keyExtractor: (value: T) => K): HashMap<K, ArrayList<T>>;
 /**
- * Checks if an index is within valid bounds [0, size).
+ * This function gives true when an index is in the bounds [0, size).
  * This function throws RangeError if out of bounds.
  *
  * @param index The index to check
@@ -4719,7 +4751,7 @@ export declare function groupBy<T, K>(iterable: Iterable<T>, keyExtractor: (valu
  */
 export declare function checkBounds(index: number, size: number, collectionName?: string): void;
 /**
- * Checks if an index is valid for insertion [0, size].
+ * This function gives true when an index is valid for an insertion, in [0, size].
  * In this function, index === size is correct for append operations.
  *
  * @param index The index to check
@@ -4729,7 +4761,7 @@ export declare function checkBounds(index: number, size: number, collectionName?
  */
 export declare function checkInsertBounds(index: number, size: number, collectionName?: string): void;
 /**
- * Checks if a range [start, end) is valid.
+ * This function gives true when a range [start, end) is valid.
  *
  * @param start Start index (inclusive)
  * @param end End index (exclusive)
@@ -4757,7 +4789,7 @@ export declare function findIndex<T>(array: T[], element: T, eq: Eq<T>): number;
  */
 export declare function findLastIndex<T>(array: T[], element: T, eq: Eq<T>): number;
 /**
- * Checks if an array contains an element using custom equality.
+ * This function gives true when an array has an element, with a custom equality.
  *
  * @param array The array to search
  * @param element The element to find