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

package/dist/Cache.d.ts

@@ -11,7 +11,8 @@ declare 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"
  *
@@ -31,7 +32,8 @@ declare const TypeId = "~effect/Cache";
  * })
  * ```
  *
- * @example
+ * **Example** (Handling lookup failures)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -53,7 +55,8 @@ declare const TypeId = "~effect/Cache";
  * })
  * ```
  *
- * @example
+ * **Example** (Using complex keys with TTL)
+ *
  * ```ts
  * import { Cache, Data, Duration, Effect } from "effect"
  *
@@ -74,8 +77,8 @@ declare 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;
@@ -85,11 +88,17 @@ export interface Cache<in out Key, in out A, in out E = never, out R = never> ex
     readonly timeToLive: (exit: Exit.Exit<A, E>, key: Key) => Duration.Duration;
 }
 /**
- * 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;
@@ -101,7 +110,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"
  *
@@ -125,8 +135,8 @@ export interface Entry<A, E> {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Constructors
+ * @since 4.0.0
  */
 export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extends "lookup" | "construction" = never>(lookup: (key: Key) => Effect.Effect<A, E, R>, options: {
     readonly capacity: number;
@@ -139,7 +149,8 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  * 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"
  *
@@ -156,12 +167,17 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  * })
  * ```
  *
- * @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 },
@@ -169,22 +185,25 @@ export declare const makeWith: <Key, A, E = never, R = never, ServiceMode extend
  *   >({
  *     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 declare const make: <Key, A, E = never, R = never, ServiceMode extends "lookup" | "construction" = never>(options: {
     readonly lookup: (key: Key) => Effect.Effect<A, E, R>;
@@ -193,12 +212,17 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
     readonly requireServicesAt?: ServiceMode | undefined;
 }) => Effect.Effect<Cache<Key, A, E, "lookup" extends ServiceMode ? R : never>, never, "lookup" extends ServiceMode ? never : 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"
  *
@@ -220,7 +244,8 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  * })
  * ```
  *
- * @example
+ * **Example** (Handling lookup failures)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -244,7 +269,8 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  * })
  * ```
  *
- * @example
+ * **Example** (Sharing concurrent lookups)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -272,17 +298,22 @@ export declare const make: <Key, A, E = never, R = never, ServiceMode extends "l
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare 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"
      *
@@ -304,7 +335,8 @@ export declare const get: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Handling lookup failures)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -328,7 +360,8 @@ export declare const get: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Sharing concurrent lookups)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -356,17 +389,22 @@ export declare 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**
      *
-     * 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"
      *
