@mark1russell7/collections 0.9.3 → 0.9.5

package/src/dag/executor.ts

@@ -11,7 +11,7 @@ import type {
 } from "./types.js";
 
 /**
- * Start a batch of items with concurrency limit
+ * This function starts a batch of items with a limit of concurrency.
  */
 async function executeWithConcurrency<T, R>(
   items: T[],
@@ -45,7 +45,7 @@ async function executeWithConcurrency<T, R>(
 }
 
 /**
- * Call a listener. A listener that throws does not stop the run: the function gives a log
+ * This function calls a listener. A listener that throws does not stop the run: the function gives a log
  * line for its error (deep dive DATA-21).
  */
 function notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg: T): string | undefined {
@@ -59,7 +59,7 @@ function notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg:
 }
 
 /**
- * Start DAG with level-based parallelization
+ * This function starts a DAG level by level, with the nodes of each level in parallel.
  *
  * - Levels are processed sequentially (level 0 first, then level 1, and so on)
  * - Within each level, nodes are processed in parallel up to concurrency limit
@@ -167,7 +167,7 @@ export async function executeDAG<TNode extends DAGNode>(
 }
 
 /**
- * Start DAG sequentially (no parallelization)
+ * This function starts a DAG one node at a time, with no nodes in parallel.
  */
 export async function executeDAGSequential<TNode extends DAGNode>(
   dag: DependencyDAG<TNode>,
@@ -178,7 +178,7 @@ export async function executeDAGSequential<TNode extends DAGNode>(
 }
 
 /**
- * Make a simple processor that wraps an async function
+ * This function makes a simple processor that wraps an async function.
  */
 export function createProcessor<TNode extends DAGNode>(
   fn: (node: TNode) => Promise<void>

package/src/dag/traversal.ts

@@ -8,7 +8,7 @@
 import type { DAGNode, DependencyDAG } from "./types.js";
 
 /**
- * Build a leveled DAG from nodes using Kahn's algorithm
+ * This function builds a leveled DAG from nodes, with Kahn's algorithm.
  *
  * This assigns levels to each node where:
  * - Level 0: Nodes with no dependencies (leaves)
@@ -97,7 +97,7 @@ export function buildLeveledDAG<TNode extends DAGNode>(
 }
 
 /**
- * Get the topological order (flat list, leaves first)
+ * This function gives the topological order: a flat list, leaves first.
  */
 export function getTopologicalOrder<TNode extends DAGNode>(
   dag: DependencyDAG<TNode>

package/src/fx/collectors.ts

@@ -149,7 +149,7 @@ export function groupingBy<T, K>(
 }
 
 /**
- * Groups and transforms with a downstream collector.
+ * This function groups the elements and transforms each group with a downstream collector.
  *
  * @example
  * const countByAge = collect(

package/src/impl/hash-map.ts

@@ -44,7 +44,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
    */
@@ -73,7 +73,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.
  */

package/src/impl/hash-set.ts

@@ -34,7 +34,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;

package/src/impl/linked-hash-map.ts

@@ -57,7 +57,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;

package/src/index.ts

@@ -93,6 +93,7 @@ export * from "./behaviors/ttl.js";
 export * from "./async/async-queue.js";
 export * from "./async/channels.js";
 export * from "./async/settled.js";
+export * from "./async/semaphore.js";
 
 // ============================================================================
 // Functional Operations
@@ -135,6 +136,7 @@ export { ttlMap, ttlCache, TTLCache, ttlCollection } from "./behaviors/ttl.js";
 // Async/Concurrent
 export { asyncQueue, AsyncQueue } from "./async/async-queue.js";
 export { asSettled, type Settled } from "./async/settled.js";
+export { semaphore, type Semaphore } from "./async/semaphore.js";
 export {
   channel,
   Channel,

package/src/interfaces/collection.ts

@@ -129,12 +129,12 @@ export type IsReadonly<C> = C extends ReadonlyCollection<any>
   : 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>

package/src/interfaces/list.ts

@@ -1,5 +1,5 @@
 /**
- * List interfaces that mirror Java's List interface.
+ * This module has the list interfaces, which mirror the List interface of Java.
  *
  * Lists are ordered collections that can hold duplicate elements
  * and give positional (indexed) access to elements.
@@ -153,7 +153,7 @@ 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
@@ -161,7 +161,7 @@ export interface List<T> extends ReadonlyList<T>, Collection<T> {
   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
@@ -209,7 +209,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
    */

package/src/interfaces/map.ts

@@ -1,5 +1,5 @@
 /**
- * Map interfaces that mirror Java's Map interface hierarchy.
+ * This module has the map interfaces, which mirror the Map interface hierarchy of Java.
  *
  * A map holds key-value pairs and gives efficient lookup by key.
  * Keys are unique within a map.
@@ -288,12 +288,12 @@ 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;
 

package/src/interfaces/queue.ts

@@ -15,7 +15,7 @@ import type { Compare } from "../core/traits.js";
  */
 export 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
@@ -47,7 +47,7 @@ export 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
@@ -55,7 +55,7 @@ export interface Queue<T> extends ReadonlyQueue<T>, Collection<T> {
   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;
 
@@ -66,7 +66,7 @@ export 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;
@@ -96,14 +96,14 @@ export 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;
 
@@ -135,14 +135,14 @@ export 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;
 
@@ -197,7 +197,7 @@ export 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
@@ -258,7 +258,7 @@ export interface AsyncQueue<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>;

package/src/interfaces/set.ts

@@ -1,5 +1,5 @@
 /**
- * Set interfaces that mirror Java's Set interface hierarchy.
+ * This module has the set interfaces, which mirror the Set interface hierarchy of Java.
  *
  * Sets are collections that contain no duplicate elements.
  * They give efficient membership testing.
@@ -137,12 +137,12 @@ 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;
 

package/src/utils/defaults.ts

@@ -338,7 +338,7 @@ export 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
@@ -355,7 +355,7 @@ export 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)

package/src/utils/helpers.ts

@@ -11,7 +11,7 @@ import type { Eq } from "../core/traits.js";
 // ============================================================================
 
 /**
- * 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
@@ -26,7 +26,7 @@ export function checkBounds(index: number, size: number, collectionName: string
 }
 
 /**
- * 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
@@ -41,7 +41,7 @@ export function checkInsertBounds(index: number, size: number, collectionName: s
 }
 
 /**
- * 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)
@@ -101,7 +101,7 @@ export 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