effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/RequestResolver.ts

@@ -52,14 +52,14 @@ const TypeId = "~effect/RequestResolver"
  *
  * **Example** (Defining a request resolver)
  *
- * ```ts
- * import { Effect, Exit, RequestResolver } from "effect"
- * import type { Request } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetUserRequest extends Request.Request<string, Error> {
  *   readonly _tag: "GetUserRequest"
  *   readonly id: number
  * }
+ * const GetUserRequest = Request.tagged<GetUserRequest>("GetUserRequest")
  *
  * // In practice, you would typically use RequestResolver.make() instead
  * const resolver = RequestResolver.make<GetUserRequest>((entries) =>
@@ -69,6 +69,9 @@ const TypeId = "~effect/RequestResolver"
  *     }
  *   })
  * )
+ *
+ * const program = Effect.request(GetUserRequest({ id: 1 }), resolver)
+ * await Effect.runPromise(program) // => "User 1"
  * ```
  *
  * @category models
@@ -202,7 +205,7 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
  *
  * **Example** (Creating a request resolver)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * // Define a request type
@@ -224,6 +227,7 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
  *
  * // Use the resolver to handle requests
  * const getUserEffect = Effect.request(GetUserRequest({ id: 123 }), UserResolver)
+ * await Effect.runPromise(getUserEffect) // => "User 123"
  * ```
  *
  * @category constructors
@@ -248,7 +252,7 @@ export const make = <A extends Request.Any>(
  *
  * **Example** (Grouping requests by key)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetUserByRole extends Request.Request<string, Error> {
@@ -258,12 +262,14 @@ export const make = <A extends Request.Any>(
  * }
  * const GetUserByRole = Request.tagged<GetUserByRole>("GetUserByRole")
  *
+ * const batches: Array<[role: string, size: number]> = []
+ *
  * // Group requests by role for efficient batch processing
  * const UserByRoleResolver = RequestResolver.makeGrouped<GetUserByRole, string>({
  *   key: ({ request }) => request.role,
  *   resolver: (entries, role) =>
  *     Effect.sync(() => {
- *       console.log(`Processing ${entries.length} requests for role: ${role}`)
+ *       batches.push([role, entries.length])
  *       for (const entry of entries) {
  *         entry.completeUnsafe(
  *           Exit.succeed(`User ${entry.request.id} with role ${role}`)
@@ -271,6 +277,15 @@ export const make = <A extends Request.Any>(
  *       }
  *     })
  * })
+ *
+ * const program = Effect.all([
+ *   Effect.request<GetUserByRole>(GetUserByRole({ role: "admin", id: 1 }), UserByRoleResolver),
+ *   Effect.request<GetUserByRole>(GetUserByRole({ role: "admin", id: 2 }), UserByRoleResolver)
+ * ] as const, { concurrency: "unbounded" })
+ * const result = await Effect.runPromise(program)
+ *
+ * batches // => [["admin", 2]]
+ * result // => ["User 1 with role admin", "User 2 with role admin"]
  * ```
  *
  * @category constructors
@@ -305,7 +320,7 @@ const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
  *
  * **Example** (Creating a resolver from a pure function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Request, RequestResolver } from "effect"
  *
  * interface GetSquareRequest extends Request.Request<number> {
@@ -324,7 +339,7 @@ const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
  *   GetSquareRequest({ value: 5 }),
  *   SquareResolver
  * )
- * // Will resolve to 25
+ * await Effect.runPromise(getSquareEffect) // => 25
  * ```
  *
  * @category constructors
@@ -350,7 +365,7 @@ export const fromFunction = <A extends Request.Any>(
  *
  * **Example** (Batching pure request handling)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Request, RequestResolver } from "effect"
  *
  * interface GetDoubleRequest extends Request.Request<number> {
@@ -368,7 +383,8 @@ export const fromFunction = <A extends Request.Any>(
  * const effects = [1, 2, 3].map((value) =>
  *   Effect.request(GetDoubleRequest({ value }), DoubleResolver)
  * )
- * const batchedEffect = Effect.all(effects) // [2, 4, 6]
+ * const batchedEffect = Effect.all(effects)
+ * await Effect.runPromise(batchedEffect) // => [2, 4, 6]
  * ```
  *
  * @category constructors
