effect 4.0.0-beta.99 → 4.0.0-rc.109

package/dist/Cache.d.ts

@@ -1,7 +1,7 @@
-import * as Deferred from "./Deferred.ts";
 import * as Duration from "./Duration.ts";
 import type * as Effect from "./Effect.ts";
 import type * as Exit from "./Exit.ts";
+import type * as Fiber from "./Fiber.ts";
 import * as MutableHashMap from "./MutableHashMap.ts";
 import * as Option from "./Option.ts";
 import type { Pipeable } from "./Pipeable.ts";
@@ -13,7 +13,7 @@ declare const TypeId = "~effect/Cache";
  *
  * **Example** (Creating a basic cache)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic cache with string keys and number values
@@ -30,12 +30,15 @@ declare const TypeId = "~effect/Cache";
  *
  *   return [value1, value2, value3]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [5, 5, 5]
  * ```
  *
  * **Example** (Handling lookup failures)
  *
- * ```ts
- * import { Cache, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cache, Effect, Exit } from "effect"
  *
  * // Cache with error handling
  * const program = Effect.gen(function*() {
@@ -48,16 +51,19 @@ declare const TypeId = "~effect/Cache";
  *   })
  *
  *   // Handle successful and failed lookups
- *   const success = yield* Cache.get(cache, "test") // 4
- *   const failure = yield* Effect.exit(Cache.get(cache, "error")) // Exit.fail
+ *   const success = yield* Cache.get(cache, "test")
+ *   const failure = yield* Effect.exit(Cache.get(cache, "error"))
  *
- *   return { success, failure }
+ *   return [success, failure] as const
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [4, Exit.fail("Lookup failed")]
  * ```
  *
  * **Example** (Using complex keys with TTL)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Data, Duration, Effect } from "effect"
  *
  * // Cache with complex key types and TTL
@@ -73,8 +79,11 @@ declare const TypeId = "~effect/Cache";
  *   const userId = new UserId({ id: 123 })
  *   const userName = yield* Cache.get(userCache, userId)
  *
- *   return userName // "User-123"
+ *   return userName
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => "User-123"
  * ```
  *
  * @category models
