effect 4.0.0-beta.102 → 4.0.0-beta.103

package/src/Ref.ts

@@ -35,24 +35,18 @@ const TypeId = "~effect/Ref"
  *
  * **Example** (Reading and updating a ref)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
- *   // Create a ref with initial value
  *   const counter = yield* Ref.make(0)
- *
- *   // Read the current value
  *   const value = yield* Ref.get(counter)
- *   console.log(value) // 0
- *
- *   // Update the value atomically
  *   yield* Ref.update(counter, (n) => n + 1)
- *
- *   // Read the updated value
  *   const newValue = yield* Ref.get(counter)
- *   console.log(newValue) // 1
+ *   return [value, newValue]
  * })
+ *
+ * await Effect.runPromise(program) // => [0, 1]
  * ```
  *
  * @see {@link make} for creating a `Ref`
@@ -85,18 +79,17 @@ export declare namespace Ref {
    *
    * **Example** (Using invariant refs)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
-   * // This interface defines the invariant nature of Ref's type parameter
-   * // A Ref<A> is both a producer and consumer of A
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make(42)
-   *
-   *   // Ref is invariant - it can both produce and consume numbers
-   *   const value = yield* Ref.get(ref) // produces number
-   *   yield* Ref.set(ref, value + 1) // consumes number
+   *   const value = yield* Ref.get(ref)
+   *   yield* Ref.set(ref, value + 1)
+   *   return yield* Ref.get(ref)
    * })
+   *
+   * await Effect.runPromise(program) // => 43
    * ```
    *
    * @category models
