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

package/src/Ref.ts

@@ -1,32 +1,54 @@
 /**
- * This module provides utilities for working with mutable references in a functional context.
- *
- * A Ref is a mutable reference that can be read, written, and atomically modified. Unlike plain
- * mutable variables, Refs are thread-safe and work seamlessly with Effect's concurrency model.
- * They provide atomic operations for safe state management in concurrent programs.
- *
- * **Example** (Managing shared state with refs)
+ * The `Ref` module provides fiber-safe mutable references for state inside
+ * Effect programs. A `Ref<A>` holds one value of type `A` and exposes reads,
+ * writes, and atomic transformations as effects, so state changes compose with
+ * Effect's concurrency model.
+ *
+ * **Mental model**
+ *
+ * - {@link make} creates a reference with an initial value
+ * - {@link get} reads the current value, and {@link set} replaces it
+ * - {@link update}, {@link updateAndGet}, and {@link getAndUpdate} transform
+ *   the current value atomically
+ * - {@link modify} updates the value and returns a separate result computed
+ *   from the previous value
+ * - The `Some` variants use `Option` to leave the value unchanged when a
+ *   partial update does not apply
+ *
+ * **Common tasks**
+ *
+ * - Create refs: {@link make}, {@link makeUnsafe}
+ * - Read and write: {@link get}, {@link set}, {@link getAndSet},
+ *   {@link setAndGet}
+ * - Update state: {@link update}, {@link updateAndGet}, {@link getAndUpdate}
+ * - Update conditionally: {@link updateSome}, {@link updateSomeAndGet},
+ *   {@link getAndUpdateSome}, {@link modifySome}
+ * - Compute while updating: {@link modify}
+ *
+ * **Example** (Updating shared state)
  *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   // Create a ref with initial value
  *   const counter = yield* Ref.make(0)
  *
- *   // Atomic operations
- *   yield* Ref.update(counter, (n) => n + 1)
- *   yield* Ref.update(counter, (n) => n * 2)
- *
- *   const value = yield* Ref.get(counter)
- *   console.log(value) // 2
+ *   const next = yield* Ref.updateAndGet(counter, (n) => n + 1)
+ *   const label = yield* Ref.modify(counter, (n) => [`count=${n}`, n + 1])
  *
- *   // Atomic modify with return value
- *   const previous = yield* Ref.getAndSet(counter, 100)
- *   console.log(previous) // 2
+ *   return { label, next }
  * })
  * ```
  *
+ * **Gotchas**
+ *
+ * - Each `Ref` operation is atomic for that reference, but multiple refs are
+ *   not updated transactionally as a group
+ * - If the new value depends on the old value, prefer {@link update} or
+ *   {@link modify} over a separate {@link get} followed by {@link set}
+ * - Unsafe operations are synchronous low-level accessors; prefer effectful
+ *   operations in application code
+ *
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -42,6 +64,11 @@ const TypeId = "~effect/Ref"
 /**
  * A mutable reference that provides atomic read, write, and update operations.
  *
+ * **When to use**
+ *
+ * Use to keep shared mutable state that is read and updated inside Effect
+ * programs.
+ *
  * **Details**
  *
  * A `Ref` is a thread-safe mutable reference type for shared state. It supports
@@ -69,6 +96,10 @@ const TypeId = "~effect/Ref"
  * })
  * ```
  *
+ * @see {@link make} for creating a `Ref`
+ * @see {@link get} for reading the current value
+ * @see {@link set} for replacing the current value
+ *
  * @category models
  * @since 2.0.0
  */
