effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/MutableHashSet.ts

@@ -1,49 +1,43 @@
 /**
- * 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.
+ * `MutableHashSet` is an in-place hash set for storing unique values with fast
+ * membership checks, insertion, removal, clearing, 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
+ * - {@link add}, {@link remove}, and {@link clear} mutate the same set instance
+ * - Duplicate values are ignored according to Effect equality and hashing
+ *   semantics
+ * - Values that implement `Equal` / `Hash` can be compared structurally;
+ *   primitive values and ordinary object references use the underlying hash map
+ *   behavior
+ * - The set is iterable, so `for...of` and `Array.from(set)` can inspect the
+ *   current 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}
+ * - Create from values or an iterable: {@link make}, {@link fromIterable}
+ * - Add, remove, and clear values: {@link add}, {@link remove}, {@link clear}
+ * - Check membership and size: {@link has}, {@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
+ * - This data structure is intentionally mutable; keep ownership clear if the
+ *   same set is shared by multiple callers
+ * - Mutating operations return the same set instance for convenient piping
+ * - Do not use iteration order as a sorting or presentation guarantee
+ * - Use immutable collection modules when callers need persistent snapshots
  *
  * **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)
+ * - Add, membership checks, and removal are O(1) on average
+ * - Hash collisions can make those operations O(n)
+ * - Clearing and reading size are O(1)
  * - Iteration is O(n)
  *
  * **Quickstart**
@@ -53,21 +47,24 @@
  * ```ts
  * import { MutableHashSet } from "effect"
  *
- * const set = MutableHashSet.make("apple", "banana", "apple")
+ * const set = MutableHashSet.make("alice", "bob", "alice")
  *
- * MutableHashSet.add(set, "cherry")
- * MutableHashSet.remove(set, "banana")
+ * MutableHashSet.add(set, "carol")
+ * MutableHashSet.remove(set, "bob")
  *
- * console.log(MutableHashSet.has(set, "apple"))
+ * console.log(MutableHashSet.has(set, "alice"))
  * // Output: true
  *
  * console.log(MutableHashSet.size(set))
  * // Output: 2
- *
- * console.log(Array.from(set))
- * // Output: ["apple", "cherry"]
  * ```
  *
+ * **See also**
+ *
+ * - {@link MutableHashMap} for the mutable key-value structure underneath
+ * - {@link empty}, {@link make}, and {@link fromIterable} for construction
+ * - {@link add}, {@link remove}, and {@link has} for core set operations
+ *
  * @since 2.0.0
  */
 import { format } from "./Formatter.ts"
@@ -84,6 +81,11 @@ const TypeId = "~effect/collections/MutableHashSet"
  * A mutable hash set for storing unique values with Effect structural equality
  * support.
  *
+ * **When to use**
+ *
+ * Use to store and mutate a collection of unique values with Effect hashing and
+ * equality semantics.
+ *
  * **Details**
  *
  * Operations mutate the set in place. Values that implement `Equal` / `Hash`