@@ -388,7 +426,8 @@ export declare const get: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Handling lookup failures)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -412,7 +451,8 @@ export declare const get: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Sharing concurrent lookups)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -440,20 +480,23 @@ export declare 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>;
 };
 /**
- * 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"
  *
@@ -478,7 +521,8 @@ export declare const get: {
  * })
  * ```
  *
- * @example
+ * **Example** (Skipping expired entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -507,7 +551,8 @@ export declare const get: {
  * })
  * ```
  *
- * @example
+ * **Example** (Waiting for pending lookups)
+ *
  * ```ts
  * import { Cache, Deferred, Effect, Fiber } from "effect"
  *
@@ -530,22 +575,28 @@ export declare const get: {
  *
  *   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 declare 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.
+     *
+     * **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"
      *
@@ -570,7 +621,8 @@ export declare const getOption: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Skipping expired entries)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -599,7 +651,8 @@ export declare const getOption: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Waiting for pending lookups)
+     *
      * ```ts
      * import { Cache, Deferred, Effect, Fiber } from "effect"
      *
@@ -622,22 +675,28 @@ export declare 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**
      *
-     * 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"
      *
@@ -662,7 +721,8 @@ export declare const getOption: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Skipping expired entries)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -691,7 +751,8 @@ export declare const getOption: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Waiting for pending lookups)
+     *
      * ```ts
      * import { Cache, Deferred, Effect, Fiber } from "effect"
      *
@@ -714,11 +775,14 @@ export declare 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>;
 };
@@ -726,24 +790,24 @@ export declare const getOption: {
  * 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 declare 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>>;
 };
@@ -751,7 +815,8 @@ export declare 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"
  *
@@ -768,7 +833,8 @@ export declare const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Overwriting cached values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -790,7 +856,8 @@ export declare const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Applying TTL to set values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -813,7 +880,8 @@ export declare const getSuccess: {
  * })
  * ```
  *
- * @example
+ * **Example** (Enforcing capacity when setting values)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -837,15 +905,16 @@ export declare const getSuccess: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare 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"
      *
@@ -862,7 +931,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Overwriting cached values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -884,7 +954,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Applying TTL to set values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -907,7 +978,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Enforcing capacity when setting values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -931,15 +1003,16 @@ export declare 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"
      *
@@ -956,7 +1029,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Overwriting cached values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -978,7 +1052,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Applying TTL to set values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -1001,7 +1076,8 @@ export declare const set: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Enforcing capacity when setting values)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1025,15 +1101,16 @@ export declare 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>;
 };
 /**
  * Checks if the cache contains an entry for the specified key.
  *
- * @example
+ * **Example** (Checking for cached keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1052,7 +1129,8 @@ export declare const set: {
  * })
  * ```
  *
- * @example
+ * **Example** (Checking TTL expiration)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -1079,7 +1157,8 @@ export declare const set: {
  * })
  * ```
  *
- * @example
+ * **Example** (Checking multiple keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1108,14 +1187,15 @@ export declare const set: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare 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"
      *
@@ -1134,7 +1214,8 @@ export declare const has: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Checking TTL expiration)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -1161,7 +1242,8 @@ export declare const has: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Checking multiple keys)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1190,14 +1272,15 @@ export declare 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"
      *
@@ -1216,7 +1299,8 @@ export declare const has: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Checking TTL expiration)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -1243,7 +1327,8 @@ export declare const has: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Checking multiple keys)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1272,15 +1357,16 @@ export declare 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>;
 };
 /**
  * Invalidates the entry associated with the specified key in the cache.
  *
- * @example
+ * **Example** (Invalidating cached entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1318,14 +1404,15 @@ export declare const has: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const invalidate: {
     /**
      * Invalidates the entry associated with the specified key in the cache.
      *
-     * @example
+     * **Example** (Invalidating cached entries)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1363,14 +1450,15 @@ export declare 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"
      *
@@ -1408,8 +1496,8 @@ export declare 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>;
 };
@@ -1417,7 +1505,8 @@ export declare 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"
  *
@@ -1474,15 +1563,16 @@ export declare const invalidate: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare 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"
      *
@@ -1539,15 +1629,16 @@ export declare 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"
      *
@@ -1604,8 +1695,8 @@ export declare 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>;
 };
@@ -1615,7 +1706,8 @@ export declare 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"
  *
@@ -1645,7 +1737,8 @@ export declare const invalidateWhen: {
  * })
  * ```
  *
- * @example
+ * **Example** (Resetting TTL on refresh)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  * import { TestClock } from "effect/testing"
@@ -1673,7 +1766,8 @@ export declare const invalidateWhen: {
  * })
  * ```
  *
- * @example
+ * **Example** (Refreshing missing keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1693,8 +1787,8 @@ export declare const invalidateWhen: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const refresh: {
     /**
@@ -1703,7 +1797,8 @@ export declare 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"
      *
@@ -1733,7 +1828,8 @@ export declare const refresh: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Resetting TTL on refresh)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -1761,7 +1857,8 @@ export declare const refresh: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Refreshing missing keys)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1781,8 +1878,8 @@ export declare 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>;
     /**
@@ -1791,7 +1888,8 @@ export declare 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"
      *
@@ -1821,7 +1919,8 @@ export declare const refresh: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Resetting TTL on refresh)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      * import { TestClock } from "effect/testing"
@@ -1849,7 +1948,8 @@ export declare const refresh: {
      * })
      * ```
      *
-     * @example
+     * **Example** (Refreshing missing keys)
+     *
      * ```ts
      * import { Cache, Effect } from "effect"
      *
@@ -1869,15 +1969,16 @@ export declare 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>;
 };
 /**
  * Invalidates all entries in the cache.
  *
- * @example
+ * **Example** (Invalidating all entries)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1907,8 +2008,8 @@ export declare const refresh: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const invalidateAll: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<void>;
 /**
@@ -1918,7 +2019,8 @@ export declare const invalidateAll: <Key, A, E, R>(self: Cache<Key, A, E, R>) =>
  * 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"
  *
@@ -1945,14 +2047,15 @@ export declare const invalidateAll: <Key, A, E, R>(self: Cache<Key, A, E, R>) =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const size: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<number>;
 /**
  * Retrieves all active keys from the cache, automatically filtering out expired entries.
  *
- * @example
+ * **Example** (Reading active keys)
+ *
  * ```ts
  * import { Cache, Effect } from "effect"
  *
@@ -1971,19 +2074,20 @@ export declare const size: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  *   // Retrieve all active keys
  *   const keys = yield* Cache.keys(cache)
  *
- *   console.log(Array.from(keys)) // ["hello", "world", "cache"]
+ *   console.log(Array.from(keys).sort()) // ["cache", "hello", "world"]
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const keys: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<Iterable<Key>>;
 /**
  * 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"
  *
@@ -2006,8 +2110,8 @@ export declare const keys: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.E
  * })
  * ```
  *
- * @since 4.0.0
  * @category Combinators
+ * @since 4.0.0
  */
 export declare const values: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<Iterable<A>>;
 /**
@@ -2015,8 +2119,8 @@ export declare const values: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect
  * 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 declare const entries: <Key, A, E, R>(self: Cache<Key, A, E, R>) => Effect.Effect<Iterable<[Key, A]>>;
 export {};