@mark1russell7/collections 0.9.3 → 0.9.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",
@@ -76,7 +76,10 @@
     "@mark1russell7/rigor-generators": "^0.1.5",
     "@mark1russell7/rigor-statistics": "^0.1.8",
     "@mark1russell7/rigor-testkit": "^0.1.0",
+    "@stryker-mutator/core": "^10.1.1",
+    "@stryker-mutator/vitest-runner": "^10.1.1",
     "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.1.0",
     "esbuild": "^0.28.2",
     "fast-check": "^4.10.2",
     "tsdown": "^0.23.1",

package/src/async/async-queue.ts

@@ -22,12 +22,19 @@
 
 import type { AsyncQueue as IAsyncQueue } from "../interfaces/queue.js";
 
+/** The text of the error of a put, a new one or a waiting one, on a closed queue. */
+const CLOSED = "Queue is closed";
+
+/** The text of the error of a take, a peek or a wait on a queue that is closed and empty. */
+const CLOSED_AND_EMPTY = "Queue is closed and empty";
+
 /**
  * Options for making an AsyncQueue.
  */
 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;
@@ -80,7 +87,12 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
   private readonly defaultTimeout?: number;
 
   constructor(options: AsyncQueueOptions = {}) {
-    this.capacity = options.capacity ?? Infinity;
+    const capacity = options.capacity ?? Infinity;
+    // A capacity of -1, 1.5 or NaN gave a wrong remainingCapacity, or each put waited with no end.
+    if (capacity !== Infinity && !(Number.isInteger(capacity) && capacity >= 0)) {
+      throw new RangeError(`The capacity must be a whole number of 0 or more, or Infinity: ${String(capacity)}`);
+    }
+    this.capacity = capacity;
     if (options.timeout !== undefined) {
       this.defaultTimeout = options.timeout;
     }
@@ -124,7 +136,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
    */
   async put(element: T, timeout?: number): Promise<void> {
     if (this._isClosed) {
-      throw new Error("Queue is closed");
+      throw new Error(CLOSED);
     }
     if (this.tryPutNow(element)) {
       return;
@@ -152,7 +164,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
   }
 
   /**
-   * 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
@@ -166,7 +178,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
 
     // If closed and empty, throw
     if (this._isClosed) {
-      throw new Error("Queue is closed and empty");
+      throw new Error(CLOSED_AND_EMPTY);
     }
 
     // Wait for an element
@@ -203,7 +215,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
       return () => false;
     }
     if (this._isClosed) {
-      onClosed(new Error("Queue is closed and empty"));
+      onClosed(new Error(CLOSED_AND_EMPTY));
       return () => false;
     }
     const taker: Resolver<T> = { resolve: onElement, reject: onClosed };
@@ -306,7 +318,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
     }
 
     if (this._isClosed) {
-      throw new Error("Queue is closed and empty");
+      throw new Error(CLOSED_AND_EMPTY);
     }
 
     // Wait for the next element without a take. (Before, peek took the element and put it back
@@ -349,7 +361,7 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
     // Reject all waiting putters
     for (const putter of this.putters) {
       this.clearTimeout(putter);
-      putter.reject(new Error("Queue closed"));
+      putter.reject(new Error(CLOSED));
     }
     this.putters = [];
 
@@ -357,12 +369,12 @@ export class AsyncQueue<T> implements IAsyncQueue<T> {
     if (this.buffer.length === 0) {
       for (const taker of this.takers) {
         this.clearTimeout(taker);
-        taker.reject(new Error("Queue closed and empty"));
+        taker.reject(new Error(CLOSED_AND_EMPTY));
       }
       this.takers = [];
       for (const peeker of this.peekers) {
         this.clearTimeout(peeker);
-        peeker.reject(new Error("Queue closed and empty"));
+        peeker.reject(new Error(CLOSED_AND_EMPTY));
       }
       this.peekers = [];
     }
@@ -471,6 +483,8 @@ export class AsyncQueue<T> implements IAsyncQueue<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)

package/src/async/channels.ts

@@ -42,7 +42,7 @@ export class Channel<T> {
 
   /**
    * 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
    */
@@ -55,7 +55,7 @@ export class Channel<T> {
 
   /**
    * 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
    */
@@ -337,7 +337,7 @@ export function fanOut<T>(input: Channel<T>, count: number, bufferSize: number =
 }
 
 /**
- * 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>()

package/src/async/semaphore.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 function semaphore(permits: number): Semaphore {
+  if (!(permits === Infinity || (Number.isInteger(permits) && permits >= 1))) {
+    throw new RangeError(`A semaphore needs a whole number of permits of 1 or more, or Infinity: ${permits}`);
+  }
+  let held = 0;
+  // The waiting callers, in the order that they came. A release gives its permit to the first.
+  const queue: Array<() => void> = [];
+  let head = 0;
+
+  const releaseOnce = (): (() => void) => {
+    let done = false;
+    return () => {
+      if (done) return;
+      done = true;
+      if (head < queue.length) {
+        const next = queue[head]!;
+        head += 1;
+        // The permit goes from the releaser to the next caller, so `held` does not change
+        if (head > 64 && head * 2 > queue.length) {
+          queue.splice(0, head);
+          head = 0;
+        }
+        next();
+      } else {
+        held -= 1;
+      }
+    };
+  };
+
+  const acquire = (): Promise<() => void> => {
+    if (held < permits) {
+      held += 1;
+      return Promise.resolve(releaseOnce());
+    }
+    return new Promise((resolve) => {
+      queue.push(() => resolve(releaseOnce()));
+    });
+  };
+
+  return {
+    permits,
+    get available() {
+      return permits - held;
+    },
+    get waiting() {
+      return queue.length - head;
+    },
+    acquire,
+    async run<R>(task: () => R | PromiseLike<R>): Promise<R> {
+      const release = await acquire();
+      try {
+        return await task();
+      } finally {
+        release();
+      }
+    },
+  };
+}

package/src/behaviors/bounded.ts

@@ -1,5 +1,5 @@
 /**
- * Bounded behavior - Enforces capacity limits on collections.
+ * Bounded behavior: this module enforces capacity limits on collections.
  *
  * This module wraps collections to prevent them from exceeding a maximum size.
  * This module gives various overflow policies to handle full collections.

package/src/behaviors/evented.ts

@@ -1,5 +1,5 @@
 /**
- * Evented behavior - Emits typed events on collection mutations.
+ * Evented behavior: this module emits typed events on collection mutations.
  *
  * This module wraps collections to emit events whenever elements are added, removed,
  * or the collection is cleared. This module enables reactive programming patterns.

package/src/behaviors/readonly.ts

@@ -1,5 +1,5 @@
 /**
- * Readonly behavior - Makes immutable views of collections.
+ * Readonly behavior: this module makes immutable views of collections.
  *
  * This module wraps collections to prevent modifications by throwing errors
  * on any mutation try. Mirrors Java's Collections.unmodifiable*() methods.

package/src/behaviors/safe.ts

@@ -21,27 +21,27 @@ import { none, some, toOptional, tryCatch, type Optional, type Result } from "@m
  */
 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>;
 
@@ -61,17 +61,17 @@ 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>;
 }
@@ -81,27 +81,27 @@ 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>;
 }
@@ -111,17 +111,17 @@ 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>;
 }

