effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/HashSet.ts

@@ -1,4 +1,41 @@
 /**
+ * The `HashSet` module provides an immutable set data structure for storing
+ * unique values with efficient membership checks, additions, removals, and set
+ * operations. A `HashSet<A>` contains at most one value for each equality class
+ * as determined by Effect's `Equal` / `Hash` semantics.
+ *
+ * **Mental model**
+ *
+ * - `HashSet<A>` is an immutable collection of unique values of type `A`
+ * - Operations such as {@link add}, {@link remove}, {@link union}, and
+ *   {@link difference} return new sets; the input set is never mutated
+ * - Membership is checked with {@link has}, using Effect equality and hashing
+ *   rather than array-style linear scanning
+ * - Duplicate values are collapsed when using {@link make}, {@link fromIterable},
+ *   {@link add}, or {@link map}
+ * - `HashSet` is iterable, but iteration order is not a sorting guarantee
+ *
+ * **Common tasks**
+ *
+ * - Create sets: {@link empty}, {@link make}, {@link fromIterable}
+ * - Check membership and size: {@link has}, {@link size}, {@link isEmpty}
+ * - Add or remove values: {@link add}, {@link remove}
+ * - Combine sets: {@link union}, {@link intersection}, {@link difference}
+ * - Compare sets: {@link isSubset}
+ * - Transform or select values: {@link map}, {@link filter}
+ * - Test values: {@link some}, {@link every}
+ * - Fold values: {@link reduce}
+ *
+ * **Gotchas**
+ *
+ * - Values that should compare structurally should implement compatible
+ *   `Equal` and `Hash` behavior; otherwise object identity may affect whether
+ *   values are considered distinct
+ * - {@link map} may reduce the set size when multiple input values map to the
+ *   same output value
+ * - Do not rely on iteration order for deterministic presentation; sort the
+ *   values after converting to an array when order matters
+ *
  * @since 2.0.0
  */
 
@@ -16,9 +53,10 @@ const TypeId = internal.HashSetTypeId
  * A HashSet is an immutable set data structure that provides efficient storage
  * and retrieval of unique values. It uses a HashMap internally for optimal performance.
  *
