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

package/dist/SubscriptionRef.d.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";
@@ -10,8 +24,14 @@ import * as Stream from "./Stream.ts";
 import type { Invariant } from "./Types.ts";
 declare 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;
@@ -19,19 +39,25 @@ export interface SubscriptionRef<in out A> extends SubscriptionRef.Variance<A>,
     readonly pubsub: PubSub.PubSub<A>;
 }
 /**
- * @since 4.0.0
+ * Returns `true` if the provided value is a `SubscriptionRef`.
+ *
  * @category guards
+ * @since 4.0.0
  */
 export declare const isSubscriptionRef: (u: unknown) => u is SubscriptionRef<unknown>;
 /**
- * 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
      */
     interface Variance<in out A> {
         readonly [TypeId]: {
@@ -42,8 +68,8 @@ export declare namespace SubscriptionRef {
 /**
  * Constructs a new `SubscriptionRef` from an initial value.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <A>(value: A) => Effect.Effect<SubscriptionRef<A>>;
 /**
@@ -53,23 +79,31 @@ export declare 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
@@ -83,7 +117,8 @@ export declare const changes: <A>(self: SubscriptionRef<A>) => Stream.Stream<A>;
  * 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"
  *
@@ -95,14 +130,15 @@ export declare const changes: <A>(self: SubscriptionRef<A>) => Stream.Stream<A>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const getUnsafe: <A>(self: SubscriptionRef<A>) => A;
 /**
  * Retrieves the current value of the `SubscriptionRef`.
  *
- * @example
+ * **Example** (Reading the current value)
+ *
  * ```ts
  * import { Effect, SubscriptionRef } from "effect"
  *
@@ -114,15 +150,16 @@ export declare const getUnsafe: <A>(self: SubscriptionRef<A>) => A;
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare const get: <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"
  *
@@ -137,15 +174,16 @@ export declare const get: <A>(self: SubscriptionRef<A>) => Effect.Effect<A>;
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -160,15 +198,16 @@ export declare 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"
      *
@@ -183,8 +222,8 @@ export declare const getAndSet: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category getters
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<A>;
 };
@@ -192,7 +231,8 @@ export declare const getAndSet: {
  * 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"
  *
@@ -207,15 +247,16 @@ export declare const getAndSet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -230,15 +271,16 @@ export declare 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"
      *
@@ -253,8 +295,8 @@ export declare const getAndUpdate: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category getters
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<A>;
 };
@@ -262,7 +304,8 @@ export declare 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"
  *
@@ -280,15 +323,16 @@ export declare const getAndUpdate: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -306,15 +350,16 @@ export declare 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"
      *
@@ -332,17 +377,18 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -360,16 +406,17 @@ export declare const getAndUpdateEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -387,16 +434,17 @@ export declare 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"
      *
@@ -414,17 +462,19 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -442,16 +492,18 @@ export declare const getAndUpdateSome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -469,16 +521,18 @@ export declare 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"
      *
@@ -496,8 +550,8 @@ export declare const getAndUpdateSomeEffect: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category getters
+     * @since 2.0.0
      */
     <A, R, E>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): Effect.Effect<A, E, R>;
 };
@@ -505,7 +559,8 @@ export declare 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"
  *
@@ -523,15 +578,16 @@ export declare const getAndUpdateSomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -549,15 +605,16 @@ export declare 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"
      *
@@ -575,8 +632,8 @@ export declare 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>;
 };
@@ -585,7 +642,8 @@ export declare 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"
  *