package/src/behaviors/synchronized.ts

@@ -1,5 +1,5 @@
 /**
- * Synchronized behavior - Gives thread-safe access with mutex locking.
+ * Synchronized behavior: this module gives thread-safe access with mutex locking.
  *
  * This module wraps collections to serialize all operations using a mutex, making sure that
  * thread-safe access in concurrent environments. Mirrors Java's

package/src/behaviors/ttl.ts

@@ -1,7 +1,7 @@
 /**
  * TTL (Time-To-Live) expiration behavior.
  *
- * Automatically expires elements after a specified time period.
+ * The behavior removes each element when its time to live ends.
  * Perfect for temporary caches and time-limited data.
  *
  * @example
@@ -20,7 +20,7 @@ import { removals, removalSource, type ElementRemoval, type MapRemoval } from ".
 import type { Collection } from "../interfaces/collection.js";
 
 /**
- * Start the background expiration checker without keeping a Node.js process alive.
+ * This function starts the background expiration checker, and it does not keep a Node.js process alive.
  * (In a browser, setInterval gives a number and there is nothing to unref.)
  */
 function startExpirationTimer(check: () => void, interval: number): ReturnType<typeof setInterval> {
@@ -368,7 +368,7 @@ export class TTLCache<K, V> {
   }
 
   /**
-   * Manually trigger cleanup of expired entries.
+   * This method removes the expired entries at once.
    */
   cleanup(): void {
     const now = Date.now();
@@ -392,7 +392,7 @@ export class TTLCache<K, V> {
   }
 
   /**
-   * 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 {
@@ -404,7 +404,7 @@ export class TTLCache<K, V> {
   }
 
   /**
-   * 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 {
     const entry = this.map.get(key);
@@ -425,7 +425,7 @@ export class TTLCache<K, V> {
   }
 
   /**
-   * Stop the background expiration checker and clean up.
+   * This method stops the background expiration checker and cleans up.
    */
   dispose(): void {
     if (this.intervalId) {

package/src/core/events.ts

@@ -54,7 +54,7 @@ export class Emitter<E extends EventMap> {
   private listeners = new Map<keyof E, Set<Listener<any>>>();
 
   /**
-   * 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
@@ -79,7 +79,7 @@ export class Emitter<E extends EventMap> {
   }
 
   /**
-   * 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
@@ -96,7 +96,7 @@ export class Emitter<E extends EventMap> {
   }
 
   /**
-   * 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
@@ -121,7 +121,7 @@ export class Emitter<E extends EventMap> {
   }
 
   /**
-   * 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
    */
@@ -134,7 +134,7 @@ export class Emitter<E extends EventMap> {
   }
 
   /**
-   * 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
@@ -144,21 +144,21 @@ export class Emitter<E extends EventMap> {
   }
 
   /**
-   * 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)[] {
     return Array.from(this.listeners.keys());
   }
 
   /**
-   * 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 {
     return this.listenerCount(event) > 0;
   }
 
   /**
-   * Remove all listeners and clean up resources.
+   * This method removes all listeners and releases the resources.
    */
   dispose(): void {
     this.listeners.clear();
@@ -166,7 +166,7 @@ export class Emitter<E extends EventMap> {
 }
 
 /**
- * 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.
  *
@@ -205,7 +205,7 @@ export class EventBatcher<E extends EventMap, K extends keyof E> {
   }
 
   /**
-   * Add an event to the current batch.
+   * This method adds an event to the current batch.
    */
   queue(payload: E[K]): void {
     this.batch.push(payload);
@@ -216,7 +216,7 @@ export class EventBatcher<E extends EventMap, K extends keyof E> {
   }
 
   /**
-   * Immediately emit all batched events.
+   * This method emits all batched events at once.
    */
   flush(): void {
     if (this.timer !== null) {
@@ -232,7 +232,7 @@ export class EventBatcher<E extends EventMap, K extends keyof E> {
   }
 
   /**
-   * Clean up resources.
+   * This method sends the events of the batch and releases the resources.
    */
   dispose(): void {
     this.flush();
@@ -272,7 +272,7 @@ export class AsyncEmitter<E extends EventMap> {
   }
 
   /**
-   * 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
@@ -340,7 +340,7 @@ export const forwardEvent = <
 };
 
 /**
- * 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 } }>()

package/src/core/middleware.ts

@@ -90,13 +90,13 @@ export const hasCapability = <C extends Collection<any>, K extends keyof any>(
  */
 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;
 
   /**
-   * Emit an event (internal use by middleware).
+   * This method emits an event. Only the middleware calls it.
    * @internal
    */
   emit?<K extends keyof E>(event: K, payload: E[K]): void;
@@ -135,7 +135,7 @@ export interface SafeCollection {
 }
 
 /**
- * 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>;
@@ -148,7 +148,7 @@ export type ElementType<C> = C extends {
   : 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
@@ -265,7 +265,7 @@ export abstract class CollectionBuilder<C> {
   protected middleware: Middleware<C>[] = [];
 
   /**
-   * Apply a custom middleware.
+   * This method applies a custom middleware.
    */
   use(middleware: Middleware<C>): this {
     this.middleware.push(middleware);
@@ -273,7 +273,7 @@ export abstract class CollectionBuilder<C> {
   }
 
   /**
-   * 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;
 }

package/src/core/policies.ts

@@ -209,11 +209,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;
 }
 

package/src/dag/builder.ts

@@ -5,7 +5,7 @@
 import type { DAGNode } from "./types.js";
 
 /**
- * Filter DAG to only include nodes reachable from a root
+ * This function filters a DAG to the nodes that a root can reach.
  */
 export function filterDAGFromRoot<TNode extends DAGNode>(
   nodes: Map<string, TNode>,
@@ -33,7 +33,7 @@ export function filterDAGFromRoot<TNode extends DAGNode>(
 }
 
 /**
- * Get all ancestors of a node (nodes that this node depends on, transitively)
+ * This function gives all ancestors of a node: the nodes that this node depends on, transitively.
  */
 export function getAncestors<TNode extends DAGNode>(
   nodes: Map<string, TNode>,
@@ -62,7 +62,7 @@ export function getAncestors<TNode extends DAGNode>(
 }
 
 /**
- * Get all descendants of a node (nodes that depend on this node, transitively)
+ * This function gives all descendants of a node: the nodes that depend on this node, transitively.
  */
 export function getDescendants<TNode extends DAGNode>(
   nodes: Map<string, TNode>,
@@ -100,7 +100,7 @@ export function getDescendants<TNode extends DAGNode>(
 }
 
 /**
- * Make a DAG node from minimal input
+ * This function makes a DAG node from a minimal input.
  */
 export function createNode<TData = unknown>(
   id: string,
@@ -115,7 +115,7 @@ export function createNode<TData = unknown>(
 }
 
 /**
- * Build a Map of nodes from an array
+ * This function builds a Map of nodes from an array.
  */
 export function buildNodeMap<TNode extends DAGNode>(
   nodes: TNode[]