@@ -108,7 +117,9 @@ export interface Cache<in out Key, in out A, in out E = never, out R = never> ex
  */
 export interface Entry<A, E> {
     expiresAt: number | undefined;
-    readonly deferred: Deferred.Deferred<A, E>;
+    awaiters: number;
+    readonly fiber: Fiber.Fiber<A, E>;
+    await(this: Entry<A, E>): Effect.Effect<A, E>;
 }
 /**
  * Creates a cache with dynamic time-to-live based on the result and key.
@@ -125,11 +136,11 @@ export interface Entry<A, E> {
  *
  * **Example** (Configuring dynamic time to live)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect, Exit } from "effect"
  *
  * // Cache with TTL based on computed value
- * const userCache = Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
  *   const cache = yield* Cache.makeWith(
  *     (id: number) => Effect.succeed({ id, active: id % 2 === 0 }),
  *     {
@@ -144,8 +155,11 @@ export interface Entry<A, E> {
  *     }
  *   )
  *
- *   return cache
+ *   return cache.capacity
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => 1000
  * ```
  *
  * @see {@link make} for a simpler cache constructor with a fixed time-to-live for all entries
@@ -167,7 +181,7 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  *
  * **Example** (Creating a basic cache)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic cache with string keys
@@ -179,13 +193,16 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  *
  *   const result1 = yield* Cache.get(cache, "hello")
  *   const result2 = yield* Cache.get(cache, "world")
- *   console.log({ result1, result2 }) // { result1: 5, result2: 5 }
+ *   return { result1, result2 }
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => { result1: 5, result2: 5 }
  * ```
  *
  * **Example** (Creating a cache with TTL)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -211,11 +228,12 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  *   })
  *
  *   const user1 = yield* Cache.get(cache, 123)
- *   console.log(user1) // { name: "Ada", email: "ada@example.com" }
- *
  *   const user2 = yield* Cache.get(cache, 123)
- *   console.log(user2) // { name: "Ada", email: "ada@example.com" }
+ *   return [user1, user2, user1 === user2] as const
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [{ name: "Ada", email: "ada@example.com" }, { name: "Ada", email: "ada@example.com" }, true]
  * ```
  *
  * @category constructors
@@ -239,7 +257,7 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  *
  * **Example** (Getting cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -250,20 +268,21 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  *
  *   // Cache miss - triggers lookup function
  *   const result1 = yield* Cache.get(cache, "hello")
- *   console.log(result1) // 5
  *
  *   // Cache hit - returns cached value without lookup
  *   const result2 = yield* Cache.get(cache, "hello")
- *   console.log(result2) // 5 (from cache)
  *
  *   return { result1, result2 }
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => { result1: 5, result2: 5 }
  * ```
  *
  * **Example** (Handling lookup failures)
  *
- * ```ts
- * import { Cache, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cache, Effect, Exit } from "effect"
  *
  * // Error handling when lookup fails
  * const program = Effect.gen(function*() {
@@ -277,17 +296,19 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  *
  *   // Successful lookup
  *   const success = yield* Cache.get(cache, "hello")
- *   console.log(success) // 5
  *
  *   // Failed lookup - returns error
  *   const failure = yield* Effect.exit(Cache.get(cache, "error"))
- *   console.log(failure) // Exit.fail("Lookup failed")
+ *   return [success, failure] as const
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [5, Exit.fail("Lookup failed")]
  * ```
  *
  * **Example** (Sharing concurrent lookups)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Concurrent access - multiple gets of same key only invoke lookup once
@@ -309,9 +330,11 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  *     Cache.get(cache, "hello")
  *   ], { concurrency: "unbounded" })
  *
- *   console.log(results) // [5, 5, 5]
- *   console.log(lookupCount) // 1 (lookup called only once)
+ *   return { results, lookupCount }
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => { results: [5, 5, 5], lookupCount: 1 }
  * ```
  *
  * @category combinators
@@ -330,7 +353,7 @@ export declare const get: {
      *
      * **Example** (Getting cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -341,20 +364,21 @@ export declare const get: {
      *
      *   // Cache miss - triggers lookup function
      *   const result1 = yield* Cache.get(cache, "hello")
-     *   console.log(result1) // 5
      *
      *   // Cache hit - returns cached value without lookup
      *   const result2 = yield* Cache.get(cache, "hello")
-     *   console.log(result2) // 5 (from cache)
      *
      *   return { result1, result2 }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { result1: 5, result2: 5 }
      * ```
      *
      * **Example** (Handling lookup failures)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Exit } from "effect"
      *
      * // Error handling when lookup fails
      * const program = Effect.gen(function*() {
@@ -368,17 +392,19 @@ export declare const get: {
      *
      *   // Successful lookup
      *   const success = yield* Cache.get(cache, "hello")
-     *   console.log(success) // 5
      *
      *   // Failed lookup - returns error
      *   const failure = yield* Effect.exit(Cache.get(cache, "error"))
-     *   console.log(failure) // Exit.fail("Lookup failed")
+     *   return [success, failure] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [5, Exit.fail("Lookup failed")]
      * ```
      *
      * **Example** (Sharing concurrent lookups)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Concurrent access - multiple gets of same key only invoke lookup once
@@ -400,9 +426,11 @@ export declare const get: {
      *     Cache.get(cache, "hello")
      *   ], { concurrency: "unbounded" })
      *
-     *   console.log(results) // [5, 5, 5]
-     *   console.log(lookupCount) // 1 (lookup called only once)
+     *   return { results, lookupCount }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { results: [5, 5, 5], lookupCount: 1 }
      * ```
      *
      * @category combinators
@@ -421,7 +449,7 @@ export declare const get: {
      *
      * **Example** (Getting cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -432,20 +460,21 @@ export declare const get: {
      *
      *   // Cache miss - triggers lookup function
      *   const result1 = yield* Cache.get(cache, "hello")
-     *   console.log(result1) // 5
      *
      *   // Cache hit - returns cached value without lookup
      *   const result2 = yield* Cache.get(cache, "hello")
-     *   console.log(result2) // 5 (from cache)
      *
      *   return { result1, result2 }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { result1: 5, result2: 5 }
      * ```
      *
      * **Example** (Handling lookup failures)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Exit } from "effect"
      *
      * // Error handling when lookup fails
      * const program = Effect.gen(function*() {
@@ -459,17 +488,19 @@ export declare const get: {
      *
      *   // Successful lookup
      *   const success = yield* Cache.get(cache, "hello")
-     *   console.log(success) // 5
      *
      *   // Failed lookup - returns error
      *   const failure = yield* Effect.exit(Cache.get(cache, "error"))
-     *   console.log(failure) // Exit.fail("Lookup failed")
+     *   return [success, failure] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [5, Exit.fail("Lookup failed")]
      * ```
      *
      * **Example** (Sharing concurrent lookups)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Concurrent access - multiple gets of same key only invoke lookup once
@@ -491,9 +522,11 @@ export declare const get: {
      *     Cache.get(cache, "hello")
      *   ], { concurrency: "unbounded" })
      *
-     *   console.log(results) // [5, 5, 5]
-     *   console.log(lookupCount) // 1 (lookup called only once)
+     *   return { results, lookupCount }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { results: [5, 5, 5], lookupCount: 1 }
      * ```
      *
      * @category combinators
@@ -513,8 +546,8 @@ export declare const get: {
  *
  * **Example** (Reading cached values without lookup)
  *
- * ```ts
- * import { Cache, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cache, Effect, Option } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const cache = yield* Cache.make({
@@ -524,23 +557,23 @@ export declare const get: {
  *
  *   // No value in cache yet - returns None without lookup
  *   const empty = yield* Cache.getOption(cache, "hello")
- *   console.log(empty) // Option.none()
  *
  *   // Populate cache using get
  *   yield* Cache.get(cache, "hello")
  *
  *   // Now getOption returns the cached value
  *   const cached = yield* Cache.getOption(cache, "hello")
- *   console.log(cached) // Option.some(5)
- *
- *   return { empty, cached }
+ *   return [empty, cached] as const
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [Option.none(), Option.some(5)]
  * ```
  *
  * **Example** (Skipping expired entries)
  *
- * ```ts
- * import { Cache, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cache, Effect, Option } from "effect"
  * import { TestClock } from "effect/testing"
  *
  * // Expired entries return None
@@ -556,21 +589,23 @@ export declare const get: {
  *
  *   // Value exists before expiration
  *   const beforeExpiry = yield* Cache.getOption(cache, "hello")
- *   console.log(beforeExpiry) // Option.some(5)
  *
  *   // Simulate time passing
  *   yield* TestClock.adjust("2 hours")
  *
  *   // Value expired - returns None
  *   const afterExpiry = yield* Cache.getOption(cache, "hello")
- *   console.log(afterExpiry) // Option.none()
+ *   return [beforeExpiry, afterExpiry] as const
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+ * actual // => [Option.some(5), Option.none()]
  * ```
  *
  * **Example** (Waiting for pending lookups)
  *
- * ```ts
- * import { Cache, Deferred, Effect, Fiber } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cache, Deferred, Effect, Fiber, Option } from "effect"
  *
  * // Waits for ongoing computation to complete
  * const program = Effect.gen(function*() {
@@ -590,11 +625,12 @@ export declare const get: {
  *   yield* Deferred.succeed(deferred, void 0)
  *
  *   const result = yield* Fiber.join(optionFiber)
- *   console.log(result) // Option.some(42)
- *
  *   const value = yield* Fiber.join(getFiber)
- *   console.log(value) // 42
+ *   return [result, value] as const
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [Option.some(42), 42]
  * ```
  *
  * @category combinators
@@ -613,8 +649,8 @@ export declare const getOption: {
      *
      * **Example** (Reading cached values without lookup)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Option } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const cache = yield* Cache.make({
@@ -624,23 +660,23 @@ export declare const getOption: {
      *
      *   // No value in cache yet - returns None without lookup
      *   const empty = yield* Cache.getOption(cache, "hello")
-     *   console.log(empty) // Option.none()
      *
      *   // Populate cache using get
      *   yield* Cache.get(cache, "hello")
      *
      *   // Now getOption returns the cached value
      *   const cached = yield* Cache.getOption(cache, "hello")
-     *   console.log(cached) // Option.some(5)
-     *
-     *   return { empty, cached }
+     *   return [empty, cached] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [Option.none(), Option.some(5)]
      * ```
      *
      * **Example** (Skipping expired entries)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Option } from "effect"
      * import { TestClock } from "effect/testing"
      *
      * // Expired entries return None
@@ -656,21 +692,23 @@ export declare const getOption: {
      *
      *   // Value exists before expiration
      *   const beforeExpiry = yield* Cache.getOption(cache, "hello")
-     *   console.log(beforeExpiry) // Option.some(5)
      *
      *   // Simulate time passing
      *   yield* TestClock.adjust("2 hours")
      *
      *   // Value expired - returns None
      *   const afterExpiry = yield* Cache.getOption(cache, "hello")
-     *   console.log(afterExpiry) // Option.none()
+     *   return [beforeExpiry, afterExpiry] as const
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [Option.some(5), Option.none()]
      * ```
      *
      * **Example** (Waiting for pending lookups)
      *
-     * ```ts
-     * import { Cache, Deferred, Effect, Fiber } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Deferred, Effect, Fiber, Option } from "effect"
      *
      * // Waits for ongoing computation to complete
      * const program = Effect.gen(function*() {
@@ -690,11 +728,12 @@ export declare const getOption: {
      *   yield* Deferred.succeed(deferred, void 0)
      *
      *   const result = yield* Fiber.join(optionFiber)
-     *   console.log(result) // Option.some(42)
-     *
      *   const value = yield* Fiber.join(getFiber)
-     *   console.log(value) // 42
+     *   return [result, value] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [Option.some(42), 42]
      * ```
      *
      * @category combinators
@@ -713,8 +752,8 @@ export declare const getOption: {
      *
      * **Example** (Reading cached values without lookup)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Option } from "effect"
      *
      * const program = Effect.gen(function*() {
      *   const cache = yield* Cache.make({
@@ -724,23 +763,23 @@ export declare const getOption: {
      *
      *   // No value in cache yet - returns None without lookup
      *   const empty = yield* Cache.getOption(cache, "hello")
-     *   console.log(empty) // Option.none()
      *
      *   // Populate cache using get
      *   yield* Cache.get(cache, "hello")
      *
      *   // Now getOption returns the cached value
      *   const cached = yield* Cache.getOption(cache, "hello")
-     *   console.log(cached) // Option.some(5)
-     *
-     *   return { empty, cached }
+     *   return [empty, cached] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [Option.none(), Option.some(5)]
      * ```
      *
      * **Example** (Skipping expired entries)
      *
-     * ```ts
-     * import { Cache, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Effect, Option } from "effect"
      * import { TestClock } from "effect/testing"
      *
      * // Expired entries return None
@@ -756,21 +795,23 @@ export declare const getOption: {
      *
      *   // Value exists before expiration
      *   const beforeExpiry = yield* Cache.getOption(cache, "hello")
-     *   console.log(beforeExpiry) // Option.some(5)
      *
      *   // Simulate time passing
      *   yield* TestClock.adjust("2 hours")
      *
      *   // Value expired - returns None
      *   const afterExpiry = yield* Cache.getOption(cache, "hello")
-     *   console.log(afterExpiry) // Option.none()
+     *   return [beforeExpiry, afterExpiry] as const
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [Option.some(5), Option.none()]
      * ```
      *
      * **Example** (Waiting for pending lookups)
      *
-     * ```ts
-     * import { Cache, Deferred, Effect, Fiber } from "effect"
+     * ```ts import.meta.vitest
+     * import { Cache, Deferred, Effect, Fiber, Option } from "effect"
      *
      * // Waits for ongoing computation to complete
      * const program = Effect.gen(function*() {
@@ -790,11 +831,12 @@ export declare const getOption: {
      *   yield* Deferred.succeed(deferred, void 0)
      *
      *   const result = yield* Fiber.join(optionFiber)
-     *   console.log(result) // Option.some(42)
-     *
      *   const value = yield* Fiber.join(getFiber)
-     *   console.log(value) // 42
+     *   return [result, value] as const
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [Option.some(42), 42]
      * ```
      *
      * @category combinators
@@ -860,7 +902,7 @@ export declare const getSuccess: {
  *
  * **Example** (Setting values directly)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -871,14 +913,16 @@ export declare const getSuccess: {
  *
  *   // Set a value directly without invoking lookup
  *   yield* Cache.set(cache, "hello", 42)
- *   const result = yield* Cache.get(cache, "hello")
- *   console.log(result) // 42 (not 5 from lookup)
+ *   return yield* Cache.get(cache, "hello")
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => 42
  * ```
  *
  * **Example** (Overwriting cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Overwriting existing cached values
@@ -895,13 +939,16 @@ export declare const getSuccess: {
  *   yield* Cache.set(cache, "test", 999)
  *   const updated = yield* Cache.get(cache, "test") // 999
  *
- *   console.log({ original, updated })
+ *   return { original, updated }
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => { original: 4, updated: 999 }
  * ```
  *
  * **Example** (Applying TTL to set values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
  *
@@ -915,17 +962,21 @@ export declare const getSuccess: {
  *
  *   // Set value with TTL applied
  *   yield* Cache.set(cache, "temporary", 123)
- *   console.log(yield* Cache.has(cache, "temporary")) // true
+ *   const beforeExpiry = yield* Cache.has(cache, "temporary")
  *
  *   // Advance time past TTL
  *   yield* TestClock.adjust("2 hours")
- *   console.log(yield* Cache.has(cache, "temporary")) // false
+ *   const afterExpiry = yield* Cache.has(cache, "temporary")
+ *   return [beforeExpiry, afterExpiry]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+ * actual // => [true, false]
  * ```
  *
  * **Example** (Enforcing capacity when setting values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Capacity enforcement with set operations
@@ -938,14 +989,18 @@ export declare const getSuccess: {
  *   // Fill cache to capacity
  *   yield* Cache.set(cache, "a", 1)
  *   yield* Cache.set(cache, "b", 2)
- *   console.log(yield* Cache.size(cache)) // 2
+ *   const sizeBeforeEviction = yield* Cache.size(cache)
  *
  *   // Adding another entry evicts oldest
  *   yield* Cache.set(cache, "c", 3)
- *   console.log(yield* Cache.size(cache)) // 2
- *   console.log(yield* Cache.has(cache, "a")) // false (evicted)
- *   console.log(yield* Cache.has(cache, "c")) // true
+ *   const sizeAfterEviction = yield* Cache.size(cache)
+ *   const hasOldest = yield* Cache.has(cache, "a")
+ *   const hasNewest = yield* Cache.has(cache, "c")
+ *   return [sizeBeforeEviction, sizeAfterEviction, hasOldest, hasNewest]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [2, 2, false, true]
  * ```
  *
  * @category combinators
@@ -958,7 +1013,7 @@ export declare const set: {
      *
      * **Example** (Setting values directly)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -969,14 +1024,16 @@ export declare const set: {
      *
      *   // Set a value directly without invoking lookup
      *   yield* Cache.set(cache, "hello", 42)
-     *   const result = yield* Cache.get(cache, "hello")
-     *   console.log(result) // 42 (not 5 from lookup)
+     *   return yield* Cache.get(cache, "hello")
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => 42
      * ```
      *
      * **Example** (Overwriting cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Overwriting existing cached values
@@ -993,13 +1050,16 @@ export declare const set: {
      *   yield* Cache.set(cache, "test", 999)
      *   const updated = yield* Cache.get(cache, "test") // 999
      *
-     *   console.log({ original, updated })
+     *   return { original, updated }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { original: 4, updated: 999 }
      * ```
      *
      * **Example** (Applying TTL to set values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -1013,17 +1073,21 @@ export declare const set: {
      *
      *   // Set value with TTL applied
      *   yield* Cache.set(cache, "temporary", 123)
-     *   console.log(yield* Cache.has(cache, "temporary")) // true
+     *   const beforeExpiry = yield* Cache.has(cache, "temporary")
      *
      *   // Advance time past TTL
      *   yield* TestClock.adjust("2 hours")
-     *   console.log(yield* Cache.has(cache, "temporary")) // false
+     *   const afterExpiry = yield* Cache.has(cache, "temporary")
+     *   return [beforeExpiry, afterExpiry]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, false]
      * ```
      *
      * **Example** (Enforcing capacity when setting values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Capacity enforcement with set operations
@@ -1036,14 +1100,18 @@ export declare const set: {
      *   // Fill cache to capacity
      *   yield* Cache.set(cache, "a", 1)
      *   yield* Cache.set(cache, "b", 2)
-     *   console.log(yield* Cache.size(cache)) // 2
+     *   const sizeBeforeEviction = yield* Cache.size(cache)
      *
      *   // Adding another entry evicts oldest
      *   yield* Cache.set(cache, "c", 3)
-     *   console.log(yield* Cache.size(cache)) // 2
-     *   console.log(yield* Cache.has(cache, "a")) // false (evicted)
-     *   console.log(yield* Cache.has(cache, "c")) // true
+     *   const sizeAfterEviction = yield* Cache.size(cache)
+     *   const hasOldest = yield* Cache.has(cache, "a")
+     *   const hasNewest = yield* Cache.has(cache, "c")
+     *   return [sizeBeforeEviction, sizeAfterEviction, hasOldest, hasNewest]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [2, 2, false, true]
      * ```
      *
      * @category combinators
@@ -1056,7 +1124,7 @@ export declare const set: {
      *
      * **Example** (Setting values directly)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1067,14 +1135,16 @@ export declare const set: {
      *
      *   // Set a value directly without invoking lookup
      *   yield* Cache.set(cache, "hello", 42)
-     *   const result = yield* Cache.get(cache, "hello")
-     *   console.log(result) // 42 (not 5 from lookup)
+     *   return yield* Cache.get(cache, "hello")
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => 42
      * ```
      *
      * **Example** (Overwriting cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Overwriting existing cached values
@@ -1091,13 +1161,16 @@ export declare const set: {
      *   yield* Cache.set(cache, "test", 999)
      *   const updated = yield* Cache.get(cache, "test") // 999
      *
-     *   console.log({ original, updated })
+     *   return { original, updated }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { original: 4, updated: 999 }
      * ```
      *
      * **Example** (Applying TTL to set values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -1111,17 +1184,21 @@ export declare const set: {
      *
      *   // Set value with TTL applied
      *   yield* Cache.set(cache, "temporary", 123)
-     *   console.log(yield* Cache.has(cache, "temporary")) // true
+     *   const beforeExpiry = yield* Cache.has(cache, "temporary")
      *
      *   // Advance time past TTL
      *   yield* TestClock.adjust("2 hours")
-     *   console.log(yield* Cache.has(cache, "temporary")) // false
+     *   const afterExpiry = yield* Cache.has(cache, "temporary")
+     *   return [beforeExpiry, afterExpiry]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, false]
      * ```
      *
      * **Example** (Enforcing capacity when setting values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Capacity enforcement with set operations
@@ -1134,14 +1211,18 @@ export declare const set: {
      *   // Fill cache to capacity
      *   yield* Cache.set(cache, "a", 1)
      *   yield* Cache.set(cache, "b", 2)
-     *   console.log(yield* Cache.size(cache)) // 2
+     *   const sizeBeforeEviction = yield* Cache.size(cache)
      *
      *   // Adding another entry evicts oldest
      *   yield* Cache.set(cache, "c", 3)
-     *   console.log(yield* Cache.size(cache)) // 2
-     *   console.log(yield* Cache.has(cache, "a")) // false (evicted)
-     *   console.log(yield* Cache.has(cache, "c")) // true
+     *   const sizeAfterEviction = yield* Cache.size(cache)
+     *   const hasOldest = yield* Cache.has(cache, "a")
+     *   const hasNewest = yield* Cache.has(cache, "c")
+     *   return [sizeBeforeEviction, sizeAfterEviction, hasOldest, hasNewest]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [2, 2, false, true]
      * ```
      *
      * @category combinators
@@ -1159,7 +1240,7 @@ export declare const set: {
  *
  * **Example** (Checking for cached keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1169,17 +1250,21 @@ export declare const set: {
  *   })
  *
  *   // Check non-existent key
- *   console.log(yield* Cache.has(cache, "missing")) // false
+ *   const missing = yield* Cache.has(cache, "missing")
  *
  *   // Add entry and check existence
  *   yield* Cache.get(cache, "hello")
- *   console.log(yield* Cache.has(cache, "hello")) // true
+ *   const present = yield* Cache.has(cache, "hello")
+ *   return [missing, present]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [false, true]
  * ```
  *
  * **Example** (Checking TTL expiration)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
  *
@@ -1193,21 +1278,25 @@ export declare const set: {
  *
  *   // Add entry with TTL
  *   yield* Cache.get(cache, "expires")
- *   console.log(yield* Cache.has(cache, "expires")) // true
+ *   const initial = yield* Cache.has(cache, "expires")
  *
  *   // Still valid before expiration
  *   yield* TestClock.adjust("30 minutes")
- *   console.log(yield* Cache.has(cache, "expires")) // true
+ *   const beforeExpiry = yield* Cache.has(cache, "expires")
  *
  *   // Expired after TTL
  *   yield* TestClock.adjust("31 minutes")
- *   console.log(yield* Cache.has(cache, "expires")) // false
+ *   const afterExpiry = yield* Cache.has(cache, "expires")
+ *   return [initial, beforeExpiry, afterExpiry]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+ * actual // => [true, true, false]
  * ```
  *
  * **Example** (Checking multiple keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Checking multiple keys efficiently
@@ -1223,16 +1312,16 @@ export declare const set: {
  *
  *   // Check multiple keys
  *   const keys = ["apple", "banana", "cherry", "date"]
+ *   const results: Array<string> = []
  *   for (const key of keys) {
  *     const exists = yield* Cache.has(cache, key)
- *     console.log(`${key}: ${exists}`)
+ *     results.push(`${key}: ${exists}`)
  *   }
- *   // Output:
- *   // apple: true
- *   // banana: true
- *   // cherry: false
- *   // date: false
+ *   return results
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
  * ```
  *
  * @category combinators
@@ -1249,7 +1338,7 @@ export declare const has: {
      *
      * **Example** (Checking for cached keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1259,17 +1348,21 @@ export declare const has: {
      *   })
      *
      *   // Check non-existent key
-     *   console.log(yield* Cache.has(cache, "missing")) // false
+     *   const missing = yield* Cache.has(cache, "missing")
      *
      *   // Add entry and check existence
      *   yield* Cache.get(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // true
+     *   const present = yield* Cache.has(cache, "hello")
+     *   return [missing, present]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [false, true]
      * ```
      *
      * **Example** (Checking TTL expiration)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -1283,21 +1376,25 @@ export declare const has: {
      *
      *   // Add entry with TTL
      *   yield* Cache.get(cache, "expires")
-     *   console.log(yield* Cache.has(cache, "expires")) // true
+     *   const initial = yield* Cache.has(cache, "expires")
      *
      *   // Still valid before expiration
      *   yield* TestClock.adjust("30 minutes")
-     *   console.log(yield* Cache.has(cache, "expires")) // true
+     *   const beforeExpiry = yield* Cache.has(cache, "expires")
      *
      *   // Expired after TTL
      *   yield* TestClock.adjust("31 minutes")
-     *   console.log(yield* Cache.has(cache, "expires")) // false
+     *   const afterExpiry = yield* Cache.has(cache, "expires")
+     *   return [initial, beforeExpiry, afterExpiry]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, true, false]
      * ```
      *
      * **Example** (Checking multiple keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Checking multiple keys efficiently
@@ -1313,16 +1410,16 @@ export declare const has: {
      *
      *   // Check multiple keys
      *   const keys = ["apple", "banana", "cherry", "date"]
+     *   const results: Array<string> = []
      *   for (const key of keys) {
      *     const exists = yield* Cache.has(cache, key)
-     *     console.log(`${key}: ${exists}`)
+     *     results.push(`${key}: ${exists}`)
      *   }
-     *   // Output:
-     *   // apple: true
-     *   // banana: true
-     *   // cherry: false
-     *   // date: false
+     *   return results
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
      * ```
      *
      * @category combinators
@@ -1339,7 +1436,7 @@ export declare const has: {
      *
      * **Example** (Checking for cached keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1349,17 +1446,21 @@ export declare const has: {
      *   })
      *
      *   // Check non-existent key
-     *   console.log(yield* Cache.has(cache, "missing")) // false
+     *   const missing = yield* Cache.has(cache, "missing")
      *
      *   // Add entry and check existence
      *   yield* Cache.get(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // true
+     *   const present = yield* Cache.has(cache, "hello")
+     *   return [missing, present]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [false, true]
      * ```
      *
      * **Example** (Checking TTL expiration)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -1373,21 +1474,25 @@ export declare const has: {
      *
      *   // Add entry with TTL
      *   yield* Cache.get(cache, "expires")
-     *   console.log(yield* Cache.has(cache, "expires")) // true
+     *   const initial = yield* Cache.has(cache, "expires")
      *
      *   // Still valid before expiration
      *   yield* TestClock.adjust("30 minutes")
-     *   console.log(yield* Cache.has(cache, "expires")) // true
+     *   const beforeExpiry = yield* Cache.has(cache, "expires")
      *
      *   // Expired after TTL
      *   yield* TestClock.adjust("31 minutes")
-     *   console.log(yield* Cache.has(cache, "expires")) // false
+     *   const afterExpiry = yield* Cache.has(cache, "expires")
+     *   return [initial, beforeExpiry, afterExpiry]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, true, false]
      * ```
      *
      * **Example** (Checking multiple keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Checking multiple keys efficiently
@@ -1403,16 +1508,16 @@ export declare const has: {
      *
      *   // Check multiple keys
      *   const keys = ["apple", "banana", "cherry", "date"]
+     *   const results: Array<string> = []
      *   for (const key of keys) {
      *     const exists = yield* Cache.has(cache, key)
-     *     console.log(`${key}: ${exists}`)
+     *     results.push(`${key}: ${exists}`)
      *   }
-     *   // Output:
-     *   // apple: true
-     *   // banana: true
-     *   // cherry: false
-     *   // date: false
+     *   return results
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
      * ```
      *
      * @category combinators
@@ -1425,7 +1530,7 @@ export declare const has: {
  *
  * **Example** (Invalidating cached entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1436,11 +1541,11 @@ export declare const has: {
  *
  *   // Add a value to the cache
  *   yield* Cache.get(cache, "hello")
- *   console.log(yield* Cache.has(cache, "hello")) // true
+ *   const beforeInvalidation = yield* Cache.has(cache, "hello")
  *
  *   // Invalidate the entry
  *   yield* Cache.invalidate(cache, "hello")
- *   console.log(yield* Cache.has(cache, "hello")) // false
+ *   const afterInvalidation = yield* Cache.has(cache, "hello")
  *
  *   // Invalidating non-existent keys doesn't error
  *   yield* Cache.invalidate(cache, "nonexistent")
@@ -1459,7 +1564,11 @@ export declare const has: {
  *   yield* Cache.get(cache2, "test") // lookupCount = 1
  *   yield* Cache.invalidate(cache2, "test")
  *   yield* Cache.get(cache2, "test") // lookupCount = 2 (lookup called again)
+ *   return { beforeInvalidation, afterInvalidation, lookupCount }
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
  * ```
  *
  * @category combinators
@@ -1471,7 +1580,7 @@ export declare const invalidate: {
      *
      * **Example** (Invalidating cached entries)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1482,11 +1591,11 @@ export declare const invalidate: {
      *
      *   // Add a value to the cache
      *   yield* Cache.get(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // true
+     *   const beforeInvalidation = yield* Cache.has(cache, "hello")
      *
      *   // Invalidate the entry
      *   yield* Cache.invalidate(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // false
+     *   const afterInvalidation = yield* Cache.has(cache, "hello")
      *
      *   // Invalidating non-existent keys doesn't error
      *   yield* Cache.invalidate(cache, "nonexistent")
@@ -1505,7 +1614,11 @@ export declare const invalidate: {
      *   yield* Cache.get(cache2, "test") // lookupCount = 1
      *   yield* Cache.invalidate(cache2, "test")
      *   yield* Cache.get(cache2, "test") // lookupCount = 2 (lookup called again)
+     *   return { beforeInvalidation, afterInvalidation, lookupCount }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
      * ```
      *
      * @category combinators
@@ -1517,7 +1630,7 @@ export declare const invalidate: {
      *
      * **Example** (Invalidating cached entries)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1528,11 +1641,11 @@ export declare const invalidate: {
      *
      *   // Add a value to the cache
      *   yield* Cache.get(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // true
+     *   const beforeInvalidation = yield* Cache.has(cache, "hello")
      *
      *   // Invalidate the entry
      *   yield* Cache.invalidate(cache, "hello")
-     *   console.log(yield* Cache.has(cache, "hello")) // false
+     *   const afterInvalidation = yield* Cache.has(cache, "hello")
      *
      *   // Invalidating non-existent keys doesn't error
      *   yield* Cache.invalidate(cache, "nonexistent")
@@ -1551,7 +1664,11 @@ export declare const invalidate: {
      *   yield* Cache.get(cache2, "test") // lookupCount = 1
      *   yield* Cache.invalidate(cache2, "test")
      *   yield* Cache.get(cache2, "test") // lookupCount = 2 (lookup called again)
+     *   return { beforeInvalidation, afterInvalidation, lookupCount }
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
      * ```
      *
      * @category combinators
@@ -1565,7 +1682,7 @@ export declare const invalidate: {
  *
  * **Example** (Invalidating entries conditionally)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1584,8 +1701,7 @@ export declare const invalidate: {
  *     "hello",
  *     (value) => value === 5
  *   )
- *   console.log(invalidated1) // true
- *   console.log(yield* Cache.has(cache, "hello")) // false
+ *   const hasHello = yield* Cache.has(cache, "hello")
  *
  *   // Don't invalidate when predicate doesn't match
  *   const invalidated2 = yield* Cache.invalidateWhen(
@@ -1593,8 +1709,7 @@ export declare const invalidate: {
  *     "hi",
  *     (value) => value === 5
  *   )
- *   console.log(invalidated2) // false
- *   console.log(yield* Cache.has(cache, "hi")) // true (still present)
+ *   const hasHi = yield* Cache.has(cache, "hi")
  *
  *   // Returns false for non-existent keys
  *   const invalidated3 = yield* Cache.invalidateWhen(
@@ -1602,7 +1717,6 @@ export declare const invalidate: {
  *     "nonexistent",
  *     () => true
  *   )
- *   console.log(invalidated3) // false
  *
  *   // Returns false for failed cached values
  *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -1617,8 +1731,11 @@ export declare const invalidate: {
  *     "fail",
  *     () => true
  *   )
- *   console.log(invalidated4) // false (can't invalidate failed values)
+ *   return [invalidated1, hasHello, invalidated2, hasHi, invalidated3, invalidated4]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [true, false, false, true, false, false]
  * ```
  *
  * @category combinators
@@ -1631,7 +1748,7 @@ export declare const invalidateWhen: {
      *
      * **Example** (Invalidating entries conditionally)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1650,8 +1767,7 @@ export declare const invalidateWhen: {
      *     "hello",
      *     (value) => value === 5
      *   )
-     *   console.log(invalidated1) // true
-     *   console.log(yield* Cache.has(cache, "hello")) // false
+     *   const hasHello = yield* Cache.has(cache, "hello")
      *
      *   // Don't invalidate when predicate doesn't match
      *   const invalidated2 = yield* Cache.invalidateWhen(
@@ -1659,8 +1775,7 @@ export declare const invalidateWhen: {
      *     "hi",
      *     (value) => value === 5
      *   )
-     *   console.log(invalidated2) // false
-     *   console.log(yield* Cache.has(cache, "hi")) // true (still present)
+     *   const hasHi = yield* Cache.has(cache, "hi")
      *
      *   // Returns false for non-existent keys
      *   const invalidated3 = yield* Cache.invalidateWhen(
@@ -1668,7 +1783,6 @@ export declare const invalidateWhen: {
      *     "nonexistent",
      *     () => true
      *   )
-     *   console.log(invalidated3) // false
      *
      *   // Returns false for failed cached values
      *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -1683,8 +1797,11 @@ export declare const invalidateWhen: {
      *     "fail",
      *     () => true
      *   )
-     *   console.log(invalidated4) // false (can't invalidate failed values)
+     *   return [invalidated1, hasHello, invalidated2, hasHi, invalidated3, invalidated4]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [true, false, false, true, false, false]
      * ```
      *
      * @category combinators
@@ -1697,7 +1814,7 @@ export declare const invalidateWhen: {
      *
      * **Example** (Invalidating entries conditionally)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * const program = Effect.gen(function*() {
@@ -1716,8 +1833,7 @@ export declare const invalidateWhen: {
      *     "hello",
      *     (value) => value === 5
      *   )
-     *   console.log(invalidated1) // true
-     *   console.log(yield* Cache.has(cache, "hello")) // false
+     *   const hasHello = yield* Cache.has(cache, "hello")
      *
      *   // Don't invalidate when predicate doesn't match
      *   const invalidated2 = yield* Cache.invalidateWhen(
@@ -1725,8 +1841,7 @@ export declare const invalidateWhen: {
      *     "hi",
      *     (value) => value === 5
      *   )
-     *   console.log(invalidated2) // false
-     *   console.log(yield* Cache.has(cache, "hi")) // true (still present)
+     *   const hasHi = yield* Cache.has(cache, "hi")
      *
      *   // Returns false for non-existent keys
      *   const invalidated3 = yield* Cache.invalidateWhen(
@@ -1734,7 +1849,6 @@ export declare const invalidateWhen: {
      *     "nonexistent",
      *     () => true
      *   )
-     *   console.log(invalidated3) // false
      *
      *   // Returns false for failed cached values
      *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -1749,8 +1863,11 @@ export declare const invalidateWhen: {
      *     "fail",
      *     () => true
      *   )
-     *   console.log(invalidated4) // false (can't invalidate failed values)
+     *   return [invalidated1, hasHello, invalidated2, hasHi, invalidated3, invalidated4]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => [true, false, false, true, false, false]
      * ```
      *
      * @category combinators
@@ -1768,7 +1885,7 @@ export declare const invalidateWhen: {
  *
  * **Example** (Refreshing cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Force refresh of existing cached values
@@ -1781,25 +1898,25 @@ export declare const invalidateWhen: {
  *
  *   // Initial cache population
  *   const value1 = yield* Cache.get(cache, "user")
- *   console.log(value1) // "user-1"
  *
  *   // Get from cache (no lookup)
  *   const value2 = yield* Cache.get(cache, "user")
- *   console.log(value2) // "user-1" (same value)
  *
  *   // Force refresh - always calls lookup
  *   const refreshed = yield* Cache.refresh(cache, "user")
- *   console.log(refreshed) // "user-2" (new value)
  *
  *   // Subsequent gets return refreshed value
  *   const value3 = yield* Cache.get(cache, "user")
- *   console.log(value3) // "user-2"
+ *   return [value1, value2, refreshed, value3, counter]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => ["user-1", "user-1", "user-2", "user-2", 2]
  * ```
  *
  * **Example** (Resetting TTL on refresh)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
  *
@@ -1815,20 +1932,24 @@ export declare const invalidateWhen: {
  *   yield* TestClock.adjust("45 minutes")
  *
  *   // Entry would normally expire in 15 minutes
- *   console.log(yield* Cache.has(cache, "test")) // true
+ *   const beforeRefresh = yield* Cache.has(cache, "test")
  *
  *   // Refresh resets the TTL to full 1 hour
  *   yield* Cache.refresh(cache, "test")
  *   yield* TestClock.adjust("30 minutes")
  *
  *   // Still valid because TTL was reset
- *   console.log(yield* Cache.has(cache, "test")) // true
+ *   const afterRefresh = yield* Cache.has(cache, "test")
+ *   return [beforeRefresh, afterRefresh]
  * })
+ *
+ * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+ * actual // => [true, true]
  * ```
  *
  * **Example** (Refreshing missing keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Refresh non-existent keys
@@ -1840,11 +1961,14 @@ export declare const invalidateWhen: {
  *
  *   // Refresh non-existent key creates new entry
  *   const result = yield* Cache.refresh(cache, "newKey")
- *   console.log(result) // "value-for-newKey"
  *
  *   // Verify it's now cached
- *   console.log(yield* Cache.has(cache, "newKey")) // true
+ *   const cached = yield* Cache.has(cache, "newKey")
+ *   return [result, cached]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => ["value-for-newKey", true]
  * ```
  *
  * @category combinators
@@ -1861,7 +1985,7 @@ export declare const refresh: {
      *
      * **Example** (Refreshing cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Force refresh of existing cached values
@@ -1874,25 +1998,25 @@ export declare const refresh: {
      *
      *   // Initial cache population
      *   const value1 = yield* Cache.get(cache, "user")
-     *   console.log(value1) // "user-1"
      *
      *   // Get from cache (no lookup)
      *   const value2 = yield* Cache.get(cache, "user")
-     *   console.log(value2) // "user-1" (same value)
      *
      *   // Force refresh - always calls lookup
      *   const refreshed = yield* Cache.refresh(cache, "user")
-     *   console.log(refreshed) // "user-2" (new value)
      *
      *   // Subsequent gets return refreshed value
      *   const value3 = yield* Cache.get(cache, "user")
-     *   console.log(value3) // "user-2"
+     *   return [value1, value2, refreshed, value3, counter]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["user-1", "user-1", "user-2", "user-2", 2]
      * ```
      *
      * **Example** (Resetting TTL on refresh)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -1908,20 +2032,24 @@ export declare const refresh: {
      *   yield* TestClock.adjust("45 minutes")
      *
      *   // Entry would normally expire in 15 minutes
-     *   console.log(yield* Cache.has(cache, "test")) // true
+     *   const beforeRefresh = yield* Cache.has(cache, "test")
      *
      *   // Refresh resets the TTL to full 1 hour
      *   yield* Cache.refresh(cache, "test")
      *   yield* TestClock.adjust("30 minutes")
      *
      *   // Still valid because TTL was reset
-     *   console.log(yield* Cache.has(cache, "test")) // true
+     *   const afterRefresh = yield* Cache.has(cache, "test")
+     *   return [beforeRefresh, afterRefresh]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, true]
      * ```
      *
      * **Example** (Refreshing missing keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Refresh non-existent keys
@@ -1933,11 +2061,14 @@ export declare const refresh: {
      *
      *   // Refresh non-existent key creates new entry
      *   const result = yield* Cache.refresh(cache, "newKey")
-     *   console.log(result) // "value-for-newKey"
      *
      *   // Verify it's now cached
-     *   console.log(yield* Cache.has(cache, "newKey")) // true
+     *   const cached = yield* Cache.has(cache, "newKey")
+     *   return [result, cached]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["value-for-newKey", true]
      * ```
      *
      * @category combinators
@@ -1954,7 +2085,7 @@ export declare const refresh: {
      *
      * **Example** (Refreshing cached values)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Force refresh of existing cached values
@@ -1967,25 +2098,25 @@ export declare const refresh: {
      *
      *   // Initial cache population
      *   const value1 = yield* Cache.get(cache, "user")
-     *   console.log(value1) // "user-1"
      *
      *   // Get from cache (no lookup)
      *   const value2 = yield* Cache.get(cache, "user")
-     *   console.log(value2) // "user-1" (same value)
      *
      *   // Force refresh - always calls lookup
      *   const refreshed = yield* Cache.refresh(cache, "user")
-     *   console.log(refreshed) // "user-2" (new value)
      *
      *   // Subsequent gets return refreshed value
      *   const value3 = yield* Cache.get(cache, "user")
-     *   console.log(value3) // "user-2"
+     *   return [value1, value2, refreshed, value3, counter]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["user-1", "user-1", "user-2", "user-2", 2]
      * ```
      *
      * **Example** (Resetting TTL on refresh)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
      *
@@ -2001,20 +2132,24 @@ export declare const refresh: {
      *   yield* TestClock.adjust("45 minutes")
      *
      *   // Entry would normally expire in 15 minutes
-     *   console.log(yield* Cache.has(cache, "test")) // true
+     *   const beforeRefresh = yield* Cache.has(cache, "test")
      *
      *   // Refresh resets the TTL to full 1 hour
      *   yield* Cache.refresh(cache, "test")
      *   yield* TestClock.adjust("30 minutes")
      *
      *   // Still valid because TTL was reset
-     *   console.log(yield* Cache.has(cache, "test")) // true
+     *   const afterRefresh = yield* Cache.has(cache, "test")
+     *   return [beforeRefresh, afterRefresh]
      * })
+     *
+     * const actual = await Effect.runPromise(Effect.provide(program, TestClock.layer()))
+     * actual // => [true, true]
      * ```
      *
      * **Example** (Refreshing missing keys)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Cache, Effect } from "effect"
      *
      * // Refresh non-existent keys
@@ -2026,11 +2161,14 @@ export declare const refresh: {
      *
      *   // Refresh non-existent key creates new entry
      *   const result = yield* Cache.refresh(cache, "newKey")
-     *   console.log(result) // "value-for-newKey"
      *
      *   // Verify it's now cached
-     *   console.log(yield* Cache.has(cache, "newKey")) // true
+     *   const cached = yield* Cache.has(cache, "newKey")
+     *   return [result, cached]
      * })
+     *
+     * const actual = await Effect.runPromise(program)
+     * actual // => ["value-for-newKey", true]
      * ```
      *
      * @category combinators
@@ -2043,7 +2181,7 @@ export declare const refresh: {
  *
  * **Example** (Invalidating all entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Clear all cached entries at once
@@ -2058,18 +2196,29 @@ export declare const refresh: {
  *   yield* Cache.get(cache, "banana")
  *   yield* Cache.get(cache, "cherry")
  *
- *   console.log(yield* Cache.size(cache)) // 3
- *   console.log(yield* Cache.has(cache, "apple")) // true
+ *   const sizeBeforeInvalidation = yield* Cache.size(cache)
+ *   const hasAppleBeforeInvalidation = yield* Cache.has(cache, "apple")
  *
  *   // Clear all entries
  *   yield* Cache.invalidateAll(cache)
  *
  *   // Verify cache is empty
- *   console.log(yield* Cache.size(cache)) // 0
- *   console.log(yield* Cache.has(cache, "apple")) // false
- *   console.log(yield* Cache.has(cache, "banana")) // false
- *   console.log(yield* Cache.has(cache, "cherry")) // false
+ *   const sizeAfterInvalidation = yield* Cache.size(cache)
+ *   const hasAppleAfterInvalidation = yield* Cache.has(cache, "apple")
+ *   const hasBananaAfterInvalidation = yield* Cache.has(cache, "banana")
+ *   const hasCherryAfterInvalidation = yield* Cache.has(cache, "cherry")
+ *   return [
+ *     sizeBeforeInvalidation,
+ *     hasAppleBeforeInvalidation,
+ *     sizeAfterInvalidation,
+ *     hasAppleAfterInvalidation,
+ *     hasBananaAfterInvalidation,
+ *     hasCherryAfterInvalidation
+ *   ]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [3, true, 0, false, false, false]
  * ```
  *
  * @category combinators
@@ -2087,7 +2236,7 @@ export declare const invalidateAll: <Key, A, E, R>(self: Cache<Key, A, E, R>) =>
  *
  * **Example** (Reading cache size)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2098,19 +2247,20 @@ export declare const invalidateAll: <Key, A, E, R>(self: Cache<Key, A, E, R>) =>
  *
  *   // Empty cache has size 0
  *   const emptySize = yield* Cache.size(cache)
- *   console.log(emptySize) // 0
  *
  *   // Add entries and check size
  *   yield* Cache.get(cache, "hello")
  *   yield* Cache.get(cache, "world")
  *   const sizeAfterAdding = yield* Cache.size(cache)
- *   console.log(sizeAfterAdding) // 2
  *
  *   // Size decreases after invalidation
  *   yield* Cache.invalidate(cache, "hello")
  *   const sizeAfterInvalidation = yield* Cache.size(cache)
- *   console.log(sizeAfterInvalidation) // 1
+ *   return [emptySize, sizeAfterAdding, sizeAfterInvalidation]
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [0, 2, 1]
  * ```
  *
  * @category combinators
@@ -2122,7 +2272,7 @@ export declare const size: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  *
  * **Example** (Reading active keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic key enumeration
@@ -2139,9 +2289,11 @@ export declare const size: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  *
  *   // Retrieve all active keys
  *   const keys = yield* Cache.keys(cache)
- *
- *   console.log(Array.from(keys).sort()) // ["cache", "hello", "world"]
+ *   return Array.from(keys).sort()
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => ["cache", "hello", "world"]
  * ```
  *
  * @category combinators
@@ -2154,7 +2306,7 @@ export declare const keys: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  *
  * **Example** (Reading all cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2170,10 +2322,11 @@ export declare const keys: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  *
  *   // Retrieve all cached values
  *   const values = yield* Cache.values(cache)
- *   const valuesArray = Array.from(values).sort()
- *
- *   console.log(valuesArray) // [1, 2, 3]
+ *   return Array.from(values).sort()
  * })
+ *
+ * const actual = await Effect.runPromise(program)
+ * actual // => [1, 2, 3]
  * ```
  *
  * @category combinators