effect 4.0.0-beta.65 → 4.0.0-beta.67

package/src/Cache.ts

@@ -1,4 +1,39 @@
 /**
+ * The `Cache` module provides an effectful, mutable key-value cache for values
+ * that are computed by a lookup function. A `Cache<Key, A, E, R>` stores lookup
+ * results for keys, shares concurrent lookups for the same key, and manages
+ * entry lifetime with capacity limits and optional time-to-live policies.
+ *
+ * **Mental model**
+ *
+ * - A cache is created from a lookup function and a maximum capacity
+ * - {@link get} returns a cached value when present, or runs the lookup on a miss
+ * - Concurrent misses for the same key share one pending lookup
+ * - Lookup failures are cached as failures until the entry expires, is invalidated, or is refreshed
+ * - Entries can live forever, expire after a fixed duration, or use a dynamic TTL based on the lookup `Exit`
+ * - Capacity is enforced by removing the oldest stored entries when new entries are added
+ *
+ * **Common tasks**
+ *
+ * - Create a cache: {@link make}, {@link makeWith}
+ * - Read values: {@link get}, {@link getOption}, {@link getSuccess}
+ * - Seed or overwrite values: {@link set}
+ * - Refresh values: {@link refresh}
+ * - Remove entries: {@link invalidate}, {@link invalidateWhen}, {@link invalidateAll}
+ * - Inspect contents: {@link has}, {@link size}, {@link keys}, {@link values}, {@link entries}
+ *
+ * **Gotchas**
+ *
+ * - {@link getOption} does not run the lookup; it only reads an existing non-expired entry
+ * - {@link size} may include expired entries until they are observed and removed
+ * - {@link values} and {@link entries} include only successfully resolved entries
+ * - Use `Data` or another `Equal`-compatible key type when keys need structural equality
+ *
+ * **See also**
+ *
+ * - {@link Duration} for configuring fixed or dynamic time-to-live values
+ * - {@link Effect} for the lookup effects used to compute cached values
+ *
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
@@ -24,7 +59,8 @@ const TypeId = "~effect/Cache"
  * A cache interface that provides a mutable key-value store with automatic TTL management,
  * capacity limits, and lookup functions for cache misses.
  *
- * @example
+ * **Example** (Creating a basic cache)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -44,7 +80,8 @@ const TypeId = "~effect/Cache"
  * })
  * ```
  *
- * @example
+ * **Example** (Handling lookup failures)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -66,7 +103,8 @@ const TypeId = "~effect/Cache"
  * })
  * ```
  *
- * @example
+ * **Example** (Using complex keys with TTL)
+ *
  * ```ts
  * import { Cache, Data, Duration, Effect } from "effect"
  *
@@ -87,8 +125,8 @@ const TypeId = "~effect/Cache"
  * })
  * ```
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface Cache<in out Key, in out A, in out E = never, out R = never> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -99,11 +137,17 @@ export interface Cache<in out Key, in out A, in out E = never, out R = never> ex
 }
 
 /**
- * Represents a cache entry containing a deferred value and optional expiration time.
- * This is used internally by the cache implementation to track cached values and their lifetimes.
+ * Represents a low-level cache entry containing a deferred lookup result and
+ * an optional expiration timestamp.
+ *
+ * **Notes**
+ *
+ * An `expiresAt` value of `undefined` means the entry does not expire. Most
+ * users should interact with entries through the `Cache` combinators rather
+ * than constructing them directly.
  *
- * @since 4.0.0
  * @category Models
+ * @since 4.0.0
  */
 export interface Entry<A, E> {
   expiresAt: number | undefined
@@ -116,7 +160,8 @@ export interface Entry<A, E> {
  * The timeToLive function receives both the exit result and the key, allowing
  * for flexible TTL policies based on success/failure state and key characteristics.
  *
- * @example
+ * **Example** (Using dynamic time to live)
+ *
  * ```ts
  * import { Cache, Effect, Exit } from "effect"
  *
@@ -140,8 +185,8 @@ export interface Entry<A, E> {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const makeWith = <
   Key,
@@ -179,7 +224,8 @@ export const makeWith = <
  * This is the basic cache constructor where all entries share the same TTL.
  * The lookup function will be called when a key is not found or has expired.
  *
- * @example
+ * **Example** (Creating a basic cache)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -196,12 +242,17 @@ export const makeWith = <
  * })
  * ```
  *
- * @example
+ * **Example** (Creating a cache with TTL)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
- * // Cache with TTL and async lookup
- * const fetchUserCache = Effect.gen(function*() {
+ * const program = Effect.gen(function*() {
+ *   const users = new Map([
+ *     [123, { name: "Ada", email: "ada@example.com" }],
+ *     [456, { name: "Grace", email: "grace@example.com" }]
+ *   ])
+ *
  *   const cache = yield* Cache.make<
  *     number,
  *     { name: string; email: string },
@@ -209,22 +260,25 @@ export const makeWith = <
  *   >({
  *     capacity: 500,
  *     lookup: (userId) =>
- *       Effect.tryPromise({
- *         try: () => fetch(`/api/users/${userId}`).then((r) => r.json()),
- *         catch: () => "Failed to fetch user"
+ *       Effect.suspend(() => {
+ *         const user = users.get(userId)
+ *         return user === undefined
+ *           ? Effect.fail(`User ${userId} not found`)
+ *           : Effect.succeed(user)
  *       }),
  *     timeToLive: "15 minutes"
  *   })
  *
- *   // First call fetches from API, second call returns cached result
  *   const user1 = yield* Cache.get(cache, 123)
- *   const user2 = yield* Cache.get(cache, 123) // From cache
- *   return { user1, user2 }
+ *   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" }
  * })
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export const make = <
   Key,
@@ -264,12 +318,17 @@ const Proto = {
 const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Duration => Duration.infinity
 
 /**
- * Retrieves the value associated with the specified key from the cache.
+ * 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.
  *
- * If the key is not present or has expired, it will invoke the lookup function
- * to construct the value, store it in the cache, and return it.
+ * **Example** (Getting cached values)
  *
- * @example
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -291,7 +350,8 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * })
  * ```
  *
- * @example
+ * **Example** (Handling lookup failures)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -315,7 +375,8 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * })
  * ```
  *
- * @example
+ * **Example** (Sharing concurrent lookups)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -343,17 +404,22 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const get: {
   /**
-   * Retrieves the value associated with the specified key from the cache.
+   * 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.
    *
-   * If the key is not present or has expired, it will invoke the lookup function
-   * to construct the value, store it in the cache, and return it.
+   * **Example** (Getting cached values)
    *
-   * @example
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -375,7 +441,8 @@ export const get: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Handling lookup failures)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -399,7 +466,8 @@ export const get: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Sharing concurrent lookups)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -427,17 +495,22 @@ export const get: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<A, E, R>
   /**
-   * Retrieves the value associated with the specified key from the cache.
+   * 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.
    *
-   * If the key is not present or has expired, it will invoke the lookup function
-   * to construct the value, store it in the cache, and return it.
+   * **Example** (Getting cached values)
    *
-   * @example
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -459,7 +532,8 @@ export const get: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Handling lookup failures)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -483,7 +557,8 @@ export const get: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Sharing concurrent lookups)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -511,8 +586,8 @@ export const get: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R>
 } = dual(
@@ -527,12 +602,17 @@ export const get: {
         return Deferred.await(oentry.value.deferred)
       }
       const deferred = Deferred.makeUnsafe</**
-       * Retrieves the value associated with the specified key from the cache.
+       * Retrieves the value for a key, invoking the lookup function on a cache miss
+       * or expired entry.
+       *
+       * **Details**
        *
-       * If the key is not present or has expired, it will invoke the lookup function
-       * to construct the value, store it in the cache, and return it.
+       * 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)
        *
-       * @example
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -554,7 +634,8 @@ export const get: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Handling lookup failures)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -578,7 +659,8 @@ export const get: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Sharing concurrent lookups)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -606,16 +688,21 @@ export const get: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       A, /**
-       * Retrieves the value associated with the specified key from the cache.
+       * Retrieves the value for a key, invoking the lookup function on a cache miss
+       * or expired entry.
+       *
+       * **Details**
        *
-       * If the key is not present or has expired, it will invoke the lookup function
-       * to construct the value, store it in the cache, and return it.
+       * 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)
        *
-       * @example
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -637,7 +724,8 @@ export const get: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Handling lookup failures)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -661,7 +749,8 @@ export const get: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Sharing concurrent lookups)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -689,8 +778,8 @@ export const get: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       E>()
       const entry: Entry<A, E> = {
@@ -733,14 +822,17 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
 }
 
 /**
- * Retrieves the value associated with the specified key from the cache,
- * returning an `Option` that is `Some` if the key exists and has not expired,
- * or `None` if the key does not exist or has expired.
+ * Reads an existing cache entry without invoking the lookup function.
+ *
+ * **Details**
  *
- * Unlike `get`, this function will not invoke the lookup function if the key
- * is missing or expired.
+ * Returns `Option.none()` when the key is missing or expired, and `Option.some`
+ * when a cached lookup has succeeded. If the entry is still pending, waits for
+ * it to complete. If the cached or pending lookup fails, this effect fails with
+ * the same error.
+ *
+ * **Example** (Reading cached values without lookup)
  *
- * @example
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -765,7 +857,8 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  * })
  * ```
  *
- * @example
+ * **Example** (Skipping expired entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -794,7 +887,8 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  * })
  * ```
  *
- * @example
+ * **Example** (Waiting for pending lookups)
+ *
  * ```ts
  * import { Cache, Deferred, Effect, Fiber } from "effect"
  *
@@ -817,22 +911,28 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  *
  *   const result = yield* Fiber.join(optionFiber)
  *   console.log(result) // Option.some(42)
+ *
+ *   const value = yield* Fiber.join(getFiber)
+ *   console.log(value) // 42
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const getOption: {
   /**
-   * Retrieves the value associated with the specified key from the cache,
-   * returning an `Option` that is `Some` if the key exists and has not expired,
-   * or `None` if the key does not exist or has expired.
+   * Reads an existing cache entry without invoking the lookup function.
    *
-   * Unlike `get`, this function will not invoke the lookup function if the key
-   * is missing or expired.
+   * **Details**
+   *
+   * Returns `Option.none()` when the key is missing or expired, and `Option.some`
+   * when a cached lookup has succeeded. If the entry is still pending, waits for
+   * it to complete. If the cached or pending lookup fails, this effect fails with
+   * the same error.
+   *
+   * **Example** (Reading cached values without lookup)
    *
-   * @example
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -857,7 +957,8 @@ export const getOption: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Skipping expired entries)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -886,7 +987,8 @@ export const getOption: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Waiting for pending lookups)
+   *
    * ```ts
    * import { Cache, Deferred, Effect, Fiber } from "effect"
    *
@@ -909,22 +1011,28 @@ export const getOption: {
    *
    *   const result = yield* Fiber.join(optionFiber)
    *   console.log(result) // Option.some(42)
+   *
+   *   const value = yield* Fiber.join(getFiber)
+   *   console.log(value) // 42
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<Option.Option<A>, E>
   /**
-   * Retrieves the value associated with the specified key from the cache,
-   * returning an `Option` that is `Some` if the key exists and has not expired,
-   * or `None` if the key does not exist or has expired.
+   * Reads an existing cache entry without invoking the lookup function.
+   *
+   * **Details**
+   *
+   * Returns `Option.none()` when the key is missing or expired, and `Option.some`
+   * when a cached lookup has succeeded. If the entry is still pending, waits for
+   * it to complete. If the cached or pending lookup fails, this effect fails with
+   * the same error.
    *
-   * Unlike `get`, this function will not invoke the lookup function if the key
-   * is missing or expired.
+   * **Example** (Reading cached values without lookup)
    *
-   * @example
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -949,7 +1057,8 @@ export const getOption: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Skipping expired entries)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -978,7 +1087,8 @@ export const getOption: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Waiting for pending lookups)
+   *
    * ```ts
    * import { Cache, Deferred, Effect, Fiber } from "effect"
    *
@@ -1001,11 +1111,14 @@ export const getOption: {
    *
    *   const result = yield* Fiber.join(optionFiber)
    *   console.log(result) // Option.some(42)
+   *
+   *   const value = yield* Fiber.join(getFiber)
+   *   console.log(value) // 42
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>, E>
 } = dual(
@@ -1040,24 +1153,24 @@ const getImpl = <Key, A, E, R>(
  * Retrieves the value associated with the specified key from the cache, only if
  * it contains a resolved successful value.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const getSuccess: {
   /**
    * Retrieves the value associated with the specified key from the cache, only if
    * it contains a resolved successful value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, R>(key: Key): <E>(self: Cache<Key, A, E, R>) => Effect.Effect<Option.Option<A>>
   /**
    * Retrieves the value associated with the specified key from the cache, only if
    * it contains a resolved successful value.
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>>
 } = dual(
@@ -1076,7 +1189,8 @@ export const getSuccess: {
  * 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
+ * **Example** (Setting values directly)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1093,7 +1207,8 @@ export const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Overwriting cached values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1115,7 +1230,8 @@ export const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Applying TTL to set values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -1138,7 +1254,8 @@ export const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Enforcing capacity when setting values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1162,15 +1279,16 @@ export const getSuccess: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
    * 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
+   * **Example** (Setting values directly)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1187,7 +1305,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Overwriting cached values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1209,7 +1328,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Applying TTL to set values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -1232,7 +1352,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Enforcing capacity when setting values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1256,15 +1377,16 @@ export const set: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key, value: A): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<void>
   /**
    * 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
+   * **Example** (Setting values directly)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1281,7 +1403,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Overwriting cached values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1303,7 +1426,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Applying TTL to set values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -1326,7 +1450,8 @@ export const set: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Enforcing capacity when setting values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1350,8 +1475,8 @@ export const set: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, value: A): Effect.Effect<void>
 } = dual(
@@ -1363,7 +1488,8 @@ export const set: {
        * 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
+       * **Example** (Setting values directly)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1380,7 +1506,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Overwriting cached values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1402,7 +1529,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Applying TTL to set values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        * import { TestClock } from "effect/testing"
@@ -1425,7 +1553,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Enforcing capacity when setting values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1449,14 +1578,15 @@ export const set: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @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
+       * **Example** (Setting values directly)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1473,7 +1603,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Overwriting cached values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1495,7 +1626,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Applying TTL to set values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        * import { TestClock } from "effect/testing"
@@ -1518,7 +1650,8 @@ export const set: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Enforcing capacity when setting values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -1542,8 +1675,8 @@ export const set: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       E>()
       Deferred.doneUnsafe(deferred, exit)
@@ -1566,7 +1699,8 @@ export const set: {
 /**
  * Checks if the cache contains an entry for the specified key.
  *
- * @example
+ * **Example** (Checking for cached keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1585,7 +1719,8 @@ export const set: {
  * })
  * ```
  *
- * @example
+ * **Example** (Checking TTL expiration)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -1612,7 +1747,8 @@ export const set: {
  * })
  * ```
  *
- * @example
+ * **Example** (Checking multiple keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1641,14 +1777,15 @@ export const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const has: {
   /**
    * Checks if the cache contains an entry for the specified key.
    *
-   * @example
+   * **Example** (Checking for cached keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1667,7 +1804,8 @@ export const has: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Checking TTL expiration)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -1694,7 +1832,8 @@ export const has: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Checking multiple keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1723,14 +1862,15 @@ export const has: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
    * Checks if the cache contains an entry for the specified key.
    *
-   * @example
+   * **Example** (Checking for cached keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1749,7 +1889,8 @@ export const has: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Checking TTL expiration)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -1776,7 +1917,8 @@ export const has: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Checking multiple keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1805,8 +1947,8 @@ export const has: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<boolean>
 } = dual(
@@ -1821,7 +1963,8 @@ export const has: {
 /**
  * Invalidates the entry associated with the specified key in the cache.
  *
- * @example
+ * **Example** (Invalidating cached entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1859,14 +2002,15 @@ export const has: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidate: {
   /**
    * Invalidates the entry associated with the specified key in the cache.
    *
-   * @example
+   * **Example** (Invalidating cached entries)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1904,14 +2048,15 @@ export const invalidate: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<void>
   /**
    * Invalidates the entry associated with the specified key in the cache.
    *
-   * @example
+   * **Example** (Invalidating cached entries)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -1949,8 +2094,8 @@ export const invalidate: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<void>
 } = dual(2, <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<void> =>
@@ -1962,7 +2107,8 @@ export const invalidate: {
  * Conditionally invalidates the entry associated with the specified key in the cache
  * if the predicate returns true for the cached value.
  *
- * @example
+ * **Example** (Invalidating entries conditionally)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2019,15 +2165,16 @@ export const invalidate: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidateWhen: {
   /**
    * Conditionally invalidates the entry associated with the specified key in the cache
    * if the predicate returns true for the cached value.
    *
-   * @example
+   * **Example** (Invalidating entries conditionally)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2084,15 +2231,16 @@ export const invalidateWhen: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key, f: Predicate<A>): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<boolean>
   /**
    * Conditionally invalidates the entry associated with the specified key in the cache
    * if the predicate returns true for the cached value.
    *
-   * @example
+   * **Example** (Invalidating entries conditionally)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2149,8 +2297,8 @@ export const invalidateWhen: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, f: Predicate<A>): Effect.Effect<boolean>
 } = dual(
@@ -2180,7 +2328,8 @@ export const invalidateWhen: {
  * It will always invoke the lookup function to construct a new value,
  * overwriting any existing value for that key.
  *
- * @example
+ * **Example** (Refreshing cached values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2210,7 +2359,8 @@ export const invalidateWhen: {
  * })
  * ```
  *
- * @example
+ * **Example** (Resetting TTL on refresh)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -2238,7 +2388,8 @@ export const invalidateWhen: {
  * })
  * ```
  *
- * @example
+ * **Example** (Refreshing missing keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2258,8 +2409,8 @@ export const invalidateWhen: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const refresh: {
   /**
@@ -2268,7 +2419,8 @@ export const refresh: {
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
-   * @example
+   * **Example** (Refreshing cached values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2298,7 +2450,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Resetting TTL on refresh)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -2326,7 +2479,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Refreshing missing keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2346,8 +2500,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<A, E, R>
   /**
@@ -2356,7 +2510,8 @@ export const refresh: {
    * It will always invoke the lookup function to construct a new value,
    * overwriting any existing value for that key.
    *
-   * @example
+   * **Example** (Refreshing cached values)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2386,7 +2541,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Resetting TTL on refresh)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    * import { TestClock } from "effect/testing"
@@ -2414,7 +2570,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @example
+   * **Example** (Refreshing missing keys)
+   *
    * ```ts
    * import { Cache, Effect } from "effect"
    *
@@ -2434,8 +2591,8 @@ export const refresh: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category Combinators
+   * @since 4.0.0
    */
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R>
 } = dual(
@@ -2448,7 +2605,8 @@ export const refresh: {
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
-       * @example
+       * **Example** (Refreshing cached values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -2478,7 +2636,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Resetting TTL on refresh)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        * import { TestClock } from "effect/testing"
@@ -2506,7 +2665,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Refreshing missing keys)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -2526,8 +2686,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       A, /**
        * Forces a refresh of the value associated with the specified key in the cache.
@@ -2535,7 +2695,8 @@ export const refresh: {
        * It will always invoke the lookup function to construct a new value,
        * overwriting any existing value for that key.
        *
-       * @example
+       * **Example** (Refreshing cached values)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -2565,7 +2726,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Resetting TTL on refresh)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        * import { TestClock } from "effect/testing"
@@ -2593,7 +2755,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @example
+       * **Example** (Refreshing missing keys)
+       *
        * ```ts
        * import { Cache, Effect } from "effect"
        *
@@ -2613,8 +2776,8 @@ export const refresh: {
        * })
        * ```
        *
-       * @since 4.0.0
        * @category Combinators
+       * @since 4.0.0
        */
       E>()
       const entry: Entry<A, E> = {
@@ -2647,7 +2810,8 @@ export const refresh: {
 /**
  * Invalidates all entries in the cache.
  *
- * @example
+ * **Example** (Invalidating all entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2677,8 +2841,8 @@ export const refresh: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<void> =>
   effect.sync(() => {
@@ -2692,7 +2856,8 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
  * The size reflects the current number of entries stored, not the number
  * of valid entries.
  *
- * @example
+ * **Example** (Reading cache size)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2719,8 +2884,8 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const size = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<number> =>
   effect.sync(() => MutableHashMap.size(self.map))
@@ -2728,7 +2893,8 @@ export const size = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<num
 /**
  * Retrieves all active keys from the cache, automatically filtering out expired entries.
  *
- * @example
+ * **Example** (Reading active keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2747,12 +2913,12 @@ 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)) // ["hello", "world", "cache"]
+ *   console.log(Array.from(keys).sort()) // ["cache", "hello", "world"]
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Iterable<Key>> =>
   core.withFiber((fiber) => {
@@ -2770,7 +2936,8 @@ export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Ite
  * Retrieves all successfully cached values from the cache, excluding failed
  * lookups and expired entries.
  *
- * @example
+ * **Example** (Reading all cached values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -2793,8 +2960,8 @@ export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Ite
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const values = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Iterable<A>> =>
   effect.map(entries(self), Iterable.map(([, value]) => value))
@@ -2804,8 +2971,8 @@ export const values = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<I
  * only returns entries with successfully resolved values, filtering out any
  * failed lookups or expired entries.
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export const entries = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Iterable<[Key, A]>> =>
   core.withFiber((fiber) => {