effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/RequestResolver.d.ts

@@ -1,4 +1,47 @@
 /**
+ * The `RequestResolver` module provides the data-loading side of
+ * `Effect.request`. A `Request` describes what a fiber needs, while a
+ * `RequestResolver` describes how to collect, batch, execute, cache, trace,
+ * and complete those requests.
+ *
+ * **Mental model**
+ *
+ * - A resolver receives one or more `Request.Entry` values and must complete
+ *   each entry with either a success or failure
+ * - Concurrent requests made with the same resolver can be gathered into a
+ *   batch before the resolver is run
+ * - Batch keys split pending requests into independent groups, which is useful
+ *   when different backends, tenants, or query shapes must be resolved
+ *   separately
+ * - Delays and `batchN` tune how long requests are collected and how large
+ *   each batch may become
+ * - Resolvers can be wrapped with tracing, in-memory caching, cache services,
+ *   and persistence without changing the request type
+ *
+ * **Common tasks**
+ *
+ * - Create a resolver from batch logic: {@link make}
+ * - Create grouped batch logic: {@link makeGrouped} or {@link grouped}
+ * - Create a resolver from pure logic: {@link fromFunction} or
+ *   {@link fromFunctionBatched}
+ * - Create a resolver from effectful logic: {@link fromEffect} or
+ *   {@link fromEffectTagged}
+ * - Control batching: {@link setDelay}, {@link setDelayEffect},
+ *   {@link batchN}
+ * - Add operational behavior: {@link around}, {@link race}, {@link withSpan}
+ * - Reuse results: {@link withCache}, {@link asCache}, {@link persisted}
+ *
+ * **Gotchas**
+ *
+ * - Every entry passed to a resolver must be completed; leaving an entry
+ *   incomplete causes the waiting request to fail
+ * - Batched result collections must line up with the input entries in order
+ *   and length when using the batched helper constructors
+ * - Grouping controls which requests share a resolver run; choose stable keys
+ *   for requests that can safely be handled together
+ * - Caching and persistence depend on request identity and the request's
+ *   equality semantics, so model request values deliberately when cached
+ *
  * @since 2.0.0
  */
 import type { NonEmptyArray } from "./Array.ts";
