effect 4.0.0-beta.66 → 4.0.0-beta.67

package/dist/MutableHashSet.js

@@ -1,28 +1,76 @@
 /**
- * @fileoverview
- * MutableHashSet is a high-performance, mutable set implementation that provides efficient storage
- * and retrieval of unique values. Built on top of MutableHashMap, it inherits the same performance
- * characteristics and support for both structural and referential equality.
- *
- * The implementation uses a MutableHashMap internally where each value is stored as a key with a
- * boolean flag, providing O(1) average-case performance for all operations.
- *
- * Key Features:
- * - Mutable operations for performance-critical scenarios
- * - Supports both structural and referential equality
- * - Efficient duplicate detection and removal
- * - Iterable interface for easy traversal
- * - Memory-efficient storage with automatic deduplication
- * - Seamless integration with Effect's Equal and Hash interfaces
- *
- * Performance Characteristics:
- * - Add/Has/Remove: O(1) average, O(n) worst case (hash collisions)
- * - Clear: O(1)
- * - Size: O(1)
- * - Iteration: O(n)
+ * The `MutableHashSet` module provides a mutable hash set for storing unique
+ * values with efficient membership checks, insertion, removal, and iteration.
+ * It is built on {@link MutableHashMap}: each set value is stored as a map key,
+ * so uniqueness follows the same hashing and equality rules as the underlying
+ * mutable hash map.
+ *
+ * **Mental model**
+ *
+ * - `MutableHashSet<V>` is a mutable collection of unique values of type `V`
+ * - Operations such as {@link add}, {@link remove}, and {@link clear} mutate
+ *   the set in place
+ * - Duplicate values are ignored according to Effect equality and hashing semantics
+ * - Values that implement `Equal` / `Hash` are compared structurally
+ * - Primitive values and references that do not implement Effect equality use
+ *   the normal hash map behavior
+ * - The set is iterable, so `Array.from(set)` or `for...of` can be used to
+ *   inspect its values
+ *
+ * **Common tasks**
+ *
+ * - Create an empty set: {@link empty}
+ * - Create from values: {@link make}
+ * - Create from any iterable: {@link fromIterable}
+ * - Add a value: {@link add}
+ * - Check membership: {@link has}
+ * - Remove a value: {@link remove}
+ * - Remove all values: {@link clear}
+ * - Count unique values: {@link size}
+ * - Narrow unknown values: {@link isMutableHashSet}
+ *
+ * **Gotchas**
+ *
+ * - This data structure is intentionally mutable; keep ownership clear when
+ *   sharing it between callers
+ * - Mutating operations return the same set instance for convenient piping, not
+ *   a copy
+ * - Iteration order should not be used as a stable sorting mechanism
+ * - For immutable set operations, use Effect's immutable collection modules
+ *   instead
+ *
+ * **Performance**
+ *
+ * - Add, membership checks, and removal are O(1) on average and O(n) in the
+ *   presence of hash collisions
+ * - Clearing and reading the size are O(1)
+ * - Iteration is O(n)
+ *
+ * **Quickstart**
+ *
+ * **Example** (Tracking unique values)
  *
- * @since 2.0.0
+ * ```ts
+ * import { MutableHashSet } from "effect"
+ *
+ * const set = MutableHashSet.make("apple", "banana", "apple")
+ *
+ * MutableHashSet.add(set, "cherry")
+ * MutableHashSet.remove(set, "banana")
+ *
+ * console.log(MutableHashSet.has(set, "apple"))
+ * // Output: true
+ *
+ * console.log(MutableHashSet.size(set))
+ * // Output: 2
+ *
+ * console.log(Array.from(set))
+ * // Output: ["apple", "cherry"]
+ * ```
+ *
+ * @fileoverview
  * @category data-structures
+ * @since 2.0.0
  */
 import { format } from "./Formatter.js";
 import * as Dual from "./Function.js";