@@ -136,18 +129,11 @@ const RefProto = {
  *
  * **Example** (Creating a ref unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Ref } from "effect"
  *
- * // Create a ref directly without Effect
  * const counter = Ref.makeUnsafe(0)
- *
- * // Get the current value
- * const value = Ref.getUnsafe(counter)
- * console.log(value) // 0
- *
- * // Note: This is unsafe and should be used carefully
- * // Prefer Ref.make for Effect-wrapped creation
+ * Ref.getUnsafe(counter) // => 0
  * ```
  *
  * @category constructors
@@ -168,14 +154,15 @@ export const makeUnsafe = <A>(value: A): Ref<A> => {
  *
  * **Example** (Creating a ref)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* Ref.make(42)
- *   const value = yield* Ref.get(ref)
- *   console.log(value) // 42
+ *   return yield* Ref.get(ref)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
  * ```
  *
  * @see {@link makeUnsafe} for synchronous construction outside Effect code
@@ -194,14 +181,15 @@ export const make = <A>(value: A): Effect.Effect<Ref<A>> => Effect.sync(() => ma
  *
  * **Example** (Getting the current value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* Ref.make(42)
- *   const value = yield* Ref.get(ref)
- *   console.log(value) // 42
+ *   return yield* Ref.get(ref)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
  * ```
  *
  * @see {@link set} for replacing the current value
@@ -220,29 +208,29 @@ export const get = <A>(self: Ref<A>) => Effect.sync(() => self.ref.current)
  *
  * **Example** (Setting a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* Ref.make(0)
  *   yield* Ref.set(ref, 42)
- *   const value = yield* Ref.get(ref)
- *   console.log(value) // 42
+ *   return yield* Ref.get(ref)
  * })
  *
- * // Using multiple operations
  * const program2 = Effect.gen(function*() {
  *   const ref = yield* Ref.make(0)
  *   yield* Ref.set(ref, 100)
- *   const value = yield* Ref.get(ref)
- *   console.log(value) // 100
+ *   return yield* Ref.get(ref)
  * })
+ *
+ * await Effect.runPromise(program) // => 42
+ * await Effect.runPromise(program2) // => 100
  * ```
  *
  * @see {@link getAndSet} for setting while returning the previous value
  * @see {@link setAndGet} for setting while returning the new value
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const set = dual<
@@ -255,29 +243,29 @@ export const set = dual<
    *
    * **Example** (Setting a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make(0)
    *   yield* Ref.set(ref, 42)
-   *   const value = yield* Ref.get(ref)
-   *   console.log(value) // 42
+   *   return yield* Ref.get(ref)
    * })
    *
-   * // Using multiple operations
    * const program2 = Effect.gen(function*() {
    *   const ref = yield* Ref.make(0)
    *   yield* Ref.set(ref, 100)
-   *   const value = yield* Ref.get(ref)
-   *   console.log(value) // 100
+   *   return yield* Ref.get(ref)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
+   * await Effect.runPromise(program2) // => 100
    * ```
    *
    * @see {@link getAndSet} for setting while returning the previous value
    * @see {@link setAndGet} for setting while returning the new value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(value: A) => (self: Ref<A>) => Effect.Effect<void>,
@@ -290,29 +278,29 @@ export const set = dual<
    *
    * **Example** (Setting a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make(0)
    *   yield* Ref.set(ref, 42)
-   *   const value = yield* Ref.get(ref)
-   *   console.log(value) // 42
+   *   return yield* Ref.get(ref)
    * })
    *
-   * // Using multiple operations
    * const program2 = Effect.gen(function*() {
    *   const ref = yield* Ref.make(0)
    *   yield* Ref.set(ref, 100)
-   *   const value = yield* Ref.get(ref)
-   *   console.log(value) // 100
+   *   return yield* Ref.get(ref)
    * })
+   *
+   * await Effect.runPromise(program) // => 42
+   * await Effect.runPromise(program2) // => 100
    * ```
    *
    * @see {@link getAndSet} for setting while returning the previous value
    * @see {@link setAndGet} for setting while returning the new value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, value: A) => Effect.Effect<void>
@@ -327,19 +315,18 @@ export const set = dual<
  *
  * **Example** (Replacing a value atomically)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* Ref.make("initial")
  *
- *   // Get current value and set new value atomically
  *   const previous = yield* Ref.getAndSet(ref, "updated")
- *   console.log(previous) // "initial"
- *
  *   const current = yield* Ref.get(ref)
- *   console.log(current) // "updated"
+ *   return [previous, current]
  * })
+ *
+ * await Effect.runPromise(program) // => ["initial", "updated"]
  * ```
  *
  * @see {@link set} for setting without returning the previous value
@@ -358,19 +345,18 @@ export const getAndSet = dual<
    *
    * **Example** (Replacing a value atomically)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make("initial")
    *
-   *   // Get current value and set new value atomically
    *   const previous = yield* Ref.getAndSet(ref, "updated")
-   *   console.log(previous) // "initial"
-   *
    *   const current = yield* Ref.get(ref)
-   *   console.log(current) // "updated"
+   *   return [previous, current]
    * })
+   *
+   * await Effect.runPromise(program) // => ["initial", "updated"]
    * ```
    *
    * @see {@link set} for setting without returning the previous value
@@ -389,19 +375,18 @@ export const getAndSet = dual<
    *
    * **Example** (Replacing a value atomically)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make("initial")
    *
-   *   // Get current value and set new value atomically
    *   const previous = yield* Ref.getAndSet(ref, "updated")
-   *   console.log(previous) // "initial"
-   *
    *   const current = yield* Ref.get(ref)
-   *   console.log(current) // "updated"
+   *   return [previous, current]
    * })
+   *
+   * await Effect.runPromise(program) // => ["initial", "updated"]
    * ```
    *
    * @see {@link set} for setting without returning the previous value
@@ -427,19 +412,18 @@ export const getAndSet = dual<
  *
  * **Example** (Updating and returning the previous value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(10)
  *
- *   // Get current value and update it atomically
  *   const previous = yield* Ref.getAndUpdate(counter, (n) => n * 2)
- *   console.log(previous) // 10
- *
  *   const current = yield* Ref.get(counter)
- *   console.log(current) // 20
+ *   return [previous, current]
  * })
+ *
+ * await Effect.runPromise(program) // => [10, 20]
  * ```
  *
  * @see {@link update} for updating without returning the previous value
@@ -458,19 +442,18 @@ export const getAndUpdate = dual<
    *
    * **Example** (Updating and returning the previous value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Get current value and update it atomically
    *   const previous = yield* Ref.getAndUpdate(counter, (n) => n * 2)
-   *   console.log(previous) // 10
-   *
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 20
+   *   return [previous, current]
    * })
