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

package/src/SubscriptionRef.ts

@@ -1,17 +1,58 @@
 /**
- * The `SubscriptionRef` module provides a mutable reference that can be read
- * and updated like a `Ref`, while also exposing a stream of its current value
- * and every subsequent change. It is useful when one part of an application
- * owns evolving state and many fibers need to subscribe to consistent updates,
- * such as configuration, coordination state, cached snapshots, or UI models.
- *
- * Updates are serialized with an internal semaphore and each update is
- * published to subscribers. The {@link changes} stream replays the latest value
- * first, then emits future updates, so new subscribers can start from the
- * current state without performing a separate read. Prefer the effectful
- * getters and update operations for concurrent code; the unsafe helpers bypass
- * synchronization and should only be used when the caller already controls
- * access.
+ * The `SubscriptionRef` module combines a fiber-safe mutable reference with a
+ * replaying stream of state changes. A `SubscriptionRef<A>` stores the latest
+ * value, serializes updates, and publishes each committed value so subscribers
+ * can observe state as it evolves.
+ *
+ * **Mental model**
+ *
+ * - {@link make} creates the reference and immediately publishes the initial
+ *   value.
+ * - {@link get} reads the latest value without subscribing.
+ * - {@link set}, {@link update}, and {@link modify} change the value under the
+ *   reference semaphore and publish the new value.
+ * - {@link changes} returns a stream that first emits the current value and
+ *   then emits future published values.
+ * - The `Some` variants leave the value unchanged and publish nothing when
+ *   their `Option` result is empty.
+ *
+ * **Common tasks**
+ *
+ * - Create shared state with {@link make}.
+ * - Read once with {@link get} or observe over time with {@link changes}.
+ * - Replace state with {@link set}, {@link setAndGet}, or {@link getAndSet}.
+ * - Transform state with {@link update}, {@link updateAndGet},
+ *   {@link getAndUpdate}, or their effectful variants.
+ * - Compute a separate result while updating with {@link modify} or
+ *   {@link modifyEffect}.
+ *
+ * **Example** (Reading the current value through changes)
+ *
+ * ```ts
+ * import { Effect, Stream, SubscriptionRef } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const ref = yield* SubscriptionRef.make(0)
+ *
+ *   yield* SubscriptionRef.update(ref, (n) => n + 1)
+ *
+ *   const latest = yield* SubscriptionRef.changes(ref).pipe(
+ *     Stream.take(1),
+ *     Stream.runCollect
+ *   )
+ *
+ *   return latest
+ * })
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Every successful set or non-empty update is published, even when the new
+ *   value is equal to the old one.
+ * - New subscribers receive the current value from the replay buffer before
+ *   future updates.
+ * - Unsafe helpers bypass the semaphore and should only be used when the caller
+ *   already controls access.
  *
  * @since 2.0.0
  */
@@ -34,7 +75,7 @@ const TypeId = "~effect/SubscriptionRef"
  *
  * **When to use**
  *
- * Use `changes` to observe the current value and subsequent updates as a
+ * Use to observe the current value and subsequent updates as a
  * stream.
  *
  * @category models
