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

package/dist/SynchronizedRef.d.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
@@ -32,6 +32,14 @@ declare 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
  */
@@ -45,7 +53,7 @@ export interface SynchronizedRef<in out A> extends Ref.Ref<A> {
  *
  * **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
@@ -54,6 +62,19 @@ export declare 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
  */
@@ -62,6 +83,13 @@ export declare const make: <A>(value: A) => Effect.Effect<SynchronizedRef<A>>;
  * 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
  */
@@ -69,6 +97,13 @@ export declare const getUnsafe: <A>(self: SynchronizedRef<A>) => A;
 /**
  * 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
  */
@@ -77,6 +112,15 @@ export declare const get: <A>(self: SynchronizedRef<A>) => Effect.Effect<A>;
  * 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
  */
@@ -85,6 +129,15 @@ export declare 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
      */
@@ -93,6 +146,15 @@ export declare 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
      */
@@ -102,6 +164,14 @@ export declare 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
  */
@@ -110,6 +180,14 @@ export declare 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
      */
@@ -118,6 +196,14 @@ export declare 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
      */
@@ -127,6 +213,16 @@ export declare 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
  */
@@ -135,6 +231,16 @@ export declare 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
      */
@@ -143,6 +249,16 @@ export declare 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
      */
@@ -153,6 +269,13 @@ export declare 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
  */
@@ -162,6 +285,13 @@ export declare 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
      */
@@ -171,6 +301,13 @@ export declare 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
      */
@@ -181,6 +318,14 @@ export declare 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
  */
@@ -190,6 +335,14 @@ export declare 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
      */
@@ -199,6 +352,14 @@ export declare 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
      */
@@ -208,6 +369,15 @@ export declare 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
  */
@@ -216,6 +386,15 @@ export declare 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
      */
@@ -224,6 +403,15 @@ export declare 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
      */
@@ -233,6 +421,14 @@ export declare 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
  */
@@ -241,6 +437,14 @@ export declare 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
      */
@@ -249,6 +453,14 @@ export declare 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
      */
@@ -258,6 +470,13 @@ export declare 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
  */
@@ -266,6 +485,13 @@ export declare 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
      */
@@ -274,6 +500,13 @@ export declare 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
      */
@@ -284,6 +517,14 @@ export declare 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
  */
@@ -293,6 +534,14 @@ export declare 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
      */
@@ -302,6 +551,14 @@ export declare 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
      */
@@ -310,6 +567,15 @@ export declare 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
  */
@@ -317,6 +583,15 @@ export declare 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
      */
@@ -324,6 +599,15 @@ export declare 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
      */
@@ -332,6 +616,14 @@ export declare 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
  */
@@ -339,6 +631,14 @@ export declare 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
      */
@@ -346,6 +646,14 @@ export declare 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
      */
@@ -355,6 +663,15 @@ export declare 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
  */
@@ -363,6 +680,15 @@ export declare 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
      */
@@ -371,6 +697,15 @@ export declare 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
      */
@@ -380,6 +715,17 @@ export declare 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
  */
@@ -388,6 +734,17 @@ export declare 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
      */
@@ -396,6 +753,17 @@ export declare 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
      */
@@ -405,6 +773,13 @@ export declare 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
  */
@@ -413,6 +788,13 @@ export declare 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
      */
@@ -421,6 +803,13 @@ export declare 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
      */
@@ -430,6 +819,13 @@ export declare 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
  */
@@ -438,6 +834,13 @@ export declare 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
      */
@@ -446,6 +849,13 @@ export declare 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
      */
@@ -455,6 +865,13 @@ export declare 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
  */
@@ -463,6 +880,13 @@ export declare 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
      */
@@ -471,6 +895,13 @@ export declare 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
      */
@@ -480,6 +911,13 @@ export declare 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
  */
@@ -488,6 +926,13 @@ export declare 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
      */
@@ -496,6 +941,13 @@ export declare 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
      */
@@ -506,6 +958,14 @@ export declare 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
  */
@@ -515,6 +975,14 @@ export declare 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
      */
@@ -524,6 +992,14 @@ export declare 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
      */
@@ -534,6 +1010,14 @@ export declare 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
  */
@@ -543,6 +1027,14 @@ export declare 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
      */
@@ -552,6 +1044,14 @@ export declare 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
      */