+   *
+   * await Effect.runPromise(program) // => [10, 20]
    * ```
    *
    * @see {@link update} for updating without returning the previous value
@@ -489,19 +472,18 @@ export const getAndUpdate = dual<
    *
    * **Example** (Updating and returning the previous value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Get current value and update it atomically
    *   const previous = yield* Ref.getAndUpdate(counter, (n) => n * 2)
-   *   console.log(previous) // 10
-   *
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 20
+   *   return [previous, current]
    * })
+   *
+   * await Effect.runPromise(program) // => [10, 20]
    * ```
    *
    * @see {@link update} for updating without returning the previous value
@@ -533,32 +515,26 @@ export const getAndUpdate = dual<
  *
  * **Example** (Conditionally updating and returning the previous value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *
- *   // Only update if value is greater than 3
  *   const previous1 = yield* Ref.getAndUpdateSome(
  *     counter,
  *     (n) => n > 3 ? Option.some(n * 2) : Option.none()
  *   )
- *   console.log(previous1) // 5
- *
  *   const current1 = yield* Ref.get(counter)
- *   console.log(current1) // 10
- *
- *   // Try to update again (won't update since 10 > 3 is true but let's say condition is n < 3)
  *   const previous2 = yield* Ref.getAndUpdateSome(
  *     counter,
  *     (n) => n < 3 ? Option.some(n * 2) : Option.none()
  *   )
- *   console.log(previous2) // 10
- *
  *   const current2 = yield* Ref.get(counter)
- *   console.log(current2) // 10 (unchanged)
+ *   return [previous1, current1, previous2, current2]
  * })
+ *
+ * await Effect.runPromise(program) // => [5, 10, 10, 10]
  * ```
  *
  * @see {@link getAndUpdate} for always applying an update
@@ -583,32 +559,26 @@ export const getAndUpdateSome = dual<
    *
    * **Example** (Conditionally updating and returning the previous value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only update if value is greater than 3
    *   const previous1 = yield* Ref.getAndUpdateSome(
    *     counter,
    *     (n) => n > 3 ? Option.some(n * 2) : Option.none()
    *   )
-   *   console.log(previous1) // 5
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 10
-   *
-   *   // Try to update again (won't update since 10 > 3 is true but let's say condition is n < 3)
    *   const previous2 = yield* Ref.getAndUpdateSome(
    *     counter,
    *     (n) => n < 3 ? Option.some(n * 2) : Option.none()
    *   )
-   *   console.log(previous2) // 10
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 10 (unchanged)
+   *   return [previous1, current1, previous2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 10, 10, 10]
    * ```
    *
    * @see {@link getAndUpdate} for always applying an update
@@ -633,32 +603,26 @@ export const getAndUpdateSome = dual<
    *
    * **Example** (Conditionally updating and returning the previous value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only update if value is greater than 3
    *   const previous1 = yield* Ref.getAndUpdateSome(
    *     counter,
    *     (n) => n > 3 ? Option.some(n * 2) : Option.none()
    *   )
-   *   console.log(previous1) // 5
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 10
-   *
-   *   // Try to update again (won't update since 10 > 3 is true but let's say condition is n < 3)
    *   const previous2 = yield* Ref.getAndUpdateSome(
    *     counter,
    *     (n) => n < 3 ? Option.some(n * 2) : Option.none()
    *   )
-   *   console.log(previous2) // 10
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 10 (unchanged)
+   *   return [previous1, current1, previous2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 10, 10, 10]
    * ```
    *
    * @see {@link getAndUpdate} for always applying an update
@@ -688,28 +652,24 @@ export const getAndUpdateSome = dual<
  *
  * **Example** (Setting and returning the new value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const ref = yield* Ref.make(10)
  *
- *   // Set new value and get it back in one operation
  *   const newValue = yield* Ref.setAndGet(ref, 42)
- *   console.log(newValue) // 42
- *
- *   // Verify the ref contains the new value
  *   const current = yield* Ref.get(ref)
- *   console.log(current) // 42
+ *   return [newValue, current]
  * })
  *
- * // Useful for sequential operations
  * const program2 = Effect.gen(function*() {
  *   const counter = yield* Ref.make(0)
- *
- *   const newValue = yield* Ref.setAndGet(counter, 20)
- *   console.log(newValue) // 20
+ *   return yield* Ref.setAndGet(counter, 20)
  * })
+ *
+ * await Effect.runPromise(program) // => [42, 42]
+ * await Effect.runPromise(program2) // => 20
  * ```
  *
  * @category mutations
@@ -726,28 +686,24 @@ export const setAndGet = dual<
    *
    * **Example** (Setting and returning the new value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make(10)
    *
-   *   // Set new value and get it back in one operation
    *   const newValue = yield* Ref.setAndGet(ref, 42)
-   *   console.log(newValue) // 42
-   *
-   *   // Verify the ref contains the new value
    *   const current = yield* Ref.get(ref)
-   *   console.log(current) // 42
+   *   return [newValue, current]
    * })
    *