@@ -126,7 +128,21 @@ export interface MutableHashSet<out V> extends Iterable<V>, Pipeable, Inspectabl
 }
 
 /**
- * Checks if the specified value is a `MutableHashSet`, `false` otherwise.
+ * Checks whether the specified value is a `MutableHashSet`, `false` otherwise.
+ *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before treating it as a mutable hash set.
+ *
+ * **Details**
+ *
+ * The check looks for the `MutableHashSet` runtime marker.
+ *
+ * **Gotchas**
+ *
+ * Native `Set` values do not satisfy this check.
+ *
+ * @see {@link MutableHashSet} for the mutable hash set interface
  *
  * @category refinements
  * @since 4.0.0
@@ -164,6 +180,14 @@ const fromHashMap = <V>(keyMap: MutableHashMap.MutableHashMap<V, boolean>): Muta
 /**
  * Creates an empty MutableHashSet.
  *
+ * **When to use**
+ *
+ * Use to create a fresh mutable set before adding values over time.
+ *
+ * **Details**
+ *
+ * Each call returns a new empty set backed by an empty `MutableHashMap`.
+ *
  * **Example** (Creating an empty set)
  *
  * ```ts
@@ -180,6 +204,10 @@ const fromHashMap = <V>(keyMap: MutableHashMap.MutableHashMap<V, boolean>): Muta
  * console.log(Array.from(set)) // ["apple", "banana"]
  * ```
  *
+ * @see {@link make} for creating a set from explicit values
+ * @see {@link fromIterable} for creating a set from an iterable of values
+ * @see {@link clear} for emptying an existing mutable set
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -189,6 +217,10 @@ export const empty = <K = never>(): MutableHashSet<K> => fromHashMap(MutableHash
  * Creates a MutableHashSet from an iterable collection of values.
  * Duplicates are automatically removed.
  *
+ * **When to use**
+ *
+ * Use to build a mutable hash set from any iterable of values.
+ *
  * **Example** (Creating a set from an iterable)
  *
  * ```ts
@@ -219,6 +251,10 @@ export const fromIterable = <K = never>(keys: Iterable<K>): MutableHashSet<K> =>
  * Creates a MutableHashSet from a variable number of values.
  * Duplicates are automatically removed.
  *
+ * **When to use**
+ *
+ * Use to build a mutable hash set from explicit values.
+ *
  * **Example** (Creating a set from values)
  *
  * ```ts
@@ -250,6 +286,10 @@ export const make = <Keys extends ReadonlyArray<unknown>>(
  * Adds a value to the MutableHashSet, mutating the set in place.
  * If the value already exists, the set remains unchanged.
  *
+ * **When to use**
+ *
+ * Use to insert a value into a mutable set while keeping uniqueness.
+ *
  * **Example** (Adding values)
  *
  * ```ts
@@ -282,6 +322,10 @@ export const add: {
    * Adds a value to the MutableHashSet, mutating the set in place.
    * If the value already exists, the set remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to insert a value into a mutable set while keeping uniqueness.
+   *
    * **Example** (Adding values)
    *
    * ```ts
@@ -314,6 +358,10 @@ export const add: {
    * Adds a value to the MutableHashSet, mutating the set in place.
    * If the value already exists, the set remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to insert a value into a mutable set while keeping uniqueness.
+   *
    * **Example** (Adding values)
    *
    * ```ts
@@ -348,7 +396,16 @@ export const add: {
 >(2, (self, key) => (MutableHashMap.set(self.keyMap, key, true), self))
 
 /**
- * Checks if the MutableHashSet contains the specified value.
+ * Checks whether the MutableHashSet contains the specified value.
+ *
+ * **When to use**
+ *
+ * Use to test whether a mutable set currently contains a value.
+ *
+ * **Details**
+ *
+ * Membership follows the same hashing and equality rules as the underlying
+ * `MutableHashMap`.
  *
  * **Example** (Checking for a value)
  *
@@ -369,12 +426,24 @@ export const add: {
  * console.log(MutableHashSet.has(set, "grape")) // true
  * ```
  *
+ * @see {@link add} for adding a value to the set
+ * @see {@link remove} for removing a value from the set
+ *
  * @category elements
  * @since 2.0.0
  */
 export const has: {
   /**
-   * Checks if the MutableHashSet contains the specified value.
+   * Checks whether the MutableHashSet contains the specified value.
+   *
+   * **When to use**
+   *
+   * Use to test whether a mutable set currently contains a value.
+   *
+   * **Details**
+   *
+   * Membership follows the same hashing and equality rules as the underlying
+   * `MutableHashMap`.
    *
    * **Example** (Checking for a value)
    *
@@ -395,12 +464,24 @@ export const has: {
    * console.log(MutableHashSet.has(set, "grape")) // true
    * ```
    *
+   * @see {@link add} for adding a value to the set
+   * @see {@link remove} for removing a value from the set
+   *
    * @category elements
    * @since 2.0.0
    */
   <V>(key: V): (self: MutableHashSet<V>) => boolean
   /**
-   * Checks if the MutableHashSet contains the specified value.
+   * Checks whether the MutableHashSet contains the specified value.
+   *
+   * **When to use**
+   *
+   * Use to test whether a mutable set currently contains a value.
+   *
+   * **Details**
+   *
+   * Membership follows the same hashing and equality rules as the underlying
+   * `MutableHashMap`.
    *
    * **Example** (Checking for a value)
    *
@@ -421,6 +502,9 @@ export const has: {
    * console.log(MutableHashSet.has(set, "grape")) // true
    * ```
    *
+   * @see {@link add} for adding a value to the set
+   * @see {@link remove} for removing a value from the set
+   *
    * @category elements
    * @since 2.0.0
    */
@@ -434,6 +518,10 @@ export const has: {
  * Removes the specified value from the MutableHashSet, mutating the set in place.
  * If the value doesn't exist, the set remains unchanged.
  *
+ * **When to use**
+ *
+ * Use to delete a value from a mutable set if it is present.
+ *
  * **Example** (Removing a value)
  *
  * ```ts
@@ -466,6 +554,10 @@ export const remove: {
    * Removes the specified value from the MutableHashSet, mutating the set in place.
    * If the value doesn't exist, the set remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete a value from a mutable set if it is present.
+   *
    * **Example** (Removing a value)
    *
    * ```ts
@@ -498,6 +590,10 @@ export const remove: {
    * Removes the specified value from the MutableHashSet, mutating the set in place.
    * If the value doesn't exist, the set remains unchanged.
    *
+   * **When to use**
+   *
+   * Use to delete a value from a mutable set if it is present.
+   *
    * **Example** (Removing a value)
    *
    * ```ts
@@ -534,6 +630,10 @@ export const remove: {
 /**
  * Returns the number of unique values in the MutableHashSet.
  *
+ * **When to use**
+ *
+ * Use to read how many unique values are currently stored in the set.
+ *
  * **Example** (Checking set size)
  *
  * ```ts
@@ -563,6 +663,10 @@ export const size = <V>(self: MutableHashSet<V>): number => MutableHashMap.size(
  * Removes all values from the MutableHashSet, mutating the set in place.
  * The set becomes empty after this operation.
  *
+ * **When to use**
+ *
+ * Use to empty a mutable set while keeping the same set instance.
+ *
  * **Example** (Clearing all values)
  *
  * ```ts

package/src/MutableList.ts

@@ -172,9 +172,14 @@ export declare namespace MutableList {
 }
 
 /**
- * A unique symbol used to represent an empty result when taking elements from a MutableList.
+ * Defines the 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.
  *
+ * **When to use**
+ *
+ * Use to detect that `take` returned no element before handling the result as a
+ * list item.
+ *
  * **Example** (Checking for empty results)
  *
  * ```ts
@@ -205,7 +210,7 @@ export declare namespace MutableList {
  * console.log(empty === MutableList.Empty) // true, list is empty
  * ```
  *
- * @category Symbols
+ * @category symbols
  * @since 4.0.0
  */
 export const Empty: unique symbol = Symbol.for("effect/MutableList/Empty")
@@ -255,7 +260,7 @@ export const Empty: unique symbol = Symbol.for("effect/MutableList/Empty")
  * }
  * ```
  *
- * @category Symbols
+ * @category symbols
  * @since 4.0.0
  */
 export type Empty = typeof Empty
@@ -674,12 +679,20 @@ export const takeN = <A>(self: MutableList<A>, n: number): Array<A> => {
  * Removes up to `n` elements from the beginning of the `MutableList` without
  * returning them.
  *
+ * **When to use**
+ *
+ * Use to discard a bounded number of values from the head of a `MutableList`
+ * when the removed values are not needed.
+ *
  * **Details**
  *
  * 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.
  *
+ * @see {@link takeN} for removing up to `n` values and returning them as an array
+ * @see {@link clear} for removing every value from the list
+ *
  * @category elements
  * @since 4.0.0
  */
@@ -822,7 +835,10 @@ export const take = <A>(self: MutableList<A>): Empty | A => {
  *
  * **When to use**
  *
- * Use `takeN` when the copied elements should also be removed from the list.
+ * Use when you need to inspect or snapshot a bounded prefix of the list without
+ * consuming it.
+ *
+ * @see {@link takeN} for removing up to `n` values and returning them as an array
  *
  * @category elements
  * @since 4.0.0
@@ -848,8 +864,10 @@ export const toArrayN = <A>(self: MutableList<A>, n: number): Array<A> => {
  *
  * **When to use**
  *
- * Use `takeAll` when the list should be emptied after converting it to an
- * array.
+ * Use when you need a snapshot of all current elements while keeping the list
+ * unchanged.
+ *
+ * @see {@link takeAll} for converting all elements to an array and clearing the list
  *
  * @category elements
  * @since 4.0.0