@@ -49,6 +90,11 @@ export interface SubscriptionRef<in out A> extends SubscriptionRef.Variance<A>,
 /**
  * Returns `true` if the provided value is a `SubscriptionRef`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before calling `SubscriptionRef` operations
+ * that require a subscription reference.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -93,6 +139,19 @@ const Proto = {
 /**
  * Constructs a new `SubscriptionRef` from an initial value.
  *
+ * **When to use**
+ *
+ * Use to create shared mutable state when consumers need to read the latest
+ * value and subscribe to every update.
+ *
+ * **Details**
+ *
+ * The initial value is published during construction, so `changes` starts new
+ * subscribers with that value before future updates.
+ *
+ * @see {@link changes} for streaming the current value and subsequent updates
+ * @see {@link set} for replacing the value and notifying subscribers
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -148,7 +207,7 @@ export const make = <A>(value: A): Effect.Effect<SubscriptionRef<A>> =>
 export const changes = <A>(self: SubscriptionRef<A>): Stream.Stream<A> => Stream.fromPubSub(self.pubsub)
 
 /**
- * Unsafely retrieves the current value of the `SubscriptionRef`.
+ * Retrieves the current value of the `SubscriptionRef` unsafely.
  *
  * **Gotchas**
  *
@@ -196,7 +255,7 @@ export const getUnsafe = <A>(self: SubscriptionRef<A>): A => self.value
 export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.sync(() => self.value)
 
 /**
- * Atomically retrieves the current value and sets a new value, notifying
+ * Retrieves the current value and sets a new value atomically, notifying
  * subscribers of the change.
  *
  * **Example** (Getting and setting a value)
@@ -220,7 +279,7 @@ export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.syn
  */
 export const getAndSet: {
   /**
-   * Atomically retrieves the current value and sets a new value, notifying
+   * Retrieves the current value and sets a new value atomically, notifying
    * subscribers of the change.
    *
    * **Example** (Getting and setting a value)
@@ -244,7 +303,7 @@ export const getAndSet: {
    */
   <A>(value: A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and sets a new value, notifying
+   * Retrieves the current value and sets a new value atomically, notifying
    * subscribers of the change.
    *
    * **Example** (Getting and setting a value)
@@ -280,7 +339,7 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
 }
 
 /**
- * Atomically retrieves the current value and updates it with the result of
+ * Retrieves the current value and updates it atomically with the result of
  * applying a function, notifying subscribers of the change.
  *
  * **Example** (Getting and updating a value)
@@ -304,7 +363,7 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
  */
 export const getAndUpdate: {
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying a function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating a value)
@@ -328,7 +387,7 @@ export const getAndUpdate: {
    */
   <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying a function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating a value)
@@ -360,7 +419,7 @@ export const getAndUpdate: {
   })))
 
 /**
- * Atomically retrieves the current value and updates it with the result of
+ * Retrieves the current value and updates it atomically with the result of
  * applying an effectful function, notifying subscribers of the change.
  *
  * **Example** (Getting and updating with an effect)
@@ -387,7 +446,7 @@ export const getAndUpdate: {
  */
 export const getAndUpdateEffect: {
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying an effectful function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating with an effect)
@@ -414,7 +473,7 @@ export const getAndUpdateEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically retrieves the current value and updates it with the result of
+   * Retrieves the current value and updates it atomically with the result of
    * applying an effectful function, notifying subscribers of the change.
    *
    * **Example** (Getting and updating with an effect)
