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

package/src/SynchronizedRef.ts

@@ -7,7 +7,7 @@
  *
  * **When to use**
  *
- * - Coordinating shared state that may be updated by many fibers
+ * Use to coordinate shared state that may be updated by many fibers
  * - Running effectful state transitions that must not overlap
  * - Computing both a return value and a new stored value atomically
  * - Applying partial updates with `Option`, where `None` leaves the value
@@ -36,6 +36,14 @@ const TypeId = "~effect/SynchronizedRef"
  * A mutable reference whose update and modify operations are serialized with an
  * internal semaphore, including effectful transformations.
  *
+ * **When to use**
+ *
+ * Use when shared state may be updated by multiple fibers and each update,
+ * including effectful state transitions, must observe one current value and run
+ * one at a time.
+ *
+ * @see {@link Ref.Ref} for a plain `Ref` when updates do not need effectful synchronization
+ *
  * @category models
  * @since 2.0.0
  */
@@ -61,7 +69,7 @@ const Proto = {
  *
  * **When to use**
  *
- * This bypasses `Effect` construction; prefer `make` in effectful code.
+ * Use when synchronous construction is required outside an Effect workflow.
  *
  * @category constructors
  * @since 4.0.0
@@ -76,6 +84,19 @@ export const makeUnsafe = <A>(value: A): SynchronizedRef<A> => {
 /**
  * Creates a `SynchronizedRef` from an initial value, wrapped in an `Effect`.
  *
+ * **When to use**
+ *
+ * Use to create a synchronized reference inside an Effect program when later
+ * updates may run effects and must be serialized.
+ *
+ * **Details**
+ *
+ * The returned effect constructs a fresh `SynchronizedRef` by delegating to
+ * `makeUnsafe` when the effect is evaluated.
+ *
+ * @see {@link makeUnsafe} for synchronous construction when the caller controls safe initialization
+ * @see {@link Ref.make} for a plain `Ref` when updates do not need effectful synchronization
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -85,6 +106,13 @@ export const make = <A>(value: A): Effect.Effect<SynchronizedRef<A>> => Effect.s
  * Reads the current value synchronously, bypassing the `Effect` API and the
  * ref's semaphore.
  *
+ * **When to use**
+ *
+ * Use when you need immediate synchronous access to a `SynchronizedRef` value
+ * in low-level code that can safely read outside an `Effect`.
+ *
+ * @see {@link get} for the Effect-wrapped read when composing inside Effect programs
+ *
  * @category getters
  * @since 4.0.0
  */
@@ -93,6 +121,13 @@ export const getUnsafe = <A>(self: SynchronizedRef<A>): A => self.backing.ref.cu
 /**
  * Returns an `Effect` that reads the current value of the `SynchronizedRef`.
  *
+ * **When to use**
+ *
+ * Use to read the current value of a `SynchronizedRef` inside an `Effect`
+ * program without changing it.
+ *
+ * @see {@link getUnsafe} for synchronous reads when the caller controls safe access outside `Effect`
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -102,6 +137,15 @@ export const get = <A>(self: SynchronizedRef<A>): Effect.Effect<A> => Effect.syn
  * Atomically sets a new value and returns the previous value, serialized by the
  * ref's semaphore.
  *
+ * **When to use**
+ *
+ * Use to replace a `SynchronizedRef` with a known value when the previous value
+ * is also needed.
+ *
+ * @see {@link set} for setting a value without returning the previous value
+ * @see {@link setAndGet} for setting a value and returning the new value
+ * @see {@link getAndUpdate} for deriving the new value from the current value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -110,6 +154,15 @@ export const getAndSet: {
    * Atomically sets a new value and returns the previous value, serialized by the
    * ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to replace a `SynchronizedRef` with a known value when the previous value
+   * is also needed.
+   *
+   * @see {@link set} for setting a value without returning the previous value
+   * @see {@link setAndGet} for setting a value and returning the new value
+   * @see {@link getAndUpdate} for deriving the new value from the current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -118,6 +171,15 @@ export const getAndSet: {
    * Atomically sets a new value and returns the previous value, serialized by the
    * ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to replace a `SynchronizedRef` with a known value when the previous value
+   * is also needed.
+   *
+   * @see {@link set} for setting a value without returning the previous value
+   * @see {@link setAndGet} for setting a value and returning the new value
+   * @see {@link getAndUpdate} for deriving the new value from the current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -132,6 +194,14 @@ export const getAndSet: {
  * Atomically updates the current value with a function and returns the previous
  * value, serialized by the ref's semaphore.
  *
+ * **When to use**
+ *
+ * Use to run a pure state update when the previous stored value is also needed.
+ *
+ * @see {@link update} for updating without returning a value
+ * @see {@link updateAndGet} for updating and returning the new value
+ * @see {@link getAndUpdateEffect} for effectful updates that return the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -140,6 +210,14 @@ export const getAndUpdate: {
    * Atomically updates the current value with a function and returns the previous
    * value, serialized by the ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to run a pure state update when the previous stored value is also needed.
+   *
+   * @see {@link update} for updating without returning a value
+   * @see {@link updateAndGet} for updating and returning the new value
+   * @see {@link getAndUpdateEffect} for effectful updates that return the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -148,6 +226,14 @@ export const getAndUpdate: {
    * Atomically updates the current value with a function and returns the previous
    * value, serialized by the ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to run a pure state update when the previous stored value is also needed.
+   *
+   * @see {@link update} for updating without returning a value
+   * @see {@link updateAndGet} for updating and returning the new value
+   * @see {@link getAndUpdateEffect} for effectful updates that return the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -162,6 +248,16 @@ export const getAndUpdate: {
  * Atomically runs an effectful update while holding the ref's semaphore, sets
  * the new value if the effect succeeds, and returns the previous value.
  *
+ * **When to use**
+ *
+ * Use when an effectful state transition must return the previous stored value.
+ *
+ * @see {@link getAndUpdate} for pure updates that return the previous value
+ * @see {@link updateEffect} for effectful updates without returning a value
+ * @see {@link updateAndGetEffect} for effectful updates that return the new value
+ * @see {@link modifyEffect} for effectful updates with a custom return value
+ * @see {@link getAndUpdateSomeEffect} for conditional effectful updates that return the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -170,6 +266,16 @@ export const getAndUpdateEffect: {
    * Atomically runs an effectful update while holding the ref's semaphore, sets
    * the new value if the effect succeeds, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use when an effectful state transition must return the previous stored value.
+   *
+   * @see {@link getAndUpdate} for pure updates that return the previous value
+   * @see {@link updateEffect} for effectful updates without returning a value
+   * @see {@link updateAndGetEffect} for effectful updates that return the new value
+   * @see {@link modifyEffect} for effectful updates with a custom return value
+   * @see {@link getAndUpdateSomeEffect} for conditional effectful updates that return the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -178,6 +284,16 @@ export const getAndUpdateEffect: {
    * Atomically runs an effectful update while holding the ref's semaphore, sets
    * the new value if the effect succeeds, and returns the previous value.
    *
+   * **When to use**
+   *
+   * Use when an effectful state transition must return the previous stored value.
+   *
+   * @see {@link getAndUpdate} for pure updates that return the previous value
+   * @see {@link updateEffect} for effectful updates without returning a value
+   * @see {@link updateAndGetEffect} for effectful updates that return the new value
+   * @see {@link modifyEffect} for effectful updates with a custom return value
+   * @see {@link getAndUpdateSomeEffect} for conditional effectful updates that return the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -199,6 +315,13 @@ export const getAndUpdateEffect: {
  * function returns `Option.some`, the ref is updated; if it returns
  * `Option.none`, the ref is left unchanged.
  *
+ * **When to use**
+ *
+ * Use to return the previous value while applying a pure conditional update.
+ *
+ * @see {@link getAndUpdate} for always applying a pure update
+ * @see {@link updateSome} for applying a pure conditional update without returning the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -208,6 +331,13 @@ export const getAndUpdateSome: {
    * function returns `Option.some`, the ref is updated; if it returns
    * `Option.none`, the ref is left unchanged.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a pure conditional update.
+   *
+   * @see {@link getAndUpdate} for always applying a pure update
+   * @see {@link updateSome} for applying a pure conditional update without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -217,6 +347,13 @@ export const getAndUpdateSome: {
    * function returns `Option.some`, the ref is updated; if it returns
    * `Option.none`, the ref is left unchanged.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while applying a pure conditional update.
+   *
+   * @see {@link getAndUpdate} for always applying a pure update
+   * @see {@link updateSome} for applying a pure conditional update without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -232,6 +369,14 @@ export const getAndUpdateSome: {
  * and returns the previous value. `Option.some` updates the ref; `Option.none`
  * leaves it unchanged.
  *
+ * **When to use**
+ *
+ * Use to return the previous value while running an effectful conditional
+ * update.
+ *
+ * @see {@link getAndUpdateSome} for the pure conditional variant
+ * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -241,6 +386,14 @@ export const getAndUpdateSomeEffect: {
    * and returns the previous value. `Option.some` updates the ref; `Option.none`
    * leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while running an effectful conditional
+   * update.
+   *
+   * @see {@link getAndUpdateSome} for the pure conditional variant
+   * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -250,6 +403,14 @@ export const getAndUpdateSomeEffect: {
    * and returns the previous value. `Option.some` updates the ref; `Option.none`
    * leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to return the previous value while running an effectful conditional
+   * update.
+   *
+   * @see {@link getAndUpdateSome} for the pure conditional variant
+   * @see {@link updateSomeEffect} for effectful conditional updates without returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -276,6 +437,15 @@ export const getAndUpdateSomeEffect: {
  * Atomically computes a return value and a new ref value, stores the new value,
  * and returns the computed result.
  *
+ * **When to use**
+ *
+ * Use to derive a separate result and the next stored value from the same
+ * current value in one serialized pure update.
+ *
+ * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
+ * @see {@link modifySome} for deriving a result and optionally updating the stored value
+ * @see {@link updateAndGet} for returning the new stored value instead of a separate result
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -284,6 +454,15 @@ export const modify: {
    * Atomically computes a return value and a new ref value, stores the new value,
    * and returns the computed result.
    *
+   * **When to use**
+   *
+   * Use to derive a separate result and the next stored value from the same
+   * current value in one serialized pure update.
+   *
+   * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
+   * @see {@link modifySome} for deriving a result and optionally updating the stored value
+   * @see {@link updateAndGet} for returning the new stored value instead of a separate result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -292,6 +471,15 @@ export const modify: {
    * Atomically computes a return value and a new ref value, stores the new value,
    * and returns the computed result.
    *
+   * **When to use**
+   *
+   * Use to derive a separate result and the next stored value from the same
+   * current value in one serialized pure update.
+   *
+   * @see {@link modifyEffect} for effectfully deriving both the result and next stored value
+   * @see {@link modifySome} for deriving a result and optionally updating the stored value
+   * @see {@link updateAndGet} for returning the new stored value instead of a separate result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -306,6 +494,14 @@ export const modify: {
  * Atomically runs an effectful modification while holding the ref's semaphore,
  * stores the new value if the effect succeeds, and returns the computed result.
  *
+ * **When to use**
+ *
+ * Use to effectfully compute both a separate return value and the next stored
+ * value in one serialized update.
+ *
+ * @see {@link modify} for the pure variant
+ * @see {@link updateEffect} for effectfully storing a new value without a separate result
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -314,6 +510,14 @@ export const modifyEffect: {
    * Atomically runs an effectful modification while holding the ref's semaphore,
    * stores the new value if the effect succeeds, and returns the computed result.
    *
+   * **When to use**
+   *
+   * Use to effectfully compute both a separate return value and the next stored
+   * value in one serialized update.
+   *
+   * @see {@link modify} for the pure variant
+   * @see {@link updateEffect} for effectfully storing a new value without a separate result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -322,6 +526,14 @@ export const modifyEffect: {
    * Atomically runs an effectful modification while holding the ref's semaphore,
    * stores the new value if the effect succeeds, and returns the computed result.
    *
+   * **When to use**
+   *
+   * Use to effectfully compute both a separate return value and the next stored
+   * value in one serialized update.
+   *
+   * @see {@link modify} for the pure variant
+   * @see {@link updateEffect} for effectfully storing a new value without a separate result
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -345,6 +557,13 @@ export const modifyEffect: {
  * Atomically computes a return value and an optional new ref value.
  * `Option.some` updates the ref; `Option.none` leaves it unchanged.
  *
+ * **When to use**
+ *
+ * Use to compute a return value while optionally updating the stored value.
+ *
+ * @see {@link modify} for always storing a new value
+ * @see {@link updateSome} for optional updates without a separate return value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -353,6 +572,13 @@ export const modifySome: {
    * Atomically computes a return value and an optional new ref value.
    * `Option.some` updates the ref; `Option.none` leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -361,6 +587,13 @@ export const modifySome: {
    * Atomically computes a return value and an optional new ref value.
    * `Option.some` updates the ref; `Option.none` leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to compute a return value while optionally updating the stored value.
+   *
+   * @see {@link modify} for always storing a new value
+   * @see {@link updateSome} for optional updates without a separate return value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -378,6 +611,14 @@ export const modifySome: {
  * The effect computes a return value and an optional new ref value;
  * `Option.some` updates the ref and `Option.none` leaves it unchanged.
  *
+ * **When to use**
+ *
+ * Use to effectfully compute a return value while optionally updating the
+ * stored value.
+ *
+ * @see {@link modifySome} for the pure variant
+ * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -387,6 +628,14 @@ export const modifySomeEffect: {
    * The effect computes a return value and an optional new ref value;
    * `Option.some` updates the ref and `Option.none` leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to effectfully compute a return value while optionally updating the
+   * stored value.
+   *
+   * @see {@link modifySome} for the pure variant
+   * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -399,6 +648,14 @@ export const modifySomeEffect: {
    * The effect computes a return value and an optional new ref value;
    * `Option.some` updates the ref and `Option.none` leaves it unchanged.
    *
+   * **When to use**
+   *
+   * Use to effectfully compute a return value while optionally updating the
+   * stored value.
+   *
+   * @see {@link modifySome} for the pure variant
+   * @see {@link updateSomeEffect} for effectful optional updates without a separate return value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -427,6 +684,15 @@ export const modifySomeEffect: {
 /**
  * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
  *
+ * **When to use**
+ *
+ * Use to replace the current value of a `SynchronizedRef` with a known value
+ * while keeping the write serialized with other synchronized updates.
+ *
+ * @see {@link getAndSet} for replacing the value when the previous value is needed
+ * @see {@link setAndGet} for replacing the value when the new value should be returned
+ * @see {@link update} for deriving the next value from the current value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -434,6 +700,15 @@ export const set: {
   /**
    * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to replace the current value of a `SynchronizedRef` with a known value
+   * while keeping the write serialized with other synchronized updates.
+   *
+   * @see {@link getAndSet} for replacing the value when the previous value is needed
+   * @see {@link setAndGet} for replacing the value when the new value should be returned
+   * @see {@link update} for deriving the next value from the current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -441,6 +716,15 @@ export const set: {
   /**
    * Sets the value of the `SynchronizedRef`, serialized by the ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to replace the current value of a `SynchronizedRef` with a known value
+   * while keeping the write serialized with other synchronized updates.
+   *
+   * @see {@link getAndSet} for replacing the value when the previous value is needed
+   * @see {@link setAndGet} for replacing the value when the new value should be returned
+   * @see {@link update} for deriving the next value from the current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -454,6 +738,14 @@ export const set: {
 /**
  * Sets the value of the `SynchronizedRef` and returns the new value.
  *
+ * **When to use**
+ *
+ * Use to replace the current value with a known value and return that new
+ * value.
+ *
+ * @see {@link set} for setting without returning a value
+ * @see {@link getAndSet} for setting while returning the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -461,6 +753,14 @@ export const setAndGet: {
   /**
    * Sets the value of the `SynchronizedRef` and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value and return that new
+   * value.
+   *
+   * @see {@link set} for setting without returning a value
+   * @see {@link getAndSet} for setting while returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -468,6 +768,14 @@ export const setAndGet: {
   /**
    * Sets the value of the `SynchronizedRef` and returns the new value.
    *
+   * **When to use**
+   *
+   * Use to replace the current value with a known value and return that new
+   * value.
+   *
+   * @see {@link set} for setting without returning a value
+   * @see {@link getAndSet} for setting while returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -482,6 +790,15 @@ export const setAndGet: {
  * Updates the value of the `SynchronizedRef` with a function, serialized by the
  * ref's semaphore.
  *
+ * **When to use**
+ *
+ * Use to apply a pure state transition to a `SynchronizedRef` as a serialized
+ * `Effect`.
+ *
+ * @see {@link updateEffect} for effectfully deriving the next value
+ * @see {@link updateAndGet} for returning the new stored value
+ * @see {@link getAndUpdate} for returning the previous stored value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -490,6 +807,15 @@ export const update: {
    * Updates the value of the `SynchronizedRef` with a function, serialized by the
    * ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to apply a pure state transition to a `SynchronizedRef` as a serialized
+   * `Effect`.
+   *
+   * @see {@link updateEffect} for effectfully deriving the next value
+   * @see {@link updateAndGet} for returning the new stored value
+   * @see {@link getAndUpdate} for returning the previous stored value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -498,6 +824,15 @@ export const update: {
    * Updates the value of the `SynchronizedRef` with a function, serialized by the
    * ref's semaphore.
    *
+   * **When to use**
+   *
+   * Use to apply a pure state transition to a `SynchronizedRef` as a serialized
+   * `Effect`.
+   *
+   * @see {@link updateEffect} for effectfully deriving the next value
+   * @see {@link updateAndGet} for returning the new stored value
+   * @see {@link getAndUpdate} for returning the previous stored value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -512,6 +847,17 @@ export const update: {
  * Runs an effectful update while holding the ref's semaphore and stores the new
  * value if the effect succeeds.
  *
+ * **When to use**
+ *
+ * Use to run an effectful state transition on a `SynchronizedRef` when storing
+ * the new value is the only result you need.
+ *
+ * @see {@link update} for a pure state transition
+ * @see {@link getAndUpdateEffect} for returning the previous stored value
+ * @see {@link updateAndGetEffect} for returning the new stored value
+ * @see {@link modifyEffect} for returning a separate result while storing a new value
+ * @see {@link updateSomeEffect} for effectfully applying only some state transitions
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -520,6 +866,17 @@ export const updateEffect: {
    * Runs an effectful update while holding the ref's semaphore and stores the new
    * value if the effect succeeds.
    *
+   * **When to use**
+   *
+   * Use to run an effectful state transition on a `SynchronizedRef` when storing
+   * the new value is the only result you need.
+   *
+   * @see {@link update} for a pure state transition
+   * @see {@link getAndUpdateEffect} for returning the previous stored value
+   * @see {@link updateAndGetEffect} for returning the new stored value
+   * @see {@link modifyEffect} for returning a separate result while storing a new value
+   * @see {@link updateSomeEffect} for effectfully applying only some state transitions
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -528,6 +885,17 @@ export const updateEffect: {
    * Runs an effectful update while holding the ref's semaphore and stores the new
    * value if the effect succeeds.
    *
+   * **When to use**
+   *
+   * Use to run an effectful state transition on a `SynchronizedRef` when storing
+   * the new value is the only result you need.
+   *
+   * @see {@link update} for a pure state transition
+   * @see {@link getAndUpdateEffect} for returning the previous stored value
+   * @see {@link updateAndGetEffect} for returning the new stored value
+   * @see {@link modifyEffect} for returning a separate result while storing a new value
+   * @see {@link updateSomeEffect} for effectfully applying only some state transitions
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -547,6 +915,13 @@ export const updateEffect: {
  * Updates the value of the `SynchronizedRef` with a function and returns the
  * new value.
  *
+ * **When to use**
+ *
+ * Use to apply a pure state transition and return the new stored value.
+ *
+ * @see {@link update} for updating without returning the new value
+ * @see {@link getAndUpdate} for updating while returning the previous value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -555,6 +930,13 @@ export const updateAndGet: {
    * Updates the value of the `SynchronizedRef` with a function and returns the
    * new value.
    *
+   * **When to use**
+   *
+   * Use to apply a pure state transition and return the new stored value.
+   *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for updating while returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -563,6 +945,13 @@ export const updateAndGet: {
    * Updates the value of the `SynchronizedRef` with a function and returns the
    * new value.
    *
+   * **When to use**
+   *
+   * Use to apply a pure state transition and return the new stored value.
+   *
+   * @see {@link update} for updating without returning the new value
+   * @see {@link getAndUpdate} for updating while returning the previous value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -577,6 +966,13 @@ export const updateAndGet: {
  * Runs an effectful update while holding the ref's semaphore, stores the new
  * value if the effect succeeds, and returns that new value.
  *
+ * **When to use**
+ *
+ * Use to run an effectful state transition and return the new stored value.
+ *
+ * @see {@link updateEffect} for effectful updates without returning the new value
+ * @see {@link updateAndGet} for the pure variant
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -585,6 +981,13 @@ export const updateAndGetEffect: {
    * Runs an effectful update while holding the ref's semaphore, stores the new
    * value if the effect succeeds, and returns that new value.
    *
+   * **When to use**
+   *
+   * Use to run an effectful state transition and return the new stored value.
+   *
+   * @see {@link updateEffect} for effectful updates without returning the new value
+   * @see {@link updateAndGet} for the pure variant
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -593,6 +996,13 @@ export const updateAndGetEffect: {
    * Runs an effectful update while holding the ref's semaphore, stores the new
    * value if the effect succeeds, and returns that new value.
    *
+   * **When to use**
+   *
+   * Use to run an effectful state transition and return the new stored value.
+   *
+   * @see {@link updateEffect} for effectful updates without returning the new value
+   * @see {@link updateAndGet} for the pure variant
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -613,6 +1023,13 @@ export const updateAndGetEffect: {
  * Applies a partial update to the current value. `Option.some` stores the new
  * value; `Option.none` leaves the ref unchanged.
  *
+ * **When to use**
+ *
+ * Use to apply a pure conditional update without returning a value.
+ *
+ * @see {@link update} for always applying a pure update
+ * @see {@link updateSomeAndGet} for returning the resulting current value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -621,6 +1038,13 @@ export const updateSome: {
    * Applies a partial update to the current value. `Option.some` stores the new
    * value; `Option.none` leaves the ref unchanged.
    *
+   * **When to use**
+   *
+   * Use to apply a pure conditional update without returning a value.
+   *
+   * @see {@link update} for always applying a pure update
+   * @see {@link updateSomeAndGet} for returning the resulting current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -629,6 +1053,13 @@ export const updateSome: {
    * Applies a partial update to the current value. `Option.some` stores the new
    * value; `Option.none` leaves the ref unchanged.
    *
+   * **When to use**
+   *
+   * Use to apply a pure conditional update without returning a value.
+   *
+   * @see {@link update} for always applying a pure update
+   * @see {@link updateSomeAndGet} for returning the resulting current value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -643,6 +1074,13 @@ export const updateSome: {
  * Runs an effectful partial update while holding the ref's semaphore.
  * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
  *
+ * **When to use**
+ *
+ * Use to run an effectful conditional update without returning a value.
+ *
+ * @see {@link updateSome} for the pure conditional variant
+ * @see {@link updateEffect} for effectful updates that always store a new value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -651,6 +1089,13 @@ export const updateSomeEffect: {
    * Runs an effectful partial update while holding the ref's semaphore.
    * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
    *
+   * **When to use**
+   *
+   * Use to run an effectful conditional update without returning a value.
+   *
+   * @see {@link updateSome} for the pure conditional variant
+   * @see {@link updateEffect} for effectful updates that always store a new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -659,6 +1104,13 @@ export const updateSomeEffect: {
    * Runs an effectful partial update while holding the ref's semaphore.
    * `Option.some` stores the new value; `Option.none` leaves the ref unchanged.
    *
+   * **When to use**
+   *
+   * Use to run an effectful conditional update without returning a value.
+   *
+   * @see {@link updateSome} for the pure conditional variant
+   * @see {@link updateEffect} for effectful updates that always store a new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -685,6 +1137,14 @@ export const updateSomeEffect: {
  * `Option.some` stores and returns the new value; `Option.none` returns the
  * unchanged value.
  *
+ * **When to use**
+ *
+ * Use to apply a pure conditional update and return the resulting current
+ * value.
+ *
+ * @see {@link updateSome} for conditional updates without returning a value
+ * @see {@link updateAndGet} for always applying a pure update and returning the new value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -694,6 +1154,14 @@ export const updateSomeAndGet: {
    * `Option.some` stores and returns the new value; `Option.none` returns the
    * unchanged value.
    *
+   * **When to use**
+   *
+   * Use to apply a pure conditional update and return the resulting current
+   * value.
+   *
+   * @see {@link updateSome} for conditional updates without returning a value
+   * @see {@link updateAndGet} for always applying a pure update and returning the new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -703,6 +1171,14 @@ export const updateSomeAndGet: {
    * `Option.some` stores and returns the new value; `Option.none` returns the
    * unchanged value.
    *
+   * **When to use**
+   *
+   * Use to apply a pure conditional update and return the resulting current
+   * value.
+   *
+   * @see {@link updateSome} for conditional updates without returning a value
+   * @see {@link updateAndGet} for always applying a pure update and returning the new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -718,6 +1194,14 @@ export const updateSomeAndGet: {
  * returns the resulting current value. `Option.some` stores and returns the new
  * value; `Option.none` returns the unchanged value.
  *
+ * **When to use**
+ *
+ * Use to run an effectful conditional update and return the resulting current
+ * value.
+ *
+ * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
+ * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -727,6 +1211,14 @@ export const updateSomeAndGetEffect: {
    * returns the resulting current value. `Option.some` stores and returns the new
    * value; `Option.none` returns the unchanged value.
    *
+   * **When to use**
+   *
+   * Use to run an effectful conditional update and return the resulting current
+   * value.
+   *
+   * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
+   * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value
+   *
    * @category utils
    * @since 2.0.0
    */
@@ -736,6 +1228,14 @@ export const updateSomeAndGetEffect: {
    * returns the resulting current value. `Option.some` stores and returns the new
    * value; `Option.none` returns the unchanged value.
    *
+   * **When to use**
+   *
+   * Use to run an effectful conditional update and return the resulting current
+   * value.
+   *
+   * @see {@link updateSomeEffect} for effectful conditional updates without returning a value
+   * @see {@link updateAndGetEffect} for effectful updates that always store and return a new value
+   *
    * @category utils
    * @since 2.0.0
    */