-   * // Useful for sequential operations
    * const program2 = Effect.gen(function*() {
    *   const counter = yield* Ref.make(0)
-   *
-   *   const newValue = yield* Ref.setAndGet(counter, 20)
-   *   console.log(newValue) // 20
+   *   return yield* Ref.setAndGet(counter, 20)
    * })
+   *
+   * await Effect.runPromise(program) // => [42, 42]
+   * await Effect.runPromise(program2) // => 20
    * ```
    *
    * @category mutations
@@ -764,28 +720,24 @@ export const setAndGet = dual<
    *
    * **Example** (Setting and returning the new value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const ref = yield* Ref.make(10)
    *
-   *   // Set new value and get it back in one operation
    *   const newValue = yield* Ref.setAndGet(ref, 42)
-   *   console.log(newValue) // 42
-   *
-   *   // Verify the ref contains the new value
    *   const current = yield* Ref.get(ref)
-   *   console.log(current) // 42
+   *   return [newValue, current]
    * })
    *
-   * // Useful for sequential operations
    * const program2 = Effect.gen(function*() {
    *   const counter = yield* Ref.make(0)
-   *
-   *   const newValue = yield* Ref.setAndGet(counter, 20)
-   *   console.log(newValue) // 20
+   *   return yield* Ref.setAndGet(counter, 20)
    * })
+   *
+   * await Effect.runPromise(program) // => [42, 42]
+   * await Effect.runPromise(program2) // => 20
    * ```
    *
    * @category mutations
@@ -810,41 +762,36 @@ export const setAndGet = dual<
  *
  * **Example** (Modifying a value atomically)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(10)
  *
- *   // Modify the ref and return some computation result
  *   const result = yield* Ref.modify(counter, (n) => [
- *     `Previous value was ${n}`, // Return value
- *     n * 2 // New ref value
+ *     `Previous value was ${n}`,
+ *     n * 2
  *   ])
- *
- *   console.log(result) // "Previous value was 10"
- *
  *   const current = yield* Ref.get(counter)
- *   console.log(current) // 20
+ *   return [result, current]
  * })
  *
- * // Example with more complex computation
  * const program2 = Effect.gen(function*() {
  *   const state = yield* Ref.make({ count: 0, total: 0 })
- *
- *   const incremented = yield* Ref.modify(state, (s) => [
- *     s.count, // Return previous count
- *     { count: s.count + 1, total: s.total + s.count + 1 } // New state
+ *   return yield* Ref.modify(state, (s) => [
+ *     s.count,
+ *     { count: s.count + 1, total: s.total + s.count + 1 }
  *   ])
- *
- *   console.log(incremented) // 0
  * })
+ *
+ * await Effect.runPromise(program) // => ["Previous value was 10", 20]
+ * await Effect.runPromise(program2) // => 0
  * ```
  *
  * @see {@link updateAndGet} for returning the new stored value
  * @see {@link modifySome} for optionally updating while returning a separate result
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const modify = dual<
@@ -864,41 +811,36 @@ export const modify = dual<
    *
    * **Example** (Modifying a value atomically)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Modify the ref and return some computation result
    *   const result = yield* Ref.modify(counter, (n) => [
-   *     `Previous value was ${n}`, // Return value
-   *     n * 2 // New ref value
+   *     `Previous value was ${n}`,
+   *     n * 2
    *   ])
-   *
-   *   console.log(result) // "Previous value was 10"
-   *
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 20
+   *   return [result, current]
    * })
    *
-   * // Example with more complex computation
    * const program2 = Effect.gen(function*() {
    *   const state = yield* Ref.make({ count: 0, total: 0 })
-   *
-   *   const incremented = yield* Ref.modify(state, (s) => [
-   *     s.count, // Return previous count
-   *     { count: s.count + 1, total: s.total + s.count + 1 } // New state
+   *   return yield* Ref.modify(state, (s) => [
+   *     s.count,
+   *     { count: s.count + 1, total: s.total + s.count + 1 }
    *   ])
-   *
-   *   console.log(incremented) // 0
    * })
+   *
+   * await Effect.runPromise(program) // => ["Previous value was 10", 20]
+   * await Effect.runPromise(program2) // => 0
    * ```
    *
    * @see {@link updateAndGet} for returning the new stored value
    * @see {@link modifySome} for optionally updating while returning a separate result
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, B>(f: (a: A) => readonly [B, A]) => (self: Ref<A>) => Effect.Effect<B>,
@@ -918,41 +860,36 @@ export const modify = dual<
    *
    * **Example** (Modifying a value atomically)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Modify the ref and return some computation result
    *   const result = yield* Ref.modify(counter, (n) => [
-   *     `Previous value was ${n}`, // Return value
-   *     n * 2 // New ref value
+   *     `Previous value was ${n}`,
+   *     n * 2
    *   ])
-   *
-   *   console.log(result) // "Previous value was 10"
-   *
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 20
+   *   return [result, current]
    * })
    *