@@ -453,9 +512,18 @@ export const getAndUpdateEffect: {
   })))
 
 /**
- * Atomically retrieves the current value and applies an update function. If
- * the function returns `Option.some`, sets and publishes that value; if it
- * returns `Option.none`, leaves the reference unchanged and does not publish.
+ * Retrieves the current value and optionally updates the reference.
+ *
+ * **When to use**
+ *
+ * Use to read the old value while applying a synchronous update only when a
+ * new value is available.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some`, the new value is set and published. If
+ * it returns `Option.none`, the reference is left unchanged and no update is
+ * published.
  *
  * **Example** (Getting and conditionally updating a value)
  *
@@ -481,9 +549,18 @@ export const getAndUpdateEffect: {
  */
 export const getAndUpdateSome: {
   /**
-   * Atomically retrieves the current value and applies an update function. If
-   * the function returns `Option.some`, sets and publishes that value; if it
-   * returns `Option.none`, leaves the reference unchanged and does not publish.
+   * Retrieves the current value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying a synchronous update only when a
+   * new value is available.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set and published. If
+   * it returns `Option.none`, the reference is left unchanged and no update is
+   * published.
    *
    * **Example** (Getting and conditionally updating a value)
    *
@@ -509,9 +586,18 @@ export const getAndUpdateSome: {
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and applies an update function. If
-   * the function returns `Option.some`, sets and publishes that value; if it
-   * returns `Option.none`, leaves the reference unchanged and does not publish.
+   * Retrieves the current value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying a synchronous update only when a
+   * new value is available.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set and published. If
+   * it returns `Option.none`, the reference is left unchanged and no update is
+   * published.
    *
    * **Example** (Getting and conditionally updating a value)
    *
@@ -551,10 +637,18 @@ export const getAndUpdateSome: {
   })))
 
 /**
- * Atomically retrieves the current value and applies an effectful update
- * function. If it succeeds with `Option.some`, sets and publishes that value;
- * if it succeeds with `Option.none`, leaves the reference unchanged and does
- * not publish.
+ * Retrieves the current value and optionally updates the reference effectfully.
+ *
+ * **When to use**
+ *
+ * Use to read the old value while applying an effectful update only when a new
+ * value is available.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Getting and conditionally updating with an effect)
  *
@@ -580,10 +674,18 @@ export const getAndUpdateSome: {
  */
 export const getAndUpdateSomeEffect: {
   /**
-   * Atomically retrieves the current value and applies an effectful update
-   * function. If it succeeds with `Option.some`, sets and publishes that value;
-   * if it succeeds with `Option.none`, leaves the reference unchanged and does
-   * not publish.
+   * Retrieves the current value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying an effectful update only when a new
+   * value is available.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Getting and conditionally updating with an effect)
    *
@@ -609,10 +711,18 @@ export const getAndUpdateSomeEffect: {
    */
   <A, R, E>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Atomically retrieves the current value and applies an effectful update
-   * function. If it succeeds with `Option.some`, sets and publishes that value;
-   * if it succeeds with `Option.none`, leaves the reference unchanged and does
-   * not publish.
+   * Retrieves the current value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to read the old value while applying an effectful update only when a new
+   * value is available.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Getting and conditionally updating with an effect)
    *
@@ -654,7 +764,7 @@ export const getAndUpdateSomeEffect: {
   })))
 
 /**
- * Atomically modifies the `SubscriptionRef` with a function that computes a
+ * Modifies the `SubscriptionRef` atomically with a function that computes a
  * return value and a new value, notifying subscribers of the change.
  *
  * **Example** (Modifying a value)
@@ -681,7 +791,7 @@ export const getAndUpdateSomeEffect: {
  */
 export const modify: {
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
+   * Modifies the `SubscriptionRef` atomically with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
    * **Example** (Modifying a value)
@@ -708,7 +818,7 @@ export const modify: {
    */
   <A, B>(modify: (a: A) => readonly [B, A]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
+   * Modifies the `SubscriptionRef` atomically with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
    * **Example** (Modifying a value)
@@ -745,7 +855,7 @@ export const modify: {
   })))
 
 /**
- * Atomically modifies the `SubscriptionRef` with an effectful function that
+ * Modifies the `SubscriptionRef` atomically with an effectful function that
  * computes a return value and a new value, notifying subscribers of the
  * change.
  *
@@ -773,7 +883,7 @@ export const modify: {
  */
 export const modifyEffect: {
   /**
-   * Atomically modifies the `SubscriptionRef` with an effectful function that
+   * Modifies the `SubscriptionRef` atomically with an effectful function that
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
@@ -801,7 +911,7 @@ export const modifyEffect: {
    */
   <B, A, E, R>(modify: (a: A) => Effect.Effect<readonly [B, A], E, R>): (self: SubscriptionRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically modifies the `SubscriptionRef` with an effectful function that
+   * Modifies the `SubscriptionRef` atomically with an effectful function that
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
@@ -843,9 +953,18 @@ export const modifyEffect: {
   )))
 
 /**
- * Atomically computes a return value and an optional new value. If the function
- * returns `Option.some` for the new value, sets and publishes it; if it returns
- * `Option.none`, leaves the reference unchanged and does not publish.
+ * Computes a return value and optionally updates the reference.
+ *
+ * **When to use**
+ *
+ * Use to return a separate result while synchronously deciding whether to
+ * publish a new value.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some` for the new value, the value is set and
+ * published. If it returns `Option.none`, the reference is left unchanged and
+ * no update is published.
  *
  * **Example** (Conditionally modifying a value)
  *
@@ -872,9 +991,18 @@ export const modifyEffect: {
  */
 export const modifySome: {
   /**
-   * Atomically computes a return value and an optional new value. If the function
-   * returns `Option.some` for the new value, sets and publishes it; if it returns
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while synchronously deciding whether to
+   * publish a new value.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some` for the new value, the value is set and
+   * published. If it returns `Option.none`, the reference is left unchanged and
+   * no update is published.
    *
    * **Example** (Conditionally modifying a value)
    *
@@ -901,9 +1029,18 @@ export const modifySome: {
    */
   <B, A>(modify: (a: A) => readonly [B, Option.Option<A>]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
-   * Atomically computes a return value and an optional new value. If the function
-   * returns `Option.some` for the new value, sets and publishes it; if it returns
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while synchronously deciding whether to
+   * publish a new value.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some` for the new value, the value is set and
+   * published. If it returns `Option.none`, the reference is left unchanged and
+   * no update is published.
    *
    * **Example** (Conditionally modifying a value)
    *
@@ -941,10 +1078,18 @@ export const modifySome: {
   })))
 
 /**
- * Atomically computes a return value and an optional new value with an
- * effectful function. If the effect succeeds with `Option.some`, sets and
- * publishes the new value; if it succeeds with `Option.none`, leaves the
- * reference unchanged and does not publish.
+ * Computes a return value and optionally updates the reference effectfully.
+ *
+ * **When to use**
+ *
+ * Use to return a separate result while effectfully deciding whether to publish
+ * a new value.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Conditionally modifying with an effect)
  *
@@ -975,10 +1120,18 @@ export const modifySome: {
  */
 export const modifySomeEffect: {
   /**
-   * Atomically computes a return value and an optional new value with an
-   * effectful function. If the effect succeeds with `Option.some`, sets and
-   * publishes the new value; if it succeeds with `Option.none`, leaves the
-   * reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while effectfully deciding whether to publish
+   * a new value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally modifying with an effect)
    *
@@ -1009,10 +1162,18 @@ export const modifySomeEffect: {
    */
   <A, B, R, E>(modify: (a: A) => Effect.Effect<readonly [B, Option.Option<A>], E, R>): (self: SubscriptionRef<A>) => Effect.Effect<B, E, R>
   /**
-   * Atomically computes a return value and an optional new value with an
-   * effectful function. If the effect succeeds with `Option.some`, sets and
-   * publishes the new value; if it succeeds with `Option.none`, leaves the
-   * reference unchanged and does not publish.
+   * Computes a return value and optionally updates the reference effectfully.
+   *
+   * **When to use**
+   *
+   * Use to return a separate result while effectfully deciding whether to publish
+   * a new value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally modifying with an effect)
    *
@@ -1600,9 +1761,18 @@ export const updateSome: {
   })))
 
 /**
- * Applies an effectful update function to the current value. If it succeeds
- * with `Option.some`, sets and publishes that value; if it succeeds with
- * `Option.none`, leaves the reference unchanged and does not publish.
+ * Applies an effectful update only when it produces a new value.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` with an effectful function
+ * while discarding the resulting value.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set and
+ * published. If it succeeds with `Option.none`, the reference is left unchanged
+ * and no update is published.
  *
  * **Example** (Conditionally updating with an effect)
  *
@@ -1627,9 +1797,18 @@ export const updateSome: {
  */
 export const updateSomeEffect: {
   /**
-   * Applies an effectful update function to the current value. If it succeeds
-   * with `Option.some`, sets and publishes that value; if it succeeds with
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Applies an effectful update only when it produces a new value.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` with an effectful function
+   * while discarding the resulting value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally updating with an effect)
    *
@@ -1654,9 +1833,18 @@ export const updateSomeEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<void, E, R>
   /**
-   * Applies an effectful update function to the current value. If it succeeds
-   * with `Option.some`, sets and publishes that value; if it succeeds with
-   * `Option.none`, leaves the reference unchanged and does not publish.
+   * Applies an effectful update only when it produces a new value.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` with an effectful function
+   * while discarding the resulting value.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set and
+   * published. If it succeeds with `Option.none`, the reference is left unchanged
+   * and no update is published.
    *
    * **Example** (Conditionally updating with an effect)
    *
@@ -1695,10 +1883,18 @@ export const updateSomeEffect: {
   )))
 
 /**
- * Applies an update function and returns the resulting current value. If the
- * function returns `Option.some`, sets, publishes, and returns that value; if
- * it returns `Option.none`, returns the unchanged current value without
- * publishing.
+ * Applies an optional update and returns the current value afterward.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` and read the value that is
+ * current after the update decision.
+ *
+ * **Details**
+ *
+ * If the function returns `Option.some`, the new value is set, published, and
+ * returned. If it returns `Option.none`, the unchanged current value is
+ * returned without publishing.
  *
  * **Example** (Conditionally updating and reading the new value)
  *
@@ -1721,10 +1917,18 @@ export const updateSomeEffect: {
  */
 export const updateSomeAndGet: {
   /**
-   * Applies an update function and returns the resulting current value. If the
-   * function returns `Option.some`, sets, publishes, and returns that value; if
-   * it returns `Option.none`, returns the unchanged current value without
-   * publishing.
+   * Applies an optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` and read the value that is
+   * current after the update decision.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set, published, and
+   * returned. If it returns `Option.none`, the unchanged current value is
+   * returned without publishing.
    *
    * **Example** (Conditionally updating and reading the new value)
    *
@@ -1747,10 +1951,18 @@ export const updateSomeAndGet: {
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Applies an update function and returns the resulting current value. If the
-   * function returns `Option.some`, sets, publishes, and returns that value; if
-   * it returns `Option.none`, returns the unchanged current value without
-   * publishing.
+   * Applies an optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` and read the value that is
+   * current after the update decision.
+   *
+   * **Details**
+   *
+   * If the function returns `Option.some`, the new value is set, published, and
+   * returned. If it returns `Option.none`, the unchanged current value is
+   * returned without publishing.
    *
    * **Example** (Conditionally updating and reading the new value)
    *
@@ -1785,10 +1997,18 @@ export const updateSomeAndGet: {
   })))
 
 /**
- * Applies an effectful update function and returns the resulting current
- * value. If the effect succeeds with `Option.some`, sets, publishes, and
- * returns that value; if it succeeds with `Option.none`, returns the unchanged
- * current value without publishing.
+ * Applies an effectful optional update and returns the current value afterward.
+ *
+ * **When to use**
+ *
+ * Use to conditionally update a `SubscriptionRef` effectfully and read the
+ * value that is current after the update decision.
+ *
+ * **Details**
+ *
+ * If the effect succeeds with `Option.some`, the new value is set, published,
+ * and returned. If it succeeds with `Option.none`, the unchanged current value
+ * is returned without publishing.
  *
  * **Example** (Conditionally updating with an effect and reading the new value)
  *
@@ -1811,10 +2031,18 @@ export const updateSomeAndGet: {
  */
 export const updateSomeAndGetEffect: {
   /**
-   * Applies an effectful update function and returns the resulting current
-   * value. If the effect succeeds with `Option.some`, sets, publishes, and
-   * returns that value; if it succeeds with `Option.none`, returns the unchanged
-   * current value without publishing.
+   * Applies an effectful optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` effectfully and read the
+   * value that is current after the update decision.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set, published,
+   * and returned. If it succeeds with `Option.none`, the unchanged current value
+   * is returned without publishing.
    *
    * **Example** (Conditionally updating with an effect and reading the new value)
    *
@@ -1837,10 +2065,18 @@ export const updateSomeAndGetEffect: {
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Applies an effectful update function and returns the resulting current
-   * value. If the effect succeeds with `Option.some`, sets, publishes, and
-   * returns that value; if it succeeds with `Option.none`, returns the unchanged
-   * current value without publishing.
+   * Applies an effectful optional update and returns the current value afterward.
+   *
+   * **When to use**
+   *
+   * Use to conditionally update a `SubscriptionRef` effectfully and read the
+   * value that is current after the update decision.
+   *
+   * **Details**
+   *
+   * If the effect succeeds with `Option.some`, the new value is set, published,
+   * and returned. If it succeeds with `Option.none`, the unchanged current value
+   * is returned without publishing.
    *
    * **Example** (Conditionally updating with an effect and reading the new value)
    *