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

package/dist/MutableRef.js

@@ -33,21 +33,24 @@ const MutableRefProto = {
  *
  * **Example** (Creating mutable refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * // Create a counter reference
  * const counter = MutableRef.make(0)
- * console.log(MutableRef.get(counter)) // 0
+ *
+ * MutableRef.get(counter) // => 0
  *
  * // Create a configuration reference
  * const config = MutableRef.make({ debug: false, timeout: 5000 })
- * console.log(MutableRef.get(config)) // { debug: false, timeout: 5000 }
+ *
+ * MutableRef.get(config) // => { debug: false, timeout: 5000 }
  *
  * // Create a string reference
  * const status = MutableRef.make("idle")
  * MutableRef.set(status, "running")
- * console.log(MutableRef.get(status)) // "running"
+ *
+ * MutableRef.get(status) // => "running"
  * ```
  *
  * @category constructors
@@ -70,20 +73,22 @@ export const make = value => {
  *
  * **Example** (Comparing and setting values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const ref = MutableRef.make("initial")
  *
  * // Successful compare and set
  * const updated = MutableRef.compareAndSet(ref, "initial", "updated")
- * console.log(updated) // true
- * console.log(MutableRef.get(ref)) // "updated"
+ *
+ * updated // => true
+ * MutableRef.get(ref) // => "updated"
  *
  * // Failed compare and set (value doesn't match)
  * const failed = MutableRef.compareAndSet(ref, "initial", "failed")
- * console.log(failed) // false
- * console.log(MutableRef.get(ref)) // "updated" (unchanged)
+ *
+ * failed // => false
+ * MutableRef.get(ref) // => "updated"
  *
  * // Thread-safe counter increment
  * const counter = MutableRef.make(5)
@@ -92,12 +97,16 @@ export const make = value => {
  *   current = MutableRef.get(counter)
  * } while (!MutableRef.compareAndSet(counter, current, current + 1))
  *
+ * MutableRef.get(counter) // => 6
+ *
  * // Pipe-able version
  * const casUpdate = MutableRef.compareAndSet("updated", "final")
- * console.log(casUpdate(ref)) // true
+ *
+ * casUpdate(ref) // => true
+ * MutableRef.get(ref) // => "final"
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue) => {
@@ -117,29 +126,32 @@ export const compareAndSet = /*#__PURE__*/Dual.dual(3, (self, oldValue, newValue
  *
  * **Example** (Decrementing numeric refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Decrement the counter
  * MutableRef.decrement(counter)
- * console.log(MutableRef.get(counter)) // 4
+ *
+ * MutableRef.get(counter) // => 4
  *
  * // Chain operations
  * MutableRef.decrement(counter)
  * MutableRef.decrement(counter)
- * console.log(MutableRef.get(counter)) // 2
+ *
+ * MutableRef.get(counter) // => 2
  *
  * // Useful for countdown scenarios
  * const countdown = MutableRef.make(10)
  * while (MutableRef.get(countdown) > 0) {
- *   console.log(MutableRef.get(countdown))
  *   MutableRef.decrement(countdown)
  * }
+ *
+ * MutableRef.get(countdown) // => 0
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const decrement = self => update(self, n => n - 1);
@@ -153,29 +165,35 @@ export const decrement = self => update(self, n => n - 1);
  *
  * **Example** (Decrementing and reading refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Decrement and get the new value
  * const newValue = MutableRef.decrementAndGet(counter)
- * console.log(newValue) // 4
- * console.log(MutableRef.get(counter)) // 4
+ *
+ * newValue // => 4
+ * MutableRef.get(counter) // => 4
  *
  * // Use in expressions
  * const lives = MutableRef.make(3)
- * console.log(`Lives remaining: ${MutableRef.decrementAndGet(lives)}`) // "Lives remaining: 2"
+ * const message = `Lives remaining: ${MutableRef.decrementAndGet(lives)}`
+ *
+ * message // => "Lives remaining: 2"
  *
  * // Conditional logic based on decremented value
  * const attempts = MutableRef.make(3)
+ * let retries = 0
  * while (MutableRef.decrementAndGet(attempts) >= 0) {
- *   console.log("Retrying...")
- *   // retry logic
+ *   retries += 1
  * }
+ *
+ * retries // => 3
+ * MutableRef.get(attempts) // => -1
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const decrementAndGet = self => updateAndGet(self, n => n - 1);
@@ -188,27 +206,31 @@ export const decrementAndGet = self => updateAndGet(self, n => n - 1);
  *
  * **Example** (Reading current values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const ref = MutableRef.make("hello")
- * console.log(MutableRef.get(ref)) // "hello"
+ *
+ * MutableRef.get(ref) // => "hello"
  *
  * MutableRef.set(ref, "world")
- * console.log(MutableRef.get(ref)) // "world"
+ *
+ * MutableRef.get(ref) // => "world"
  *
  * // Reading complex objects
  * const config = MutableRef.make({ port: 3000, host: "localhost" })
  * const currentConfig = MutableRef.get(config)
- * console.log(currentConfig.port) // 3000
+ *
+ * currentConfig // => { port: 3000, host: "localhost" }
  *
  * // Multiple reads return the same value
  * const value1 = MutableRef.get(ref)
  * const value2 = MutableRef.get(ref)
- * console.log(value1 === value2) // true
+ *
+ * value1 === value2 // => true
  * ```
  *
- * @category general
+ * @category getters
  * @since 2.0.0
  */
 export const get = self => self.current;
@@ -221,30 +243,38 @@ export const get = self => self.current;
  *
  * **Example** (Reading before decrementing)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Get current value and then decrement
  * const previousValue = MutableRef.getAndDecrement(counter)
- * console.log(previousValue) // 5
- * console.log(MutableRef.get(counter)) // 4
+ *
+ * previousValue // => 5
+ * MutableRef.get(counter) // => 4
  *
  * // Useful for processing where you need the original value
  * const itemsLeft = MutableRef.make(10)
+ * const processedItems: Array<number> = []
  * while (MutableRef.get(itemsLeft) > 0) {
  *   const currentItem = MutableRef.getAndDecrement(itemsLeft)
- *   console.log(`Processing item ${currentItem}`)
+ *   processedItems.push(currentItem)
  * }
  *
+ * processedItems // => [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
+ * MutableRef.get(itemsLeft) // => 0
+ *
  * // Post-decrement semantics (like i-- in other languages)
  * const index = MutableRef.make(3)
  * const currentIndex = MutableRef.getAndDecrement(index)
- * console.log(`Current: ${currentIndex}, Next: ${MutableRef.get(index)}`) // "Current: 3, Next: 2"
+ * const nextIndex = MutableRef.get(index)
+ *
+ * currentIndex // => 3
+ * nextIndex // => 2
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndDecrement = self => getAndUpdate(self, n => n - 1);
@@ -257,38 +287,45 @@ export const getAndDecrement = self => getAndUpdate(self, n => n - 1);
  *
  * **Example** (Reading before incrementing)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Get current value and then increment
  * const previousValue = MutableRef.getAndIncrement(counter)
- * console.log(previousValue) // 5
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * previousValue // => 5
+ * MutableRef.get(counter) // => 6
  *
  * // Useful for ID generation
  * const idGenerator = MutableRef.make(0)
  * const getId = () => MutableRef.getAndIncrement(idGenerator)
+ * const ids = [getId(), getId(), getId()]
  *
- * console.log(getId()) // 0
- * console.log(getId()) // 1
- * console.log(getId()) // 2
+ * ids // => [0, 1, 2]
  *
  * // Post-increment semantics (like i++ in other languages)
  * const position = MutableRef.make(0)
  * const currentPos = MutableRef.getAndIncrement(position)
- * console.log(`Was at: ${currentPos}, Now at: ${MutableRef.get(position)}`) // "Was at: 0, Now at: 1"
+ * const nextPos = MutableRef.get(position)
+ *
+ * currentPos // => 0
+ * nextPos // => 1
  *
  * // Useful for iteration counters
  * const iterations = MutableRef.make(0)
+ * const visited: Array<number> = []
  * while (MutableRef.get(iterations) < 5) {
  *   const iteration = MutableRef.getAndIncrement(iterations)
- *   console.log(`Iteration ${iteration}`)
+ *   visited.push(iteration)
  * }
+ *
+ * visited // => [0, 1, 2, 3, 4]
+ * MutableRef.get(iterations) // => 5
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndIncrement = self => getAndUpdate(self, n => n + 1);
@@ -302,34 +339,41 @@ export const getAndIncrement = self => getAndUpdate(self, n => n + 1);
  *
  * **Example** (Reading before setting)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const ref = MutableRef.make("old")
  *
  * // Set new value and get the previous one
  * const previous = MutableRef.getAndSet(ref, "new")
- * console.log(previous) // "old"
- * console.log(MutableRef.get(ref)) // "new"
+ *
+ * previous // => "old"
+ * MutableRef.get(ref) // => "new"
  *
  * // Swapping values
  * const counter = MutableRef.make(5)
  * const oldValue = MutableRef.getAndSet(counter, 10)
- * console.log(`Changed from ${oldValue} to ${MutableRef.get(counter)}`) // "Changed from 5 to 10"
+ * const newValue = MutableRef.get(counter)
+ *
+ * oldValue // => 5
+ * newValue // => 10
  *
  * // Pipe-able version
  * const setValue = MutableRef.getAndSet("final")
  * const previousValue = setValue(ref)
- * console.log(previousValue) // "new"
+ *
+ * previousValue // => "new"
+ * MutableRef.get(ref) // => "final"
  *
  * // Useful for atomic swaps in algorithms
  * const buffer = MutableRef.make<Array<string>>(["a", "b", "c"])
  * const oldBuffer = MutableRef.getAndSet(buffer, [])
- * console.log(oldBuffer) // ["a", "b", "c"]
- * console.log(MutableRef.get(buffer)) // []
+ *
+ * oldBuffer // => ["a", "b", "c"]
+ * MutableRef.get(buffer) // => []
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
@@ -348,40 +392,46 @@ export const getAndSet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  *
  * **Example** (Reading before updating)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Increment and get the old value
  * const oldValue = MutableRef.getAndUpdate(counter, (n) => n + 1)
- * console.log(oldValue) // 5
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * oldValue // => 5
+ * MutableRef.get(counter) // => 6
  *
  * // Double the value and get the previous one
  * const previous = MutableRef.getAndUpdate(counter, (n) => n * 2)
- * console.log(previous) // 6
- * console.log(MutableRef.get(counter)) // 12
+ *
+ * previous // => 6
+ * MutableRef.get(counter) // => 12
  *
  * // Transform string and get old value
  * const message = MutableRef.make("hello")
  * const oldMessage = MutableRef.getAndUpdate(message, (s) => s.toUpperCase())
- * console.log(oldMessage) // "hello"
- * console.log(MutableRef.get(message)) // "HELLO"
+ *
+ * oldMessage // => "hello"
+ * MutableRef.get(message) // => "HELLO"
  *
  * // Pipe-able version
  * const addOne = MutableRef.getAndUpdate((n: number) => n + 1)
  * const result = addOne(counter)
- * console.log(result) // Previous value before increment
+ *
+ * result // => 12
+ * MutableRef.get(counter) // => 13
  *
  * // Useful for implementing atomic operations
  * const list = MutableRef.make<Array<number>>([1, 2, 3])
  * const oldList = MutableRef.getAndUpdate(list, (arr) => [...arr, 4])
- * console.log(oldList) // [1, 2, 3]
- * console.log(MutableRef.get(list)) // [1, 2, 3, 4]
+ *
+ * oldList // => [1, 2, 3]
+ * MutableRef.get(list) // => [1, 2, 3, 4]
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const getAndUpdate = /*#__PURE__*/Dual.dual(2, (self, f) => getAndSet(self, f(get(self))));
@@ -395,32 +445,37 @@ export const getAndUpdate = /*#__PURE__*/Dual.dual(2, (self, f) => getAndSet(sel
  *
  * **Example** (Incrementing numeric refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Increment the counter
  * MutableRef.increment(counter)
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * MutableRef.get(counter) // => 6
  *
  * // Chain operations
  * MutableRef.increment(counter)
  * MutableRef.increment(counter)
- * console.log(MutableRef.get(counter)) // 8
+ *
+ * MutableRef.get(counter) // => 8
  *
  * // Useful for simple counting
  * const visits = MutableRef.make(0)
  * MutableRef.increment(visits) // User visited
  * MutableRef.increment(visits) // Another visit
- * console.log(MutableRef.get(visits)) // 2
+ *
+ * MutableRef.get(visits) // => 2
  *
  * // Returns the reference for chaining
  * const result = MutableRef.increment(counter)
- * console.log(result === counter) // true
+ *
+ * result === counter // => true
+ * MutableRef.get(counter) // => 9
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const increment = self => update(self, n => n + 1);
@@ -434,33 +489,38 @@ export const increment = self => update(self, n => n + 1);
  *
  * **Example** (Incrementing and reading refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Increment and get the new value
  * const newValue = MutableRef.incrementAndGet(counter)
- * console.log(newValue) // 6
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * newValue // => 6
+ * MutableRef.get(counter) // => 6
  *
  * // Use in expressions
  * const score = MutableRef.make(100)
- * console.log(`New score: ${MutableRef.incrementAndGet(score)}`) // "New score: 101"
+ * const message = `New score: ${MutableRef.incrementAndGet(score)}`
+ *
+ * message // => "New score: 101"
  *
  * // Pre-increment semantics (like ++i in other languages)
  * const level = MutableRef.make(0)
  * const nextLevel = MutableRef.incrementAndGet(level)
- * console.log(`Reached level ${nextLevel}`) // "Reached level 1"
+ *
+ * nextLevel // => 1
  *
  * // Conditional logic based on incremented value
  * const attempts = MutableRef.make(0)
- * if (MutableRef.incrementAndGet(attempts) > 3) {
- *   console.log("Too many attempts")
- * }
+ * const tooManyAttempts = MutableRef.incrementAndGet(attempts) > 3
+ *
+ * tooManyAttempts // => false
+ * MutableRef.get(attempts) // => 1
  * ```
  *
- * @category numeric
+ * @category mutations
  * @since 2.0.0
  */
 export const incrementAndGet = self => updateAndGet(self, n => n + 1);
@@ -474,38 +534,44 @@ export const incrementAndGet = self => updateAndGet(self, n => n + 1);
  *
  * **Example** (Setting values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const ref = MutableRef.make("initial")
  *
  * // Set a new value
  * MutableRef.set(ref, "updated")
- * console.log(MutableRef.get(ref)) // "updated"
+ *
+ * MutableRef.get(ref) // => "updated"
  *
  * // Chain set operations (since it returns the ref)
  * const result = MutableRef.set(ref, "final")
- * console.log(result === ref) // true (same reference)
- * console.log(MutableRef.get(ref)) // "final"
+ *
+ * result === ref // => true
+ * MutableRef.get(ref) // => "final"
  *
  * // Set complex objects
  * const config = MutableRef.make({ debug: false, verbose: false })
  * MutableRef.set(config, { debug: true, verbose: true })
- * console.log(MutableRef.get(config)) // { debug: true, verbose: true }
+ *
+ * MutableRef.get(config) // => { debug: true, verbose: true }
  *
  * // Pipe-able version
  * const setValue = MutableRef.set("new value")
  * setValue(ref)
- * console.log(MutableRef.get(ref)) // "new value"
+ *
+ * MutableRef.get(ref) // => "new value"
  *
  * // Useful for state management
  * const state = MutableRef.make<"idle" | "loading" | "success" | "error">("idle")
  * MutableRef.set(state, "loading")
  * // ... perform async operation
  * MutableRef.set(state, "success")
+ *
+ * MutableRef.get(state) // => "success"
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
@@ -522,34 +588,40 @@ export const set = /*#__PURE__*/Dual.dual(2, (self, value) => {
  *
  * **Example** (Setting and reading values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const ref = MutableRef.make("old")
  *
  * // Set and get the new value
  * const newValue = MutableRef.setAndGet(ref, "new")
- * console.log(newValue) // "new"
- * console.log(MutableRef.get(ref)) // "new"
+ *
+ * newValue // => "new"
+ * MutableRef.get(ref) // => "new"
  *
  * // Useful for assignments that need the value
  * const counter = MutableRef.make(0)
  * const currentValue = MutableRef.setAndGet(counter, 42)
- * console.log(`Counter set to: ${currentValue}`) // "Counter set to: 42"
+ *
+ * currentValue // => 42
  *
  * // Pipe-able version
  * const setValue = MutableRef.setAndGet("final")
  * const result = setValue(ref)
- * console.log(result) // "final"
+ *
+ * result // => "final"
  *
  * // Difference from set: returns value instead of reference
  * const ref1 = MutableRef.make(1)
  * const returnedRef = MutableRef.set(ref1, 2) // Returns MutableRef
  * const returnedValue = MutableRef.setAndGet(ref1, 3) // Returns value
- * console.log(returnedValue) // 3
+ *
+ * returnedRef === ref1 // => true
+ * returnedValue // => 3
+ * MutableRef.get(ref1) // => 3
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
@@ -567,42 +639,48 @@ export const setAndGet = /*#__PURE__*/Dual.dual(2, (self, value) => {
  *
  * **Example** (Updating values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Increment the counter
  * MutableRef.update(counter, (n) => n + 1)
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * MutableRef.get(counter) // => 6
  *
  * // Chain updates (since it returns the ref)
  * const result = MutableRef.update(counter, (n) => n * 2)
- * console.log(result === counter) // true (same reference)
- * console.log(MutableRef.get(counter)) // 12
+ *
+ * result === counter // => true
+ * MutableRef.get(counter) // => 12
  *
  * // Transform string
  * const message = MutableRef.make("hello")
  * MutableRef.update(message, (s) => s.toUpperCase())
- * console.log(MutableRef.get(message)) // "HELLO"
+ *
+ * MutableRef.get(message) // => "HELLO"
  *
  * // Update complex objects
  * const user = MutableRef.make({ name: "Alice", age: 30 })
  * MutableRef.update(user, (u) => ({ ...u, age: u.age + 1 }))
- * console.log(MutableRef.get(user)) // { name: "Alice", age: 31 }
+ *
+ * MutableRef.get(user) // => { name: "Alice", age: 31 }
  *
  * // Pipe-able version
  * const double = MutableRef.update((n: number) => n * 2)
  * double(counter)
- * console.log(MutableRef.get(counter)) // 24
+ *
+ * MutableRef.get(counter) // => 24
  *
  * // Array operations
  * const list = MutableRef.make<Array<number>>([1, 2, 3])
  * MutableRef.update(list, (arr) => [...arr, 4])
- * console.log(MutableRef.get(list)) // [1, 2, 3, 4]
+ *
+ * MutableRef.get(list) // => [1, 2, 3, 4]
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(self))));
@@ -617,44 +695,50 @@ export const update = /*#__PURE__*/Dual.dual(2, (self, f) => set(self, f(get(sel
  *
  * **Example** (Updating and reading values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const counter = MutableRef.make(5)
  *
  * // Increment and get the new value
  * const newValue = MutableRef.updateAndGet(counter, (n) => n + 1)
- * console.log(newValue) // 6
- * console.log(MutableRef.get(counter)) // 6
+ *
+ * newValue // => 6
+ * MutableRef.get(counter) // => 6
  *
  * // Double the value and get the result
  * const doubled = MutableRef.updateAndGet(counter, (n) => n * 2)
- * console.log(doubled) // 12
+ *
+ * doubled // => 12
  *
  * // Transform string and get result
  * const message = MutableRef.make("hello")
  * const upperCase = MutableRef.updateAndGet(message, (s) => s.toUpperCase())
- * console.log(upperCase) // "HELLO"
+ *
+ * upperCase // => "HELLO"
  *
  * // Pipe-able version
  * const increment = MutableRef.updateAndGet((n: number) => n + 1)
  * const result = increment(counter)
- * console.log(result) // 13 (new value)
+ *
+ * result // => 13
  *
  * // Useful for calculations that need the result
  * const score = MutableRef.make(100)
  * const bonus = 50
  * const newScore = MutableRef.updateAndGet(score, (s) => s + bonus)
- * console.log(`New score: ${newScore}`) // "New score: 150"
+ *
+ * newScore // => 150
  *
  * // Array transformations
  * const list = MutableRef.make<Array<number>>([1, 2, 3])
  * const newList = MutableRef.updateAndGet(list, (arr) => arr.map((x) => x * 2))
- * console.log(newList) // [2, 4, 6]
- * console.log(MutableRef.get(list)) // [2, 4, 6]
+ *
+ * newList // => [2, 4, 6]
+ * MutableRef.get(list) // => [2, 4, 6]
  * ```
  *
- * @category general
+ * @category mutations
  * @since 2.0.0
  */
 export const updateAndGet = /*#__PURE__*/Dual.dual(2, (self, f) => setAndGet(self, f(get(self))));
@@ -669,40 +753,45 @@ export const updateAndGet = /*#__PURE__*/Dual.dual(2, (self, f) => setAndGet(sel
  *
  * **Example** (Toggling boolean refs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { MutableRef } from "effect"
  *
  * const flag = MutableRef.make(false)
  *
  * // Toggle the flag
  * MutableRef.toggle(flag)
- * console.log(MutableRef.get(flag)) // true
+ *
+ * MutableRef.get(flag) // => true
  *
  * // Toggle again
  * MutableRef.toggle(flag)
- * console.log(MutableRef.get(flag)) // false
+ *
+ * MutableRef.get(flag) // => false
  *
  * // Useful for state switches
  * const isVisible = MutableRef.make(true)
  * MutableRef.toggle(isVisible) // Hide
- * console.log(MutableRef.get(isVisible)) // false
+ *
+ * MutableRef.get(isVisible) // => false
  *
  * // Toggle button implementation
  * const darkMode = MutableRef.make(false)
  * const toggleDarkMode = () => {
  *   MutableRef.toggle(darkMode)
- *   console.log(`Dark mode: ${MutableRef.get(darkMode) ? "ON" : "OFF"}`)
+ *   return MutableRef.get(darkMode) ? "ON" : "OFF"
  * }
  *
- * toggleDarkMode() // "Dark mode: ON"
- * toggleDarkMode() // "Dark mode: OFF"
+ * toggleDarkMode() // => "ON"
+ * toggleDarkMode() // => "OFF"
  *
  * // Returns the reference for chaining
  * const result = MutableRef.toggle(flag)
- * console.log(result === flag) // true
+ *
+ * result === flag // => true
+ * MutableRef.get(flag) // => true
  * ```
  *
- * @category boolean
+ * @category mutations
  * @since 2.0.0
  */
 export const toggle = self => update(self, _ => !_);