effect 4.0.0-beta.70 → 4.0.0-beta.71

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
    */
@@ -290,6 +362,10 @@ export const set = dual<
 /**
  * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to replace the value while returning the previous value.
+ *
  * **Example** (Replacing a value atomically)
  *
  * ```ts
@@ -307,6 +383,9 @@ 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
  */
@@ -314,6 +393,10 @@ export const getAndSet = dual<
   /**
    * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
+   *
    * **Example** (Replacing a value atomically)
    *
    * ```ts
@@ -331,6 +414,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
    */
@@ -338,6 +424,10 @@ export const getAndSet = dual<
   /**
    * Atomically gets the current value of the Ref, sets it to the specified value, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to replace the value while returning the previous value.
+   *
    * **Example** (Replacing a value atomically)
    *
    * ```ts
@@ -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
    */
@@ -369,6 +462,10 @@ export const getAndSet = dual<
 /**
  * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use to derive a new value while returning the previous value.
+ *
  * **Example** (Updating and returning the previous value)
  *
  * ```ts
@@ -386,6 +483,9 @@ 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
  */
@@ -393,6 +493,10 @@ export const getAndUpdate = dual<
   /**
    * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to derive a new value while returning the previous value.
+   *
    * **Example** (Updating and returning the previous value)
    *
    * ```ts
@@ -410,6 +514,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
    */
@@ -417,6 +524,10 @@ export const getAndUpdate = dual<
   /**
    * Atomically gets the current value of the Ref, updates it with the given function, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use to derive a new value while returning the previous value.
+   *
    * **Example** (Updating and returning the previous value)
    *
    * ```ts
@@ -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
    */
@@ -448,6 +562,10 @@ export const getAndUpdate = dual<
 /**
  * Atomically gets the current value of the Ref and updates it with the given partial function.
  *
+ * **When to use**
+ *
+ * Use to return the previous value while applying a conditional update.
+ *
  * **Details**
  *
  * If the partial function returns `Option.some`, the Ref is updated with the
@@ -484,6 +602,9 @@ 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
  */
@@ -491,6 +612,10 @@ export const getAndUpdateSome = dual<
   /**
    * Atomically gets the current value of the Ref and updates it with the given partial function.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a conditional update.
+   *
    * **Details**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -527,6 +652,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
    */
@@ -534,6 +662,10 @@ export const getAndUpdateSome = dual<
   /**
    * Atomically gets the current value of the Ref and updates it with the given partial function.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a conditional update.
+   *
    * **Details**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -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
    */
@@ -589,7 +724,7 @@ export const getAndUpdateSome = dual<
  *
  * **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)
@@ -627,7 +762,7 @@ export const setAndGet = dual<
    *
    * **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)
@@ -665,7 +800,7 @@ export const setAndGet = dual<
    *
    * **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)
@@ -703,6 +838,11 @@ export const setAndGet = dual<
 /**
  * Atomically modifies the value of the Ref 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**
  *
  * The function receives the current value and returns a tuple of
@@ -742,6 +882,9 @@ 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
  */
@@ -749,6 +892,11 @@ export const modify = dual<
   /**
    * Atomically modifies the value of the Ref 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**
    *
    * The function receives the current value and returns a tuple of
@@ -788,6 +936,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
    */
@@ -795,6 +946,11 @@ export const modify = dual<
   /**
    * Atomically modifies the value of the Ref 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**
    *
    * The function receives the current value and returns a tuple of
@@ -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
    */
@@ -848,6 +1007,10 @@ export const modify = dual<
 /**
  * Atomically computes a result and optionally updates the value of the `Ref`.
  *
+ * **When to use**
+ *
+ * Use to compute a return value while optionally updating the stored value.
+ *
  * **Details**
  *
  * The callback receives the current value and returns `[result, nextValue]`,
@@ -893,6 +1056,9 @@ 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
  */
