effect 4.0.0-beta.66 → 4.0.0-beta.68

package/src/Ref.ts

@@ -5,7 +5,8 @@
  * mutable variables, Refs are thread-safe and work seamlessly with Effect's concurrency model.
  * They provide atomic operations for safe state management in concurrent programs.
  *
- * @example
+ * **Example** (Managing shared state with refs)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -45,7 +46,8 @@ const TypeId = "~effect/Ref"
  * on shared state. It supports both simple read/write operations and complex
  * atomic transformations.
  *
- * @example
+ * **Example** (Reading and updating a ref)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -66,8 +68,8 @@ const TypeId = "~effect/Ref"
  * })
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface Ref<in out A> extends Ref.Variance<A>, Pipeable {
   readonly ref: MutableRef.MutableRef<A>
@@ -77,13 +79,13 @@ export interface Ref<in out A> extends Ref.Variance<A>, Pipeable {
  * The Ref namespace containing type definitions and utilities.
  *
  * @since 2.0.0
- * @category models
  */
 export declare namespace Ref {
   /**
    * Variance interface for Ref types, defining the type parameter constraints.
    *
-   * @example
+   * **Example** (Using invariant refs)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -98,8 +100,8 @@ export declare namespace Ref {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category models
+   * @since 2.0.0
    */
   export interface Variance<in out A> {
     readonly [TypeId]: {
@@ -127,7 +129,8 @@ const RefProto = {
  * This function creates a Ref synchronously without wrapping in Effect.
  * Use this only when you're sure about the safety of immediate creation.
  *
- * @example
+ * **Example** (Creating a ref unsafely)
+ *
  * ```ts
  * import { Ref } from "effect"
  *
@@ -142,8 +145,8 @@ const RefProto = {
  * // Prefer Ref.make for Effect-wrapped creation
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <A>(value: A): Ref<A> => {
   const self = Object.create(RefProto)
@@ -154,10 +157,8 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
 /**
  * Creates a new Ref with the specified initial value.
  *
- * @param value - The initial value for the Ref
- * @returns An Effect that creates a new Ref
+ * **Example** (Creating a ref)
  *
- * @example
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -168,15 +169,16 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => makeUnsafe(value))
 
 /**
  * Gets the current value of the Ref.
  *
- * @example
+ * **Example** (Getting the current value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -187,15 +189,16 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
  * })
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 2.0.0
  */
 export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
 
 /**
  * Sets the value of the Ref to the specified value.
  *
- * @example
+ * **Example** (Setting a value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -215,14 +218,15 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const set = dual<
   /**
    * Sets the value of the Ref to the specified value.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -242,14 +246,15 @@ export const set = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<void>,
   /**
    * Sets the value of the Ref to the specified value.
    *
-   * @example
+   * **Example** (Setting a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -269,8 +274,8 @@ export const set = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => MutableRef.set(self.ref, value)))
@@ -280,7 +285,8 @@ export const set = dual<
  *
  * Returns the value that was in the Ref before the update.
  *
- * @example
+ * **Example** (Replacing a value atomically)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -296,8 +302,8 @@ export const set = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndSet = dual<
   /**
@@ -305,7 +311,8 @@ export const getAndSet = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Replacing a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -321,8 +328,8 @@ export const getAndSet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -330,7 +337,8 @@ export const getAndSet = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Replacing a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -346,8 +354,8 @@ export const getAndSet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, value: A) =>
@@ -362,7 +370,8 @@ export const getAndSet = dual<
  *
  * Returns the value that was in the Ref before the update.
  *
- * @example
+ * **Example** (Updating and returning the previous value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -378,8 +387,8 @@ export const getAndSet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdate = dual<
   /**
@@ -387,7 +396,8 @@ export const getAndUpdate = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -403,8 +413,8 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -412,7 +422,8 @@ export const getAndUpdate = dual<
    *
    * Returns the value that was in the Ref before the update.
    *
-   * @example
+   * **Example** (Updating and returning the previous value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -428,8 +439,8 @@ export const getAndUpdate = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) =>
@@ -446,10 +457,10 @@ export const getAndUpdate = dual<
  * If it returns `Option.none`, the Ref is left unchanged.
  * Always returns the value that was in the Ref before the attempted update.
  *
- * @example
+ * **Example** (Conditionally updating and returning the previous value)
+ *
  * ```ts
- * import { Effect, Ref } from "effect"
- * import * as Option from "effect/Option"
+ * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
@@ -476,8 +487,8 @@ export const getAndUpdate = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const getAndUpdateSome = dual<
   /**
@@ -487,10 +498,10 @@ export const getAndUpdateSome = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Always returns the value that was in the Ref before the attempted update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the previous value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -517,8 +528,8 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -528,10 +539,10 @@ export const getAndUpdateSome = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Always returns the value that was in the Ref before the attempted update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the previous value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -558,8 +569,8 @@ export const getAndUpdateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) =>
@@ -577,7 +588,8 @@ export const getAndUpdateSome = dual<
  *
  * This is useful when you want to set a value and immediately get it back in one atomic operation.
  *
- * @example
+ * **Example** (Setting and returning the new value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -602,8 +614,8 @@ export const getAndUpdateSome = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const setAndGet = dual<
   /**
@@ -611,7 +623,8 @@ export const setAndGet = dual<
    *
    * This is useful when you want to set a value and immediately get it back in one atomic operation.
    *
-   * @example
+   * **Example** (Setting and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -636,8 +649,8 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -645,7 +658,8 @@ export const setAndGet = dual<
    *
    * This is useful when you want to set a value and immediately get it back in one atomic operation.
    *
-   * @example
+   * **Example** (Setting and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -670,8 +684,8 @@ export const setAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, value: A) => Effect.sync(() => self.ref.current = value))
@@ -682,7 +696,8 @@ export const setAndGet = dual<
  * The function receives the current value and returns a tuple of [result, newValue].
  * The Ref is updated with the newValue and the result is returned.
  *
- * @example
+ * **Example** (Modifying a value atomically)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -714,8 +729,8 @@ export const setAndGet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const modify = dual<
   /**
@@ -724,7 +739,8 @@ export const modify = dual<
    * The function receives the current value and returns a tuple of [result, newValue].
    * The Ref is updated with the newValue and the result is returned.
    *
-   * @example
+   * **Example** (Modifying a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -756,8 +772,8 @@ export const modify = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(f: (a: A) => readonly [B, A]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
@@ -766,7 +782,8 @@ export const modify = dual<
    * The function receives the current value and returns a tuple of [result, newValue].
    * The Ref is updated with the newValue and the result is returned.
    *
-   * @example
+   * **Example** (Modifying a value atomically)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -798,8 +815,8 @@ export const modify = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, f: (a: A) => readonly [B, A]) => Effect.Effect<B>
 >(2, (self, f) =>
@@ -810,16 +827,19 @@ export const modify = dual<
   }))
 
 /**
- * Atomically modifies the value of the Ref using the given partial function.
+ * Atomically computes a result and optionally updates the value of the `Ref`.
+ *
+ * **Details**
+ *
+ * The callback receives the current value and returns `[result, nextValue]`,
+ * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+ * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+ * unchanged. The returned effect always succeeds with `result`.
  *
- * The function receives the current value and returns an Option of [result, newValue].
- * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
- * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+ * **Example** (Conditionally modifying a value)
  *
- * @example
  * ```ts
- * import { Effect, Ref } from "effect"
- * import * as Option from "effect/Option"
+ * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
@@ -854,21 +874,24 @@ export const modify = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const modifySome: {
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -903,21 +926,24 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: Ref<A>) => Effect.Effect<B>
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
+   *
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -952,22 +978,25 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual<
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
+   *
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -1002,21 +1031,24 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]) => (self: Ref<A>) => Effect.Effect<B>,
   /**
-   * Atomically modifies the value of the Ref using the given partial function.
+   * Atomically computes a result and optionally updates the value of the `Ref`.
+   *
+   * **Details**
+   *
+   * The callback receives the current value and returns `[result, nextValue]`,
+   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
+   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
+   * unchanged. The returned effect always succeeds with `result`.
    *
-   * The function receives the current value and returns an Option of [result, newValue].
-   * If the function returns `Option.some([result, newValue])`, the Ref is updated with newValue and result is returned.
-   * If it returns `Option.none()`, the Ref is left unchanged and the fallback value is returned.
+   * **Example** (Conditionally modifying a value)
    *
-   * @example
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -1051,8 +1083,8 @@ export const modifySome: {
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]) => Effect.Effect<B>
 >(2, (self, pf) =>
@@ -1064,7 +1096,8 @@ export const modifySome: {
 /**
  * Atomically updates the value of the Ref using the given function.
  *
- * @example
+ * **Example** (Updating a value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -1087,14 +1120,15 @@ export const modifySome: {
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const update = dual<
   /**
    * Atomically updates the value of the Ref using the given function.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1117,14 +1151,15 @@ export const update = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<void>,
   /**
    * Atomically updates the value of the Ref using the given function.
    *
-   * @example
+   * **Example** (Updating a value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1147,8 +1182,8 @@ export const update = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) =>
@@ -1159,7 +1194,8 @@ export const update = dual<
 /**
  * Atomically updates the value of the Ref using the given function and returns the new value.
  *
- * @example
+ * **Example** (Updating and returning the new value)
+ *
  * ```ts
  * import { Effect, Ref } from "effect"
  *
@@ -1176,14 +1212,15 @@ export const update = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const updateAndGet = dual<
   /**
    * Atomically updates the value of the Ref using the given function and returns the new value.
    *
-   * @example
+   * **Example** (Updating and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1200,14 +1237,15 @@ export const updateAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<A>,
   /**
    * Atomically updates the value of the Ref using the given function and returns the new value.
    *
-   * @example
+   * **Example** (Updating and returning the new value)
+   *
    * ```ts
    * import { Effect, Ref } from "effect"
    *
@@ -1224,8 +1262,8 @@ export const updateAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, f: (a: A) => A) => Effect.sync(() => self.ref.current = f(self.ref.current)))
@@ -1236,10 +1274,10 @@ export const updateAndGet = dual<
  * If the partial function returns `Option.some`, the Ref is updated with the new value.
  * If it returns `Option.none`, the Ref is left unchanged.
  *
- * @example
+ * **Example** (Conditionally updating a value)
+ *
  * ```ts
- * import { Effect, Ref } from "effect"
- * import * as Option from "effect/Option"
+ * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
@@ -1265,8 +1303,8 @@ export const updateAndGet = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category setters
+ * @since 2.0.0
  */
 export const updateSome = dual<
   /**
@@ -1275,10 +1313,10 @@ export const updateSome = dual<
    * If the partial function returns `Option.some`, the Ref is updated with the new value.
    * If it returns `Option.none`, the Ref is left unchanged.
    *
-   * @example
+   * **Example** (Conditionally updating a value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -1304,8 +1342,8 @@ export const updateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(f: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<void>,
   /**
@@ -1314,10 +1352,10 @@ export const updateSome = dual<
    * If the partial function returns `Option.some`, the Ref is updated with the new value.
    * If it returns `Option.none`, the Ref is left unchanged.
    *
-   * @example
+   * **Example** (Conditionally updating a value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
@@ -1343,8 +1381,8 @@ export const updateSome = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category setters
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => Option.Option<A>) => Effect.Effect<void>
 >(2, <A>(self: Ref<A>, f: (a: A) => Option.Option<A>) =>
@@ -1362,10 +1400,10 @@ export const updateSome = dual<
  * If it returns `Option.none`, the Ref is left unchanged.
  * Returns the current value of the Ref after the potential update.
  *
- * @example
+ * **Example** (Conditionally updating and returning the current value)
+ *
  * ```ts
- * import { Effect, Ref } from "effect"
- * import * as Option from "effect/Option"
+ * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(10)
@@ -1386,8 +1424,8 @@ export const updateSome = dual<
  * })
  * ```
  *
- * @since 2.0.0
  * @category utils
+ * @since 2.0.0
  */
 export const updateSomeAndGet = dual<
   /**
@@ -1397,10 +1435,10 @@ export const updateSomeAndGet = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Returns the current value of the Ref after the potential update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the current value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
@@ -1421,8 +1459,8 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(pf: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<A>,
   /**
@@ -1432,10 +1470,10 @@ export const updateSomeAndGet = dual<
    * If it returns `Option.none`, the Ref is left unchanged.
    * Returns the current value of the Ref after the potential update.
    *
-   * @example
+   * **Example** (Conditionally updating and returning the current value)
+   *
    * ```ts
-   * import { Effect, Ref } from "effect"
-   * import * as Option from "effect/Option"
+   * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
@@ -1456,8 +1494,8 @@ export const updateSomeAndGet = dual<
    * })
    * ```
    *
-   * @since 2.0.0
    * @category utils
+   * @since 2.0.0
    */
   <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) => Effect.Effect<A>
 >(2, <A>(self: Ref<A>, pf: (a: A) => Option.Option<A>) =>
@@ -1475,7 +1513,8 @@ export const updateSomeAndGet = dual<
  * This function reads the current value without wrapping in Effect.
  * Use this only when you're sure about the safety of immediate access.
  *
- * @example
+ * **Example** (Reading a ref unsafely)
+ *
  * ```ts
  * import { Ref } from "effect"
  *
@@ -1490,7 +1529,7 @@ export const updateSomeAndGet = dual<
  * // Prefer Ref.get for Effect-wrapped access
  * ```
  *
- * @since 2.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const getUnsafe = <A>(self: Ref<A>): A => self.ref.current