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

package/src/Cache.ts

@@ -9,7 +9,6 @@
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
-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"
@@ -33,7 +32,7 @@ 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
@@ -50,12 +49,15 @@ 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*() {
@@ -68,16 +70,19 @@ 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
@@ -93,8 +98,11 @@ 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
@@ -129,7 +137,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>
 }
 
 /**
@@ -147,11 +157,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 }),
  *     {
@@ -166,8 +176,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
@@ -214,7 +227,7 @@ export const makeWith = <
  *
  * **Example** (Creating a basic cache)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic cache with string keys
@@ -226,13 +239,16 @@ export const makeWith = <
  *
  *   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*() {
@@ -258,11 +274,12 @@ export const makeWith = <
  *   })
  *
  *   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
@@ -288,7 +305,7 @@ export const make = <
 > =>
   makeWith<Key, A, E, R, ServiceMode>(options.lookup, {
     ...options,
-    timeToLive: options.timeToLive ? () => options.timeToLive! : defaultTimeToLive
+    timeToLive: options.timeToLive !== undefined ? () => options.timeToLive! : defaultTimeToLive
   })
 
 const Proto = {
@@ -317,7 +334,7 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  *
  * **Example** (Getting cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -328,20 +345,21 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  *
  *   // 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*() {
@@ -355,17 +373,19 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  *
  *   // 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
@@ -387,9 +407,11 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  *     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
@@ -408,7 +430,7 @@ export const get: {
    *
    * **Example** (Getting cached values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -419,20 +441,21 @@ export 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*() {
@@ -446,17 +469,19 @@ export 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
@@ -478,9 +503,11 @@ export 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
@@ -499,7 +526,7 @@ export const get: {
    *
    * **Example** (Getting cached values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -510,20 +537,21 @@ export 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*() {
@@ -537,17 +565,19 @@ export 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
@@ -569,9 +599,11 @@ export 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
@@ -587,210 +619,58 @@ export const get: {
         // Move the entry to the end of the map to keep it fresh
         MutableHashMap.remove(self.map, key)
         MutableHashMap.set(self.map, key, oentry.value)
-        return Deferred.await(oentry.value.deferred)
-      }
-      const deferred = Deferred.makeUnsafe</**
-       * Retrieves the value for a key, invoking the lookup function on a cache miss
-       * or expired entry.
-       *
-       * **Details**
-       *
-       * Concurrent `get` calls for the same missing key share the same pending
-       * lookup. The cache stores the lookup `Exit`, so failed lookups are cached and
-       * will fail again until the entry expires, is invalidated, or is refreshed.
-       *
-       * **Example** (Getting cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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 }
-       * })
-       * ```
-       *
-       * **Example** (Handling lookup failures)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Error handling when lookup fails
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make<string, number, string>({
-       *     capacity: 10,
-       *     lookup: (key: string) =>
-       *       key === "error"
-       *         ? Effect.fail("Lookup failed")
-       *         : Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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")
-       * })
-       * ```
-       *
-       * **Example** (Sharing concurrent lookups)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Concurrent access - multiple gets of same key only invoke lookup once
-       * const program = Effect.gen(function*() {
-       *   let lookupCount = 0
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) =>
-       *       Effect.sync(() => {
-       *         lookupCount++
-       *         return key.length
-       *       })
-       *   })
-       *
-       *   // Multiple concurrent gets
-       *   const results = yield* Effect.all([
-       *     Cache.get(cache, "hello"),
-       *     Cache.get(cache, "hello"),
-       *     Cache.get(cache, "hello")
-       *   ], { concurrency: "unbounded" })
-       *
-       *   console.log(results) // [5, 5, 5]
-       *   console.log(lookupCount) // 1 (lookup called only once)
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      A, /**
-       * Retrieves the value for a key, invoking the lookup function on a cache miss
-       * or expired entry.
-       *
-       * **Details**
-       *
-       * Concurrent `get` calls for the same missing key share the same pending
-       * lookup. The cache stores the lookup `Exit`, so failed lookups are cached and
-       * will fail again until the entry expires, is invalidated, or is refreshed.
-       *
-       * **Example** (Getting cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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 }
-       * })
-       * ```
-       *
-       * **Example** (Handling lookup failures)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Error handling when lookup fails
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make<string, number, string>({
-       *     capacity: 10,
-       *     lookup: (key: string) =>
-       *       key === "error"
-       *         ? Effect.fail("Lookup failed")
-       *         : Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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")
-       * })
-       * ```
-       *
-       * **Example** (Sharing concurrent lookups)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Concurrent access - multiple gets of same key only invoke lookup once
-       * const program = Effect.gen(function*() {
-       *   let lookupCount = 0
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) =>
-       *       Effect.sync(() => {
-       *         lookupCount++
-       *         return key.length
-       *       })
-       *   })
-       *
-       *   // Multiple concurrent gets
-       *   const results = yield* Effect.all([
-       *     Cache.get(cache, "hello"),
-       *     Cache.get(cache, "hello"),
-       *     Cache.get(cache, "hello")
-       *   ], { concurrency: "unbounded" })
-       *
-       *   console.log(results) // [5, 5, 5]
-       *   console.log(lookupCount) // 1 (lookup called only once)
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      E>()
-      const entry: Entry<A, E> = {
-        expiresAt: undefined,
-        deferred
-      }
-      MutableHashMap.set(self.map, key, entry)
-      if (Number.isFinite(self.capacity)) {
-        checkCapacity(self)
+        return oentry.value.await()
       }
-      return effect.onExit(self.lookup(key), (exit) => {
-        Deferred.doneUnsafe(deferred, exit)
+      const entry = new EntryImpl(fiber, self.lookup(key))
+      entry.fiber.addObserver((exit) => {
+        if (effect.exitHasInterrupts(exit)) {
+          const current = MutableHashMap.get(self.map, key)
+          if (Option.isSome(current) && current.value === entry) {
+            MutableHashMap.remove(self.map, key)
+          }
+          return
+        }
         const ttl = self.timeToLive(exit, key)
         if (Duration.isFinite(ttl)) {
           entry.expiresAt = fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
         } else if (Duration.isZero(ttl)) {
           MutableHashMap.remove(self.map, key)
         }
-        return effect.void
       })
+      MutableHashMap.set(self.map, key, entry)
+      if (Number.isFinite(self.capacity)) {
+        checkCapacity(self)
+      }
+      return entry.await()
     })
 )
 
+class EntryImpl<A, E> implements Entry<A, E> {
+  expiresAt: number | undefined
+  awaiters: number
+  fiber: Fiber.Fiber<A, E>
+
+  constructor(
+    parent: Fiber.Fiber<unknown, unknown>,
+    valueEffect: Effect.Effect<A, E, any>
+  ) {
+    this.fiber = effect.forkUnsafe(parent, valueEffect, true, true)
+    this.awaiters = 0
+    this.expiresAt = undefined
+  }
+
+  await(): Effect.Effect<A, E> {
+    const exit = this.fiber.pollUnsafe()
+    if (exit) return exit
+    this.awaiters++
+    return effect.onExit(effect.fiberJoin(this.fiber), () => {
+      this.awaiters--
+      if (this.awaiters > 0 || this.fiber.pollUnsafe()) return effect.void
+      return effect.fiberInterrupt(this.fiber)
+    })
+  }
+}
+
 const hasExpired = <A, E>(entry: Entry<A, E>, fiber: Fiber.Fiber<unknown, unknown>): boolean => {
   if (entry.expiresAt === undefined) {
     return false
@@ -821,8 +701,8 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  *
  * **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({
@@ -832,23 +712,23 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  *
  *   // 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
@@ -864,21 +744,23 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  *
  *   // 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*() {
@@ -898,11 +780,12 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  *   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
@@ -921,8 +804,8 @@ export 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({
@@ -932,23 +815,23 @@ export 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
@@ -964,21 +847,23 @@ export 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*() {
@@ -998,11 +883,12 @@ export 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
@@ -1021,8 +907,8 @@ export 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({
@@ -1032,23 +918,23 @@ export 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
@@ -1064,21 +950,23 @@ export 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*() {
@@ -1098,11 +986,12 @@ export 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
@@ -1114,7 +1003,7 @@ export const getOption: {
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>, E> =>
     core.withFiber((fiber) => {
       const entry = getImpl(self, key, fiber)
-      return entry ? effect.asSome(Deferred.await(entry.deferred)) : effect.succeedNone
+      return entry ? effect.asSome(entry.await()) : effect.succeedNone
     })
 )
 
@@ -1192,7 +1081,7 @@ export const getSuccess: {
   2,
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>> =>
     core.withFiber((fiber) => {
-      const exit = getImpl(self, key, fiber)?.deferred.effect as Exit.Exit<A, E> | undefined
+      const exit = getImpl(self, key, fiber)?.fiber.pollUnsafe()
       if (exit && effect.exitIsSuccess(exit)) {
         return effect.succeedSome(exit.value)
       }
@@ -1206,7 +1095,7 @@ export const getSuccess: {
  *
  * **Example** (Setting values directly)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1217,14 +1106,16 @@ export 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
@@ -1241,13 +1132,16 @@ export 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"
  *
@@ -1261,17 +1155,21 @@ export 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
@@ -1284,14 +1182,18 @@ export 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
@@ -1304,7 +1206,7 @@ export const set: {
    *
    * **Example** (Setting values directly)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1315,14 +1217,16 @@ export 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
@@ -1339,13 +1243,16 @@ export 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"
    *
@@ -1359,17 +1266,21 @@ export 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
@@ -1382,14 +1293,18 @@ export 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
@@ -1402,7 +1317,7 @@ export const set: {
    *
    * **Example** (Setting values directly)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1413,14 +1328,16 @@ export 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
@@ -1437,13 +1354,16 @@ export 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"
    *
@@ -1457,17 +1377,21 @@ export 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
@@ -1480,14 +1404,18 @@ export 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
@@ -1499,213 +1427,16 @@ export const set: {
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, value: A): Effect.Effect<void> =>
     core.withFiber((fiber) => {
       const exit = core.exitSucceed(value)
-      const deferred = Deferred.makeUnsafe</**
-       * Sets the value associated with the specified key in the cache. This will
-       * overwrite any existing value for that key, skipping the lookup function.
-       *
-       * **Example** (Setting values directly)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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)
-       * })
-       * ```
-       *
-       * **Example** (Overwriting cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Overwriting existing cached values
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // First get populates via lookup
-       *   const original = yield* Cache.get(cache, "test") // 4
-       *
-       *   // Set overwrites the cached value
-       *   yield* Cache.set(cache, "test", 999)
-       *   const updated = yield* Cache.get(cache, "test") // 999
-       *
-       *   console.log({ original, updated })
-       * })
-       * ```
-       *
-       * **Example** (Applying TTL to set values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       * import { TestClock } from "effect/testing"
-       *
-       * // TTL behavior with set operations
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length),
-       *     timeToLive: "1 hour"
-       *   })
-       *
-       *   // Set value with TTL applied
-       *   yield* Cache.set(cache, "temporary", 123)
-       *   console.log(yield* Cache.has(cache, "temporary")) // true
-       *
-       *   // Advance time past TTL
-       *   yield* TestClock.adjust("2 hours")
-       *   console.log(yield* Cache.has(cache, "temporary")) // false
-       * })
-       * ```
-       *
-       * **Example** (Enforcing capacity when setting values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Capacity enforcement with set operations
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 2,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // Fill cache to capacity
-       *   yield* Cache.set(cache, "a", 1)
-       *   yield* Cache.set(cache, "b", 2)
-       *   console.log(yield* Cache.size(cache)) // 2
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      A, /**
-       * Sets the value associated with the specified key in the cache. This will
-       * overwrite any existing value for that key, skipping the lookup function.
-       *
-       * **Example** (Setting values directly)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // 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)
-       * })
-       * ```
-       *
-       * **Example** (Overwriting cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Overwriting existing cached values
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // First get populates via lookup
-       *   const original = yield* Cache.get(cache, "test") // 4
-       *
-       *   // Set overwrites the cached value
-       *   yield* Cache.set(cache, "test", 999)
-       *   const updated = yield* Cache.get(cache, "test") // 999
-       *
-       *   console.log({ original, updated })
-       * })
-       * ```
-       *
-       * **Example** (Applying TTL to set values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       * import { TestClock } from "effect/testing"
-       *
-       * // TTL behavior with set operations
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 100,
-       *     lookup: (key: string) => Effect.succeed(key.length),
-       *     timeToLive: "1 hour"
-       *   })
-       *
-       *   // Set value with TTL applied
-       *   yield* Cache.set(cache, "temporary", 123)
-       *   console.log(yield* Cache.has(cache, "temporary")) // true
-       *
-       *   // Advance time past TTL
-       *   yield* TestClock.adjust("2 hours")
-       *   console.log(yield* Cache.has(cache, "temporary")) // false
-       * })
-       * ```
-       *
-       * **Example** (Enforcing capacity when setting values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Capacity enforcement with set operations
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 2,
-       *     lookup: (key: string) => Effect.succeed(key.length)
-       *   })
-       *
-       *   // Fill cache to capacity
-       *   yield* Cache.set(cache, "a", 1)
-       *   yield* Cache.set(cache, "b", 2)
-       *   console.log(yield* Cache.size(cache)) // 2
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      E>()
-      Deferred.doneUnsafe(deferred, exit)
+      const entry = new EntryImpl(fiber, exit)
       const ttl = self.timeToLive(exit, key)
       if (Duration.isZero(ttl)) {
         MutableHashMap.remove(self.map, key)
         return effect.void
       }
-      MutableHashMap.set(self.map, key, {
-        deferred,
-        expiresAt: Duration.isFinite(ttl)
-          ? fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
-          : undefined
-      })
+      entry.expiresAt = Duration.isFinite(ttl)
+        ? fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
+        : undefined
+      MutableHashMap.set(self.map, key, entry)
       checkCapacity(self)
       return effect.void
     })
@@ -1721,7 +1452,7 @@ export const set: {
  *
  * **Example** (Checking for cached keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1731,17 +1462,21 @@ export 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"
  *
@@ -1755,21 +1490,25 @@ export 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
@@ -1785,16 +1524,16 @@ export 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
@@ -1811,7 +1550,7 @@ export const has: {
    *
    * **Example** (Checking for cached keys)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1821,17 +1560,21 @@ export 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"
    *
@@ -1845,21 +1588,25 @@ export 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
@@ -1875,16 +1622,16 @@ export 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
@@ -1901,7 +1648,7 @@ export const has: {
    *
    * **Example** (Checking for cached keys)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -1911,17 +1658,21 @@ export 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"
    *
@@ -1935,21 +1686,25 @@ export 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
@@ -1965,16 +1720,16 @@ export 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
@@ -1995,7 +1750,7 @@ export const has: {
  *
  * **Example** (Invalidating cached entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2006,11 +1761,11 @@ export 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")
@@ -2029,7 +1784,11 @@ export 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
@@ -2041,7 +1800,7 @@ export const invalidate: {
    *
    * **Example** (Invalidating cached entries)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -2052,11 +1811,11 @@ export 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")
@@ -2075,7 +1834,11 @@ export 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
@@ -2087,7 +1850,7 @@ export const invalidate: {
    *
    * **Example** (Invalidating cached entries)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -2098,11 +1861,11 @@ export 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")
@@ -2121,7 +1884,11 @@ export 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
@@ -2139,7 +1906,7 @@ export const invalidate: {
  *
  * **Example** (Invalidating entries conditionally)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2158,8 +1925,7 @@ export 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(
@@ -2167,8 +1933,7 @@ export 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(
@@ -2176,7 +1941,6 @@ export const invalidate: {
  *     "nonexistent",
  *     () => true
  *   )
- *   console.log(invalidated3) // false
  *
  *   // Returns false for failed cached values
  *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -2191,8 +1955,11 @@ export 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
@@ -2205,7 +1972,7 @@ export const invalidateWhen: {
    *
    * **Example** (Invalidating entries conditionally)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -2224,8 +1991,7 @@ export 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(
@@ -2233,8 +1999,7 @@ export 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(
@@ -2242,7 +2007,6 @@ export const invalidateWhen: {
    *     "nonexistent",
    *     () => true
    *   )
-   *   console.log(invalidated3) // false
    *
    *   // Returns false for failed cached values
    *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -2257,8 +2021,11 @@ export 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
@@ -2271,7 +2038,7 @@ export const invalidateWhen: {
    *
    * **Example** (Invalidating entries conditionally)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * const program = Effect.gen(function*() {
@@ -2290,8 +2057,7 @@ export 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(
@@ -2299,8 +2065,7 @@ export 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(
@@ -2308,7 +2073,6 @@ export const invalidateWhen: {
    *     "nonexistent",
    *     () => true
    *   )
-   *   console.log(invalidated3) // false
    *
    *   // Returns false for failed cached values
    *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -2323,8 +2087,11 @@ export 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
@@ -2339,7 +2106,7 @@ export const invalidateWhen: {
       if (oentry === undefined) {
         return effect.succeed(false)
       }
-      return Deferred.await(oentry.deferred).pipe(
+      return oentry.await().pipe(
         effect.map((value) => {
           if (f(value)) {
             MutableHashMap.remove(self.map, key)
@@ -2362,7 +2129,7 @@ export const invalidateWhen: {
  *
  * **Example** (Refreshing cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Force refresh of existing cached values
@@ -2375,25 +2142,25 @@ export 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"
  *
@@ -2409,20 +2176,24 @@ export 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
@@ -2434,11 +2205,14 @@ export 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
@@ -2455,7 +2229,7 @@ export const refresh: {
    *
    * **Example** (Refreshing cached values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * // Force refresh of existing cached values
@@ -2468,25 +2242,25 @@ export 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"
    *
@@ -2502,20 +2276,24 @@ export 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
@@ -2527,11 +2305,14 @@ export 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
@@ -2548,7 +2329,7 @@ export const refresh: {
    *
    * **Example** (Refreshing cached values)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Cache, Effect } from "effect"
    *
    * // Force refresh of existing cached values
@@ -2561,25 +2342,25 @@ export 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"
    *
@@ -2595,20 +2376,24 @@ export 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
@@ -2620,11 +2405,14 @@ export 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
@@ -2635,202 +2423,17 @@ export const refresh: {
   2,
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R> =>
     core.withFiber((fiber) => {
-      const deferred = Deferred.makeUnsafe</**
-       * Forces a refresh of the value associated with the specified key in the cache.
-       *
-       * **Details**
-       *
-       * It will always invoke the lookup function to construct a new value,
-       * overwriting any existing value for that key.
-       *
-       * **Example** (Refreshing cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Force refresh of existing cached values
-       * const program = Effect.gen(function*() {
-       *   let counter = 0
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.sync(() => `${key}-${++counter}`)
-       *   })
-       *
-       *   // 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"
-       * })
-       * ```
-       *
-       * **Example** (Resetting TTL on refresh)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       * import { TestClock } from "effect/testing"
-       *
-       * // Refresh resets TTL (Time To Live)
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(key.length),
-       *     timeToLive: "1 hour"
-       *   })
-       *
-       *   yield* Cache.get(cache, "test")
-       *   yield* TestClock.adjust("45 minutes")
-       *
-       *   // Entry would normally expire in 15 minutes
-       *   console.log(yield* Cache.has(cache, "test")) // true
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * **Example** (Refreshing missing keys)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Refresh non-existent keys
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(`value-for-${key}`)
-       *   })
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      A, /**
-       * Forces a refresh of the value associated with the specified key in the cache.
-       *
-       * **Details**
-       *
-       * It will always invoke the lookup function to construct a new value,
-       * overwriting any existing value for that key.
-       *
-       * **Example** (Refreshing cached values)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Force refresh of existing cached values
-       * const program = Effect.gen(function*() {
-       *   let counter = 0
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.sync(() => `${key}-${++counter}`)
-       *   })
-       *
-       *   // 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"
-       * })
-       * ```
-       *
-       * **Example** (Resetting TTL on refresh)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       * import { TestClock } from "effect/testing"
-       *
-       * // Refresh resets TTL (Time To Live)
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(key.length),
-       *     timeToLive: "1 hour"
-       *   })
-       *
-       *   yield* Cache.get(cache, "test")
-       *   yield* TestClock.adjust("45 minutes")
-       *
-       *   // Entry would normally expire in 15 minutes
-       *   console.log(yield* Cache.has(cache, "test")) // true
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * **Example** (Refreshing missing keys)
-       *
-       * ```ts
-       * import { Cache, Effect } from "effect"
-       *
-       * // Refresh non-existent keys
-       * const program = Effect.gen(function*() {
-       *   const cache = yield* Cache.make({
-       *     capacity: 10,
-       *     lookup: (key: string) => Effect.succeed(`value-for-${key}`)
-       *   })
-       *
-       *   // 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
-       * })
-       * ```
-       *
-       * @category combinators
-       * @since 4.0.0
-       */
-      E>()
-      const entry: Entry<A, E> = {
-        expiresAt: undefined,
-        deferred
-      }
+      const entry = new EntryImpl(fiber, self.lookup(key))
       const existing = getImpl(self, key, fiber, false) !== undefined
       if (!existing) {
         MutableHashMap.set(self.map, key, entry)
         checkCapacity(self)
       }