@@ -67,7 +115,8 @@ const fromHashMap = keyMap => {
 /**
  * Creates an empty MutableHashSet.
  *
- * @example
+ * **Example** (Creating an empty set)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -82,15 +131,16 @@ const fromHashMap = keyMap => {
  * console.log(Array.from(set)) // ["apple", "banana"]
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = () => fromHashMap(MutableHashMap.empty());
 /**
  * Creates a MutableHashSet from an iterable collection of values.
  * Duplicates are automatically removed.
  *
- * @example
+ * **Example** (Creating a set from an iterable)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -109,15 +159,16 @@ export const empty = () => fromHashMap(MutableHashMap.empty());
  * console.log(Array.from(fromString)) // ["h", "e", "l", "o"]
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = keys => fromHashMap(MutableHashMap.fromIterable(Array.from(keys).map(k => [k, true])));
 /**
  * Creates a MutableHashSet from a variable number of values.
  * Duplicates are automatically removed.
  *
- * @example
+ * **Example** (Creating a set from values)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -136,15 +187,16 @@ export const fromIterable = keys => fromHashMap(MutableHashMap.fromIterable(Arra
  * console.log(MutableHashSet.size(mixed)) // 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = (...keys) => fromIterable(keys);
 /**
  * Adds a value to the MutableHashSet, mutating the set in place.
  * If the value already exists, the set remains unchanged.
  *
- * @example
+ * **Example** (Adding values)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -167,14 +219,15 @@ export const make = (...keys) => fromIterable(keys);
  * console.log(MutableHashSet.size(set)) // 3
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const add = /*#__PURE__*/Dual.dual(2, (self, key) => (MutableHashMap.set(self.keyMap, key, true), self));
 /**
  * Checks if the MutableHashSet contains the specified value.
  *
- * @example
+ * **Example** (Checking for a value)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -192,15 +245,16 @@ export const add = /*#__PURE__*/Dual.dual(2, (self, key) => (MutableHashMap.set(
  * console.log(MutableHashSet.has(set, "grape")) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has = /*#__PURE__*/Dual.dual(2, (self, key) => MutableHashMap.has(self.keyMap, key));
 /**
  * Removes the specified value from the MutableHashSet, mutating the set in place.
  * If the value doesn't exist, the set remains unchanged.
  *
- * @example
+ * **Example** (Removing a value)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -223,14 +277,15 @@ export const has = /*#__PURE__*/Dual.dual(2, (self, key) => MutableHashMap.has(s
  * console.log(MutableHashSet.size(set)) // 1
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove = /*#__PURE__*/Dual.dual(2, (self, key) => (MutableHashMap.remove(self.keyMap, key), self));
 /**
  * Returns the number of unique values in the MutableHashSet.
  *
- * @example
+ * **Example** (Checking set size)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -249,15 +304,16 @@ export const remove = /*#__PURE__*/Dual.dual(2, (self, key) => (MutableHashMap.r
  * console.log(MutableHashSet.size(set)) // 0
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const size = self => MutableHashMap.size(self.keyMap);
 /**
  * Removes all values from the MutableHashSet, mutating the set in place.
  * The set becomes empty after this operation.
  *
- * @example
+ * **Example** (Clearing all values)
+ *
  * ```ts
  * import { MutableHashSet } from "effect"
  *
@@ -277,8 +333,8 @@ export const size = self => MutableHashMap.size(self.keyMap);
  * console.log(MutableHashSet.size(set)) // 1
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const clear = self => (MutableHashMap.clear(self.keyMap), self);
 //# sourceMappingURL=MutableHashSet.js.map

package/dist/MutableHashSet.js.map

@@ -1 +1 @@
-{"version":3,"file":"MutableHashSet.js","names":["format","Dual","NodeInspectSymbol","toJson","MutableHashMap","pipeArguments","hasProperty","TypeId","isMutableHashSet","value","MutableHashSetProto","Symbol","iterator","Array","from","keyMap","map","_","toString","toJSON","_id","values","pipe","arguments","fromHashMap","set","Object","create","empty","fromIterable","keys","k","make","add","dual","self","key","has","remove","size","clear"],"sources":["../src/MutableHashSet.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"MutableHashSet.js","names":["format","Dual","NodeInspectSymbol","toJson","MutableHashMap","pipeArguments","hasProperty","TypeId","isMutableHashSet","value","MutableHashSetProto","Symbol","iterator","Array","from","keyMap","map","_","toString","toJSON","_id","values","pipe","arguments","fromHashMap","set","Object","create","empty","fromIterable","keys","k","make","add","dual","self","key","has","remove","size","clear"],"sources":["../src/MutableHashSet.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/MutableList.d.ts

@@ -3,7 +3,8 @@
  * MutableList provides efficient append/prepend operations and is ideal for
  * producer-consumer patterns, queues, and streaming scenarios.
  *
- * @example
+ * **Example** (Creating and consuming a mutable list)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -26,8 +27,8 @@
  * console.log(MutableList.take(list)) // 2
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface MutableList<in out A> {
     head: MutableList.Bucket<A> | undefined;
@@ -38,7 +39,8 @@ export interface MutableList<in out A> {
  * The MutableList namespace contains type definitions and utilities for working
  * with mutable linked lists.
  *
- * @example
+ * **Example** (Typing queue processors)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -67,15 +69,20 @@ export interface MutableList<in out A> {
  * }
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export declare namespace MutableList {
     /**
-     * Internal bucket structure used by MutableList to store elements efficiently.
-     * Buckets are linked together to form the list structure.
+     * Storage node used by the exposed `head` and `tail` fields of a
+     * `MutableList`.
+     *
+     * Most code should treat buckets as an implementation detail and use
+     * `MutableList` operations such as `append`, `prepend`, and `take` instead
+     * of constructing or mutating buckets directly.
+     *
+     * **Example** (Inspecting buckets)
      *
-     * @example
      * ```ts
      * import * as MutableList from "effect/MutableList"
      *
@@ -99,8 +106,8 @@ export declare namespace MutableList {
      * inspectBucket(list.tail)
      * ```
      *
-     * @since 4.0.0
      * @category models
+     * @since 4.0.0
      */
     interface Bucket<A> {
         readonly array: Array<A>;
@@ -113,7 +120,8 @@ export declare namespace MutableList {
  * A unique symbol used to represent an empty result when taking elements from a MutableList.
  * This symbol is returned by `take` when the list is empty, allowing for safe type checking.
  *
- * @example
+ * **Example** (Checking for empty results)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -142,15 +150,16 @@ export declare namespace MutableList {
  * console.log(empty === MutableList.Empty) // true, list is empty
  * ```
  *
- * @since 4.0.0
  * @category Symbols
+ * @since 4.0.0
  */
 export declare const Empty: unique symbol;
 /**
  * The type of the Empty symbol, used for type checking when taking elements from a MutableList.
  * This provides compile-time safety when checking for empty results.
  *
- * @example
+ * **Example** (Handling empty results type-safely)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -190,14 +199,15 @@ export declare const Empty: unique symbol;
  * }
  * ```
  *
- * @since 4.0.0
  * @category Symbols
+ * @since 4.0.0
  */
 export type Empty = typeof Empty;
 /**
  * Creates an empty MutableList.
  *
- * @example
+ * **Example** (Creating an empty mutable list)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -216,15 +226,16 @@ export type Empty = typeof Empty;
  * console.log(MutableList.take(list)) // "second"
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const make: <A>() => MutableList<A>;
 /**
  * Appends an element to the end of the MutableList.
  * This operation is optimized for high-frequency usage.
  *
- * @example
+ * **Example** (Appending elements)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -248,15 +259,16 @@ export declare const make: <A>() => MutableList<A>;
  * }
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const append: <A>(self: MutableList<A>, message: A) => void;
 /**
  * Prepends an element to the beginning of the MutableList.
  * This operation is optimized for high-frequency usage.
  *
- * @example
+ * **Example** (Prepending elements)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -280,8 +292,8 @@ export declare const append: <A>(self: MutableList<A>, message: A) => void;
  * console.log(MutableList.take(list)) // "priority"
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const prepend: <A>(self: MutableList<A>, message: A) => void;
 /**
@@ -289,7 +301,8 @@ export declare const prepend: <A>(self: MutableList<A>, message: A) => void;
  * The elements are added in order, so the first element in the iterable becomes
  * the new head of the list.
  *
- * @example
+ * **Example** (Prepending multiple elements)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -311,8 +324,8 @@ export declare const prepend: <A>(self: MutableList<A>, message: A) => void;
  * console.log(MutableList.takeAll(newList)) // ["h", "e", "l", "l", "o"]
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const prependAll: <A>(self: MutableList<A>, messages: Iterable<A>) => void;
 /**
@@ -322,7 +335,8 @@ export declare const prependAll: <A>(self: MutableList<A>, messages: Iterable<A>
  * ⚠️ **Warning**: When mutable=true, the input array may be modified internally.
  * Only use mutable=true when you control the array lifecycle.
  *
- * @example
+ * **Example** (Prepending arrays with optional mutation)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -342,15 +356,16 @@ export declare const prependAll: <A>(self: MutableList<A>, messages: Iterable<A>
  * console.log(MutableList.takeAll(list)) // [10, 20, 30, 1, 2, 3, 4]
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const prependAllUnsafe: <A>(self: MutableList<A>, messages: ReadonlyArray<A>, mutable?: boolean) => void;
 /**
  * Appends all elements from an iterable to the end of the MutableList.
  * Returns the number of elements added.
  *
- * @example
+ * **Example** (Appending multiple elements)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -380,8 +395,8 @@ export declare const prependAllUnsafe: <A>(self: MutableList<A>, messages: Reado
  * console.log(count) // 1000
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const appendAll: <A>(self: MutableList<A>, messages: Iterable<A>) => number;
 /**
@@ -392,7 +407,8 @@ export declare const appendAll: <A>(self: MutableList<A>, messages: Iterable<A>)
  * ⚠️ **Warning**: When mutable=true, the input array may be modified internally.
  * Only use mutable=true when you control the array lifecycle.
  *
- * @example
+ * **Example** (Appending arrays with optional mutation)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -417,15 +433,16 @@ export declare const appendAll: <A>(self: MutableList<A>, messages: Iterable<A>)
  * MutableList.appendAllUnsafe(list, bigArray, true) // Very efficient
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const appendAllUnsafe: <A>(self: MutableList<A>, messages: ReadonlyArray<A>, mutable?: boolean) => number;
 /**
  * Removes all elements from the MutableList, resetting it to an empty state.
  * This operation is highly optimized and releases all internal memory.
  *
- * @example
+ * **Example** (Clearing a mutable list)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -451,8 +468,8 @@ export declare const appendAllUnsafe: <A>(self: MutableList<A>, messages: Readon
  * }
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const clear: <A>(self: MutableList<A>) => void;
 /**
@@ -460,7 +477,8 @@ export declare const clear: <A>(self: MutableList<A>) => void;
  * The taken elements are removed from the list. This operation is optimized for performance
  * and includes zero-copy optimizations when possible.
  *
- * @example
+ * **Example** (Taking batches)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -493,20 +511,28 @@ export declare const clear: <A>(self: MutableList<A>) => void;
  * }
  * ```
  *
- * @since 4.0.0
  * @category elements
+ * @since 4.0.0
  */
 export declare const takeN: <A>(self: MutableList<A>, n: number) => Array<A>;
 /**
- * @since 4.0.0
+ * Removes up to `n` elements from the beginning of the `MutableList` without
+ * returning them.
+ *
+ * If `n` is less than or equal to zero, or the list is empty, the list is left
+ * unchanged. If `n` is greater than or equal to the current length, the list is
+ * cleared.
+ *
  * @category elements
+ * @since 4.0.0
  */
 export declare const takeNVoid: <A>(self: MutableList<A>, n: number) => void;
 /**
  * Takes all elements from the MutableList and returns them as an array.
  * The list becomes empty after this operation. This is equivalent to takeN(list, list.length).
  *
- * @example
+ * **Example** (Draining all elements)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -540,8 +566,8 @@ export declare const takeNVoid: <A>(self: MutableList<A>, n: number) => void;
  * }
  * ```
  *
- * @since 4.0.0
  * @category elements
+ * @since 4.0.0
  */
 export declare const takeAll: <A>(self: MutableList<A>) => Array<A>;
 /**
@@ -549,7 +575,8 @@ export declare const takeAll: <A>(self: MutableList<A>) => Array<A>;
  * Returns the element if available, or the Empty symbol if the list is empty.
  * The taken element is removed from the list.
  *
- * @example
+ * **Example** (Taking one element)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -589,25 +616,37 @@ export declare const takeAll: <A>(self: MutableList<A>) => Array<A>;
  * }
  * ```
  *
- * @since 4.0.0
  * @category elements
+ * @since 4.0.0
  */
 export declare const take: <A>(self: MutableList<A>) => Empty | A;
 /**
- * @since 4.0.0
+ * Copies up to `n` elements from the beginning of the `MutableList` into a new
+ * array without modifying the list.
+ *
+ * Use `takeN` when the copied elements should also be removed from the list.
+ *
  * @category elements
+ * @since 4.0.0
  */
 export declare const toArrayN: <A>(self: MutableList<A>, n: number) => Array<A>;
 /**
- * @since 4.0.0
+ * Copies all current elements of the `MutableList` into a new array without
+ * modifying the list.
+ *
+ * Use `takeAll` when the list should be emptied after converting it to an
+ * array.
+ *
  * @category elements
+ * @since 4.0.0
  */
 export declare const toArray: <A>(self: MutableList<A>) => Array<A>;
 /**
  * Filters the MutableList in place, keeping only elements that satisfy the predicate.
  * This operation modifies the list and rebuilds its internal structure for efficiency.
  *
- * @example
+ * **Example** (Filtering in place)
+ *
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -619,7 +658,6 @@ export declare const toArray: <A>(self: MutableList<A>) => Array<A>;
  * // Keep only even numbers
  * MutableList.filter(list, (n) => n % 2 === 0)
  *
- * console.log(list.length) // 5
  * console.log(MutableList.takeAll(list)) // [2, 4, 6, 8, 10]
  *
  * // Filter with index
@@ -641,18 +679,22 @@ export declare const toArray: <A>(self: MutableList<A>) => Array<A>;
  *
  * // Keep only errors
  * MutableList.filter(logs, (log) => log.level === "ERROR")
- * console.log(MutableList.takeAll(logs)) // Only error logs
+ * console.log(MutableList.takeAll(logs).map((log) => log.message)) // ["Connection failed", "Timeout"]
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const filter: <A>(self: MutableList<A>, f: (value: A, i: number) => boolean) => void;
 /**
- * Removes all occurrences of a specific value from the MutableList.
- * This operation modifies the list in place.
+ * Removes all occurrences of a value from the `MutableList` using JavaScript
+ * strict equality semantics.
+ *
+ * The list is modified in place. Values are compared with `!==`, so this does
+ * not use Effect structural equality.
+ *
+ * **Example** (Removing matching values)
  *
- * @example
  * ```ts
  * import * as MutableList from "effect/MutableList"
  *
@@ -664,12 +706,13 @@ export declare const filter: <A>(self: MutableList<A>, f: (value: A, i: number)
  * // Remove all occurrences of "apple"
  * MutableList.remove(list, "apple")
  *
- * console.log(list.length) // 2
  * console.log(MutableList.takeAll(list)) // ["banana", "cherry"]
  *
  * // Remove non-existent value (no effect)
- * MutableList.remove(list, "grape")
- * console.log(list.length) // 2
+ * const colors = MutableList.make<string>()
+ * MutableList.appendAll(colors, ["red", "blue"])
+ * MutableList.remove(colors, "green")
+ * console.log(MutableList.takeAll(colors)) // ["red", "blue"]
  *
  * // Real-world example: removing completed tasks
  * const tasks = MutableList.make<{ id: number; status: string }>()
@@ -682,11 +725,11 @@ export declare const filter: <A>(self: MutableList<A>, f: (value: A, i: number)
  *
  * // Remove completed tasks by filtering status
  * MutableList.filter(tasks, (task) => task.status !== "completed")
- * console.log(MutableList.takeAll(tasks)) // Only pending tasks
+ * console.log(MutableList.takeAll(tasks).map((task) => task.id)) // [1, 3]
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export declare const remove: <A>(self: MutableList<A>, value: A) => void;
 //# sourceMappingURL=MutableList.d.ts.map