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

package/dist/SubscriptionRef.d.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
  */
@@ -29,7 +70,7 @@ declare 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
@@ -43,6 +84,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
  */
@@ -70,6 +116,19 @@ export declare namespace SubscriptionRef {
 /**
  * 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
  */
@@ -115,7 +174,7 @@ export declare const make: <A>(value: A) => Effect.Effect<SubscriptionRef<A>>;
  */
 export declare const changes: <A>(self: SubscriptionRef<A>) => Stream.Stream<A>;
 /**
- * Unsafely retrieves the current value of the `SubscriptionRef`.
+ * Retrieves the current value of the `SubscriptionRef` unsafely.
  *
  * **Gotchas**
  *
@@ -161,7 +220,7 @@ export declare const getUnsafe: <A>(self: SubscriptionRef<A>) => A;
  */
 export declare const get: <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)
@@ -185,7 +244,7 @@ export declare const get: <A>(self: SubscriptionRef<A>) => Effect.Effect<A>;
  */
 export declare 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)
@@ -209,7 +268,7 @@ export declare 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)
@@ -234,7 +293,7 @@ export declare const getAndSet: {
     <A>(self: SubscriptionRef<A>, value: 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)
@@ -258,7 +317,7 @@ export declare const getAndSet: {
  */
 export declare 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)
@@ -282,7 +341,7 @@ export declare 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)
@@ -307,7 +366,7 @@ export declare const getAndUpdate: {
     <A>(self: SubscriptionRef<A>, update: (a: A) => 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 an effectful function, notifying subscribers of the change.
  *
  * **Example** (Getting and updating with an effect)
@@ -334,7 +393,7 @@ export declare const getAndUpdate: {
  */
 export declare 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)
@@ -361,7 +420,7 @@ export declare 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)
@@ -389,9 +448,18 @@ export declare const getAndUpdateEffect: {
     <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R>;
 };
 /**
- * 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)
  *
@@ -417,9 +485,18 @@ export declare const getAndUpdateEffect: {
  */
 export declare 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)
      *
@@ -445,9 +522,18 @@ export declare 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)
      *
@@ -474,10 +560,18 @@ export declare const getAndUpdateSome: {
     <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<A>;
 };
 /**
- * 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)
  *
@@ -503,10 +597,18 @@ export declare const getAndUpdateSome: {
  */
 export declare 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)
      *
@@ -532,10 +634,18 @@ export declare 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)
      *
@@ -562,7 +672,7 @@ export declare const getAndUpdateSomeEffect: {
     <A, R, E>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): Effect.Effect<A, E, R>;
 };
 /**
- * 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)
@@ -589,7 +699,7 @@ export declare const getAndUpdateSomeEffect: {
  */
 export declare 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)
@@ -616,7 +726,7 @@ export declare 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)
@@ -644,7 +754,7 @@ export declare const modify: {
     <A, B>(self: SubscriptionRef<A>, f: (a: A) => readonly [B, A]): Effect.Effect<B>;
 };
 /**
- * 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.
  *
@@ -672,7 +782,7 @@ export declare const modify: {
  */
 export declare 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.
      *
@@ -700,7 +810,7 @@ export declare 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.
      *
@@ -729,9 +839,18 @@ export declare const modifyEffect: {
     <A, B, E, R>(self: SubscriptionRef<A>, modify: (a: A) => Effect.Effect<readonly [B, A], E, R>): Effect.Effect<B, E, R>;
 };
 /**
- * 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)
  *
@@ -758,9 +877,18 @@ export declare const modifyEffect: {
  */
 export declare 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)
      *
@@ -787,9 +915,18 @@ export declare 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)
      *
@@ -817,10 +954,18 @@ export declare const modifySome: {
     <A, B>(self: SubscriptionRef<A>, modify: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>;
 };
 /**
- * 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)
  *
@@ -851,10 +996,18 @@ export declare const modifySome: {
  */
 export declare 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)
      *
@@ -885,10 +1038,18 @@ export declare 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)
      *
@@ -1416,9 +1577,18 @@ export declare const updateSome: {
     <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<void>;
 };
 /**
- * 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)
  *
@@ -1443,9 +1613,18 @@ export declare const updateSome: {
  */
 export declare 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)
      *
@@ -1470,9 +1649,18 @@ export declare 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)
      *
@@ -1498,10 +1686,18 @@ export declare const updateSomeEffect: {
     <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): Effect.Effect<void, E, R>;
 };
 /**
- * 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)
  *
@@ -1524,10 +1720,18 @@ export declare const updateSomeEffect: {
  */
 export declare 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)
      *
@@ -1550,10 +1754,18 @@ export declare 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)
      *
@@ -1577,10 +1789,18 @@ export declare const updateSomeAndGet: {
     <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<A>;
 };
 /**
- * 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)
  *
@@ -1603,10 +1823,18 @@ export declare const updateSomeAndGet: {
  */
 export declare 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)
      *
@@ -1629,10 +1857,18 @@ export declare 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)
      *