effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/RequestResolver.ts

@@ -173,15 +173,43 @@ const RequestResolverProto = {
 /**
  * Returns `true` if the specified value is a `RequestResolver`, `false` otherwise.
  *
+ * **When to use**
+ *
+ * Use to narrow unknown values before passing them to APIs that require a
+ * `RequestResolver`.
+ *
+ * @see {@link RequestResolver} for the type narrowed by this guard
+ *
  * @category guards
  * @since 2.0.0
  */
 export const isRequestResolver = (u: unknown): u is RequestResolver<any> => hasProperty(u, TypeId)
 
 /**
- * Low-level constructor for creating a request resolver with fine-grained
+ * Creates a request resolver with fine-grained
  * control over its behavior.
  *
+ * **When to use**
+ *
+ * Use when you need to supply the resolver batching primitives directly,
+ * including the batch key, optional pre-check, delay effect, collection cutoff,
+ * and batch runner.
+ *
+ * **Details**
+ *
+ * `batchKey` groups request entries, `delay` schedules batch execution,
+ * `collectWhile` can end collection early, and `runAll` receives a non-empty
+ * batch for one key.
+ *
+ * **Gotchas**
+ *
+ * Accepted entries must be completed. If `runAll` succeeds with incomplete
+ * entries, waiting requests fail. If `preCheck` returns `false`, the entry is
+ * not batched, so it must be completed or linked to another completion path.
+ *
+ * @see {@link make} for constructing a resolver from a batch runner
+ * @see {@link makeGrouped} for constructing a resolver that groups requests by key
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -756,8 +784,7 @@ 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`.
+ * Wraps request resolver execution between `before` and `after` effects.
  *
  * **Example** (Running effects around request resolution)
  *
@@ -799,8 +826,7 @@ export const setDelay: {
  */
 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`.
+   * Wraps request resolver execution between `before` and `after` effects.
    *
    * **Example** (Running effects around request resolution)
    *
@@ -845,8 +871,7 @@ export const around: {
     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`.
+   * Wraps request resolver execution between `before` and `after` effects.
    *
    * **Example** (Running effects around request resolution)
    *
@@ -907,7 +932,19 @@ export const around: {
   }))
 
 /**
- * A request resolver that never executes requests.
+ * Creates a request resolver that never executes requests.
+ *
+ * **When to use**
+ *
+ * Use as a resolver value for request types that are statically impossible and
+ * should never be issued.
+ *
+ * **Gotchas**
+ *
+ * If this resolver is used for an actual request, the request waits forever
+ * unless the fiber is interrupted.
+ *
+ * @see {@link make} for constructing a resolver that executes batches and completes request entries
  *
  * @category constructors
  * @since 2.0.0
@@ -1053,7 +1090,7 @@ export const batchN: {
   }))
 
 /**
- * Transform a request resolver by grouping requests using the specified key
+ * Transforms a request resolver by grouping requests using the specified key
  * function.
  *
  * **Example** (Grouping resolver requests)
@@ -1105,7 +1142,7 @@ export const batchN: {
  */
 export const grouped: {
   /**
-   * Transform a request resolver by grouping requests using the specified key
+   * Transforms a request resolver by grouping requests using the specified key
    * function.
    *
    * **Example** (Grouping resolver requests)
@@ -1157,7 +1194,7 @@ export const grouped: {
    */
   <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
+   * Transforms a request resolver by grouping requests using the specified key
    * function.
    *
    * **Example** (Grouping resolver requests)
@@ -1370,7 +1407,7 @@ export const race: {
   ))
 
 /**
- * Add a tracing span to the request resolver, which will also add any span
+ * Adds a tracing span to the request resolver, which will also add any span
  * links from the request's.
  *
  * **Example** (Adding a tracing span)
@@ -1413,7 +1450,7 @@ export const race: {
  */
 export const withSpan: {
   /**
-   * Add a tracing span to the request resolver, which will also add any span
+   * Adds a tracing span to the request resolver, which will also add any span
    * links from the request's.
    *
    * **Example** (Adding a tracing span)
@@ -1459,7 +1496,7 @@ export const withSpan: {
     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
+   * Adds a tracing span to the request resolver, which will also add any span
    * links from the request's.
    *
    * **Example** (Adding a tracing span)
@@ -1538,6 +1575,26 @@ 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.
  *
+ * **When to use**
+ *
+ * Use to turn a request resolver into a first-class `Cache` when callers need
+ * cache lookup, refresh, invalidation, or inspection around request results.
+ *
+ * **Details**
+ *
+ * The request value is the cache key. Cache misses run the resolver via
+ * `Effect.request`, `timeToLive` receives the request `Exit` and the request,
+ * and `requireServicesAt` controls whether services are required at lookup time
+ * or construction time.
+ *
+ * **Gotchas**
+ *
+ * Cache hits depend on the request value's equality semantics.
+ *
+ * @see {@link withCache} for keeping caching behind a resolver used with `Effect.request`
+ * @see {@link persisted} for storing persistable request results outside process memory
+ * @see {@link Cache.Cache} for operations available on the returned cache
+ *
  * @category Caching
  * @since 4.0.0
  */
@@ -1546,6 +1603,26 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to turn a request resolver into a first-class `Cache` when callers need
+   * cache lookup, refresh, invalidation, or inspection around request results.
+   *
+   * **Details**
+   *
+   * The request value is the cache key. Cache misses run the resolver via
+   * `Effect.request`, `timeToLive` receives the request `Exit` and the request,
+   * and `requireServicesAt` controls whether services are required at lookup time
+   * or construction time.
+   *
+   * **Gotchas**
+   *
+   * Cache hits depend on the request value's equality semantics.
+   *
+   * @see {@link withCache} for keeping caching behind a resolver used with `Effect.request`
+   * @see {@link persisted} for storing persistable request results outside process memory
+   * @see {@link Cache.Cache} for operations available on the returned cache
+   *
    * @category Caching
    * @since 4.0.0
    */
@@ -1572,6 +1649,26 @@ 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.
    *
+   * **When to use**
+   *
+   * Use to turn a request resolver into a first-class `Cache` when callers need
+   * cache lookup, refresh, invalidation, or inspection around request results.
+   *
+   * **Details**
+   *
+   * The request value is the cache key. Cache misses run the resolver via
+   * `Effect.request`, `timeToLive` receives the request `Exit` and the request,
+   * and `requireServicesAt` controls whether services are required at lookup time
+   * or construction time.
+   *
+   * **Gotchas**
+   *
+   * Cache hits depend on the request value's equality semantics.
+   *
+   * @see {@link withCache} for keeping caching behind a resolver used with `Effect.request`
+   * @see {@link persisted} for storing persistable request results outside process memory
+   * @see {@link Cache.Cache} for operations available on the returned cache
+   *
    * @category Caching
    * @since 4.0.0
    */
@@ -1619,16 +1716,54 @@ export const asCache: {
   }) as any)
 
 /**
- * Adds caching capabilities to a request resolver, allowing it to cache
- * results up to a specified capacity.
+ * Adds a bounded in-memory cache to a request resolver.
+ *
+ * **When to use**
+ *
+ * Use to reuse completed results for repeated equal request values while still
+ * passing a `RequestResolver` to `Effect.request`.
+ *
+ * **Details**
+ *
+ * Running the returned effect creates the cache and returns a wrapped resolver.
+ * The cache stores completed success or failure results by request equality up
+ * to `capacity`. The `strategy` option controls eviction order and defaults to
+ * `"lru"`; `"fifo"` keeps insertion order.
+ *
+ * **Gotchas**
+ *
+ * Entries do not expire by time, and completed failures are cached the same as
+ * successes. Request equality controls cache hits.
+ *
+ * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
+ * @see {@link persisted} for backing persistable requests with the configured persistence store
  *
  * @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.
+   * Adds a bounded in-memory cache to a request resolver.
+   *
+   * **When to use**
+   *
+   * Use to reuse completed results for repeated equal request values while still
+   * passing a `RequestResolver` to `Effect.request`.
+   *
+   * **Details**
+   *
+   * Running the returned effect creates the cache and returns a wrapped resolver.
+   * The cache stores completed success or failure results by request equality up
+   * to `capacity`. The `strategy` option controls eviction order and defaults to
+   * `"lru"`; `"fifo"` keeps insertion order.
+   *
+   * **Gotchas**
+   *
+   * Entries do not expire by time, and completed failures are cached the same as
+   * successes. Request equality controls cache hits.
+   *
+   * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
+   * @see {@link persisted} for backing persistable requests with the configured persistence store
    *
    * @category Caching
    * @since 4.0.0
@@ -1640,8 +1775,27 @@ export const withCache: {
     }
   ): (self: RequestResolver<A>) => Effect.Effect<RequestResolver<A>>
   /**
-   * Adds caching capabilities to a request resolver, allowing it to cache
-   * results up to a specified capacity.
+   * Adds a bounded in-memory cache to a request resolver.
+   *
+   * **When to use**
+   *
+   * Use to reuse completed results for repeated equal request values while still
+   * passing a `RequestResolver` to `Effect.request`.
+   *
+   * **Details**
+   *
+   * Running the returned effect creates the cache and returns a wrapped resolver.
+   * The cache stores completed success or failure results by request equality up
+   * to `capacity`. The `strategy` option controls eviction order and defaults to
+   * `"lru"`; `"fifo"` keeps insertion order.
+   *
+   * **Gotchas**
+   *
+   * Entries do not expire by time, and completed failures are cached the same as
+   * successes. Request equality controls cache hits.
+   *
+   * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
+   * @see {@link persisted} for backing persistable requests with the configured persistence store
    *
    * @category Caching
    * @since 4.0.0
@@ -1660,15 +1814,53 @@ export const withCache: {
   Effect.sync(() => {
     const strategy = options.strategy ?? "lru"
     const cache = MutableHashMap.empty</**
-     * Adds caching capabilities to a request resolver, allowing it to cache
-     * results up to a specified capacity.
+     * Adds a bounded in-memory cache to a request resolver.
+     *
+     * **When to use**
+     *
+     * Use to reuse completed results for repeated equal request values while still
+     * passing a `RequestResolver` to `Effect.request`.
+     *
+     * **Details**
+     *
+     * Running the returned effect creates the cache and returns a wrapped resolver.
+     * The cache stores completed success or failure results by request equality up
+     * to `capacity`. The `strategy` option controls eviction order and defaults to
+     * `"lru"`; `"fifo"` keeps insertion order.
+     *
+     * **Gotchas**
+     *
+     * Entries do not expire by time, and completed failures are cached the same as
+     * successes. Request equality controls cache hits.
+     *
+     * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
+     * @see {@link persisted} for backing persistable requests with the configured persistence store
      *
      * @category Caching
      * @since 4.0.0
      */
     A, /**
-     * Adds caching capabilities to a request resolver, allowing it to cache
-     * results up to a specified capacity.
+     * Adds a bounded in-memory cache to a request resolver.
+     *
+     * **When to use**
+     *
+     * Use to reuse completed results for repeated equal request values while still
+     * passing a `RequestResolver` to `Effect.request`.
+     *
+     * **Details**
+     *
+     * Running the returned effect creates the cache and returns a wrapped resolver.
+     * The cache stores completed success or failure results by request equality up
+     * to `capacity`. The `strategy` option controls eviction order and defaults to
+     * `"lru"`; `"fifo"` keeps insertion order.
+     *
+     * **Gotchas**
+     *
+     * Entries do not expire by time, and completed failures are cached the same as
+     * successes. Request equality controls cache hits.
+     *
+     * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
+     * @see {@link persisted} for backing persistable requests with the configured persistence store
      *
      * @category Caching
      * @since 4.0.0
@@ -1726,12 +1918,22 @@ export const withCache: {
 /**
  * Wraps a request resolver with persistent storage for persistable requests.
  *
+ * **When to use**
+ *
+ * Use to keep a `RequestResolver` interface while reusing completed
+ * `Persistable` request results through a `Persistence` store.
+ *
  * **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.
- * Creating the persisted resolver requires `Persistence.Persistence` and `Scope`.
+ * running the underlying resolver. Missing entries are resolved normally and
+ * written back to the store. Entries marked stale by `staleWhileRevalidate`
+ * receive the stored result and are also resolved again so the refreshed result
+ * can be written back to the store. Creating the persisted resolver requires
+ * `Persistence.Persistence` and `Scope`.
+ *
+ * @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
  * @since 4.0.0
@@ -1740,12 +1942,22 @@ export const persisted: {
   /**
    * Wraps a request resolver with persistent storage for persistable requests.
    *
+   * **When to use**
+   *
+   * Use to keep a `RequestResolver` interface while reusing completed
+   * `Persistable` request results through a `Persistence` store.
+   *
    * **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.
-   * Creating the persisted resolver requires `Persistence.Persistence` and `Scope`.
+   * running the underlying resolver. Missing entries are resolved normally and
+   * written back to the store. Entries marked stale by `staleWhileRevalidate`
+   * receive the stored result and are also resolved again so the refreshed result
+   * can be written back to the store. Creating the persisted resolver requires
+   * `Persistence.Persistence` and `Scope`.
+   *
+   * @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
    * @since 4.0.0
@@ -1764,12 +1976,22 @@ export const persisted: {
   /**
    * Wraps a request resolver with persistent storage for persistable requests.
    *
+   * **When to use**
+   *
+   * Use to keep a `RequestResolver` interface while reusing completed
+   * `Persistable` request results through a `Persistence` store.
+   *
    * **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.
-   * Creating the persisted resolver requires `Persistence.Persistence` and `Scope`.
+   * running the underlying resolver. Missing entries are resolved normally and
+   * written back to the store. Entries marked stale by `staleWhileRevalidate`
+   * receive the stored result and are also resolved again so the refreshed result
+   * can be written back to the store. Creating the persisted resolver requires
+   * `Persistence.Persistence` and `Scope`.
+   *
+   * @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
    * @since 4.0.0
@@ -1804,12 +2026,22 @@ export const persisted: {
     return makeWith</**
      * Wraps a request resolver with persistent storage for persistable requests.
      *
+     * **When to use**
+     *
+     * Use to keep a `RequestResolver` interface while reusing completed
+     * `Persistable` request results through a `Persistence` store.
+     *
      * **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.
-     * Creating the persisted resolver requires `Persistence.Persistence` and `Scope`.
+     * running the underlying resolver. Missing entries are resolved normally and
+     * written back to the store. Entries marked stale by `staleWhileRevalidate`
+     * receive the stored result and are also resolved again so the refreshed result
+     * can be written back to the store. Creating the persisted resolver requires
+     * `Persistence.Persistence` and `Scope`.
+     *
+     * @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
      * @since 4.0.0

package/src/Resource.ts

@@ -50,6 +50,16 @@ const TypeId = "~effect/Resource" as const
  * A `Resource` is a value loaded into memory that can be refreshed manually or
  * automatically according to a schedule.
  *
+ * **When to use**
+ *
+ * Use to model a scoped value whose latest acquisition result is kept available
+ * for repeated reads and can be refreshed manually or on a schedule.
+ *
+ * @see {@link manual} for creating a resource refreshed by the caller
+ * @see {@link auto} for creating a resource refreshed according to a schedule
+ * @see {@link get} for reading the currently stored acquisition result
+ * @see {@link refresh} for forcing a new acquisition
+ *
  * @category models
  * @since 2.0.0
  */