@@ -603,8 +661,8 @@ export declare const modify: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export declare const modifyEffect: {
     /**
@@ -612,7 +670,8 @@ export declare 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"
      *
@@ -630,8 +689,8 @@ export declare 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>;
     /**
@@ -639,7 +698,8 @@ export declare 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"
      *
@@ -657,17 +717,18 @@ export declare const modifyEffect: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category modifications
+     * @since 2.0.0
      */
     <A, B, E, R>(self: SubscriptionRef<A>, modify: (a: A) => Effect.Effect<readonly [B, A], E, R>): Effect.Effect<B, E, R>;
 };
 /**
- * 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"
  *
@@ -686,16 +747,17 @@ export declare const modifyEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -714,16 +776,17 @@ export declare 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"
      *
@@ -742,17 +805,19 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -775,16 +840,18 @@ export declare const modifySome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category modifications
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -807,16 +874,18 @@ export declare 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"
      *
@@ -839,8 +908,8 @@ export declare const modifySomeEffect: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category modifications
+     * @since 2.0.0
      */
     <A, B, R, E>(self: SubscriptionRef<A>, modify: (a: A) => Effect.Effect<readonly [B, Option.Option<A>], E, R>): Effect.Effect<B, E, R>;
 };
@@ -848,7 +917,8 @@ export declare 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"
  *
@@ -862,15 +932,16 @@ export declare const modifySomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -884,15 +955,16 @@ export declare 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"
      *
@@ -906,8 +978,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category setters
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<void>;
 };
@@ -915,7 +987,8 @@ export declare 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"
  *
@@ -927,15 +1000,16 @@ export declare const set: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -947,15 +1021,16 @@ export declare 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"
      *
@@ -967,8 +1042,8 @@ export declare const setAndGet: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category setters
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, value: A): Effect.Effect<A>;
 };
@@ -976,7 +1051,8 @@ export declare 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"
  *
@@ -990,15 +1066,16 @@ export declare const setAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1012,15 +1089,16 @@ export declare 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"
      *
@@ -1034,8 +1112,8 @@ export declare const update: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category updating
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<void>;
 };
@@ -1043,7 +1121,8 @@ export declare 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"
  *
@@ -1057,15 +1136,16 @@ export declare const update: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1079,15 +1159,16 @@ export declare 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"
      *
@@ -1101,8 +1182,8 @@ export declare 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>;
 };
@@ -1110,7 +1191,8 @@ export declare 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"
  *
@@ -1122,15 +1204,16 @@ export declare const updateEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1142,15 +1225,16 @@ export declare 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"
      *
@@ -1162,8 +1246,8 @@ export declare const updateAndGet: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category updating
+     * @since 2.0.0
      */
     <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect.Effect<A>;
 };
@@ -1172,7 +1256,8 @@ export declare 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"
  *
@@ -1187,8 +1272,8 @@ export declare const updateAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare const updateAndGetEffect: {
     /**
@@ -1196,7 +1281,8 @@ export declare 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"
      *
@@ -1211,8 +1297,8 @@ export declare 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>;
     /**
@@ -1220,7 +1306,8 @@ export declare 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"
      *
@@ -1235,17 +1322,18 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -1262,16 +1350,17 @@ export declare const updateAndGetEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1288,16 +1377,17 @@ export declare 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"
      *
@@ -1314,17 +1404,18 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -1341,16 +1432,17 @@ export declare const updateSome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1367,16 +1459,17 @@ export declare 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"
      *
@@ -1393,17 +1486,19 @@ export declare const updateSomeEffect: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category updating
+     * @since 2.0.0
      */
     <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): Effect.Effect<void, E, R>;
 };
 /**
- * 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"
  *
@@ -1418,16 +1513,18 @@ export declare const updateSomeEffect: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1442,16 +1539,18 @@ export declare 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"
      *
@@ -1466,17 +1565,19 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -1491,16 +1592,18 @@ export declare const updateSomeAndGet: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category updating
+ * @since 2.0.0
  */
 export declare 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"
      *
@@ -1515,16 +1618,18 @@ export declare 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"
      *
@@ -1539,8 +1644,8 @@ export declare const updateSomeAndGetEffect: {
      * })
      * ```
      *
-     * @since 2.0.0
      * @category updating
+     * @since 2.0.0
      */
     <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect.Effect<Option.Option<A>, E, R>): Effect.Effect<A, E, R>;
 };