-   * // Example with more complex computation
    * const program2 = Effect.gen(function*() {
    *   const state = yield* Ref.make({ count: 0, total: 0 })
-   *
-   *   const incremented = yield* Ref.modify(state, (s) => [
-   *     s.count, // Return previous count
-   *     { count: s.count + 1, total: s.total + s.count + 1 } // New state
+   *   return yield* Ref.modify(state, (s) => [
+   *     s.count,
+   *     { count: s.count + 1, total: s.total + s.count + 1 }
    *   ])
-   *
-   *   console.log(incremented) // 0
    * })
+   *
+   * await Effect.runPromise(program) // => ["Previous value was 10", 20]
+   * await Effect.runPromise(program2) // => 0
    * ```
    *
    * @see {@link updateAndGet} for returning the new stored value
    * @see {@link modifySome} for optionally updating while returning a separate result
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, B>(self: Ref<A>, f: (a: A) => readonly [B, A]) => Effect.Effect<B>
@@ -979,13 +916,12 @@ export const modify = dual<
  *
  * **Example** (Conditionally modifying a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *
- *   // Only modify if value is greater than 3
  *   const result1 = yield* Ref.modifySome(
  *     counter,
  *     (n) =>
@@ -993,13 +929,7 @@ export const modify = dual<
  *         ? [`incremented ${n}`, Option.some(n + 10)]
  *         : ["no change", Option.none()]
  *   )
- *
- *   console.log(result1) // "incremented 5"
- *
  *   const current1 = yield* Ref.get(counter)
- *   console.log(current1) // 15
- *
- *   // Try to modify with a condition that fails
  *   const result2 = yield* Ref.modifySome(
  *     counter,
  *     (n) =>
@@ -1007,18 +937,17 @@ export const modify = dual<
  *         ? [`decremented ${n}`, Option.some(n - 5)]
  *         : ["no change", Option.none()]
  *   )
- *
- *   console.log(result2) // "no change"
- *
  *   const current2 = yield* Ref.get(counter)
- *   console.log(current2) // 15 (unchanged)
+ *   return [result1, current1, result2, current2]
  * })
+ *
+ * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
  * ```
  *
  * @see {@link modify} for always storing a new value
  * @see {@link updateSome} for optional updates without a separate return value
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const modifySome: {
@@ -1038,13 +967,12 @@ export const modifySome: {
    *
    * **Example** (Conditionally modifying a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only modify if value is greater than 3
    *   const result1 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1052,13 +980,7 @@ export const modifySome: {
    *         ? [`incremented ${n}`, Option.some(n + 10)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result1) // "incremented 5"
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 15
-   *
-   *   // Try to modify with a condition that fails
    *   const result2 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1066,18 +988,17 @@ export const modifySome: {
    *         ? [`decremented ${n}`, Option.some(n - 5)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result2) // "no change"
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 15 (unchanged)
+   *   return [result1, current1, result2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
    * ```
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]): (self: Ref<A>) => Effect.Effect<B>
@@ -1097,13 +1018,12 @@ export const modifySome: {
    *
    * **Example** (Conditionally modifying a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only modify if value is greater than 3
    *   const result1 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1111,13 +1031,7 @@ export const modifySome: {
    *         ? [`incremented ${n}`, Option.some(n + 10)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result1) // "incremented 5"
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 15
-   *
-   *   // Try to modify with a condition that fails
    *   const result2 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1125,18 +1039,17 @@ export const modifySome: {
    *         ? [`decremented ${n}`, Option.some(n - 5)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result2) // "no change"
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 15 (unchanged)
+   *   return [result1, current1, result2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
    * ```
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
@@ -1157,13 +1070,12 @@ export const modifySome: {
    *
    * **Example** (Conditionally modifying a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only modify if value is greater than 3
    *   const result1 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1171,13 +1083,7 @@ export const modifySome: {
    *         ? [`incremented ${n}`, Option.some(n + 10)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result1) // "incremented 5"
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 15
-   *
-   *   // Try to modify with a condition that fails
    *   const result2 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1185,18 +1091,17 @@ export const modifySome: {
    *         ? [`decremented ${n}`, Option.some(n - 5)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result2) // "no change"
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 15 (unchanged)
+   *   return [result1, current1, result2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
    * ```
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]) => (self: Ref<A>) => Effect.Effect<B>,
@@ -1216,13 +1121,12 @@ export const modifySome: {
    *
    * **Example** (Conditionally modifying a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only modify if value is greater than 3
    *   const result1 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1230,13 +1134,7 @@ export const modifySome: {
    *         ? [`incremented ${n}`, Option.some(n + 10)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result1) // "incremented 5"
-   *
    *   const current1 = yield* Ref.get(counter)
-   *   console.log(current1) // 15
-   *
-   *   // Try to modify with a condition that fails
    *   const result2 = yield* Ref.modifySome(
    *     counter,
    *     (n) =>
@@ -1244,18 +1142,17 @@ export const modifySome: {
    *         ? [`decremented ${n}`, Option.some(n - 5)]
    *         : ["no change", Option.none()]
    *   )
-   *
-   *   console.log(result2) // "no change"
-   *
    *   const current2 = yield* Ref.get(counter)
-   *   console.log(current2) // 15 (unchanged)
+   *   return [result1, current1, result2, current2]
    * })
+   *
+   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
    * ```
    *
    * @see {@link modify} for always storing a new value
    * @see {@link updateSome} for optional updates without a separate return value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]) => Effect.Effect<B>
@@ -1274,32 +1171,30 @@ export const modifySome: {
  *
  * **Example** (Updating a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *
- *   // Update the value
  *   yield* Ref.update(counter, (n) => n * 2)
- *
- *   const value = yield* Ref.get(counter)
- *   console.log(value) // 10
+ *   return yield* Ref.get(counter)
  * })
  *
- * // Using multiple operations
  * const program2 = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *   yield* Ref.update(counter, (n: number) => n + 10)
- *   const value = yield* Ref.get(counter)
- *   console.log(value) // 15
+ *   return yield* Ref.get(counter)
  * })
+ *
+ * await Effect.runPromise(program) // => 10
+ * await Effect.runPromise(program2) // => 15
  * ```
  *
  * @see {@link updateAndGet} for returning the new value
  * @see {@link getAndUpdate} for returning the previous value
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const update = dual<
@@ -1312,32 +1207,30 @@ export const update = dual<
    *
    * **Example** (Updating a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Update the value
    *   yield* Ref.update(counter, (n) => n * 2)
-   *
-   *   const value = yield* Ref.get(counter)
-   *   console.log(value) // 10
+   *   return yield* Ref.get(counter)
    * })
    *
-   * // Using multiple operations
    * const program2 = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *   yield* Ref.update(counter, (n: number) => n + 10)
-   *   const value = yield* Ref.get(counter)
-   *   console.log(value) // 15
+   *   return yield* Ref.get(counter)
    * })
+   *
+   * await Effect.runPromise(program) // => 10
+   * await Effect.runPromise(program2) // => 15
    * ```
    *
    * @see {@link updateAndGet} for returning the new value
    * @see {@link getAndUpdate} for returning the previous value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(f: (a: A) => A) => (self: Ref<A>) => Effect.Effect<void>,
@@ -1350,32 +1243,30 @@ export const update = dual<
    *
    * **Example** (Updating a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Update the value
    *   yield* Ref.update(counter, (n) => n * 2)
-   *
-   *   const value = yield* Ref.get(counter)
-   *   console.log(value) // 10
+   *   return yield* Ref.get(counter)
    * })
    *
-   * // Using multiple operations
    * const program2 = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *   yield* Ref.update(counter, (n: number) => n + 10)
-   *   const value = yield* Ref.get(counter)
-   *   console.log(value) // 15
+   *   return yield* Ref.get(counter)
    * })
+   *
+   * await Effect.runPromise(program) // => 10
+   * await Effect.runPromise(program2) // => 15
    * ```
    *
    * @see {@link updateAndGet} for returning the new value
    * @see {@link getAndUpdate} for returning the previous value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => A) => Effect.Effect<void>
@@ -1393,20 +1284,18 @@ export const update = dual<
  *
  * **Example** (Updating and returning the new value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *
- *   // Update and get the new value in one operation
  *   const newValue = yield* Ref.updateAndGet(counter, (n) => n * 3)
- *   console.log(newValue) // 15
- *
- *   // Verify the ref contains the new value
  *   const current = yield* Ref.get(counter)
- *   console.log(current) // 15
+ *   return [newValue, current]
  * })
+ *
+ * await Effect.runPromise(program) // => [15, 15]
  * ```
  *
  * @see {@link update} for updating without returning the new value
@@ -1425,20 +1314,18 @@ export const updateAndGet = dual<
    *
    * **Example** (Updating and returning the new value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Update and get the new value in one operation
    *   const newValue = yield* Ref.updateAndGet(counter, (n) => n * 3)
-   *   console.log(newValue) // 15
-   *
-   *   // Verify the ref contains the new value
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 15
+   *   return [newValue, current]
    * })
+   *
+   * await Effect.runPromise(program) // => [15, 15]
    * ```
    *
    * @see {@link update} for updating without returning the new value
@@ -1457,20 +1344,18 @@ export const updateAndGet = dual<
    *
    * **Example** (Updating and returning the new value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Update and get the new value in one operation
    *   const newValue = yield* Ref.updateAndGet(counter, (n) => n * 3)
-   *   console.log(newValue) // 15
-   *
-   *   // Verify the ref contains the new value
    *   const current = yield* Ref.get(counter)
-   *   console.log(current) // 15
+   *   return [newValue, current]
    * })
+   *
+   * await Effect.runPromise(program) // => [15, 15]
    * ```
    *
    * @see {@link update} for updating without returning the new value
@@ -1496,37 +1381,33 @@ export const updateAndGet = dual<
  *
  * **Example** (Conditionally updating a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(5)
  *
- *   // Only update if value is even
  *   yield* Ref.updateSome(
  *     counter,
  *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
  *   )
- *
- *   let current = yield* Ref.get(counter)
- *   console.log(current) // 5 (unchanged because 5 is odd)
- *
- *   // Set to even number and try again
+ *   const before = yield* Ref.get(counter)
  *   yield* Ref.set(counter, 6)
  *   yield* Ref.updateSome(
  *     counter,
  *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
  *   )
- *
- *   current = yield* Ref.get(counter)
- *   console.log(current) // 12 (updated because 6 is even)
+ *   const after = yield* Ref.get(counter)
+ *   return [before, after]
  * })
+ *
+ * await Effect.runPromise(program) // => [5, 12]
  * ```
  *
  * @see {@link update} for always applying an update
  * @see {@link updateSomeAndGet} for returning the resulting current value
  *
- * @category setters
+ * @category mutations
  * @since 2.0.0
  */
 export const updateSome = dual<
@@ -1544,37 +1425,33 @@ export const updateSome = dual<
    *
    * **Example** (Conditionally updating a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only update if value is even
    *   yield* Ref.updateSome(
    *     counter,
    *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
    *   )
-   *
-   *   let current = yield* Ref.get(counter)
-   *   console.log(current) // 5 (unchanged because 5 is odd)
-   *
-   *   // Set to even number and try again
+   *   const before = yield* Ref.get(counter)
    *   yield* Ref.set(counter, 6)
    *   yield* Ref.updateSome(
    *     counter,
    *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
    *   )
-   *
-   *   current = yield* Ref.get(counter)
-   *   console.log(current) // 12 (updated because 6 is even)
+   *   const after = yield* Ref.get(counter)
+   *   return [before, after]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 12]
    * ```
    *
    * @see {@link update} for always applying an update
    * @see {@link updateSomeAndGet} for returning the resulting current value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(f: (a: A) => Option.Option<A>) => (self: Ref<A>) => Effect.Effect<void>,
@@ -1592,37 +1469,33 @@ export const updateSome = dual<
    *
    * **Example** (Conditionally updating a value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(5)
    *
-   *   // Only update if value is even
    *   yield* Ref.updateSome(
    *     counter,
    *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
    *   )
-   *
-   *   let current = yield* Ref.get(counter)
-   *   console.log(current) // 5 (unchanged because 5 is odd)
-   *
-   *   // Set to even number and try again
+   *   const before = yield* Ref.get(counter)
    *   yield* Ref.set(counter, 6)
    *   yield* Ref.updateSome(
    *     counter,
    *     (n) => n % 2 === 0 ? Option.some(n * 2) : Option.none()
    *   )
-   *
-   *   current = yield* Ref.get(counter)
-   *   console.log(current) // 12 (updated because 6 is even)
+   *   const after = yield* Ref.get(counter)
+   *   return [before, after]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 12]
    * ```
    *
    * @see {@link update} for always applying an update
    * @see {@link updateSomeAndGet} for returning the resulting current value
    *
-   * @category setters
+   * @category mutations
    * @since 2.0.0
    */
   <A>(self: Ref<A>, f: (a: A) => Option.Option<A>) => Effect.Effect<void>
@@ -1650,26 +1523,24 @@ export const updateSome = dual<
  *
  * **Example** (Conditionally updating and returning the current value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, Ref } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const counter = yield* Ref.make(10)
  *
- *   // Only update if value is greater than 5
  *   const result1 = yield* Ref.updateSomeAndGet(
  *     counter,
  *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
  *   )
- *   console.log(result1) // 5 (updated and returned)
- *
- *   // Try to update again with same condition
  *   const result2 = yield* Ref.updateSomeAndGet(
  *     counter,
  *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
  *   )
- *   console.log(result2) // 5 (unchanged because 5 is not > 5)
+ *   return [result1, result2]
  * })
+ *
+ * await Effect.runPromise(program) // => [5, 5]
  * ```
  *
  * @see {@link updateSome} for conditional updates without returning a value
@@ -1695,26 +1566,24 @@ export const updateSomeAndGet = dual<
    *
    * **Example** (Conditionally updating and returning the current value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Only update if value is greater than 5
    *   const result1 = yield* Ref.updateSomeAndGet(
    *     counter,
    *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
    *   )
-   *   console.log(result1) // 5 (updated and returned)
-   *
-   *   // Try to update again with same condition
    *   const result2 = yield* Ref.updateSomeAndGet(
    *     counter,
    *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
    *   )
-   *   console.log(result2) // 5 (unchanged because 5 is not > 5)
+   *   return [result1, result2]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 5]
    * ```
    *
    * @see {@link updateSome} for conditional updates without returning a value
@@ -1740,26 +1609,24 @@ export const updateSomeAndGet = dual<
    *
    * **Example** (Conditionally updating and returning the current value)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Option, Ref } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const counter = yield* Ref.make(10)
    *
-   *   // Only update if value is greater than 5
    *   const result1 = yield* Ref.updateSomeAndGet(
    *     counter,
    *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
    *   )
-   *   console.log(result1) // 5 (updated and returned)
-   *
-   *   // Try to update again with same condition
    *   const result2 = yield* Ref.updateSomeAndGet(
    *     counter,
    *     (n) => n > 5 ? Option.some(n / 2) : Option.none()
    *   )
-   *   console.log(result2) // 5 (unchanged because 5 is not > 5)
+   *   return [result1, result2]
    * })
+   *
+   * await Effect.runPromise(program) // => [5, 5]
    * ```
    *
    * @see {@link updateSome} for conditional updates without returning a value
@@ -1792,18 +1659,11 @@ export const updateSomeAndGet = dual<
  *
  * **Example** (Reading a ref unsafely)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Ref } from "effect"
  *
- * // Create a ref directly
  * const counter = Ref.makeUnsafe(42)
- *
- * // Get the value synchronously
- * const value = Ref.getUnsafe(counter)
- * console.log(value) // 42
- *
- * // Note: This is unsafe and should be used carefully
- * // Prefer Ref.get for Effect-wrapped access
+ * Ref.getUnsafe(counter) // => 42
  * ```
  *
  * @category getters