@@ -393,7 +409,7 @@ export const fromFunctionBatched = <A extends Request.Any>(
  *
  * **Example** (Creating a resolver from an effectful function)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Request, RequestResolver } from "effect"
  *
  * interface GetUserFromAPIRequest extends Request.Request<string> {
@@ -406,13 +422,7 @@ export const fromFunctionBatched = <A extends Request.Any>(
  *
  * // Create a resolver that uses effects (like HTTP calls)
  * const UserAPIResolver = RequestResolver.fromEffect<GetUserFromAPIRequest>(
- *   (entry) =>
- *     Effect.gen(function*() {
- *       // Simulate an API call
- *       yield* Effect.sleep("100 millis")
- *       // Just return the result without error handling for simplicity
- *       return `User ${entry.request.id} from API`
- *     })
+ *   (entry) => Effect.succeed(`User ${entry.request.id} from API`)
  * )
  *
  * // Usage
@@ -420,6 +430,7 @@ export const fromFunctionBatched = <A extends Request.Any>(
  *   GetUserFromAPIRequest({ id: 123 }),
  *   UserAPIResolver
  * )
+ * await Effect.runPromise(getUserEffect) // => "User 123 from API"
  * ```
  *
  * @category constructors
@@ -456,9 +467,8 @@ export const fromEffect = <A extends Request.Any>(
  *
  * **Example** (Handling tagged request batches)
  *
- * ```ts
- * import { Effect, RequestResolver } from "effect"
- * import type { Request } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Request, RequestResolver } from "effect"
  *
  * interface GetUser extends Request.Request<string, Error> {
  *   readonly _tag: "GetUser"
@@ -471,6 +481,8 @@ export const fromEffect = <A extends Request.Any>(
  * }
  *
  * type MyRequest = GetUser | GetPost
+ * const GetUser = Request.tagged<GetUser>("GetUser")
+ * const GetPost = Request.tagged<GetPost>("GetPost")
  *
  * // Create a resolver that handles different request types
  * const MyResolver = RequestResolver.fromEffectTagged<MyRequest>()({
@@ -479,6 +491,12 @@ export const fromEffect = <A extends Request.Any>(
  *   GetPost: (requests) =>
  *     Effect.succeed(requests.map((req) => `Post ${req.request.id}`))
  * })
+ *
+ * const program = Effect.all([
+ *   Effect.request<GetUser>(GetUser({ id: 1 }), MyResolver),
+ *   Effect.request<GetPost>(GetPost({ id: 2 }), MyResolver)
+ * ] as const)
+ * await Effect.runPromise(program) // => ["User 1", "Post 2"]
  * ```
  *
  * @category constructors
@@ -534,7 +552,7 @@ export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string
  *
  * **Example** (Setting an effectful batch delay)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -550,17 +568,21 @@ export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string
  *   })
  * )
  *
- * // Set a custom delay effect (e.g., with logging)
+ * let delayRan = false
+ *
+ * // Set a custom delay effect
  * const resolverWithCustomDelay = RequestResolver.setDelayEffect(
  *   resolver,
- *   Effect.gen(function*() {
- *     yield* Effect.log("Waiting before processing batch...")
- *     yield* Effect.sleep("50 millis")
+ *   Effect.sync(() => {
+ *     delayRan = true
  *   })
  * )
+ *
+ * await Effect.runPromise(resolverWithCustomDelay.delay)
+ * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
  * ```
  *
- * @category delay
+ * @category delays & timeouts
  * @since 4.0.0
  */
 export const setDelayEffect: {
@@ -569,7 +591,7 @@ export const setDelayEffect: {
    *
    * **Example** (Setting an effectful batch delay)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -585,17 +607,21 @@ export const setDelayEffect: {
    *   })
    * )
    *
-   * // Set a custom delay effect (e.g., with logging)
+   * let delayRan = false
+   *
+   * // Set a custom delay effect
    * const resolverWithCustomDelay = RequestResolver.setDelayEffect(
    *   resolver,
-   *   Effect.gen(function*() {
-   *     yield* Effect.log("Waiting before processing batch...")
-   *     yield* Effect.sleep("50 millis")
+   *   Effect.sync(() => {
+   *     delayRan = true
    *   })
    * )
+   *
+   * await Effect.runPromise(resolverWithCustomDelay.delay)
+   * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
    * ```
    *
-   * @category delay
+   * @category delays & timeouts
    * @since 4.0.0
    */
   (delay: Effect.Effect<void>): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A>
@@ -604,7 +630,7 @@ export const setDelayEffect: {
    *
    * **Example** (Setting an effectful batch delay)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -620,17 +646,21 @@ export const setDelayEffect: {
    *   })
    * )
    *
-   * // Set a custom delay effect (e.g., with logging)
+   * let delayRan = false
+   *
+   * // Set a custom delay effect
    * const resolverWithCustomDelay = RequestResolver.setDelayEffect(
    *   resolver,
-   *   Effect.gen(function*() {
-   *     yield* Effect.log("Waiting before processing batch...")
-   *     yield* Effect.sleep("50 millis")
+   *   Effect.sync(() => {
+   *     delayRan = true
    *   })
    * )
+   *
+   * await Effect.runPromise(resolverWithCustomDelay.delay)
+   * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
    * ```
    *
-   * @category delay
+   * @category delays & timeouts
    * @since 4.0.0
    */
   <A extends Request.Any>(self: RequestResolver<A>, delay: Effect.Effect<void>): RequestResolver<A>
@@ -648,7 +678,7 @@ export const setDelayEffect: {
  *
  * **Example** (Setting a batch delay)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -667,11 +697,11 @@ export const setDelayEffect: {
  * // Add a 100ms delay to batch requests together
  * const delayedResolver = RequestResolver.setDelay(resolver, "100 millis")
  *
- * // Can also use number for milliseconds
- * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
+ * const program = Effect.request(GetDataRequest(), delayedResolver)
+ * await Effect.runPromise(program) // => "data"
  * ```
  *
- * @category delay
+ * @category delays & timeouts
  * @since 4.0.0
  */
 export const setDelay: {
@@ -680,7 +710,7 @@ export const setDelay: {
    *
    * **Example** (Setting a batch delay)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -699,11 +729,11 @@ export const setDelay: {
    * // Add a 100ms delay to batch requests together
    * const delayedResolver = RequestResolver.setDelay(resolver, "100 millis")
    *
-   * // Can also use number for milliseconds
-   * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
+   * const program = Effect.request(GetDataRequest(), delayedResolver)
+   * await Effect.runPromise(program) // => "data"
    * ```
    *
-   * @category delay
+   * @category delays & timeouts
    * @since 4.0.0
    */
   (duration: Duration.Input): <A extends Request.Any>(self: RequestResolver<A>) => RequestResolver<A>
@@ -712,7 +742,7 @@ export const setDelay: {
    *
    * **Example** (Setting a batch delay)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -731,11 +761,11 @@ export const setDelay: {
    * // Add a 100ms delay to batch requests together
    * const delayedResolver = RequestResolver.setDelay(resolver, "100 millis")
    *
-   * // Can also use number for milliseconds
-   * const delayedResolver2 = RequestResolver.setDelay(resolver, 100)
+   * const program = Effect.request(GetDataRequest(), delayedResolver)
+   * await Effect.runPromise(program) // => "data"
    * ```
    *
-   * @category delay
+   * @category delays & timeouts
    * @since 4.0.0
    */
   <A extends Request.Any>(self: RequestResolver<A>, duration: Duration.Input): RequestResolver<A>
@@ -753,7 +783,7 @@ export const setDelay: {
  *
  * **Example** (Running effects around request resolution)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -761,6 +791,8 @@ export const setDelay: {
  * }
  * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
  *
+ * const events: Array<string> = []
+ *
  * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
  *   Effect.sync(() => {
  *     for (const entry of entries) {
@@ -774,16 +806,20 @@ export const setDelay: {
  *   resolver,
  *   (entries) =>
  *     Effect.gen(function*() {
- *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
+ *       events.push(`Starting batch of ${entries.length} requests`)
  *       return entries.length
  *     }),
  *   (entries, initialSize) =>
- *     Effect.gen(function*() {
- *       yield* Effect.log(
- *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
- *       )
+ *     Effect.sync(() => {
+ *       events.push(`Batch completed with ${entries.length} requests (started with ${initialSize})`)
  *     })
  * )
+ *
+ * const program = Effect.request(GetDataRequest(), resolverWithAround)
+ * const result = await Effect.runPromise(program)
+ *
+ * events // => ["Starting batch of 1 requests", "Batch completed with 1 requests (started with 1)"]
+ * result // => "data"
  * ```
  *
  * @category combinators
@@ -795,7 +831,7 @@ export const around: {
    *
    * **Example** (Running effects around request resolution)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -803,6 +839,8 @@ export const around: {
    * }
    * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
    *
+   * const events: Array<string> = []
+   *
    * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
    *   Effect.sync(() => {
    *     for (const entry of entries) {
@@ -816,16 +854,20 @@ export const around: {
    *   resolver,
    *   (entries) =>
    *     Effect.gen(function*() {
-   *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
+   *       events.push(`Starting batch of ${entries.length} requests`)
    *       return entries.length
    *     }),
    *   (entries, initialSize) =>
-   *     Effect.gen(function*() {
-   *       yield* Effect.log(
-   *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
-   *       )
+   *     Effect.sync(() => {
+   *       events.push(`Batch completed with ${entries.length} requests (started with ${initialSize})`)
    *     })
    * )
+   *
+   * const program = Effect.request(GetDataRequest(), resolverWithAround)
+   * const result = await Effect.runPromise(program)
+   *
+   * events // => ["Starting batch of 1 requests", "Batch completed with 1 requests (started with 1)"]
+   * result // => "data"
    * ```
    *
    * @category combinators
@@ -840,7 +882,7 @@ export const around: {
    *
    * **Example** (Running effects around request resolution)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -848,6 +890,8 @@ export const around: {
    * }
    * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
    *
+   * const events: Array<string> = []
+   *
    * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
    *   Effect.sync(() => {
    *     for (const entry of entries) {
@@ -861,16 +905,20 @@ export const around: {
    *   resolver,
    *   (entries) =>
    *     Effect.gen(function*() {
-   *       yield* Effect.log(`Starting batch of ${entries.length} requests`)
+   *       events.push(`Starting batch of ${entries.length} requests`)
    *       return entries.length
    *     }),
    *   (entries, initialSize) =>
-   *     Effect.gen(function*() {
-   *       yield* Effect.log(
-   *         `Batch completed with ${entries.length} requests (started with ${initialSize})`
-   *       )
+   *     Effect.sync(() => {
+   *       events.push(`Batch completed with ${entries.length} requests (started with ${initialSize})`)
    *     })
    * )
+   *
+   * const program = Effect.request(GetDataRequest(), resolverWithAround)
+   * const result = await Effect.runPromise(program)
+   *
+   * events // => ["Starting batch of 1 requests", "Batch completed with 1 requests (started with 1)"]
+   * result // => "data"
    * ```
    *
    * @category combinators
@@ -928,7 +976,7 @@ export const never: RequestResolver<never> = make(() => Effect.never)
  *
  * **Example** (Limiting parallel request batches)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -937,9 +985,11 @@ export const never: RequestResolver<never> = make(() => Effect.never)
  * }
  * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
  *
+ * const batchSizes: Array<number> = []
+ *
  * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
  *   Effect.sync(() => {
- *     console.log(`Processing batch of ${entries.length} requests`)
+ *     batchSizes.push(entries.length)
  *     for (const entry of entries) {
  *       entry.completeUnsafe(Exit.succeed(`data-${entry.request.id}`))
  *     }
@@ -954,6 +1004,13 @@ export const never: RequestResolver<never> = make(() => Effect.never)
  *   { length: 12 },
  *   (_, i) => Effect.request(GetDataRequest({ id: i }), limitedResolver)
  * )
+ *
+ * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+ * batchSizes // => [5, 5, 2]
+ *
+ * result.length // => 12
+ *
+ * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
  * ```
  *
  * @category combinators
@@ -972,7 +1029,7 @@ export const batchN: {
    *
    * **Example** (Limiting parallel request batches)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -981,9 +1038,11 @@ export const batchN: {
    * }
    * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
    *
+   * const batchSizes: Array<number> = []
+   *
    * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
    *   Effect.sync(() => {
-   *     console.log(`Processing batch of ${entries.length} requests`)
+   *     batchSizes.push(entries.length)
    *     for (const entry of entries) {
    *       entry.completeUnsafe(Exit.succeed(`data-${entry.request.id}`))
    *     }
@@ -998,6 +1057,13 @@ export const batchN: {
    *   { length: 12 },
    *   (_, i) => Effect.request(GetDataRequest({ id: i }), limitedResolver)
    * )
+   *
+   * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+   * batchSizes // => [5, 5, 2]
+   *
+   * result.length // => 12
+   *
+   * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
    * ```
    *
    * @category combinators
@@ -1016,7 +1082,7 @@ export const batchN: {
    *
    * **Example** (Limiting parallel request batches)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -1025,9 +1091,11 @@ export const batchN: {
    * }
    * const GetDataRequest = Request.tagged<GetDataRequest>("GetDataRequest")
    *
+   * const batchSizes: Array<number> = []
+   *
    * const resolver = RequestResolver.make<GetDataRequest>((entries) =>
    *   Effect.sync(() => {
-   *     console.log(`Processing batch of ${entries.length} requests`)
+   *     batchSizes.push(entries.length)
    *     for (const entry of entries) {
    *       entry.completeUnsafe(Exit.succeed(`data-${entry.request.id}`))
    *     }
@@ -1042,6 +1110,13 @@ export const batchN: {
    *   { length: 12 },
    *   (_, i) => Effect.request(GetDataRequest({ id: i }), limitedResolver)
    * )
+   *
+   * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+   * batchSizes // => [5, 5, 2]
+   *
+   * result.length // => 12
+   *
+   * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
    * ```
    *
    * @category combinators
@@ -1060,7 +1135,7 @@ export const batchN: {
  *
  * **Example** (Grouping resolver requests)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetUserRequest extends Request.Request<string> {
@@ -1070,9 +1145,11 @@ export const batchN: {
  * }
  * const GetUserRequest = Request.tagged<GetUserRequest>("GetUserRequest")
  *
+ * const batchSizes: Array<number> = []
+ *
  * const resolver = RequestResolver.make<GetUserRequest>((entries) =>
  *   Effect.sync(() => {
- *     console.log(`Processing ${entries.length} users`)
+ *     batchSizes.push(entries.length)
  *     for (const entry of entries) {
  *       entry.completeUnsafe(Exit.succeed(`User ${entry.request.userId}`))
  *     }
@@ -1100,6 +1177,13 @@ export const batchN: {
  *     groupedResolver
  *   )
  * ]
+ *
+ * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+ * batchSizes.sort()
+ *
+ * batchSizes // => [1, 2]
+ *
+ * result // => ["User 1", "User 2", "User 3"]
  * ```
  *
  * @category combinators
@@ -1112,7 +1196,7 @@ export const grouped: {
    *
    * **Example** (Grouping resolver requests)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetUserRequest extends Request.Request<string> {
@@ -1122,9 +1206,11 @@ export const grouped: {
    * }
    * const GetUserRequest = Request.tagged<GetUserRequest>("GetUserRequest")
    *
+   * const batchSizes: Array<number> = []
+   *
    * const resolver = RequestResolver.make<GetUserRequest>((entries) =>
    *   Effect.sync(() => {
-   *     console.log(`Processing ${entries.length} users`)
+   *     batchSizes.push(entries.length)
    *     for (const entry of entries) {
    *       entry.completeUnsafe(Exit.succeed(`User ${entry.request.userId}`))
    *     }
@@ -1152,6 +1238,13 @@ export const grouped: {
    *     groupedResolver
    *   )
    * ]
+   *
+   * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+   * batchSizes.sort()
+   *
+   * batchSizes // => [1, 2]
+   *
+   * result // => ["User 1", "User 2", "User 3"]
    * ```
    *
    * @category combinators
@@ -1164,7 +1257,7 @@ export const grouped: {
    *
    * **Example** (Grouping resolver requests)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetUserRequest extends Request.Request<string> {
@@ -1174,9 +1267,11 @@ export const grouped: {
    * }
    * const GetUserRequest = Request.tagged<GetUserRequest>("GetUserRequest")
    *
+   * const batchSizes: Array<number> = []
+   *
    * const resolver = RequestResolver.make<GetUserRequest>((entries) =>
    *   Effect.sync(() => {
-   *     console.log(`Processing ${entries.length} users`)
+   *     batchSizes.push(entries.length)
    *     for (const entry of entries) {
    *       entry.completeUnsafe(Exit.succeed(`User ${entry.request.userId}`))
    *     }
@@ -1204,6 +1299,13 @@ export const grouped: {
    *     groupedResolver
    *   )
    * ]
+   *
+   * const result = await Effect.runPromise(Effect.all(requests, { concurrency: "unbounded" }))
+   * batchSizes.sort()
+   *
+   * batchSizes // => [1, 2]
+   *
+   * result // => ["User 1", "User 2", "User 3"]
    * ```
    *
    * @category combinators
@@ -1230,7 +1332,7 @@ export const grouped: {
  *
  * **Example** (Racing request resolvers)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -1261,6 +1363,8 @@ export const grouped: {
  *
  * // Race resolvers - will use whichever completes first
  * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
+ * const program = Effect.request(GetDataRequest({ id: 1 }), racingResolver)
+ * await Effect.runPromise(program) // => "fast-1"
  * ```
  *
  * @category combinators
@@ -1278,7 +1382,7 @@ export const race: {
    *
    * **Example** (Racing request resolvers)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -1309,6 +1413,8 @@ export const race: {
    *
    * // Race resolvers - will use whichever completes first
    * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
+   * const program = Effect.request(GetDataRequest({ id: 1 }), racingResolver)
+   * await Effect.runPromise(program) // => "fast-1"
    * ```
    *
    * @category combinators
@@ -1326,7 +1432,7 @@ export const race: {
    *
    * **Example** (Racing request resolvers)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -1357,6 +1463,8 @@ export const race: {
    *
    * // Race resolvers - will use whichever completes first
    * const racingResolver = RequestResolver.race(fastResolver, slowResolver)
+   * const program = Effect.request(GetDataRequest({ id: 1 }), racingResolver)
+   * await Effect.runPromise(program) // => "fast-1"
    * ```
    *
    * @category combinators
@@ -1377,7 +1485,7 @@ export const race: {
  *
  * **Example** (Adding a tracing span)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Exit, Request, RequestResolver } from "effect"
  *
  * interface GetDataRequest extends Request.Request<string> {
@@ -1408,6 +1516,7 @@ export const race: {
  *
  * // Spans will automatically include batch size and request links
  * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
+ * await Effect.runPromise(effect) // => "data-123"
  * ```
  *
  * @category combinators
@@ -1420,7 +1529,7 @@ export const withSpan: {
    *
    * **Example** (Adding a tracing span)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -1451,6 +1560,7 @@ export const withSpan: {
    *
    * // Spans will automatically include batch size and request links
    * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
+   * await Effect.runPromise(effect) // => "data-123"
    * ```
    *
    * @category combinators
@@ -1466,7 +1576,7 @@ export const withSpan: {
    *
    * **Example** (Adding a tracing span)
    *
-   * ```ts
+   * ```ts import.meta.vitest
    * import { Effect, Exit, Request, RequestResolver } from "effect"
    *
    * interface GetDataRequest extends Request.Request<string> {
@@ -1497,6 +1607,7 @@ export const withSpan: {
    *
    * // Spans will automatically include batch size and request links
    * const effect = Effect.request(GetDataRequest({ id: 123 }), tracedResolver)
+   * await Effect.runPromise(effect) // => "data-123"
    * ```
    *
    * @category combinators
@@ -1900,7 +2011,7 @@ export const withCache: {
  * @see {@link withCache} for in-memory resolver caching that does not require persistable request values or a persistence store
  * @see {@link asCache} for exposing resolver results through a `Cache` instead of returning another resolver
  *
- * @category Persistence
+ * @category caching
  * @since 4.0.0
  */
 export const persisted: {
@@ -1924,7 +2035,7 @@ export const persisted: {
    * @see {@link withCache} for in-memory resolver caching that does not require persistable request values or a persistence store
    * @see {@link asCache} for exposing resolver results through a `Cache` instead of returning another resolver
    *
-   * @category Persistence
+   * @category caching
    * @since 4.0.0
    */
   <A extends Request.Request<any, Persistence.PersistenceError | Schema.SchemaError, any> & Persistable.Any>(
@@ -1958,7 +2069,7 @@ export const persisted: {
    * @see {@link withCache} for in-memory resolver caching that does not require persistable request values or a persistence store
    * @see {@link asCache} for exposing resolver results through a `Cache` instead of returning another resolver
    *
-   * @category Persistence
+   * @category caching
    * @since 4.0.0
    */
   <
@@ -2008,7 +2119,7 @@ export const persisted: {
      * @see {@link withCache} for in-memory resolver caching that does not require persistable request values or a persistence store
      * @see {@link asCache} for exposing resolver results through a `Cache` instead of returning another resolver
      *
-     * @category Persistence
+     * @category caching
      * @since 4.0.0
      */
     A>({