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

package/src/RequestResolver.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"
@@ -27,26 +70,23 @@ import * as Persistence from "./unstable/persistence/Persistence.ts"
 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"
@@ -66,8 +106,8 @@ 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>
@@ -97,13 +137,22 @@ export interface RequestResolver<in A extends Request.Any> extends RequestResolv
 }
 
 /**
- * @since 2.0.0
+ * Namespace containing type-level helpers associated with `RequestResolver`.
+ *
  * @category models
+ * @since 2.0.0
  */
 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
    */
   export interface Variance<in A> {
     readonly [TypeId]: {
@@ -125,8 +174,8 @@ const RequestResolverProto = {
 /**
  * Returns `true` if the specified value is a `RequestResolver`, `false` otherwise.
  *
- * @since 2.0.0
  * @category guards
+ * @since 2.0.0
  */
 export const isRequestResolver = (u: unknown): u is RequestResolver<any> => hasProperty(u, TypeId)
 
@@ -134,8 +183,8 @@ export const isRequestResolver = (u: unknown): u is RequestResolver<any> => hasP
  * 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 const makeWith = <A extends Request.Any>(options: {
   readonly batchKey: (request: Request.Entry<A>) => unknown
@@ -159,7 +208,8 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
 /**
  * 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"
  *
@@ -184,8 +234,8 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
  * const getUserEffect = Effect.request(GetUserRequest({ id: 123 }), UserResolver)
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const make = <A extends Request.Any>(
   runAll: (entries: NonEmptyArray<Request.Entry<A>>, key: unknown) => Effect.Effect<void, Request.Error<A>>
@@ -202,7 +252,8 @@ export const make = <A extends Request.Any>(
  *
  * 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"
  *
@@ -228,8 +279,8 @@ export const make = <A extends Request.Any>(
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const makeGrouped = <A extends Request.Any, K>(options: {
   readonly key: (entry: Request.Entry<A>) => K
@@ -258,7 +309,8 @@ const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
 /**
  * Constructs a request resolver from a pure function.
  *
- * @example
+ * **Example** (Creating a resolver from a pure function)
+ *
  * ```ts
  * import { Effect, Request, RequestResolver } from "effect"
  *
@@ -281,8 +333,8 @@ const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
  * // Will resolve to 25
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromFunction = <A extends Request.Any>(
   f: (entry: Request.Entry<A>) => Request.Success<A>
@@ -302,7 +354,8 @@ export const fromFunction = <A extends Request.Any>(
  * 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"
  *
@@ -324,8 +377,8 @@ export const fromFunction = <A extends Request.Any>(
  * const batchedEffect = Effect.all(effects) // [2, 4, 6]
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromFunctionBatched = <A extends Request.Any>(
   f: (entries: NonEmptyArray<Request.Entry<A>>) => Iterable<Request.Success<A>>
@@ -344,7 +397,8 @@ export const fromFunctionBatched = <A extends Request.Any>(
 /**
  * Constructs a request resolver from an effectual function.
  *
- * @example
+ * **Example** (Creating a resolver from an effectful function)
+ *
  * ```ts
  * import { Effect, Request, RequestResolver } from "effect"
  *
@@ -374,8 +428,8 @@ export const fromFunctionBatched = <A extends Request.Any>(
  * )
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromEffect = <A extends Request.Any>(
   f: (entry: Request.Entry<A>) => Effect.Effect<Request.Success<A>, Request.Error<A>>
@@ -406,7 +460,8 @@ export const fromEffect = <A extends Request.Any>(
  * 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"
@@ -432,8 +487,8 @@ export const fromEffect = <A extends Request.Any>(
  * })
  * ```
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string }>() =>
 <
@@ -483,7 +538,8 @@ export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string
 /**
  * Sets the batch delay effect for this request resolver.
  *
- * @example
+ * **Example** (Setting an effectful batch delay)
+ *
  * ```ts
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
@@ -510,14 +566,15 @@ export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string
  * )
  * ```
  *
- * @since 4.0.0
  * @category delay
+ * @since 4.0.0
  */
 export 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"
    *
@@ -544,14 +601,15 @@ export 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"
    *
@@ -578,8 +636,8 @@ export 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>
 } = dual(
@@ -594,7 +652,8 @@ export const setDelayEffect: {
 /**
  * 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"
  *
@@ -618,14 +677,15 @@ export const setDelayEffect: {
  * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
  * ```
  *
- * @since 4.0.0
  * @category delay
+ * @since 4.0.0
  */
 export 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"
    *
@@ -649,14 +709,15 @@ export 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"
    *
@@ -680,8 +741,8 @@ export 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>
 } = dual(
@@ -697,7 +758,8 @@ export 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"
  *
@@ -720,25 +782,27 @@ export 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 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"
    *
@@ -761,18 +825,19 @@ export 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>>,
@@ -782,7 +847,8 @@ export 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"
    *
@@ -805,18 +871,19 @@ export 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>,
@@ -841,15 +908,23 @@ export const around: {
 /**
  * A request resolver that never executes requests.
  *
- * @since 2.0.0
  * @category constructors
+ * @since 2.0.0
  */
 export const never: RequestResolver<never> = make(() => Effect.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"
  *
@@ -878,14 +953,22 @@ export const never: RequestResolver<never> = make(() => Effect.never)
  * )
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export 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"
    *
@@ -914,14 +997,22 @@ export 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"
    *
@@ -950,8 +1041,8 @@ export const batchN: {
    * )
    * ```
    *
-   * @since 2.0.0
    * @category combinators
+   * @since 2.0.0
    */
   <A extends Request.Any>(self: RequestResolver<A>, n: number): RequestResolver<A>
 } = dual(2, <A extends Request.Any>(self: RequestResolver<A>, n: number): RequestResolver<A> =>
@@ -964,7 +1055,8 @@ export 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"
  *
@@ -1007,15 +1099,16 @@ export const batchN: {
  * ]
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -1058,15 +1151,16 @@ export 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"
    *
@@ -1109,8 +1203,8 @@ export 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>
 } = dual(
@@ -1123,13 +1217,16 @@ export const grouped: {
 )
 
 /**
- * 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"
  *
@@ -1163,18 +1260,21 @@ export const grouped: {
  * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
  * ```
  *
- * @since 2.0.0
  * @category combinators
+ * @since 2.0.0
  */
 export 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.
+   *
+   * **Details**
    *
-   * The batch delay is determined by the first request resolver.
+   * 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"
    *
@@ -1208,18 +1308,21 @@ export 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.
+   *
+   * **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"
    *
@@ -1253,8 +1356,8 @@ export 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>
 } = dual(2, <A extends Request.Any, A2 extends Request.Any>(
@@ -1269,7 +1372,8 @@ export 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"
  *
@@ -1303,15 +1407,16 @@ export const race: {
  * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
  * ```
  *
- * @since 4.0.0
  * @category combinators
+ * @since 4.0.0
  */
 export 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"
    *
@@ -1345,8 +1450,8 @@ export 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,
@@ -1356,7 +1461,8 @@ export 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"
    *
@@ -1390,8 +1496,8 @@ export 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>,
@@ -1431,16 +1537,16 @@ export 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 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,
@@ -1465,8 +1571,8 @@ export 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,
@@ -1515,16 +1621,16 @@ export 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 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: {
@@ -1536,8 +1642,8 @@ export 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>,
@@ -1556,15 +1662,15 @@ export 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, /**
      * 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
      */
     {
       readonly entry: Request.Entry<A>;
@@ -1617,13 +1723,39 @@ export const withCache: {
   }))
 
 /**
- * @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 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: {
@@ -1637,8 +1769,21 @@ export const persisted: {
     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
@@ -1668,8 +1813,21 @@ export const persisted: {
   ) {
     const store = yield* (yield* Persistence.Persistence).make(options as any)
     return makeWith</**
-     * @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>({
       ...self,