@@ -900,6 +1066,10 @@ export const modifySome: {
   /**
    * Atomically computes a result and optionally updates the value of the `Ref`.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
    * **Details**
    *
    * The callback receives the current value and returns `[result, nextValue]`,
@@ -945,6 +1115,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
    */
@@ -952,6 +1125,10 @@ export const modifySome: {
   /**
    * Atomically computes a result and optionally updates the value of the `Ref`.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
    * **Details**
    *
    * The callback receives the current value and returns `[result, nextValue]`,
@@ -997,6 +1174,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
    */
@@ -1005,6 +1185,10 @@ export const modifySome: {
   /**
    * Atomically computes a result and optionally updates the value of the `Ref`.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
    * **Details**
    *
    * The callback receives the current value and returns `[result, nextValue]`,
@@ -1050,6 +1234,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
    */
@@ -1057,6 +1244,10 @@ export const modifySome: {
   /**
    * Atomically computes a result and optionally updates the value of the `Ref`.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
    * **Details**
    *
    * The callback receives the current value and returns `[result, nextValue]`,
@@ -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
    */
@@ -1115,6 +1309,10 @@ export const modifySome: {
 /**
  * Atomically updates the value of the Ref using the given function.
  *
+ * **When to use**
+ *
+ * Use to apply a state transition without returning a value.
+ *
  * **Example** (Updating a value)
  *
  * ```ts
@@ -1139,6 +1337,9 @@ 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
  */
@@ -1146,6 +1347,10 @@ export const update = dual<
   /**
    * Atomically updates the value of the Ref using the given function.
    *
+   * **When to use**
+   *
+   * Use to apply a state transition without returning a value.
+   *
    * **Example** (Updating a value)
    *
    * ```ts
@@ -1170,6 +1375,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
    */
@@ -1177,6 +1385,10 @@ export const update = dual<
   /**
    * Atomically updates the value of the Ref using the given function.
    *
+   * **When to use**
+   *
+   * Use to apply a state transition without returning a value.
+   *
    * **Example** (Updating a value)
    *
    * ```ts
@@ -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
    */
@@ -1213,6 +1428,10 @@ export const update = dual<
 /**
  * Atomically updates the value of the Ref 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)
  *
  * ```ts
@@ -1231,6 +1450,9 @@ 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
  */
@@ -1238,6 +1460,10 @@ export const updateAndGet = dual<
   /**
    * Atomically updates the value of the Ref 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)
    *
    * ```ts
@@ -1256,6 +1482,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
    */
@@ -1263,6 +1492,10 @@ export const updateAndGet = dual<
   /**
    * Atomically updates the value of the Ref 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)
    *
    * ```ts
@@ -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
    */
@@ -1290,6 +1526,10 @@ export const updateAndGet = dual<
 /**
  * Atomically updates the value of the Ref using the given partial function.
  *
+ * **When to use**
+ *
+ * Use to apply a conditional update without returning a value.
+ *
  * **Details**
  *
  * If the partial function returns `Option.some`, the Ref is updated with the
@@ -1324,6 +1564,9 @@ 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
  */
@@ -1331,6 +1574,10 @@ export const updateSome = dual<
   /**
    * Atomically updates the value of the Ref using the given partial function.
    *
+   * **When to use**
+   *
+   * Use to apply a conditional update without returning a value.
+   *
    * **Details**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -1365,6 +1612,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
    */
@@ -1372,6 +1622,10 @@ export const updateSome = dual<
   /**
    * Atomically updates the value of the Ref using the given partial function.
    *
+   * **When to use**
+   *
+   * Use to apply a conditional update without returning a value.
+   *
    * **Details**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -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
    */
@@ -1421,6 +1678,10 @@ export const updateSome = dual<
 /**
  * Atomically updates the value of the Ref 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**
  *
  * If the partial function returns `Option.some`, the Ref is updated with the
@@ -1451,6 +1712,9 @@ 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
  */
@@ -1458,6 +1722,10 @@ export const updateSomeAndGet = dual<
   /**
    * Atomically updates the value of the Ref 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**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -1488,6 +1756,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
    */
@@ -1495,6 +1766,10 @@ export const updateSomeAndGet = dual<
   /**
    * Atomically updates the value of the Ref 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**
    *
    * If the partial function returns `Option.some`, the Ref is updated with the
@@ -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**