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

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} 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 4.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,31 @@ export interface TxHashSet<in out V> extends Inspectable, Pipeable {
  * })
  * ```
  *
- * @since 2.0.0
- * @category models
+ * @since 4.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 4.0.0
    */
   export type Value<T> = T extends TxHashSet<infer V> ? V : never
 }
@@ -145,7 +171,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 +189,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 +201,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 +218,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 +233,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 +247,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,10 +264,10 @@ 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"
+ * import { Effect, HashSet, TxHashSet } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const hashSet = HashSet.make("x", "y", "z")
@@ -254,8 +283,8 @@ export const fromIterable = <V>(values: Iterable<V>): Effect.Effect<TxHashSet<V>
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHashSet<V>> =>
   Effect.gen(function*() {
@@ -266,10 +295,10 @@ 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"
+ * import { Effect, HashSet, TxHashSet } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const txSet = yield* TxHashSet.make(1, 2, 3)
@@ -283,8 +312,8 @@ export const fromHashSet = <V>(hashSet: HashSet.HashSet<V>): Effect.Effect<TxHas
  * })
  * ```
  *
- * @since 2.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxHashSet = (u: unknown): u is TxHashSet<unknown> => hasProperty(u, TypeId)
 
@@ -294,7 +323,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 +341,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 +351,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 +369,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 +379,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 +397,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 +408,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 +426,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 +436,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 +454,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 +466,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 +485,8 @@ export const add: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 2.0.0
  */
 export const remove: {
   /**
@@ -460,7 +495,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 +514,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 +524,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 +543,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 +554,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 +573,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 +583,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 +602,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 +619,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 +648,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 +684,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 +720,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 +757,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 +793,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 +806,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 +823,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 +835,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 +849,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 +864,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 +879,16 @@ export const isEmpty = <V>(self: TxHashSet<V>): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 2.0.0
  * @category mutations
+ * @since 4.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 +903,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 +926,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 +949,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 +973,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 +996,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 +1011,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 +1027,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 +1050,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 +1073,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 +1097,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 +1120,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 +1135,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 +1151,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 +1174,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 +1197,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 +1221,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 +1244,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 +1259,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 +1276,15 @@ export const difference: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 4.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 +1300,15 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1324,16 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1349,15 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1373,8 @@ export const isSubset: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.0.0
    */
   <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) => Effect.Effect<boolean>
 >(2, <V0, V1>(self: TxHashSet<V0>, that: TxHashSet<V1>) =>
@@ -1320,7 +1387,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 +1403,15 @@ export const isSubset: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 4.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 +1426,15 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1449,16 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1473,15 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1496,8 @@ export const some: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, predicate: Predicate<V>) =>
@@ -1437,7 +1509,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 +1525,15 @@ export const some: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 4.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 +1548,15 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1571,16 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1595,15 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.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 +1618,8 @@ export const every: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category elements
+   * @since 4.0.0
    */
   <V>(self: TxHashSet<V>, predicate: Predicate<V>) => Effect.Effect<boolean>
 >(2, <V>(self: TxHashSet<V>, predicate: Predicate<V>) =>
@@ -1554,7 +1631,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 +1652,15 @@ export const every: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category mapping
+ * @since 4.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 +1680,15 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 4.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 +1708,16 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 4.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 +1737,15 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 4.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 +1765,8 @@ export const map: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category mapping
+   * @since 4.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 +1779,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 +1794,15 @@ export const map: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category filtering
+ * @since 4.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 +1816,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.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 +1838,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.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 +1860,15 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.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 +1882,16 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.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 +1905,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.0.0
    */
   {
     <V, U extends V>(
@@ -1831,7 +1919,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 +1934,8 @@ export const filter: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category filtering
+   * @since 4.0.0
    */
   {
     <V, U extends V>(
@@ -1865,7 +1954,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 +1971,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 +1995,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 +2019,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 +2044,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 +2068,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,10 +2081,10 @@ 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"
+ * import { Effect, HashSet, TxHashSet } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const txSet = yield* TxHashSet.make("x", "y", "z")
@@ -2006,7 +2100,7 @@ export const reduce: {
  * })
  * ```
  *
+ * @category converting
  * @since 2.0.0
- * @category conversions
  */
 export const toHashSet = <V>(self: TxHashSet<V>): Effect.Effect<HashSet.HashSet<V>> => TxRef.get(self.ref)