- * @example
+ * **Example** (Creating and updating a HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * // Create a HashSet
  * const set = HashSet.make("apple", "banana", "cherry")
@@ -36,8 +74,8 @@ const TypeId = internal.HashSetTypeId
  * console.log(HashSet.size(smaller)) // 2
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface HashSet<out Value> extends Iterable<Value>, Equal, Pipeable, Inspectable {
   readonly [TypeId]: typeof TypeId
@@ -47,9 +85,10 @@ export interface HashSet<out Value> extends Iterable<Value>, Equal, Pipeable, In
  * The HashSet namespace contains type-level utilities and helper types
  * for working with HashSet instances.
  *
- * @example
+ * **Example** (Extracting value types from a HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * // Create a concrete HashSet for type extraction
  * const fruits = HashSet.make("apple", "banana", "cherry")
@@ -64,13 +103,17 @@ export interface HashSet<out Value> extends Iterable<Value>, Equal, Pipeable, In
  * ```
  *
  * @since 2.0.0
- * @category namespace
  */
 export declare namespace HashSet {
   /**
-   * @example
+   * Extracts the element type from a `HashSet`.
+   *
+   * For `HashSet.HashSet<A>`, `HashSet.Value<...>` resolves to `A`.
+   *
+   * **Example** (Extracting a HashSet value type)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5)
    *
@@ -80,8 +123,8 @@ export declare namespace HashSet {
    * const processNumber = (n: NumberType) => n * 2
    * ```
    *
-   * @since 2.0.0
    * @category type-level
+   * @since 4.0.0
    */
   export type Value<T> = T extends HashSet<infer V> ? V : never
 }
@@ -89,9 +132,10 @@ export declare namespace HashSet {
 /**
  * Creates an empty HashSet.
  *
- * @example
+ * **Example** (Creating an empty HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set = HashSet.empty<string>()
  *
@@ -103,17 +147,18 @@ export declare namespace HashSet {
  * console.log(HashSet.size(withValues)) // 2
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty: <V = never>() => HashSet<V> = internal.empty
 
 /**
  * Creates a HashSet from a variable number of values.
  *
- * @example
+ * **Example** (Creating a HashSet from values)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const fruits = HashSet.make("apple", "banana", "cherry")
  * console.log(HashSet.size(fruits)) // 3
@@ -125,8 +170,8 @@ export const empty: <V = never>() => HashSet<V> = internal.empty
  * console.log(HashSet.size(mixed)) // 3
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make: <Values extends ReadonlyArray<any>>(
   ...values: Values
@@ -135,9 +180,10 @@ export const make: <Values extends ReadonlyArray<any>>(
 /**
  * Creates a HashSet from an iterable collection of values.
  *
- * @example
+ * **Example** (Creating a HashSet from an iterable)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const fromArray = HashSet.fromIterable(["a", "b", "c", "b", "a"])
  * console.log(HashSet.size(fromArray)) // 3
@@ -149,17 +195,18 @@ export const make: <Values extends ReadonlyArray<any>>(
  * console.log(Array.from(fromString)) // ["h", "e", "l", "o"]
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable: <V>(values: Iterable<V>) => HashSet<V> = internal.fromIterable
 
 /**
  * Checks if a value is a HashSet.
  *
- * @example
+ * **Example** (Checking for a HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set = HashSet.make(1, 2, 3)
  * const array = [1, 2, 3]
@@ -169,16 +216,17 @@ export const fromIterable: <V>(values: Iterable<V>) => HashSet<V> = internal.fro
  * console.log(HashSet.isHashSet(null)) // false
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isHashSet: {
   /**
    * Checks if a value is a HashSet.
    *
-   * @example
+   * **Example** (Checking for a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make(1, 2, 3)
    * const array = [1, 2, 3]
@@ -188,16 +236,17 @@ export const isHashSet: {
    * console.log(HashSet.isHashSet(null)) // false
    * ```
    *
-   * @since 2.0.0
    * @category guards
+   * @since 2.0.0
    */
   <V>(u: Iterable<V>): u is HashSet<V>
   /**
    * Checks if a value is a HashSet.
    *
-   * @example
+   * **Example** (Checking for a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make(1, 2, 3)
    * const array = [1, 2, 3]
@@ -207,8 +256,8 @@ export const isHashSet: {
    * console.log(HashSet.isHashSet(null)) // false
    * ```
    *
-   * @since 2.0.0
    * @category guards
+   * @since 2.0.0
    */
   (u: unknown): u is HashSet<unknown>
 } = internal.isHashSet
@@ -216,9 +265,10 @@ export const isHashSet: {
 /**
  * Adds a value to the HashSet, returning a new HashSet.
  *
- * @example
+ * **Example** (Adding values to a HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set = HashSet.make("a", "b")
  * const withC = HashSet.add(set, "c")
@@ -232,16 +282,17 @@ export const isHashSet: {
  * console.log(HashSet.size(same)) // 2
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const add: {
   /**
    * Adds a value to the HashSet, returning a new HashSet.
    *
-   * @example
+   * **Example** (Adding values to a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make("a", "b")
    * const withC = HashSet.add(set, "c")
@@ -255,16 +306,17 @@ export const add: {
    * console.log(HashSet.size(same)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V): (self: HashSet<V>) => HashSet<V>
   /**
    * Adds a value to the HashSet, returning a new HashSet.
    *
-   * @example
+   * **Example** (Adding values to a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make("a", "b")
    * const withC = HashSet.add(set, "c")
@@ -278,8 +330,8 @@ export const add: {
    * console.log(HashSet.size(same)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, value: V): HashSet<V>
 } = Dual.dual<
@@ -290,17 +342,17 @@ export const add: {
 /**
  * Checks if the HashSet contains the specified value.
  *
- * @example
+ * **Example** (Checking HashSet membership)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet" // false
+ * import { Equal, Hash, HashSet } from "effect"
  *
  * // Works with any type that implements Equal
- * import { Equal, Hash } from "effect"
  *
  * const set = HashSet.make("apple", "banana", "cherry")
  *
  * console.log(HashSet.has(set, "apple")) // true
- * console.log(HashSet.has(set, "grape"))
+ * console.log(HashSet.has(set, "grape")) // false
  *
  * class Person implements Equal.Equal {
  *   constructor(readonly name: string) {}
@@ -318,24 +370,24 @@ export const add: {
  * console.log(HashSet.has(people, new Person("Alice"))) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Checks if the HashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking HashSet membership)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet" // false
+   * import { Equal, Hash, HashSet } from "effect"
    *
    * // Works with any type that implements Equal
-   * import { Equal, Hash } from "effect"
    *
    * const set = HashSet.make("apple", "banana", "cherry")
    *
    * console.log(HashSet.has(set, "apple")) // true
-   * console.log(HashSet.has(set, "grape"))
+   * console.log(HashSet.has(set, "grape")) // false
    *
    * class Person implements Equal.Equal {
    *   constructor(readonly name: string) {}
@@ -353,24 +405,24 @@ export const has: {
    * console.log(HashSet.has(people, new Person("Alice"))) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(value: V): (self: HashSet<V>) => boolean
   /**
    * Checks if the HashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking HashSet membership)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet" // false
+   * import { Equal, Hash, HashSet } from "effect"
    *
    * // Works with any type that implements Equal
-   * import { Equal, Hash } from "effect"
    *
    * const set = HashSet.make("apple", "banana", "cherry")
    *
    * console.log(HashSet.has(set, "apple")) // true
-   * console.log(HashSet.has(set, "grape"))
+   * console.log(HashSet.has(set, "grape")) // false
    *
    * class Person implements Equal.Equal {
    *   constructor(readonly name: string) {}
@@ -388,8 +440,8 @@ export const has: {
    * console.log(HashSet.has(people, new Person("Alice"))) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, value: V): boolean
 } = Dual.dual<
@@ -400,9 +452,10 @@ export const has: {
 /**
  * Removes a value from the HashSet, returning a new HashSet.
  *
- * @example
+ * **Example** (Removing values from a HashSet)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set = HashSet.make("a", "b", "c")
  * const withoutB = HashSet.remove(set, "b")
@@ -416,16 +469,17 @@ export const has: {
  * console.log(HashSet.size(same)) // 3
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove: {
   /**
    * Removes a value from the HashSet, returning a new HashSet.
    *
-   * @example
+   * **Example** (Removing values from a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make("a", "b", "c")
    * const withoutB = HashSet.remove(set, "b")
@@ -439,16 +493,17 @@ export const remove: {
    * console.log(HashSet.size(same)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V): (self: HashSet<V>) => HashSet<V>
   /**
    * Removes a value from the HashSet, returning a new HashSet.
    *
-   * @example
+   * **Example** (Removing values from a HashSet)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set = HashSet.make("a", "b", "c")
    * const withoutB = HashSet.remove(set, "b")
@@ -462,8 +517,8 @@ export const remove: {
    * console.log(HashSet.size(same)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, value: V): HashSet<V>
 } = Dual.dual<
@@ -474,9 +529,10 @@ export const remove: {
 /**
  * Returns the number of values in the HashSet.
  *
- * @example
+ * **Example** (Getting the HashSet size)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const empty = HashSet.empty<string>()
  * console.log(HashSet.size(empty)) // 0
@@ -488,17 +544,18 @@ export const remove: {
  * console.log(HashSet.size(withDuplicates)) // 3
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size: <V>(self: HashSet<V>) => number = internal.size
 
 /**
  * Checks if the HashSet is empty.
  *
- * @example
+ * **Example** (Checking whether a HashSet is empty)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const empty = HashSet.empty<string>()
  * console.log(HashSet.isEmpty(empty)) // true
@@ -507,17 +564,18 @@ export const size: <V>(self: HashSet<V>) => number = internal.size
  * console.log(HashSet.isEmpty(nonEmpty)) // false
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const isEmpty: <V>(self: HashSet<V>) => boolean = internal.isEmpty
 
 /**
  * Creates the union of two HashSets.
  *
- * @example
+ * **Example** (Combining HashSets)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set1 = HashSet.make("a", "b")
  * const set2 = HashSet.make("b", "c")
@@ -527,16 +585,17 @@ export const isEmpty: <V>(self: HashSet<V>) => boolean = internal.isEmpty
  * console.log(HashSet.size(combined)) // 3
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const union: {
   /**
    * Creates the union of two HashSets.
    *
-   * @example
+   * **Example** (Combining HashSets)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b")
    * const set2 = HashSet.make("b", "c")
@@ -546,16 +605,17 @@ export const union: {
    * console.log(HashSet.size(combined)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: HashSet<V1>): <V0>(self: HashSet<V0>) => HashSet<V1 | V0>
   /**
    * Creates the union of two HashSets.
    *
-   * @example
+   * **Example** (Combining HashSets)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b")
    * const set2 = HashSet.make("b", "c")
@@ -565,8 +625,8 @@ export const union: {
    * console.log(HashSet.size(combined)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: HashSet<V0>, that: HashSet<V1>): HashSet<V0 | V1>
 } = Dual.dual<
@@ -577,9 +637,10 @@ export const union: {
 /**
  * Creates the intersection of two HashSets.
  *
- * @example
+ * **Example** (Finding common HashSet values)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set1 = HashSet.make("a", "b", "c")
  * const set2 = HashSet.make("b", "c", "d")
@@ -589,16 +650,17 @@ export const union: {
  * console.log(HashSet.size(common)) // 2
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const intersection: {
   /**
    * Creates the intersection of two HashSets.
    *
-   * @example
+   * **Example** (Finding common HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b", "c")
    * const set2 = HashSet.make("b", "c", "d")
@@ -608,16 +670,17 @@ export const intersection: {
    * console.log(HashSet.size(common)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: HashSet<V1>): <V0>(self: HashSet<V0>) => HashSet<V1 & V0>
   /**
    * Creates the intersection of two HashSets.
    *
-   * @example
+   * **Example** (Finding common HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b", "c")
    * const set2 = HashSet.make("b", "c", "d")
@@ -627,8 +690,8 @@ export const intersection: {
    * console.log(HashSet.size(common)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: HashSet<V0>, that: HashSet<V1>): HashSet<V0 & V1>
 } = Dual.dual<
@@ -639,9 +702,10 @@ export const intersection: {
 /**
  * Creates the difference of two HashSets (elements in the first set that are not in the second).
  *
- * @example
+ * **Example** (Finding HashSet differences)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const set1 = HashSet.make("a", "b", "c")
  * const set2 = HashSet.make("b", "d")
@@ -651,16 +715,17 @@ export const intersection: {
  * console.log(HashSet.size(diff)) // 2
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const difference: {
   /**
    * Creates the difference of two HashSets (elements in the first set that are not in the second).
    *
-   * @example
+   * **Example** (Finding HashSet differences)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b", "c")
    * const set2 = HashSet.make("b", "d")
@@ -670,16 +735,17 @@ export const difference: {
    * console.log(HashSet.size(diff)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: HashSet<V1>): <V0>(self: HashSet<V0>) => HashSet<V0>
   /**
    * Creates the difference of two HashSets (elements in the first set that are not in the second).
    *
-   * @example
+   * **Example** (Finding HashSet differences)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const set1 = HashSet.make("a", "b", "c")
    * const set2 = HashSet.make("b", "d")
@@ -689,8 +755,8 @@ export const difference: {
    * console.log(HashSet.size(diff)) // 2
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: HashSet<V0>, that: HashSet<V1>): HashSet<V0>
 } = Dual.dual<
@@ -701,9 +767,10 @@ export const difference: {
 /**
  * Checks if a HashSet is a subset of another HashSet.
  *
- * @example
+ * **Example** (Checking subset relationships)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const small = HashSet.make("a", "b")
  * const large = HashSet.make("a", "b", "c", "d")
@@ -715,16 +782,17 @@ export const difference: {
  * console.log(HashSet.isSubset(small, small)) // true
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const isSubset: {
   /**
    * Checks if a HashSet is a subset of another HashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const small = HashSet.make("a", "b")
    * const large = HashSet.make("a", "b", "c", "d")
@@ -736,16 +804,17 @@ export const isSubset: {
    * console.log(HashSet.isSubset(small, small)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V1>(that: HashSet<V1>): <V0>(self: HashSet<V0>) => boolean
   /**
    * Checks if a HashSet is a subset of another HashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const small = HashSet.make("a", "b")
    * const large = HashSet.make("a", "b", "c", "d")
@@ -757,8 +826,8 @@ export const isSubset: {
    * console.log(HashSet.isSubset(small, small)) // true
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V0, V1>(self: HashSet<V0>, that: HashSet<V1>): boolean
 } = Dual.dual<
@@ -769,9 +838,10 @@ export const isSubset: {
 /**
  * Maps each value in the HashSet using the provided function.
  *
- * @example
+ * **Example** (Mapping HashSet values)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const numbers = HashSet.make(1, 2, 3)
  * const doubled = HashSet.map(numbers, (n) => n * 2)
@@ -785,16 +855,17 @@ export const isSubset: {
  * console.log(Array.from(lengths).sort()) // [5, 6] (apple=5, banana=6, cherry=6)
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map: {
   /**
    * Maps each value in the HashSet using the provided function.
    *
-   * @example
+   * **Example** (Mapping HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3)
    * const doubled = HashSet.map(numbers, (n) => n * 2)
@@ -808,16 +879,17 @@ export const map: {
    * console.log(Array.from(lengths).sort()) // [5, 6] (apple=5, banana=6, cherry=6)
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(f: (value: V) => U): (self: HashSet<V>) => HashSet<U>
   /**
    * Maps each value in the HashSet using the provided function.
    *
-   * @example
+   * **Example** (Mapping HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3)
    * const doubled = HashSet.map(numbers, (n) => n * 2)
@@ -831,8 +903,8 @@ export const map: {
    * console.log(Array.from(lengths).sort()) // [5, 6] (apple=5, banana=6, cherry=6)
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(self: HashSet<V>, f: (value: V) => U): HashSet<U>
 } = Dual.dual<
@@ -843,9 +915,10 @@ export const map: {
 /**
  * Filters the HashSet keeping only values that satisfy the predicate.
  *
- * @example
+ * **Example** (Filtering HashSet values)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const numbers = HashSet.make(1, 2, 3, 4, 5, 6)
  * const evens = HashSet.filter(numbers, (n) => n % 2 === 0)
@@ -854,16 +927,17 @@ export const map: {
  * console.log(HashSet.size(evens)) // 3
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter: {
   /**
    * Filters the HashSet keeping only values that satisfy the predicate.
    *
-   * @example
+   * **Example** (Filtering HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5, 6)
    * const evens = HashSet.filter(numbers, (n) => n % 2 === 0)
@@ -872,16 +946,17 @@ export const filter: {
    * console.log(HashSet.size(evens)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V, U extends V>(refinement: Refinement<NoInfer<V>, U>): (self: HashSet<V>) => HashSet<U>
   /**
    * Filters the HashSet keeping only values that satisfy the predicate.
    *
-   * @example
+   * **Example** (Filtering HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5, 6)
    * const evens = HashSet.filter(numbers, (n) => n % 2 === 0)
@@ -890,16 +965,17 @@ export const filter: {
    * console.log(HashSet.size(evens)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<NoInfer<V>>): (self: HashSet<V>) => HashSet<V>
   /**
    * Filters the HashSet keeping only values that satisfy the predicate.
    *
-   * @example
+   * **Example** (Filtering HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5, 6)
    * const evens = HashSet.filter(numbers, (n) => n % 2 === 0)
@@ -908,16 +984,17 @@ export const filter: {
    * console.log(HashSet.size(evens)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V, U extends V>(self: HashSet<V>, refinement: Refinement<V, U>): HashSet<U>
   /**
    * Filters the HashSet keeping only values that satisfy the predicate.
    *
-   * @example
+   * **Example** (Filtering HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5, 6)
    * const evens = HashSet.filter(numbers, (n) => n % 2 === 0)
@@ -926,8 +1003,8 @@ export const filter: {
    * console.log(HashSet.size(evens)) // 3
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, predicate: Predicate<V>): HashSet<V>
 } = Dual.dual<
@@ -944,9 +1021,10 @@ export const filter: {
 /**
  * Tests whether at least one value in the HashSet satisfies the predicate.
  *
- * @example
+ * **Example** (Testing whether some values match)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const numbers = HashSet.make(1, 2, 3, 4, 5)
  *
@@ -957,16 +1035,17 @@ export const filter: {
  * console.log(HashSet.some(empty, (n) => n > 0)) // false
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const some: {
   /**
    * Tests whether at least one value in the HashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5)
    *
@@ -977,16 +1056,17 @@ export const some: {
    * console.log(HashSet.some(empty, (n) => n > 0)) // false
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>): (self: HashSet<V>) => boolean
   /**
    * Tests whether at least one value in the HashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5)
    *
@@ -997,8 +1077,8 @@ export const some: {
    * console.log(HashSet.some(empty, (n) => n > 0)) // false
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, predicate: Predicate<V>): boolean
 } = Dual.dual<
@@ -1009,9 +1089,10 @@ export const some: {
 /**
  * Tests whether all values in the HashSet satisfy the predicate.
  *
- * @example
+ * **Example** (Testing whether every value matches)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const numbers = HashSet.make(2, 4, 6, 8)
  *
@@ -1022,16 +1103,17 @@ export const some: {
  * console.log(HashSet.every(empty, (n) => n > 0)) // true (vacuously true)
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const every: {
   /**
    * Tests whether all values in the HashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(2, 4, 6, 8)
    *
@@ -1042,16 +1124,17 @@ export const every: {
    * console.log(HashSet.every(empty, (n) => n > 0)) // true (vacuously true)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>): (self: HashSet<V>) => boolean
   /**
    * Tests whether all values in the HashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(2, 4, 6, 8)
    *
@@ -1062,8 +1145,8 @@ export const every: {
    * console.log(HashSet.every(empty, (n) => n > 0)) // true (vacuously true)
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: HashSet<V>, predicate: Predicate<V>): boolean
 } = Dual.dual<
@@ -1074,9 +1157,10 @@ export const every: {
 /**
  * Reduces the HashSet to a single value by iterating through the values and applying an accumulator function.
  *
- * @example
+ * **Example** (Reducing HashSet values)
+ *
  * ```ts
- * import * as HashSet from "effect/HashSet"
+ * import { HashSet } from "effect"
  *
  * const numbers = HashSet.make(1, 2, 3, 4, 5)
  * const sum = HashSet.reduce(numbers, 0, (acc, n) => acc + n)
@@ -1088,16 +1172,17 @@ export const every: {
  * console.log(concatenated) // Order may vary: "abc", "bac", etc.
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const reduce: {
   /**
    * Reduces the HashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5)
    * const sum = HashSet.reduce(numbers, 0, (acc, n) => acc + n)
@@ -1109,16 +1194,17 @@ export const reduce: {
    * console.log(concatenated) // Order may vary: "abc", "bac", etc.
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(zero: U, f: (accumulator: U, value: V) => U): (self: HashSet<V>) => U
   /**
    * Reduces the HashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing HashSet values)
+   *
    * ```ts
-   * import * as HashSet from "effect/HashSet"
+   * import { HashSet } from "effect"
    *
    * const numbers = HashSet.make(1, 2, 3, 4, 5)
    * const sum = HashSet.reduce(numbers, 0, (acc, n) => acc + n)
@@ -1130,8 +1216,8 @@ export const reduce: {
    * console.log(concatenated) // Order may vary: "abc", "bac", etc.
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(self: HashSet<V>, zero: U, f: (accumulator: U, value: V) => U): U
 } = Dual.dual<