@@ -79,12 +110,20 @@ export interface Ref<in out A> extends Ref.Variance<A>, Pipeable {
 /**
  * The Ref namespace containing type definitions and utilities.
  *
+ * **When to use**
+ *
+ * Use when referring to type members nested under the `Ref` namespace.
+ *
  * @since 2.0.0
  */
 export declare namespace Ref {
   /**
    * Variance interface for Ref types, defining the type parameter constraints.
    *
+   * **When to use**
+   *
+   * Use when working with the type-level variance marker carried by `Ref`.
+   *
    * **Example** (Using invariant refs)
    *
    * ```ts
@@ -129,7 +168,7 @@ const RefProto = {
  *
  * **When to use**
  *
- * Use this when you need immediate synchronous construction and can guarantee
+ * Use when you need immediate synchronous construction and can guarantee
  * that creating the `Ref` outside of `Effect` is safe.
  *
  * **Gotchas**
@@ -164,6 +203,10 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
 /**
  * Creates a new Ref with the specified initial value.
  *
+ * **When to use**
+ *
+ * Use to create shared mutable state inside an Effect program.
+ *
  * **Example** (Creating a ref)
  *
  * ```ts
@@ -176,6 +219,8 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  * })
  * ```
  *
+ * @see {@link makeUnsafe} for synchronous construction outside Effect code
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -184,6 +229,10 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
 /**
  * Gets the current value of the Ref.
  *
+ * **When to use**
+ *
+ * Use to read the current value without changing it.
+ *
  * **Example** (Getting the current value)
  *
  * ```ts
@@ -196,6 +245,8 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
  * })
  * ```
  *
+ * @see {@link set} for replacing the current value
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -204,6 +255,10 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
 /**
  * Sets the value of the Ref to the specified value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value with a known value.
+ *
  * **Example** (Setting a value)
  *
  * ```ts
@@ -225,6 +280,9 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
  * })
  * ```
  *
+ * @see {@link getAndSet} for setting while returning the previous value
+ * @see {@link setAndGet} for setting while returning the new value
+ *
  * @category setters
  * @since 2.0.0
  */
@@ -232,6 +290,10 @@ export const set = dual<
   /**
    * Sets the value of the Ref to the specified value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value.
+   *
    * **Example** (Setting a value)
    *
    * ```ts
@@ -253,6 +315,9 @@ export const set = dual<
    * })
    * ```
    *
+   * @see {@link getAndSet} for setting while returning the previous value
+   * @see {@link setAndGet} for setting while returning the new value
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -260,6 +325,10 @@ export const set = dual<
   /**
    * Sets the value of the Ref to the specified value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value.
+   *
    * **Example** (Setting a value)
    *
    * ```ts
@@ -281,6 +350,9 @@ export const set = dual<
    * })
    * ```
    *
+   * @see {@link getAndSet} for setting while returning the previous value
+   * @see {@link setAndGet} for setting while returning the new value
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -288,7 +360,11 @@ export const set = dual<
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => MutableRef.set(self.ref, value)))
 
 /**
- * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
+ * Gets the current value of the Ref, sets it to the specified value, and returns the previous value atomically.
+ *
+ * **When to use**
+ *
+ * Use to replace the value while returning the previous value.
  *
  * **Example** (Replacing a value atomically)
  *
@@ -307,12 +383,19 @@ export const set = dual<
  * })
  * ```
  *
+ * @see {@link set} for setting without returning the previous value
+ * @see {@link getAndUpdate} for deriving the new value from the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
 export const getAndSet = dual<
   /**
-   * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
+   * Gets the current value of the Ref, sets it to the specified value, and returns the previous value atomically.
+   *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
    *
    * **Example** (Replacing a value atomically)
    *
@@ -331,12 +414,19 @@ export const getAndSet = dual<
    * })
    * ```
    *
+   * @see {@link set} for setting without returning the previous value
+   * @see {@link getAndUpdate} for deriving the new value from the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
+   * Gets the current value of the Ref, sets it to the specified value, and returns the previous value atomically.
+   *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
    *
    * **Example** (Replacing a value atomically)
    *
@@ -355,6 +445,9 @@ export const getAndSet = dual<
    * })
    * ```
    *
+   * @see {@link set} for setting without returning the previous value
+   * @see {@link getAndUpdate} for deriving the new value from the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -367,7 +460,11 @@ export const getAndSet = dual<
   }))
 
 /**
- * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
+ * Gets the current value of the Ref, updates it with the given function, and returns the previous value atomically.
+ *
+ * **When to use**
+ *
+ * Use to derive a new value while returning the previous value.
  *
  * **Example** (Updating and returning the previous value)
  *
@@ -386,12 +483,19 @@ export const getAndSet = dual<
  * })
  * ```
  *
+ * @see {@link update} for updating without returning the previous value
+ * @see {@link updateAndGet} for returning the new value instead
+ *
  * @category utils
  * @since 2.0.0
  */
 export const getAndUpdate = dual<
   /**
-   * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
+   * Gets the current value of the Ref, updates it with the given function, and returns the previous value atomically.
+   *
+   * **When to use**
+   *
+   * Use to derive a new value while returning the previous value.
    *
    * **Example** (Updating and returning the previous value)
    *
@@ -410,12 +514,19 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the previous value
+   * @see {@link updateAndGet} for returning the new value instead
+   *
    * @category utils
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
+   * Gets the current value of the Ref, updates it with the given function, and returns the previous value atomically.
+   *
+   * **When to use**
+   *
+   * Use to derive a new value while returning the previous value.
    *
    * **Example** (Updating and returning the previous value)
    *
@@ -434,6 +545,9 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the previous value
+   * @see {@link updateAndGet} for returning the new value instead
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -446,7 +560,11 @@ export const getAndUpdate = dual<
   }))
 
 /**
- * Atomically gets the current value of the Ref and updates it with the given partial function.
+ * Gets the current value of the Ref and updates it atomically with the given partial function.
+ *
+ * **When to use**
+ *
+ * Use to return the previous value while applying a conditional update.
  *
  * **Details**
  *
@@ -484,12 +602,19 @@ export const getAndUpdate = dual<
  * })
  * ```
  *
+ * @see {@link getAndUpdate} for always applying an update
+ * @see {@link updateSome} for conditional updates without returning the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
 export const getAndUpdateSome = dual<
   /**
-   * Atomically gets the current value of the Ref and updates it with the given partial function.
+   * Gets the current value of the Ref and updates it atomically with the given partial function.
+   *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a conditional update.
    *
    * **Details**
    *
@@ -527,12 +652,19 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
+   * @see {@link getAndUpdate} for always applying an update
+   * @see {@link updateSome} for conditional updates without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically gets the current value of the Ref and updates it with the given partial function.
+   * Gets the current value of the Ref and updates it atomically with the given partial function.
+   *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a conditional update.
    *
    * **Details**
    *
@@ -570,6 +702,9 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
+   * @see {@link getAndUpdate} for always applying an update
+   * @see {@link updateSome} for conditional updates without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -585,11 +720,11 @@ export const getAndUpdateSome = dual<
   }))
 
 /**
- * Atomically sets the value of the Ref to the specified value and returns the new value.
+ * Sets the value of the Ref atomically to the specified value and returns the new value.
  *
  * **When to use**
  *
- * Use this when you want to set a value and immediately get it back in one
+ * Use when you want to set a value and immediately get it back in one
  * atomic operation.
  *
  * **Example** (Setting and returning the new value)
@@ -623,11 +758,11 @@ export const getAndUpdateSome = dual<
  */
 export const setAndGet = dual<
   /**
-   * Atomically sets the value of the Ref to the specified value and returns the new value.
+   * Sets the value of the Ref atomically to the specified value and returns the new value.
    *
    * **When to use**
    *
-   * Use this when you want to set a value and immediately get it back in one
+   * Use when you want to set a value and immediately get it back in one
    * atomic operation.
    *
    * **Example** (Setting and returning the new value)
@@ -661,11 +796,11 @@ export const setAndGet = dual<
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically sets the value of the Ref to the specified value and returns the new value.
+   * Sets the value of the Ref atomically to the specified value and returns the new value.
    *
    * **When to use**
    *
-   * Use this when you want to set a value and immediately get it back in one
+   * Use when you want to set a value and immediately get it back in one
    * atomic operation.
    *
    * **Example** (Setting and returning the new value)
@@ -701,7 +836,12 @@ export const setAndGet = dual<
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => self.ref.current = value))
 
 /**
- * Atomically modifies the value of the Ref using the given function.
+ * Modifies the value of the Ref atomically using the given function.
+ *
+ * **When to use**
+ *
+ * Use to compute both a separate return value and the next stored value in one
+ * atomic update.
  *
  * **Details**
  *
@@ -742,12 +882,20 @@ export const setAndGet = dual<
  * })
  * ```
  *
+ * @see {@link updateAndGet} for returning the new stored value
+ * @see {@link modifySome} for optionally updating while returning a separate result
+ *
  * @category setters
  * @since 2.0.0
  */
 export const modify = dual<
   /**
-   * Atomically modifies the value of the Ref using the given function.
+   * Modifies the value of the Ref atomically using the given function.
+   *
+   * **When to use**
+   *
+   * Use to compute both a separate return value and the next stored value in one
+   * atomic update.
    *
    * **Details**
    *
@@ -788,12 +936,20 @@ export const modify = dual<
    * })
    * ```
    *
+   * @see {@link updateAndGet} for returning the new stored value
+   * @see {@link modifySome} for optionally updating while returning a separate result
+   *
    * @category setters
    * @since 2.0.0
    */
   <A, B>(f: (a: A) => readonly [B, A]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
-   * Atomically modifies the value of the Ref using the given function.
+   * Modifies the value of the Ref atomically using the given function.
+   *
+   * **When to use**
+   *
+   * Use to compute both a separate return value and the next stored value in one
+   * atomic update.
    *
    * **Details**
    *
@@ -834,6 +990,9 @@ export const modify = dual<
    * })
    * ```
    *
+   * @see {@link updateAndGet} for returning the new stored value
+   * @see {@link modifySome} for optionally updating while returning a separate result
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -846,7 +1005,11 @@ export const modify = dual<
   }))
 
 /**
- * Atomically computes a result and optionally updates the value of the `Ref`.
+ * Computes a result atomically and optionally updates the value of the `Ref`.
+ *
+ * **When to use**
+ *
+ * Use to compute a return value while optionally updating the stored value.
  *
  * **Details**
  *
@@ -893,12 +1056,19 @@ export const modify = dual<
  * })
  * ```
  *
+ * @see {@link modify} for always storing a new value
+ * @see {@link updateSome} for optional updates without a separate return value
+ *
  * @category setters
  * @since 2.0.0
  */
 export const modifySome: {
   /**
-   * Atomically computes a result and optionally updates the value of the `Ref`.
+   * Computes a result atomically and optionally updates the value of the `Ref`.
+   *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
    *
    * **Details**
    *
@@ -945,12 +1115,19 @@ export const modifySome: {
    * })
    * ```
    *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category setters
    * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: Ref<A>) => Effect.Effect<B>
   /**
-   * Atomically computes a result and optionally updates the value of the `Ref`.
+   * Computes a result atomically and optionally updates the value of the `Ref`.
+   *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
    *
    * **Details**
    *
@@ -997,13 +1174,20 @@ export const modifySome: {
    * })
    * ```
    *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category setters
    * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual<
   /**
-   * Atomically computes a result and optionally updates the value of the `Ref`.
+   * Computes a result atomically and optionally updates the value of the `Ref`.
+   *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
    *
    * **Details**
    *
@@ -1050,12 +1234,19 @@ export const modifySome: {
    * })
    * ```
    *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category setters
    * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
-   * Atomically computes a result and optionally updates the value of the `Ref`.
+   * Computes a result atomically and optionally updates the value of the `Ref`.
+   *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
    *
    * **Details**
    *
@@ -1102,6 +1293,9 @@ export const modifySome: {
    * })
    * ```
    *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -1113,7 +1307,11 @@ export const modifySome: {
   }))
 
 /**
- * Atomically updates the value of the Ref using the given function.
+ * Updates the value of the Ref atomically using the given function.
+ *
+ * **When to use**
+ *
+ * Use to apply a state transition without returning a value.
  *
  * **Example** (Updating a value)
  *
@@ -1139,12 +1337,19 @@ export const modifySome: {
  * })
  * ```
  *
+ * @see {@link updateAndGet} for returning the new value
+ * @see {@link getAndUpdate} for returning the previous value
+ *
  * @category setters
  * @since 2.0.0
  */
 export const update = dual<
   /**
-   * Atomically updates the value of the Ref using the given function.
+   * Updates the value of the Ref atomically using the given function.
+   *
+   * **When to use**
+   *
+   * Use to apply a state transition without returning a value.
    *
    * **Example** (Updating a value)
    *
@@ -1170,12 +1375,19 @@ export const update = dual<
    * })
    * ```
    *
+   * @see {@link updateAndGet} for returning the new value
+   * @see {@link getAndUpdate} for returning the previous value
+   *
    * @category setters
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<void>,
   /**
-   * Atomically updates the value of the Ref using the given function.
+   * Updates the value of the Ref atomically using the given function.
+   *
+   * **When to use**
+   *
+   * Use to apply a state transition without returning a value.
    *
    * **Example** (Updating a value)
    *
@@ -1201,6 +1413,9 @@ export const update = dual<
    * })
    * ```
    *
+   * @see {@link updateAndGet} for returning the new value
+   * @see {@link getAndUpdate} for returning the previous value
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -1211,7 +1426,11 @@ export const update = dual<
   }))
 
 /**
- * Atomically updates the value of the Ref using the given function and returns the new value.
+ * Updates the value of the Ref atomically using the given function and returns the new value.
+ *
+ * **When to use**
+ *
+ * Use to apply a state transition and return the new stored value.
  *
  * **Example** (Updating and returning the new value)
  *
@@ -1231,12 +1450,19 @@ export const update = dual<
  * })
  * ```
  *
+ * @see {@link update} for updating without returning the new value
+ * @see {@link getAndUpdate} for returning the previous value instead
+ *
  * @category utils
  * @since 2.0.0
  */
 export const updateAndGet = dual<
   /**
-   * Atomically updates the value of the Ref using the given function and returns the new value.
+   * Updates the value of the Ref atomically using the given function and returns the new value.
+   *
+   * **When to use**
+   *
+   * Use to apply a state transition and return the new stored value.
    *
    * **Example** (Updating and returning the new value)
    *
@@ -1256,12 +1482,19 @@ export const updateAndGet = dual<
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for returning the previous value instead
+   *
    * @category utils
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically updates the value of the Ref using the given function and returns the new value.
+   * Updates the value of the Ref atomically using the given function and returns the new value.
+   *
+   * **When to use**
+   *
+   * Use to apply a state transition and return the new stored value.
    *
    * **Example** (Updating and returning the new value)
    *
@@ -1281,6 +1514,9 @@ export const updateAndGet = dual<
    * })
    * ```
    *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for returning the previous value instead
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -1288,7 +1524,11 @@ export const updateAndGet = dual<
 >(2, <A>(self: Ref<A>, f: (a: A) => A) => Effect.sync(() => self.ref.current = f(self.ref.current)))
 
 /**
- * Atomically updates the value of the Ref using the given partial function.
+ * Updates the value of the Ref atomically using the given partial function.
+ *
+ * **When to use**
+ *
+ * Use to apply a conditional update without returning a value.
  *
  * **Details**
  *
@@ -1324,12 +1564,19 @@ export const updateAndGet = dual<
  * })
  * ```
  *
+ * @see {@link update} for always applying an update
+ * @see {@link updateSomeAndGet} for returning the resulting current value
+ *
  * @category setters
  * @since 2.0.0
  */
 export const updateSome = dual<
   /**
-   * Atomically updates the value of the Ref using the given partial function.
+   * Updates the value of the Ref atomically using the given partial function.
+   *
+   * **When to use**
+   *
+   * Use to apply a conditional update without returning a value.
    *
    * **Details**
    *
@@ -1365,12 +1612,19 @@ export const updateSome = dual<
    * })
    * ```
    *
+   * @see {@link update} for always applying an update
+   * @see {@link updateSomeAndGet} for returning the resulting current value
+   *
    * @category setters
    * @since 2.0.0
    */
   <A>(f: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<void>,
   /**
-   * Atomically updates the value of the Ref using the given partial function.
+   * Updates the value of the Ref atomically using the given partial function.
+   *
+   * **When to use**
+   *
+   * Use to apply a conditional update without returning a value.
    *
    * **Details**
    *
@@ -1406,6 +1660,9 @@ export const updateSome = dual<
    * })
    * ```
    *
+   * @see {@link update} for always applying an update
+   * @see {@link updateSomeAndGet} for returning the resulting current value
+   *
    * @category setters
    * @since 2.0.0
    */
@@ -1419,7 +1676,11 @@ export const updateSome = dual<
   }))
 
 /**
- * Atomically updates the value of the Ref using the given partial function and returns the current value.
+ * Updates the value of the Ref atomically using the given partial function and returns the current value.
+ *
+ * **When to use**
+ *
+ * Use to apply a conditional update and return the resulting current value.
  *
  * **Details**
  *
@@ -1451,12 +1712,19 @@ export const updateSome = dual<
  * })
  * ```
  *
+ * @see {@link updateSome} for conditional updates without returning a value
+ * @see {@link updateAndGet} for always updating and returning the new value
+ *
  * @category utils
  * @since 2.0.0
  */
 export const updateSomeAndGet = dual<
   /**
-   * Atomically updates the value of the Ref using the given partial function and returns the current value.
+   * Updates the value of the Ref atomically using the given partial function and returns the current value.
+   *
+   * **When to use**
+   *
+   * Use to apply a conditional update and return the resulting current value.
    *
    * **Details**
    *
@@ -1488,12 +1756,19 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
+   * @see {@link updateSome} for conditional updates without returning a value
+   * @see {@link updateAndGet} for always updating and returning the new value
+   *
    * @category utils
    * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
-   * Atomically updates the value of the Ref using the given partial function and returns the current value.
+   * Updates the value of the Ref atomically using the given partial function and returns the current value.
+   *
+   * **When to use**
+   *
+   * Use to apply a conditional update and return the resulting current value.
    *
    * **Details**
    *
@@ -1525,6 +1800,9 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
+   * @see {@link updateSome} for conditional updates without returning a value
+   * @see {@link updateAndGet} for always updating and returning the new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -1543,7 +1821,7 @@ export const updateSomeAndGet = dual<
  *
  * **When to use**
  *
- * Use this when you need immediate synchronous access and can guarantee that
+ * Use when you need immediate synchronous access and can guarantee that
  * reading the `Ref` outside of `Effect` is safe.
  *
  * **Gotchas**