@@ -15,29 +58,26 @@ import type * as Persistable from "./unstable/persistence/Persistable.ts";
 import * as Persistence from "./unstable/persistence/Persistence.ts";
 declare const TypeId = "~effect/RequestResolver";
 /**
- * The `RequestResolver<A, R>` interface requires an environment `R` and handles
- * the execution of requests of type `A`.
- *
- * Implementations must provide a `runAll` method, which processes a collection
- * of requests and produces an effect that fulfills these requests. Requests are
- * organized into a `Array<Array<A>>`, where the outer `Array` groups requests
- * into batches that are executed sequentially, and each inner `Array` contains
- * requests that can be executed in parallel. This structure allows
- * implementations to analyze all incoming requests collectively and optimize
- * query execution accordingly.
- *
- * Implementations are typically specialized for a subtype of `Request<A, E>`.
- * However, they are not strictly limited to these subtypes as long as they can
- * map any given request type to `Request<A, E>`. Implementations should inspect
- * the collection of requests to identify the needed information and execute the
- * corresponding queries. It is imperative that implementations resolve all the
- * requests they receive. Failing to do so will lead to a `QueryFailure` error
- * during query execution.
- *
- * @example
+ * A resolver that executes and completes batched `Request` entries.
+ *
+ * **Details**
+ *
+ * A resolver controls how requests are grouped, delayed, optionally
+ * pre-checked, and finally run. Its `runAll` method receives a non-empty batch
+ * of `Request.Entry` values for a single batch key and must complete every
+ * received entry, usually by calling `completeUnsafe` or one of the `Request`
+ * completion helpers.
+ *
+ * **Notes**
+ *
+ * If a resolver finishes without completing an entry, the waiting request fails
+ * because the resolver did not supply a result.
+ *
+ * **Example** (Defining a request resolver)
+ *
  * ```ts
- * import type { Request } from "effect"
  * import { Effect, Exit, RequestResolver } from "effect"
+ * import type { Request } from "effect"
  *
  * interface GetUserRequest extends Request.Request<string, Error> {
  *   readonly _tag: "GetUserRequest"
@@ -54,8 +94,8 @@ declare const TypeId = "~effect/RequestResolver";
  * )
  * ```
  *
- * @since 2.0.0
  * @category models
+ * @since 2.0.0
  */
 export interface RequestResolver<in A extends Request.Any> extends RequestResolver.Variance<A>, Pipeable {
     readonly delay: Effect.Effect<void>;
@@ -80,13 +120,21 @@ export interface RequestResolver<in A extends Request.Any> extends RequestResolv
     runAll(entries: NonEmptyArray<Request.Entry<A>>, key: unknown): Effect.Effect<void, Request.Error<A>>;
 }
 /**
+ * Namespace containing type-level helpers associated with `RequestResolver`.
+ *
  * @since 2.0.0
- * @category models
  */
 export declare namespace RequestResolver {
     /**
-     * @since 2.0.0
+     * Variance marker carried by every `RequestResolver`.
+     *
+     * **Notes**
+     *
+     * This marker preserves the request type accepted by the resolver for
+     * Effect's type-level machinery. Users normally do not implement it directly.
+     *
      * @category models
+     * @since 2.0.0
      */
     interface Variance<in A> {
         readonly [TypeId]: {
@@ -97,16 +145,16 @@ export declare namespace RequestResolver {
 /**
  * Returns `true` if the specified value is a `RequestResolver`, `false` otherwise.
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export declare const isRequestResolver: (u: unknown) => u is RequestResolver<any>;
 /**
  * Low-level constructor for creating a request resolver with fine-grained
  * control over its behavior.
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeWith: <A extends Request.Any>(options: {
     readonly batchKey: (request: Request.Entry<A>) => unknown;
@@ -118,7 +166,8 @@ export declare const makeWith: <A extends Request.Any>(options: {
 /**
  * Constructs a request resolver with the specified method to run requests.
  *
- * @example
+ * **Example** (Creating a request resolver)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -143,8 +192,8 @@ export declare const makeWith: <A extends Request.Any>(options: {
  * const getUserEffect = Effect.request(GetUserRequest({ id: 123 }), UserResolver)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const make: <A extends Request.Any>(runAll: (entries: NonEmptyArray<Request.Entry<A>>, key: unknown) => Effect.Effect<void, Request.Error<A>>) => RequestResolver<A>;
 /**
@@ -152,7 +201,8 @@ export declare const make: <A extends Request.Any>(runAll: (entries: NonEmptyArr
  *
  * The key can use the Equal trait to determine if two keys are equal.
  *
- * @example
+ * **Example** (Grouping requests by key)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -178,8 +228,8 @@ export declare const make: <A extends Request.Any>(runAll: (entries: NonEmptyArr
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export declare const makeGrouped: <A extends Request.Any, K>(options: {
     readonly key: (entry: Request.Entry<A>) => K;
@@ -188,7 +238,8 @@ export declare const makeGrouped: <A extends Request.Any, K>(options: {
 /**
  * Constructs a request resolver from a pure function.
  *
- * @example
+ * **Example** (Creating a resolver from a pure function)
+ *
  * ```ts
  * import { Effect, Request, RequestResolver } from "effect"
  *
@@ -211,8 +262,8 @@ export declare const makeGrouped: <A extends Request.Any, K>(options: {
  * // Will resolve to 25
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromFunction: <A extends Request.Any>(f: (entry: Request.Entry<A>) => Request.Success<A>) => RequestResolver<A>;
 /**
@@ -220,7 +271,8 @@ export declare const fromFunction: <A extends Request.Any>(f: (entry: Request.En
  * and returns a list of results of the same size. Each item in the result
  * list must correspond to the item at the same index in the request list.
  *
- * @example
+ * **Example** (Batching pure request handling)
+ *
  * ```ts
  * import { Effect, Request, RequestResolver } from "effect"
  *
@@ -242,14 +294,15 @@ export declare const fromFunction: <A extends Request.Any>(f: (entry: Request.En
  * const batchedEffect = Effect.all(effects) // [2, 4, 6]
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromFunctionBatched: <A extends Request.Any>(f: (entries: NonEmptyArray<Request.Entry<A>>) => Iterable<Request.Success<A>>) => RequestResolver<A>;
 /**
  * Constructs a request resolver from an effectual function.
  *
- * @example
+ * **Example** (Creating a resolver from an effectful function)
+ *
  * ```ts
  * import { Effect, Request, RequestResolver } from "effect"
  *
@@ -279,8 +332,8 @@ export declare const fromFunctionBatched: <A extends Request.Any>(f: (entries: N
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromEffect: <A extends Request.Any>(f: (entry: Request.Entry<A>) => Effect.Effect<Request.Success<A>, Request.Error<A>>) => RequestResolver<A>;
 /**
@@ -289,10 +342,11 @@ export declare const fromEffect: <A extends Request.Any>(f: (entry: Request.Entr
  * in the result list must correspond to the item at the same index in the
  * request list.
  *
- * @example
+ * **Example** (Handling tagged request batches)
+ *
  * ```ts
- * import type { Request } from "effect"
  * import { Effect, RequestResolver } from "effect"
+ * import type { Request } from "effect"
  *
  * interface GetUser extends Request.Request<string, Error> {
  *   readonly _tag: "GetUser"
@@ -315,8 +369,8 @@ export declare const fromEffect: <A extends Request.Any>(f: (entry: Request.Entr
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const fromEffectTagged: <A extends Request.Any & {
     readonly _tag: string;
@@ -326,7 +380,8 @@ export declare const fromEffectTagged: <A extends Request.Any & {
 /**
  * Sets the batch delay effect for this request resolver.
  *
- * @example
+ * **Example** (Setting an effectful batch delay)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -353,14 +408,15 @@ export declare const fromEffectTagged: <A extends Request.Any & {
  * )
  * ```
  *
- * @since 4.0.0
  * @category delay
+ * @since 4.0.0
  */
 export declare const setDelayEffect: {
     /**
      * Sets the batch delay effect for this request resolver.
      *
-     * @example
+     * **Example** (Setting an effectful batch delay)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -387,14 +443,15 @@ export declare const setDelayEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category delay
+     * @since 4.0.0
      */
     (delay: Effect.Effect<void>): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A>;
     /**
      * Sets the batch delay effect for this request resolver.
      *
-     * @example
+     * **Example** (Setting an effectful batch delay)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -421,15 +478,16 @@ export declare const setDelayEffect: {
      * )
      * ```
      *
-     * @since 4.0.0
      * @category delay
+     * @since 4.0.0
      */
     <A extends Request.Any>(self: RequestResolver<A>, delay: Effect.Effect<void>): RequestResolver<A>;
 };
 /**
  * Sets the batch delay window for this request resolver to the specified duration.
  *
- * @example
+ * **Example** (Setting a batch delay)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -453,14 +511,15 @@ export declare const setDelayEffect: {
  * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
  * ```
  *
- * @since 4.0.0
  * @category delay
+ * @since 4.0.0
  */
 export declare const setDelay: {
     /**
      * Sets the batch delay window for this request resolver to the specified duration.
      *
-     * @example
+     * **Example** (Setting a batch delay)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -484,14 +543,15 @@ export declare const setDelay: {
      * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
      * ```
      *
-     * @since 4.0.0
      * @category delay
+     * @since 4.0.0
      */
     (duration: Duration.Input): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A>;
     /**
      * Sets the batch delay window for this request resolver to the specified duration.
      *
-     * @example
+     * **Example** (Setting a batch delay)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -515,8 +575,8 @@ export declare const setDelay: {
      * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
      * ```
      *
-     * @since 4.0.0
      * @category delay
+     * @since 4.0.0
      */
     <A extends Request.Any>(self: RequestResolver<A>, duration: Duration.Input): RequestResolver<A>;
 };
@@ -524,7 +584,8 @@ export declare const setDelay: {
  * A request resolver aspect that executes requests between two effects, `before`
  * and `after`, where the result of `before` can be used by `after`.
  *
- * @example
+ * **Example** (Running effects around request resolution)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -547,25 +608,27 @@ export declare const setDelay: {
  *   (entries) =>
  *     Effect.gen(function*() {
  *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
- *       return Date.now()
+ *       return entries.length
  *     }),
- *   (entries, startTime) =>
+ *   (entries, initialSize) =>
  *     Effect.gen(function*() {
- *       const duration = Date.now() - startTime
- *       yield* Effect.log(`Batch completed in ${duration}ms`)
+ *       yield* Effect.log(
+ *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
+ *       )
  *     })
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const around: {
     /**
      * A request resolver aspect that executes requests between two effects, `before`
      * and `after`, where the result of `before` can be used by `after`.
      *
-     * @example
+     * **Example** (Running effects around request resolution)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -588,25 +651,27 @@ export declare const around: {
      *   (entries) =>
      *     Effect.gen(function*() {
      *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
-     *       return Date.now()
+     *       return entries.length
      *     }),
-     *   (entries, startTime) =>
+     *   (entries, initialSize) =>
      *     Effect.gen(function*() {
-     *       const duration = Date.now() - startTime
-     *       yield* Effect.log(`Batch completed in ${duration}ms`)
+     *       yield* Effect.log(
+     *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
+     *       )
      *     })
      * )
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A extends Request.Any, A2, X>(before: (entries: NonEmptyArray<Request.Entry<NoInfer<A>>>) => Effect.Effect<A2, Request.Error<A>>, after: (entries: NonEmptyArray<Request.Entry<NoInfer<A>>>, a: A2) => Effect.Effect<X, Request.Error<A>>): (self: RequestResolver<A>) => RequestResolver<A>;
     /**
      * A request resolver aspect that executes requests between two effects, `before`
      * and `after`, where the result of `before` can be used by `after`.
      *
-     * @example
+     * **Example** (Running effects around request resolution)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -629,32 +694,41 @@ export declare const around: {
      *   (entries) =>
      *     Effect.gen(function*() {
      *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
-     *       return Date.now()
+     *       return entries.length
      *     }),
-     *   (entries, startTime) =>
+     *   (entries, initialSize) =>
      *     Effect.gen(function*() {
-     *       const duration = Date.now() - startTime
-     *       yield* Effect.log(`Batch completed in ${duration}ms`)
+     *       yield* Effect.log(
+     *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
+     *       )
      *     })
      * )
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A extends Request.Any, A2, X>(self: RequestResolver<A>, before: (entries: NonEmptyArray<Request.Entry<NoInfer<A>>>) => Effect.Effect<A2, Request.Error<A>>, after: (entries: NonEmptyArray<Request.Entry<NoInfer<A>>>, a: A2) => Effect.Effect<X, Request.Error<A>>): RequestResolver<A>;
 };
 /**
  * A request resolver that never executes requests.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export declare const never: RequestResolver<never>;
 /**
- * Returns a request resolver that executes at most `n` requests in parallel.
+ * Returns a request resolver that collects at most `n` requests into each
+ * batch.
+ *
+ * **Details**
+ *
+ * When more than `n` requests are waiting for the same resolver and batch key,
+ * the current batch is run and additional requests are collected into later
+ * batches.
+ *
+ * **Example** (Limiting parallel request batches)
  *
- * @example
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -683,14 +757,22 @@ export declare const never: RequestResolver<never>;
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const batchN: {
     /**
-     * Returns a request resolver that executes at most `n` requests in parallel.
+     * Returns a request resolver that collects at most `n` requests into each
+     * batch.
+     *
+     * **Details**
+     *
+     * When more than `n` requests are waiting for the same resolver and batch key,
+     * the current batch is run and additional requests are collected into later
+     * batches.
+     *
+     * **Example** (Limiting parallel request batches)
      *
-     * @example
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -719,14 +801,22 @@ export declare const batchN: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     (n: number): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A>;
     /**
-     * Returns a request resolver that executes at most `n` requests in parallel.
+     * Returns a request resolver that collects at most `n` requests into each
+     * batch.
+     *
+     * **Details**
+     *
+     * When more than `n` requests are waiting for the same resolver and batch key,
+     * the current batch is run and additional requests are collected into later
+     * batches.
+     *
+     * **Example** (Limiting parallel request batches)
      *
-     * @example
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -755,8 +845,8 @@ export declare const batchN: {
      * )
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A extends Request.Any>(self: RequestResolver<A>, n: number): RequestResolver<A>;
 };
@@ -764,7 +854,8 @@ export declare const batchN: {
  * Transform a request resolver by grouping requests using the specified key
  * function.
  *
- * @example
+ * **Example** (Grouping resolver requests)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -807,15 +898,16 @@ export declare const batchN: {
  * ]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const grouped: {
     /**
      * Transform a request resolver by grouping requests using the specified key
      * function.
      *
-     * @example
+     * **Example** (Grouping resolver requests)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -858,15 +950,16 @@ export declare const grouped: {
      * ]
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A extends Request.Any, K>(f: (entry: Request.Entry<A>) => K): (self: RequestResolver<A>) => RequestResolver<A>;
     /**
      * Transform a request resolver by grouping requests using the specified key
      * function.
      *
-     * @example
+     * **Example** (Grouping resolver requests)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -909,19 +1002,22 @@ export declare const grouped: {
      * ]
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A extends Request.Any, K>(self: RequestResolver<A>, f: (entry: Request.Entry<A>) => K): RequestResolver<A>;
 };
 /**
- * Returns a new request resolver that executes requests by sending them to this
- * request resolver and that request resolver, returning the results from the first data
- * source to complete and safely interrupting the loser.
+ * Returns a request resolver that sends each batch to both resolvers and
+ * completes with the first resolver to finish.
+ *
+ * **Details**
+ *
+ * The losing resolver run is interrupted after the winning resolver completes
+ * the batch.
  *
- * The batch delay is determined by the first request resolver.
+ * **Example** (Racing request resolvers)
  *
- * @example
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -955,18 +1051,21 @@ export declare const grouped: {
  * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export declare const race: {
     /**
-     * Returns a new request resolver that executes requests by sending them to this
-     * request resolver and that request resolver, returning the results from the first data
-     * source to complete and safely interrupting the loser.
+     * Returns a request resolver that sends each batch to both resolvers and
+     * completes with the first resolver to finish.
      *
-     * The batch delay is determined by the first request resolver.
+     * **Details**
+     *
+     * The losing resolver run is interrupted after the winning resolver completes
+     * the batch.
+     *
+     * **Example** (Racing request resolvers)
      *
-     * @example
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -1000,18 +1099,21 @@ export declare const race: {
      * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A2 extends Request.Any>(that: RequestResolver<A2>): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A2 & A>;
     /**
-     * Returns a new request resolver that executes requests by sending them to this
-     * request resolver and that request resolver, returning the results from the first data
-     * source to complete and safely interrupting the loser.
+     * Returns a request resolver that sends each batch to both resolvers and
+     * completes with the first resolver to finish.
      *
-     * The batch delay is determined by the first request resolver.
+     * **Details**
+     *
+     * The losing resolver run is interrupted after the winning resolver completes
+     * the batch.
+     *
+     * **Example** (Racing request resolvers)
      *
-     * @example
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -1045,8 +1147,8 @@ export declare const race: {
      * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
      * ```
      *
-     * @since 2.0.0
      * @category combinators
+     * @since 2.0.0
      */
     <A extends Request.Any, A2 extends Request.Any>(self: RequestResolver<A>, that: RequestResolver<A2>): RequestResolver<A & A2>;
 };
@@ -1054,7 +1156,8 @@ export declare const race: {
  * Add a tracing span to the request resolver, which will also add any span
  * links from the request's.
  *
- * @example
+ * **Example** (Adding a tracing span)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -1088,15 +1191,16 @@ export declare const race: {
  * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export declare const withSpan: {
     /**
      * Add a tracing span to the request resolver, which will also add any span
      * links from the request's.
      *
-     * @example
+     * **Example** (Adding a tracing span)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -1130,15 +1234,16 @@ export declare const withSpan: {
      * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A extends Request.Any>(name: string, options?: Tracer.SpanOptions | ((entries: NonEmptyArray<Request.Entry<A>>) => Tracer.SpanOptions) | undefined): (self: RequestResolver<A>) => RequestResolver<A>;
     /**
      * Add a tracing span to the request resolver, which will also add any span
      * links from the request's.
      *
-     * @example
+     * **Example** (Adding a tracing span)
+     *
      * ```ts
      * import { Effect, Exit, Request, RequestResolver } from "effect"
      *
@@ -1172,8 +1277,8 @@ export declare const withSpan: {
      * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
      * ```
      *
-     * @since 4.0.0
      * @category combinators
+     * @since 4.0.0
      */
     <A extends Request.Any>(self: RequestResolver<A>, name: string, options?: Tracer.SpanOptions | ((entries: NonEmptyArray<Request.Entry<A>>) => Tracer.SpanOptions) | undefined): RequestResolver<A>;
 };
@@ -1181,16 +1286,16 @@ export declare const withSpan: {
  * Wraps a request resolver in a cache, allowing it to cache results up to a
  * specified capacity and optional time-to-live.
  *
- * @since 4.0.0
  * @category Caching
+ * @since 4.0.0
  */
 export declare const asCache: {
     /**
      * Wraps a request resolver in a cache, allowing it to cache results up to a
      * specified capacity and optional time-to-live.
      *
-     * @since 4.0.0
      * @category Caching
+     * @since 4.0.0
      */
     <A extends Request.Any, ServiceMode extends "lookup" | "construction" = never>(options: {
         readonly capacity: number;
@@ -1201,8 +1306,8 @@ export declare const asCache: {
      * Wraps a request resolver in a cache, allowing it to cache results up to a
      * specified capacity and optional time-to-live.
      *
-     * @since 4.0.0
      * @category Caching
+     * @since 4.0.0
      */
     <A extends Request.Any, ServiceMode extends "lookup" | "construction" = never>(self: RequestResolver<A>, options: {
         readonly capacity: number;
@@ -1214,16 +1319,16 @@ export declare const asCache: {
  * Adds caching capabilities to a request resolver, allowing it to cache
  * results up to a specified capacity.
  *
- * @since 4.0.0
  * @category Caching
+ * @since 4.0.0
  */
 export declare const withCache: {
     /**
      * Adds caching capabilities to a request resolver, allowing it to cache
      * results up to a specified capacity.
      *
-     * @since 4.0.0
      * @category Caching
+     * @since 4.0.0
      */
     <A extends Request.Any>(options: {
         readonly capacity: number;
@@ -1233,8 +1338,8 @@ export declare const withCache: {
      * Adds caching capabilities to a request resolver, allowing it to cache
      * results up to a specified capacity.
      *
-     * @since 4.0.0
      * @category Caching
+     * @since 4.0.0
      */
     <A extends Request.Any>(self: RequestResolver<A>, options: {
         readonly capacity: number;
@@ -1242,13 +1347,39 @@ export declare const withCache: {
     }): Effect.Effect<RequestResolver<A>>;
 };
 /**
- * @since 4.0.0
+ * Wraps a request resolver with persistent storage for persistable requests.
+ *
+ * **Details**
+ *
+ * Cached results are loaded from the configured persistence store before
+ * running the underlying resolver. Missing entries, and entries marked stale by
+ * `staleWhileRevalidate`, are resolved normally and written back to the store.
+ *
+ * **Notes**
+ *
+ * Creating the persisted resolver requires `Persistence.Persistence` and
+ * `Scope`.
+ *
  * @category Persistence
+ * @since 4.0.0
  */
 export declare const persisted: {
     /**
-     * @since 4.0.0
+     * Wraps a request resolver with persistent storage for persistable requests.
+     *
+     * **Details**
+     *
+     * Cached results are loaded from the configured persistence store before
+     * running the underlying resolver. Missing entries, and entries marked stale by
+     * `staleWhileRevalidate`, are resolved normally and written back to the store.
+     *
+     * **Notes**
+     *
+     * Creating the persisted resolver requires `Persistence.Persistence` and
+     * `Scope`.
+     *
      * @category Persistence
+     * @since 4.0.0
      */
     <A extends Request.Request<any, Persistence.PersistenceError | Schema.SchemaError, any> & Persistable.Any>(options: {
         readonly storeId: string;
@@ -1256,8 +1387,21 @@ export declare const persisted: {
         readonly staleWhileRevalidate?: ((exit: Request.Result<A>, request: A) => boolean) | undefined;
     }): (self: RequestResolver<A>) => Effect.Effect<RequestResolver<A>, never, Persistence.Persistence | Scope>;
     /**
-     * @since 4.0.0
+     * Wraps a request resolver with persistent storage for persistable requests.
+     *
+     * **Details**
+     *
+     * Cached results are loaded from the configured persistence store before
+     * running the underlying resolver. Missing entries, and entries marked stale by
+     * `staleWhileRevalidate`, are resolved normally and written back to the store.
+     *
+     * **Notes**
+     *
+     * Creating the persisted resolver requires `Persistence.Persistence` and
+     * `Scope`.
+     *
      * @category Persistence
+     * @since 4.0.0
      */
     <A extends Request.Request<any, Persistence.PersistenceError | Schema.SchemaError, any> & Persistable.Any>(self: RequestResolver<A>, options: {
         readonly storeId: string;