effect 4.0.0-beta.101 → 4.0.0-beta.103

package/dist/Cache.js

@@ -34,11 +34,11 @@ const TypeId = "~effect/Cache";
  *
  * **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 }),
  *     {
@@ -53,8 +53,11 @@ const TypeId = "~effect/Cache";
  *     }
  *   )
  *
- *   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
@@ -79,7 +82,7 @@ export const makeWith = (lookup, options) => effect.contextWith(context => {
  *
  * **Example** (Creating a basic cache)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic cache with string keys
@@ -91,13 +94,16 @@ export const makeWith = (lookup, options) => effect.contextWith(context => {
  *
  *   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*() {
@@ -123,11 +129,12 @@ export const makeWith = (lookup, options) => effect.contextWith(context => {
  *   })
  *
  *   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
@@ -161,7 +168,7 @@ const defaultTimeToLive = (_, _key) => Duration.infinity;
  *
  * **Example** (Getting cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -172,20 +179,21 @@ const defaultTimeToLive = (_, _key) => Duration.infinity;
  *
  *   // 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*() {
@@ -199,17 +207,19 @@ const defaultTimeToLive = (_, _key) => Duration.infinity;
  *
  *   // 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
@@ -231,9 +241,11 @@ const defaultTimeToLive = (_, _key) => Duration.infinity;
  *     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
@@ -250,7 +262,10 @@ export const get = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber => {
   const entry = new EntryImpl(fiber, self.lookup(key));
   entry.fiber.addObserver(exit => {
     if (effect.exitHasInterrupts(exit)) {
-      MutableHashMap.remove(self.map, key);
+      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);
@@ -314,8 +329,8 @@ const checkCapacity = self => {
  *
  * **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({
@@ -325,23 +340,23 @@ const checkCapacity = self => {
  *
  *   // 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
@@ -357,21 +372,23 @@ const checkCapacity = self => {
  *
  *   // 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*() {
@@ -391,11 +408,12 @@ const checkCapacity = self => {
  *   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
@@ -447,7 +465,7 @@ export const getSuccess = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fib
  *
  * **Example** (Setting values directly)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -458,14 +476,16 @@ export const getSuccess = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fib
  *
  *   // 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
@@ -482,13 +502,16 @@ export const getSuccess = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fib
  *   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"
  *
@@ -502,17 +525,21 @@ export const getSuccess = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fib
  *
  *   // 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
@@ -525,14 +552,18 @@ export const getSuccess = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fib
  *   // 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
@@ -561,7 +592,7 @@ export const set = /*#__PURE__*/dual(3, (self, key, value) => core.withFiber(fib
  *
  * **Example** (Checking for cached keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -571,17 +602,21 @@ export const set = /*#__PURE__*/dual(3, (self, key, value) => core.withFiber(fib
  *   })
  *
  *   // 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"
  *
@@ -595,21 +630,25 @@ export const set = /*#__PURE__*/dual(3, (self, key, value) => core.withFiber(fib
  *
  *   // 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
@@ -625,16 +664,16 @@ export const set = /*#__PURE__*/dual(3, (self, key, value) => core.withFiber(fib
  *
  *   // 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
@@ -649,7 +688,7 @@ export const has = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber => {
  *
  * **Example** (Invalidating cached entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -660,11 +699,11 @@ export const has = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber => {
  *
  *   // 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")
@@ -683,7 +722,11 @@ export const has = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber => {
  *   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
@@ -698,7 +741,7 @@ export const invalidate = /*#__PURE__*/dual(2, (self, key) => effect.sync(() =>
  *
  * **Example** (Invalidating entries conditionally)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -717,8 +760,7 @@ export const invalidate = /*#__PURE__*/dual(2, (self, key) => effect.sync(() =>
  *     "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(
@@ -726,8 +768,7 @@ export const invalidate = /*#__PURE__*/dual(2, (self, key) => effect.sync(() =>
  *     "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(
@@ -735,7 +776,6 @@ export const invalidate = /*#__PURE__*/dual(2, (self, key) => effect.sync(() =>
  *     "nonexistent",
  *     () => true
  *   )
- *   console.log(invalidated3) // false
  *
  *   // Returns false for failed cached values
  *   const cacheWithErrors = yield* Cache.make<string, number, string>({
@@ -750,8 +790,11 @@ export const invalidate = /*#__PURE__*/dual(2, (self, key) => effect.sync(() =>
  *     "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
@@ -780,7 +823,7 @@ export const invalidateWhen = /*#__PURE__*/dual(3, (self, key, f) => core.withFi
  *
  * **Example** (Refreshing cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Force refresh of existing cached values
@@ -793,25 +836,25 @@ export const invalidateWhen = /*#__PURE__*/dual(3, (self, key, f) => core.withFi
  *
  *   // 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"
  *
@@ -827,20 +870,24 @@ export const invalidateWhen = /*#__PURE__*/dual(3, (self, key, f) => core.withFi
  *   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
@@ -852,11 +899,14 @@ export const invalidateWhen = /*#__PURE__*/dual(3, (self, key, f) => core.withFi
  *
  *   // 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
@@ -891,7 +941,7 @@ export const refresh = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber
  *
  * **Example** (Invalidating all entries)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Clear all cached entries at once
@@ -906,18 +956,29 @@ export const refresh = /*#__PURE__*/dual(2, (self, key) => core.withFiber(fiber
  *   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
@@ -937,7 +998,7 @@ export const invalidateAll = self => effect.sync(() => {
  *
  * **Example** (Reading cache size)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -948,19 +1009,20 @@ export const invalidateAll = self => effect.sync(() => {
  *
  *   // 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
@@ -972,7 +1034,7 @@ export const size = self => effect.sync(() => MutableHashMap.size(self.map));
  *
  * **Example** (Reading active keys)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * // Basic key enumeration
@@ -989,9 +1051,11 @@ export const size = self => effect.sync(() => MutableHashMap.size(self.map));
  *
  *   // 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
@@ -1013,7 +1077,7 @@ export const keys = self => core.withFiber(fiber => {
  *
  * **Example** (Reading all cached values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Cache, Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1029,10 +1093,11 @@ export const keys = self => core.withFiber(fiber => {
  *
  *   // 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