effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/SubscriptionRef.ts

@@ -1,4 +1,18 @@
 /**
+ * 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.
+ *
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -15,8 +29,14 @@ import type { Invariant } from "./Types.ts"
 const TypeId = "~effect/SubscriptionRef"
 
 /**
- * @since 2.0.0
+ * A mutable reference whose updates are serialized and published to
+ * subscribers.
+ *
+ * Use `changes` to observe the current value and subsequent updates as a
+ * stream.
+ *
  * @category models
+ * @since 2.0.0
  */
 export interface SubscriptionRef<in out A> extends SubscriptionRef.Variance<A>, Pipeable {
   value: A
@@ -25,22 +45,28 @@ export interface SubscriptionRef<in out A> extends SubscriptionRef.Variance<A>,
 }
 
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `SubscriptionRef`.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export const isSubscriptionRef: (u: unknown) => u is SubscriptionRef<unknown> = (
   u: unknown
 ): u is SubscriptionRef<unknown> => hasProperty(u, TypeId)
 
 /**
- * The `SynchronizedRef` namespace containing type definitions and utilities.
+ * The `SubscriptionRef` namespace containing type definitions associated with
+ * subscription references.
  *
  * @since 2.0.0
  */
 export declare namespace SubscriptionRef {
   /**
-   * @since 2.0.0
+   * Type-level variance marker for the value type carried by a
+   * `SubscriptionRef`.
+   *
    * @category models
+   * @since 2.0.0
    */
   export interface Variance<in out A> {
     readonly [TypeId]: {
@@ -65,8 +91,8 @@ const Proto = {
 /**
  * Constructs a new `SubscriptionRef` from an initial value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A>(value: A): Effect.Effect<SubscriptionRef<A>> =>
   Effect.map(PubSub.unbounded<A>({ replay: 1 }), (pubsub) => {
@@ -85,23 +111,31 @@ export const make = <A>(value: A): Effect.Effect<SubscriptionRef<A>> =>
  * The stream will first emit the current value, then emit all future changes
  * as they occur.
  *
- * @example
+ * **Example** (Streaming changes)
+ *
  * ```ts
- * import { Effect, Stream, SubscriptionRef } from "effect"
+ * import { Deferred, Effect, Fiber, Stream, SubscriptionRef } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* SubscriptionRef.make(0)
+ *   const ready = yield* Deferred.make<void>()
  *
- *   const stream = SubscriptionRef.changes(ref)
- *
- *   const fiber = yield* Stream.runForEach(
- *     stream,
- *     (value) => Effect.sync(() => console.log("Value:", value))
- *   ).pipe(Effect.forkScoped)
+ *   const fiber = yield* SubscriptionRef.changes(ref).pipe(
+ *     Stream.tap(() => Deferred.succeed(ready, void 0)),
+ *     Stream.take(3),
+ *     Stream.runCollect,
+ *     Effect.forkChild
+ *   )
  *
+ *   yield* Deferred.await(ready)
  *   yield* SubscriptionRef.set(ref, 1)
  *   yield* SubscriptionRef.set(ref, 2)
+ *
+ *   const values = yield* Fiber.join(fiber)
+ *   console.log(values) // [ 0, 1, 2 ]
  * })
+ *
+ * Effect.runPromise(program)
  * ```
  *
  * @category changes
@@ -116,7 +150,8 @@ export const changes = <A>(self: SubscriptionRef<A>): Stream.Stream<A> => Stream
  * synchronization. It should only be used when you're certain there are no
  * concurrent modifications.
  *
- * @example
+ * **Example** (Reading the current value unsafely)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -128,15 +163,16 @@ export const changes = <A>(self: SubscriptionRef<A>): Stream.Stream<A> => Stream
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getUnsafe = <A>(self: SubscriptionRef<A>): A => self.value
 
 /**
  * Retrieves the current value of the `SubscriptionRef`.
  *
- * @example
+ * **Example** (Reading the current value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -148,8 +184,8 @@ export const getUnsafe = <A>(self: SubscriptionRef<A>): A => self.value
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.sync(() => self.value)
 
@@ -157,7 +193,8 @@ export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.syn
  * Atomically retrieves the current value and sets a new value, notifying
  * subscribers of the change.
  *
- * @example
+ * **Example** (Getting and setting a value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -172,15 +209,16 @@ export const get = <A>(self: SubscriptionRef<A>): Effect.Effect<A> => Effect.syn
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getAndSet: {
   /**
    * Atomically retrieves the current value and sets a new value, notifying
    * subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and setting a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -195,15 +233,16 @@ export const getAndSet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(value: A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
    * Atomically retrieves the current value and sets a new value, notifying
    * subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and setting a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -218,8 +257,8 @@ export const getAndSet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<A>
 } = dual(2, <A>(self: SubscriptionRef<A>, value: A) =>
@@ -238,7 +277,8 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
  * Atomically retrieves the current value and updates it with the result of
  * applying a function, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Getting and updating a value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -253,15 +293,16 @@ const setUnsafe = <A>(self: SubscriptionRef<A>, value: A) => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getAndUpdate: {
   /**
    * Atomically retrieves the current value and updates it with the result of
    * applying a function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and updating a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -276,15 +317,16 @@ export const getAndUpdate: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
    * Atomically retrieves the current value and updates it with the result of
    * applying a function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and updating a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -299,8 +341,8 @@ export const getAndUpdate: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<A>
 } = dual(2, <A>(self: SubscriptionRef<A>, update: (a: A) => A) =>
@@ -315,7 +357,8 @@ export const getAndUpdate: {
  * Atomically retrieves the current value and updates it with the result of
  * applying an effectful function, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Getting and updating with an effect)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -333,15 +376,16 @@ export const getAndUpdate: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getAndUpdateEffect: {
   /**
    * Atomically retrieves the current value and updates it with the result of
    * applying an effectful function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and updating with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -359,15 +403,16 @@ export const getAndUpdateEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <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
    * applying an effectful function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Getting and updating with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -385,8 +430,8 @@ export const getAndUpdateEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = dual(2, <A, E, R>(
@@ -402,11 +447,12 @@ export const getAndUpdateEffect: {
   })))
 
 /**
- * Atomically retrieves the current value and optionally updates it with the
- * result of applying a function that returns an `Option`, notifying
- * subscribers only if the value changes.
+ * 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.
+ *
+ * **Example** (Getting and conditionally updating a value)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -424,16 +470,17 @@ export const getAndUpdateEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getAndUpdateSome: {
   /**
-   * Atomically retrieves the current value and optionally updates it with the
-   * result of applying a function that returns an `Option`, notifying
-   * subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Getting and conditionally updating a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -451,16 +498,17 @@ export const getAndUpdateSome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Atomically retrieves the current value and optionally updates it with the
-   * result of applying a function that returns an `Option`, notifying
-   * subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Getting and conditionally updating a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -478,8 +526,8 @@ export const getAndUpdateSome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<A>
 } = dual(2, <A>(
@@ -497,11 +545,13 @@ export const getAndUpdateSome: {
   })))
 
 /**
- * Atomically retrieves the current value and optionally updates it with the
- * result of applying an effectful function that returns an `Option`,
- * notifying subscribers only if the value changes.
+ * 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.
+ *
+ * **Example** (Getting and conditionally updating with an effect)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -519,16 +569,18 @@ export const getAndUpdateSome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const getAndUpdateSomeEffect: {
   /**
-   * Atomically retrieves the current value and optionally updates it with the
-   * result of applying an effectful function that returns an `Option`,
-   * notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Getting and conditionally updating with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -546,16 +598,18 @@ export const getAndUpdateSomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <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 optionally updates it with the
-   * result of applying an effectful function that returns an `Option`,
-   * notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Getting and conditionally updating with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -573,8 +627,8 @@ export const getAndUpdateSomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category getters
+   * @since 2.0.0
    */
   <A, R, E>(
     self: SubscriptionRef<A>,
@@ -597,7 +651,8 @@ export const getAndUpdateSomeEffect: {
  * Atomically modifies the `SubscriptionRef` with a function that computes a
  * return value and a new value, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Modifying a value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -615,15 +670,16 @@ export const getAndUpdateSomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export const modify: {
   /**
    * Atomically modifies the `SubscriptionRef` with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Modifying a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -641,15 +697,16 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <A, B>(modify: (a: A) => readonly [B, A]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
    * Atomically modifies the `SubscriptionRef` with a function that computes a
    * return value and a new value, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Modifying a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -667,8 +724,8 @@ export const modify: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <A, B>(self: SubscriptionRef<A>, f: (a: A) => readonly [B, A]): Effect.Effect<B>
 } = dual(2, <A, B>(
@@ -686,7 +743,8 @@ export const modify: {
  * computes a return value and a new value, notifying subscribers of the
  * change.
  *
- * @example
+ * **Example** (Modifying with an effect)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -704,8 +762,8 @@ export const modify: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export const modifyEffect: {
   /**
@@ -713,7 +771,8 @@ export const modifyEffect: {
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Modifying with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -731,8 +790,8 @@ export const modifyEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <B, A, E, R>(modify: (a: A) => Effect.Effect<readonly [B, A], E, R>): (self: SubscriptionRef<A>) => Effect.Effect<B, E, R>
   /**
@@ -740,7 +799,8 @@ export const modifyEffect: {
    * computes a return value and a new value, notifying subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Modifying with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -758,8 +818,8 @@ export const modifyEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <A, B, E, R>(
     self: SubscriptionRef<A>,
@@ -777,11 +837,12 @@ export const modifyEffect: {
   )))
 
 /**
- * Atomically modifies the `SubscriptionRef` with a function that computes a
- * return value and optionally a new value, notifying subscribers only if the
- * value changes.
+ * 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.
+ *
+ * **Example** (Conditionally modifying a value)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -800,16 +861,17 @@ export const modifyEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export const modifySome: {
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
-   * return value and optionally a new value, notifying subscribers only if the
-   * value changes.
+   * 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.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -828,16 +890,17 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <B, A>(modify: (a: A) => readonly [B, Option.Option<A>]): (self: SubscriptionRef<A>) => Effect.Effect<B>
   /**
-   * Atomically modifies the `SubscriptionRef` with a function that computes a
-   * return value and optionally a new value, notifying subscribers only if the
-   * value changes.
+   * 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.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -856,8 +919,8 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <A, B>(self: SubscriptionRef<A>, modify: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual(2, <A, B>(
@@ -872,11 +935,13 @@ export const modifySome: {
   })))
 
 /**
- * Atomically modifies the `SubscriptionRef` with an effectful function that
- * computes a return value and optionally a new value, notifying subscribers
- * only if the value changes.
+ * 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.
+ *
+ * **Example** (Conditionally modifying with an effect)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -899,16 +964,18 @@ export const modifySome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export const modifySomeEffect: {
   /**
-   * Atomically modifies the `SubscriptionRef` with an effectful function that
-   * computes a return value and optionally a new value, notifying subscribers
-   * only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally modifying with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -931,16 +998,18 @@ export const modifySomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <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 modifies the `SubscriptionRef` with an effectful function that
-   * computes a return value and optionally a new value, notifying subscribers
-   * only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally modifying with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -963,8 +1032,8 @@ export const modifySomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category modifications
+   * @since 2.0.0
    */
   <A, B, R, E>(
     self: SubscriptionRef<A>,
@@ -986,7 +1055,8 @@ export const modifySomeEffect: {
  * Sets the value of the `SubscriptionRef`, notifying all subscribers of the
  * change.
  *
- * @example
+ * **Example** (Setting a value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1000,15 +1070,16 @@ export const modifySomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const set: {
   /**
    * Sets the value of the `SubscriptionRef`, notifying all subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1022,15 +1093,16 @@ export const set: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(value: A): (self: SubscriptionRef<A>) => Effect.Effect<void>
   /**
    * Sets the value of the `SubscriptionRef`, notifying all subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1044,8 +1116,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<void>
 } = dual(
@@ -1057,7 +1129,8 @@ export const set: {
  * Sets the value of the `SubscriptionRef` and returns the new value,
  * notifying all subscribers of the change.
  *
- * @example
+ * **Example** (Setting and reading the new value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1069,15 +1142,16 @@ export const set: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const setAndGet: {
   /**
    * Sets the value of the `SubscriptionRef` and returns the new value,
    * notifying all subscribers of the change.
    *
-   * @example
+   * **Example** (Setting and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1089,15 +1163,16 @@ export const setAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(value: A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
    * Sets the value of the `SubscriptionRef` and returns the new value,
    * notifying all subscribers of the change.
    *
-   * @example
+   * **Example** (Setting and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1109,8 +1184,8 @@ export const setAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<A>
 } = dual(2, <A>(self: SubscriptionRef<A>, value: A) =>
@@ -1123,7 +1198,8 @@ export const setAndGet: {
  * Updates the value of the `SubscriptionRef` with the result of applying a
  * function, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Updating a value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1137,15 +1213,16 @@ export const setAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const update: {
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying a
    * function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1159,15 +1236,16 @@ export const update: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect.Effect<void>
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying a
    * function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1181,8 +1259,8 @@ export const update: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<void>
 } = dual(
@@ -1195,7 +1273,8 @@ export const update: {
  * Updates the value of the `SubscriptionRef` with the result of applying an
  * effectful function, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Updating with an effect)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1209,15 +1288,16 @@ export const update: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateEffect: {
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying an
    * effectful function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1231,15 +1311,16 @@ export const updateEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(update: (a: A) => Effect.Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<void, E, R>
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying an
    * effectful function, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating with an effect)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1253,8 +1334,8 @@ export const updateEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<void, E, R>
 } = dual(2, <A, E, R>(
@@ -1269,7 +1350,8 @@ export const updateEffect: {
  * Updates the value of the `SubscriptionRef` with the result of applying a
  * function and returns the new value, notifying subscribers of the change.
  *
- * @example
+ * **Example** (Updating and reading the new value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1281,15 +1363,16 @@ export const updateEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateAndGet: {
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying a
    * function and returns the new value, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1301,15 +1384,16 @@ export const updateAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
    * Updates the value of the `SubscriptionRef` with the result of applying a
    * function and returns the new value, notifying subscribers of the change.
    *
-   * @example
+   * **Example** (Updating and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1321,8 +1405,8 @@ export const updateAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<A>
 } = dual(2, <A>(self: SubscriptionRef<A>, update: (a: A) => A) =>
@@ -1337,7 +1421,8 @@ export const updateAndGet: {
  * effectful function and returns the new value, notifying subscribers of the
  * change.
  *
- * @example
+ * **Example** (Updating with an effect and reading the new value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -1352,8 +1437,8 @@ export const updateAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateAndGetEffect: {
   /**
@@ -1361,7 +1446,8 @@ export const updateAndGetEffect: {
    * effectful function and returns the new value, notifying subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Updating with an effect and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1376,8 +1462,8 @@ export const updateAndGetEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(update: (a: A) => Effect.Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
@@ -1385,7 +1471,8 @@ export const updateAndGetEffect: {
    * effectful function and returns the new value, notifying subscribers of the
    * change.
    *
-   * @example
+   * **Example** (Updating with an effect and reading the new value)
+   *
    * ```ts
    * import { Effect, SubscriptionRef } from "effect"
    *
@@ -1400,8 +1487,8 @@ export const updateAndGetEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = dual(2, <A, E, R>(
@@ -1416,11 +1503,12 @@ export const updateAndGetEffect: {
   )))
 
 /**
- * Optionally updates the value of the `SubscriptionRef` with the result of
- * applying a function that returns an `Option`, notifying subscribers only if
- * the value changes.
+ * Applies an update function to the current value. If it returns
+ * `Option.some`, sets and publishes that value; if it returns `Option.none`,
+ * leaves the reference unchanged and does not publish.
+ *
+ * **Example** (Conditionally updating a value)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -1437,16 +1525,17 @@ export const updateAndGetEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateSome: {
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying a function that returns an `Option`, notifying subscribers only if
-   * the value changes.
+   * Applies an update function to the current value. If it returns
+   * `Option.some`, sets and publishes that value; if it returns `Option.none`,
+   * leaves the reference unchanged and does not publish.
+   *
+   * **Example** (Conditionally updating a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1463,16 +1552,17 @@ export const updateSome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<void>
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying a function that returns an `Option`, notifying subscribers only if
-   * the value changes.
+   * Applies an update function to the current value. If it returns
+   * `Option.some`, sets and publishes that value; if it returns `Option.none`,
+   * leaves the reference unchanged and does not publish.
+   *
+   * **Example** (Conditionally updating a value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1489,8 +1579,8 @@ export const updateSome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<void>
 } = dual(2, <A>(
@@ -1504,11 +1594,12 @@ export const updateSome: {
   })))
 
 /**
- * Optionally updates the value of the `SubscriptionRef` with the result of
- * applying an effectful function that returns an `Option`, notifying
- * subscribers only if the value changes.
+ * 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.
+ *
+ * **Example** (Conditionally updating with an effect)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -1525,16 +1616,17 @@ export const updateSome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateSomeEffect: {
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying an effectful function that returns an `Option`, notifying
-   * subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1551,16 +1643,17 @@ export const updateSomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<void, E, R>
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying an effectful function that returns an `Option`, notifying
-   * subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating with an effect)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1577,8 +1670,8 @@ export const updateSomeEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(
     self: SubscriptionRef<A>,
@@ -1596,11 +1689,13 @@ export const updateSomeEffect: {
   )))
 
 /**
- * Optionally updates the value of the `SubscriptionRef` with the result of
- * applying a function that returns an `Option` and returns the new value,
- * notifying subscribers only if the value changes.
+ * 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.
+ *
+ * **Example** (Conditionally updating and reading the new value)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -1615,16 +1710,18 @@ export const updateSomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateSomeAndGet: {
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying a function that returns an `Option` and returns the new value,
-   * notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating and reading the new value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1639,16 +1736,18 @@ export const updateSomeAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(update: (a: A) => Option.Option<A>): (self: SubscriptionRef<A>) => Effect.Effect<A>
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying a function that returns an `Option` and returns the new value,
-   * notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating and reading the new value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1663,8 +1762,8 @@ export const updateSomeAndGet: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A>(self: SubscriptionRef<A>, update: (a: A) => Option.Option<A>): Effect.Effect<A>
 } = dual(2, <A>(
@@ -1680,11 +1779,13 @@ export const updateSomeAndGet: {
   })))
 
 /**
- * Optionally updates the value of the `SubscriptionRef` with the result of
- * applying an effectful function that returns an `Option` and returns the new
- * value, notifying subscribers only if the value changes.
+ * 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.
+ *
+ * **Example** (Conditionally updating with an effect and reading the new value)
  *
- * @example
  * ```ts
  * import { Effect, Option, SubscriptionRef } from "effect"
  *
@@ -1699,16 +1800,18 @@ export const updateSomeAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export const updateSomeAndGetEffect: {
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying an effectful function that returns an `Option` and returns the new
-   * value, notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating with an effect and reading the new value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1723,16 +1826,18 @@ export const updateSomeAndGetEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): (self: SubscriptionRef<A>) => Effect.Effect<A, E, R>
   /**
-   * Optionally updates the value of the `SubscriptionRef` with the result of
-   * applying an effectful function that returns an `Option` and returns the new
-   * value, notifying subscribers only if the value changes.
+   * 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.
+   *
+   * **Example** (Conditionally updating with an effect and reading the new value)
    *
-   * @example
    * ```ts
    * import { Effect, Option, SubscriptionRef } from "effect"
    *
@@ -1747,8 +1852,8 @@ export const updateSomeAndGetEffect: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category updating
+   * @since 2.0.0
    */
   <A, E, R>(
     self: SubscriptionRef<A>,