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

package/src/TxHashSet.ts

@@ -1,4 +1,24 @@
 /**
+ * The `TxHashSet` module provides a transactional hash set for storing unique
+ * values inside Effect transactions. A `TxHashSet<A>` wraps a `HashSet<A>` in a
+ * transactional reference, so reads and writes can be composed with other
+ * transactional operations and committed atomically.
+ *
+ * **Common tasks**
+ *
+ * - Create transactional sets with {@link empty}, {@link make}, or {@link fromIterable}
+ * - Mutate an existing set with {@link add}, {@link remove}, and {@link clear}
+ * - Query membership and size with {@link has}, {@link size}, and {@link isEmpty}
+ * - Derive new sets with {@link map}, {@link filter}, {@link union}, {@link intersection}, and {@link difference}
+ * - Fold or collect values with {@link reduce}, {@link toArray}, and {@link toHashSet}
+ *
+ * **Gotchas**
+ *
+ * - Mutation operations update the same transactional set; transform operations
+ *   return a new `TxHashSet`
+ * - Operations are `Effect` values and must be yielded, piped, or run to take effect
+ * - Use `Effect.tx` when several operations must observe and commit one atomic transaction
+ *
  * @since 2.0.0
  */
 
@@ -52,7 +72,8 @@ const TxHashSetProto = {
  * - The original TxHashSet remains unchanged
  * - Examples: `union`, `intersection`, `difference`, `map`, `filter`
  *
- * @example
+ * **Example** (Using transactional hash sets)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -81,8 +102,8 @@ const TxHashSetProto = {
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface TxHashSet<in out V> extends Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -93,7 +114,8 @@ export interface TxHashSet<in out V> extends Inspectable, Pipeable {
  * The TxHashSet namespace contains type-level utilities and helper types
  * for working with TxHashSet instances.
  *
- * @example
+ * **Example** (Extracting value types inside transactions)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -111,27 +133,32 @@ export interface TxHashSet<in out V> extends Inspectable, Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export declare namespace TxHashSet {
   /**
-   * @example
+   * Extracts the value type from a `TxHashSet` type.
+   *
+   * **Example** (Extracting a TxHashSet value type)
+   *
    * ```ts
-   * import { TxHashSet } from "effect"
+   * import type { TxHashSet } from "effect"
    *
-   * const fruits = TxHashSet.make("apple", "banana", "cherry")
+   * type FruitSet = TxHashSet.TxHashSet<"apple" | "banana" | "cherry">
    *
    * // Extract the value type
-   * type Fruit = TxHashSet.TxHashSet.Value<typeof fruits> // string
+   * type Fruit = TxHashSet.TxHashSet.Value<FruitSet> // "apple" | "banana" | "cherry"
    *
    * const processFruit = (fruit: Fruit) => {
    *   return `Processing ${fruit}`
    * }
+   *
+   * console.log(processFruit("apple")) // Processing apple
    * ```
    *
-   * @since 2.0.0
    * @category type-level
+   * @since 2.0.0
    */
   export type Value<T> = T extends TxHashSet<infer V> ? V : never
 }
@@ -145,7 +172,8 @@ const makeTxHashSet = <V>(ref: TxRef.TxRef<HashSet.HashSet<V>>): TxHashSet<V> =>
 /**
  * Creates an empty TxHashSet.
  *
- * @example
+ * **Example** (Creating an empty transactional hash set)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -162,8 +190,8 @@ const makeTxHashSet = <V>(ref: TxRef.TxRef<HashSet.HashSet<V>>): TxHashSet<V> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const empty = <V = never>(): Effect.Effect<TxHashSet<V>> =>
   Effect.gen(function*() {
@@ -174,7 +202,8 @@ export const empty = <V = never>(): Effect.Effect<TxHashSet<V>> =>
 /**
  * Creates a TxHashSet from a variable number of values.
  *
- * @example
+ * **Example** (Creating transactional hash sets from values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -190,8 +219,8 @@ export const empty = <V = never>(): Effect.Effect<TxHashSet<V>> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <Values extends ReadonlyArray<any>>(
   ...values: Values
@@ -205,7 +234,8 @@ export const make = <Values extends ReadonlyArray<any>>(
 /**
  * Creates a TxHashSet from an iterable collection of values.
  *
- * @example
+ * **Example** (Creating a transactional hash set from an iterable)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -218,12 +248,12 @@ export const make = <Values extends ReadonlyArray<any>>(
  *
  *   const fromString = yield* TxHashSet.fromIterable("hello")
  *   const values = yield* TxHashSet.toHashSet(fromString)
- *   console.log(Array.from(values)) // ["h", "e", "l", "o"]
+ *   console.log(Array.from(values).sort()) // ["e", "h", "l", "o"]
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromIterable = <V>(values: Iterable<V>): Effect.Effect<TxHashSet<V>> =>
   Effect.gen(function*() {
@@ -235,7 +265,8 @@ export const fromIterable = <V>(values: Iterable<V>): Effect.Effect<TxHashSet<V>
 /**
  * Creates a TxHashSet from an existing HashSet.
  *
- * @example
+ * **Example** (Creating a transactional hash set from a HashSet)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  * import * as HashSet from "effect/HashSet"
@@ -254,8 +285,8 @@ export const fromIterable = <V>(values: Iterable<V>): Effect.Effect<TxHashSet<V>
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHashSet<V>> =>
   Effect.gen(function*() {
@@ -266,7 +297,8 @@ export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHas
 /**
  * Checks if a value is a TxHashSet.
  *
- * @example
+ * **Example** (Checking for a TxHashSet)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  * import * as HashSet from "effect/HashSet"
@@ -283,8 +315,8 @@ export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHas
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isTxHashSet = (u: unknown): u is TxHashSet<unknown> => hasProperty(u, TypeId)
 
@@ -294,7 +326,8 @@ export const isTxHashSet = (u: unknown): u is TxHashSet<unknown> => hasProperty(
  * **Mutation behavior**: This function mutates the original TxHashSet by adding
  * the specified value. It does not return a new TxHashSet reference.
  *
- * @example
+ * **Example** (Adding values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -311,8 +344,8 @@ export const isTxHashSet = (u: unknown): u is TxHashSet<unknown> => hasProperty(
  * })
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const add: {
   /**
@@ -321,7 +354,8 @@ export const add: {
    * **Mutation behavior**: This function mutates the original TxHashSet by adding
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Adding values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -338,8 +372,8 @@ export const add: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V): (self: TxHashSet<V>) => Effect.Effect<void>
   /**
@@ -348,7 +382,8 @@ export const add: {
    * **Mutation behavior**: This function mutates the original TxHashSet by adding
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Adding values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -365,8 +400,8 @@ export const add: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V): Effect.Effect<void>
 } = dual<
@@ -376,7 +411,8 @@ export const add: {
    * **Mutation behavior**: This function mutates the original TxHashSet by adding
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Adding values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -393,8 +429,8 @@ export const add: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V) => (self: TxHashSet<V>) => Effect.Effect<void>,
   /**
@@ -403,7 +439,8 @@ export const add: {
    * **Mutation behavior**: This function mutates the original TxHashSet by adding
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Adding values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -420,8 +457,8 @@ export const add: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V) => Effect.Effect<void>
 >(2, <V>(self: TxHashSet<V>, value: V) => TxRef.update(self.ref, (set) => HashSet.add(set, value)))
@@ -432,7 +469,8 @@ export const add: {
  * **Mutation behavior**: This function mutates the original TxHashSet by removing
  * the specified value. It does not return a new TxHashSet reference.
  *
- * @example
+ * **Example** (Removing values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -450,8 +488,8 @@ export const add: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove: {
   /**
@@ -460,7 +498,8 @@ export const remove: {
    * **Mutation behavior**: This function mutates the original TxHashSet by removing
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Removing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -478,8 +517,8 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
@@ -488,7 +527,8 @@ export const remove: {
    * **Mutation behavior**: This function mutates the original TxHashSet by removing
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Removing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -506,8 +546,8 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V): Effect.Effect<boolean>
 } = dual<
@@ -517,7 +557,8 @@ export const remove: {
    * **Mutation behavior**: This function mutates the original TxHashSet by removing
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Removing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -535,8 +576,8 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(value: V) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
@@ -545,7 +586,8 @@ export const remove: {
    * **Mutation behavior**: This function mutates the original TxHashSet by removing
    * the specified value. It does not return a new TxHashSet reference.
    *
-   * @example
+   * **Example** (Removing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -563,8 +605,8 @@ export const remove: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mutations
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, value: V) =>
@@ -580,7 +622,8 @@ export const remove: {
 /**
  * Checks if the TxHashSet contains the specified value.
  *
- * @example
+ * **Example** (Checking membership)
+ *
  * ```ts
  * import { Effect, Equal, Hash, TxHashSet } from "effect"
  *
@@ -608,14 +651,15 @@ export const remove: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const has: {
   /**
    * Checks if the TxHashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking membership)
+   *
    * ```ts
    * import { Effect, Equal, Hash, TxHashSet } from "effect"
    *
@@ -643,14 +687,15 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(value: V): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
    * Checks if the TxHashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking membership)
+   *
    * ```ts
    * import { Effect, Equal, Hash, TxHashSet } from "effect"
    *
@@ -678,15 +723,16 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V): Effect.Effect<boolean>
 } = dual<
   /**
    * Checks if the TxHashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking membership)
+   *
    * ```ts
    * import { Effect, Equal, Hash, TxHashSet } from "effect"
    *
@@ -714,14 +760,15 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(value: V) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
    * Checks if the TxHashSet contains the specified value.
    *
-   * @example
+   * **Example** (Checking membership)
+   *
    * ```ts
    * import { Effect, Equal, Hash, TxHashSet } from "effect"
    *
@@ -749,8 +796,8 @@ export const has: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, value: V) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, value: V) =>
@@ -762,7 +809,8 @@ export const has: {
 /**
  * Returns the number of values in the TxHashSet.
  *
- * @example
+ * **Example** (Getting the set size)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -778,8 +826,8 @@ export const has: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const size = <V>(self: TxHashSet<V>): Effect.Effect<number> =>
   Effect.gen(function*() {
@@ -790,7 +838,8 @@ export const size = <V>(self: TxHashSet<V>): Effect.Effect<number> =>
 /**
  * Checks if the TxHashSet is empty.
  *
- * @example
+ * **Example** (Checking whether a set is empty)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -803,8 +852,8 @@ export const size = <V>(self: TxHashSet<V>): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const isEmpty = <V>(self: TxHashSet<V>): Effect.Effect<boolean> =>
   Effect.gen(function*() {
@@ -818,7 +867,8 @@ export const isEmpty = <V>(self: TxHashSet<V>): Effect.Effect<boolean> =>
  * **Mutation behavior**: This function mutates the original TxHashSet by clearing
  * all values. It does not return a new TxHashSet reference.
  *
- * @example
+ * **Example** (Clearing all values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -832,15 +882,16 @@ export const isEmpty = <V>(self: TxHashSet<V>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const clear = <V>(self: TxHashSet<V>): Effect.Effect<void> => TxRef.set(self.ref, HashSet.empty<V>())
 
 /**
  * Creates the union of two TxHashSets, returning a new TxHashSet.
  *
- * @example
+ * **Example** (Combining sets with union)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -855,14 +906,15 @@ export const clear = <V>(self: TxHashSet<V>): Effect.Effect<void> => TxRef.set(s
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const union: {
   /**
    * Creates the union of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Combining sets with union)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -877,14 +929,15 @@ export const union: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>): <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V1 | V0>>
   /**
    * Creates the union of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Combining sets with union)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -899,15 +952,16 @@ export const union: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>): Effect.Effect<TxHashSet<V0 | V1>>
 } = dual<
   /**
    * Creates the union of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Combining sets with union)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -922,14 +976,15 @@ export const union: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>) => <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V1 | V0>>,
   /**
    * Creates the union of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Combining sets with union)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -944,8 +999,8 @@ export const union: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) => Effect.Effect<TxHashSet<V0 | V1>>
 >(2, <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) =>
@@ -959,7 +1014,8 @@ export const union: {
 /**
  * Creates the intersection of two TxHashSets, returning a new TxHashSet.
  *
- * @example
+ * **Example** (Finding common values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -974,14 +1030,15 @@ export const union: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const intersection: {
   /**
    * Creates the intersection of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding common values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -996,14 +1053,15 @@ export const intersection: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>): <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V1 & V0>>
   /**
    * Creates the intersection of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding common values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1018,15 +1076,16 @@ export const intersection: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>): Effect.Effect<TxHashSet<V0 & V1>>
 } = dual<
   /**
    * Creates the intersection of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding common values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1041,14 +1100,15 @@ export const intersection: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>) => <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V1 & V0>>,
   /**
    * Creates the intersection of two TxHashSets, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding common values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1063,8 +1123,8 @@ export const intersection: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) => Effect.Effect<TxHashSet<V0 & V1>>
 >(2, <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) =>
@@ -1078,7 +1138,8 @@ export const intersection: {
 /**
  * Creates the difference of two TxHashSets (elements in the first set that are not in the second), returning a new TxHashSet.
  *
- * @example
+ * **Example** (Finding values absent from another set)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1093,14 +1154,15 @@ export const intersection: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export const difference: {
   /**
    * Creates the difference of two TxHashSets (elements in the first set that are not in the second), returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding values absent from another set)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1115,14 +1177,15 @@ export const difference: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>): <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V0>>
   /**
    * Creates the difference of two TxHashSets (elements in the first set that are not in the second), returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding values absent from another set)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1137,15 +1200,16 @@ export const difference: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>): Effect.Effect<TxHashSet<V0>>
 } = dual<
   /**
    * Creates the difference of two TxHashSets (elements in the first set that are not in the second), returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding values absent from another set)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1160,14 +1224,15 @@ export const difference: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>) => <V0>(self: TxHashSet<V0>) => Effect.Effect<TxHashSet<V0>>,
   /**
    * Creates the difference of two TxHashSets (elements in the first set that are not in the second), returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Finding values absent from another set)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1182,8 +1247,8 @@ export const difference: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) => Effect.Effect<TxHashSet<V0>>
 >(2, <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) =>
@@ -1197,7 +1262,8 @@ export const difference: {
 /**
  * Checks if a TxHashSet is a subset of another TxHashSet.
  *
- * @example
+ * **Example** (Checking subset relationships)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1213,14 +1279,15 @@ export const difference: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const isSubset: {
   /**
    * Checks if a TxHashSet is a subset of another TxHashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1236,14 +1303,15 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>): <V0>(self: TxHashSet<V0>) => Effect.Effect<boolean>
   /**
    * Checks if a TxHashSet is a subset of another TxHashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1259,15 +1327,16 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>): Effect.Effect<boolean>
 } = dual<
   /**
    * Checks if a TxHashSet is a subset of another TxHashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1283,14 +1352,15 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V1>(that: TxHashSet<V1>) => <V0>(self: TxHashSet<V0>) => Effect.Effect<boolean>,
   /**
    * Checks if a TxHashSet is a subset of another TxHashSet.
    *
-   * @example
+   * **Example** (Checking subset relationships)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1306,8 +1376,8 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) => Effect.Effect<boolean>
 >(2, <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) =>
@@ -1320,7 +1390,8 @@ export const isSubset: {
 /**
  * Tests whether at least one value in the TxHashSet satisfies the predicate.
  *
- * @example
+ * **Example** (Testing whether some values match)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1335,14 +1406,15 @@ export const isSubset: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const some: {
   /**
    * Tests whether at least one value in the TxHashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1357,14 +1429,15 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
    * Tests whether at least one value in the TxHashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1379,15 +1452,16 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>): Effect.Effect<boolean>
 } = dual<
   /**
    * Tests whether at least one value in the TxHashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1402,14 +1476,15 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
    * Tests whether at least one value in the TxHashSet satisfies the predicate.
    *
-   * @example
+   * **Example** (Testing whether some values match)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1424,8 +1499,8 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, predicate: Predicate<V>) =>
@@ -1437,7 +1512,8 @@ export const some: {
 /**
  * Tests whether all values in the TxHashSet satisfy the predicate.
  *
- * @example
+ * **Example** (Testing whether every value matches)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1452,14 +1528,15 @@ export const some: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const every: {
   /**
    * Tests whether all values in the TxHashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1474,14 +1551,15 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>): (self: TxHashSet<V>) => Effect.Effect<boolean>
   /**
    * Tests whether all values in the TxHashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1496,15 +1574,16 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>): Effect.Effect<boolean>
 } = dual<
   /**
    * Tests whether all values in the TxHashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1519,14 +1598,15 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<V>) => (self: TxHashSet<V>) => Effect.Effect<boolean>,
   /**
    * Tests whether all values in the TxHashSet satisfy the predicate.
    *
-   * @example
+   * **Example** (Testing whether every value matches)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1541,8 +1621,8 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, predicate: Predicate<V>) =>
@@ -1554,7 +1634,8 @@ export const every: {
 /**
  * Maps each value in the TxHashSet using the provided function, returning a new TxHashSet.
  *
- * @example
+ * **Example** (Mapping values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1574,14 +1655,15 @@ export const every: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 2.0.0
  */
 export const map: {
   /**
    * Maps each value in the TxHashSet using the provided function, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1601,14 +1683,15 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(f: (value: V) => U): (self: TxHashSet<V>) => Effect.Effect<TxHashSet<U>>
   /**
    * Maps each value in the TxHashSet using the provided function, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1628,15 +1711,16 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(self: TxHashSet<V>, f: (value: V) => U): Effect.Effect<TxHashSet<U>>
 } = dual<
   /**
    * Maps each value in the TxHashSet using the provided function, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1656,14 +1740,15 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(f: (value: V) => U) => (self: TxHashSet<V>) => Effect.Effect<TxHashSet<U>>,
   /**
    * Maps each value in the TxHashSet using the provided function, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Mapping values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1683,8 +1768,8 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 2.0.0
    */
   <V, U>(self: TxHashSet<V>, f: (value: V) => U) => Effect.Effect<TxHashSet<U>>
 >(2, <V, U>(self: TxHashSet<V>, f: (value: V) => U) =>
@@ -1697,7 +1782,8 @@ export const map: {
 /**
  * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
  *
- * @example
+ * **Example** (Filtering values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1711,14 +1797,15 @@ export const map: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 2.0.0
  */
 export const filter: {
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1732,14 +1819,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V, U extends V>(refinement: Refinement<NoInfer<V>, U>): (self: TxHashSet<V>) => Effect.Effect<TxHashSet<U>>
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1753,14 +1841,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V>(predicate: Predicate<NoInfer<V>>): (self: TxHashSet<V>) => Effect.Effect<TxHashSet<V>>
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1774,14 +1863,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V, U extends V>(self: TxHashSet<V>, refinement: Refinement<V, U>): Effect.Effect<TxHashSet<U>>
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1795,15 +1885,16 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>): Effect.Effect<TxHashSet<V>>
 } = dual<
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1817,8 +1908,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   {
     <V, U extends V>(
@@ -1831,7 +1922,8 @@ export const filter: {
   /**
    * Filters the TxHashSet keeping only values that satisfy the predicate, returning a new TxHashSet.
    *
-   * @example
+   * **Example** (Filtering values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1845,8 +1937,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 2.0.0
    */
   {
     <V, U extends V>(
@@ -1865,7 +1957,8 @@ export const filter: {
 /**
  * Reduces the TxHashSet to a single value by iterating through the values and applying an accumulator function.
  *
- * @example
+ * **Example** (Reducing values)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  *
@@ -1881,14 +1974,15 @@ export const filter: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category folding
+ * @since 2.0.0
  */
 export const reduce: {
   /**
    * Reduces the TxHashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1904,14 +1998,15 @@ export const reduce: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(zero: U, f: (accumulator: U, value: V) => U): (self: TxHashSet<V>) => Effect.Effect<U>
   /**
    * Reduces the TxHashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1927,15 +2022,16 @@ export const reduce: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(self: TxHashSet<V>, zero: U, f: (accumulator: U, value: V) => U): Effect.Effect<U>
 } = dual<
   /**
    * Reduces the TxHashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1951,14 +2047,15 @@ export const reduce: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(zero: U, f: (accumulator: U, value: V) => U) => (self: TxHashSet<V>) => Effect.Effect<U>,
   /**
    * Reduces the TxHashSet to a single value by iterating through the values and applying an accumulator function.
    *
-   * @example
+   * **Example** (Reducing values)
+   *
    * ```ts
    * import { Effect, TxHashSet } from "effect"
    *
@@ -1974,8 +2071,8 @@ export const reduce: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category folding
+   * @since 2.0.0
    */
   <V, U>(self: TxHashSet<V>, zero: U, f: (accumulator: U, value: V) => U) => Effect.Effect<U>
 >(3, <V, U>(self: TxHashSet<V>, zero: U, f: (accumulator: U, value: V) => U) =>
@@ -1987,7 +2084,8 @@ export const reduce: {
 /**
  * Converts the TxHashSet to an immutable HashSet snapshot.
  *
- * @example
+ * **Example** (Taking a HashSet snapshot)
+ *
  * ```ts
  * import { Effect, TxHashSet } from "effect"
  * import * as HashSet from "effect/HashSet"
@@ -2006,7 +2104,7 @@ export const reduce: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category conversions
+ * @since 2.0.0
  */
 export const toHashSet = <V>(self: TxHashSet<V>): Effect.Effect<HashSet.HashSet<V>> => TxRef.get(self.ref)