@@ -62,6 +72,15 @@ export interface Resource<in out A, in out E = never> extends Pipeable {
 /**
  * Returns `true` if the specified value is a `Resource`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown values at runtime boundaries before treating them as
+ * `Resource` values.
+ *
+ * **Details**
+ *
+ * This predicate narrows the input to `Resource<unknown, unknown>`.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -92,6 +111,13 @@ const makeUnsafe = <A, E>(
 /**
  * Creates a `Resource` that must be refreshed manually.
  *
+ * **When to use**
+ *
+ * Use when you need to control the timing of resource refreshes yourself rather
+ * than relying on an automatic schedule.
+ *
+ * @see {@link auto} for schedule-driven automatic refreshes
+ * @see {@link refresh} to manually trigger a resource refresh
  * @category constructors
  * @since 2.0.0
  */
@@ -113,6 +139,14 @@ export const manual = <A, E, R>(
  * Creates a `Resource` that refreshes automatically according to the supplied
  * schedule.
  *
+ * **When to use**
+ *
+ * Use when a resource should refresh in the background according to a schedule
+ * for the lifetime of its scope.
+ *
+ * @see {@link manual} for caller-controlled refresh timing
+ * @see {@link refresh} to trigger a refresh explicitly
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -128,6 +162,17 @@ export const auto = <A, E, R, Out, E2, R2>(
 /**
  * Retrieves the current value stored in this resource.
  *
+ * **When to use**
+ *
+ * Use to read the value currently cached by a `Resource`.
+ *
+ * **Gotchas**
+ *
+ * If the resource currently stores a failed acquisition result, the returned
+ * effect fails with the stored error.
+ *
+ * @see {@link refresh} to re-run acquisition and update the stored value before a later read
+ *
  * @category getters
  * @since 2.0.0
  */
@@ -137,11 +182,25 @@ export const get = <A, E>(self: Resource<A, E>): Effect.Effect<A, E> =>
 /**
  * Re-runs this resource's acquisition effect and updates the current value.
  *
+ * **When to use**
+ *
+ * Use to force an existing `Resource` to reacquire its value at a
+ * caller-controlled point.
+ *
  * **Details**
  *
- * Refreshing replaces the value stored in the resource's scoped reference and
- * releases resources associated with the previous value. If acquisition fails,
- * the returned effect fails with the acquisition error.
+ * When acquisition succeeds, refreshing replaces the value stored in the
+ * resource's scoped reference and releases resources associated with the
+ * previous value.
+ *
+ * **Gotchas**
+ *
+ * If acquisition fails, the returned effect fails and the previously stored
+ * result is left as what `get` reads.
+ *
+ * @see {@link get} for reading the current stored value
+ * @see {@link manual} for resources refreshed only by caller action
+ * @see {@link auto} for schedule-driven automatic refreshes
  *
  * @category utils
  * @since 2.0.0