-      return effect.onExit(self.lookup(key), (exit) => {
-        Deferred.doneUnsafe(deferred, exit)
+      entry.fiber.addObserver((exit) => {
+        if (effect.exitHasInterrupts(exit)) {
+          if (!existing) MutableHashMap.remove(self.map, key)
+          return
+        }
         const ttl = self.timeToLive(exit, key)
         if (Duration.isZero(ttl)) {
           MutableHashMap.remove(self.map, key)
@@ -2842,8 +2445,8 @@ export const refresh: {
         if (existing) {
           MutableHashMap.set(self.map, key, entry)
         }
-        return effect.void
       })
+      return entry.await()
     })
 )
 
@@ -2852,7 +2455,7 @@ export const refresh: {
  *
  * **Example** (Invalidating all entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Clear all cached entries at once
@@ -2867,18 +2470,29 @@ export 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
@@ -2900,7 +2514,7 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
  *
  * **Example** (Reading cache size)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2911,19 +2525,20 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
  *
  *   // 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
@@ -2937,7 +2552,7 @@ export const size = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<num
  *
  * **Example** (Reading active keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic key enumeration
@@ -2954,9 +2569,11 @@ export const size = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<num
  *
  *   // 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
@@ -2980,7 +2597,7 @@ export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Ite
  *
  * **Example** (Reading all cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -2996,10 +2613,11 @@ export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Ite
  *
  *   // 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
@@ -3028,10 +2646,10 @@ export const entries = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<
     const now = fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe()
     return effect.succeed(Iterable.filterMap(self.map, ([key, entry]) => {
       if (entry.expiresAt === undefined || entry.expiresAt > now) {
-        const exit = entry.deferred.effect
-        return !core.isExit(exit) || effect.exitIsFailure(exit)
-          ? Result.failVoid
-          : Result.succeed([key, exit.value as A])
+        const exit = entry.fiber.pollUnsafe()
+        return exit && exit._tag === "Success"
+          ? Result.succeed([key, exit.value])
+          : Result.failVoid
       }
       MutableHashMap.remove(self.map, key)
       return Result.failVoid