effect 4.0.0 → 4.0.2

package/src/Request.ts

@@ -7,6 +7,7 @@
  * `RequestResolver`, which performs backend-specific loading and completes each
  * pending request entry with a success, failure, cause, exit, or effect.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type * as Cause from "./Cause.ts"
@@ -45,6 +46,7 @@ const TypeId = "~effect/Request"
  *
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -65,6 +67,7 @@ export interface Request<out A, out E = never, out R = never> extends Variance<A
  * @see {@link Services} for extracting a request's service requirements
  * @see {@link Result} for the exit type produced by completing a request
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -78,6 +81,7 @@ export type Any = Request<any, any, any>
  * This marker preserves the success, error, and service requirement types for
  * Effect's type-level machinery. Users normally get it by extending `Request`.
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -116,6 +120,7 @@ export interface Variance<out A, out E, out R> {
  * request.id // => 123
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -140,6 +145,7 @@ export interface Constructor<R extends Request<any, any, any>, T extends keyof R
  *
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -163,6 +169,7 @@ export type Error<T extends Request<any, any, any>> = [T] extends [Request<infer
  *
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -172,6 +179,7 @@ export type Success<T extends Request<any, any, any>> = [T] extends [Request<inf
 /**
  * A utility type to extract the requirements type from a `Request`.
  *
+ * @stability stable
  * @category utility types
  * @since 4.0.0
  */
@@ -196,6 +204,7 @@ export type Services<T extends Request<any, any, any>> = [T] extends [Request<in
  *
  * ```
  *
+ * @stability stable
  * @category utility types
  * @since 2.0.0
  */
@@ -221,6 +230,7 @@ const requestVariance = Equal.byReferenceUnsafe({
  * `Request.TaggedClass`. Most users should use those constructors instead of
  * interacting with the prototype directly.
  *
+ * @stability stable
  * @category prototypes
  * @since 4.0.0
  */
@@ -253,6 +263,7 @@ export const RequestPrototype: Request<any, any, any> = {
  * Request.isRequest("not a request") // => false
  * ```
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -287,6 +298,7 @@ export const isRequest = (u: unknown): u is Request<unknown, unknown, unknown> =
  * request.includeSettings // => true
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -331,6 +343,7 @@ export const of = <R extends Request<any, any, any>>(): Constructor<R> => (args)
  * Array.of(userRequest._tag, postRequest._tag) // => ["GetUser", "GetPost"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -364,6 +377,7 @@ export const tagged = <R extends Request<any, any, any> & { _tag: string }>(
  * getUserRequest.id // => 123
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -403,6 +417,7 @@ export const Class: new<A extends Record<string, any>, Success, Error = never, C
  * request.id // => 123
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -430,6 +445,7 @@ export const TaggedClass = <Tag extends string>(
  * @see {@link fail} for completing an entry with a typed failure
  * @see {@link failCause} for completing an entry with a failure `Cause`
  *
+ * @stability stable
  * @category completion
  * @since 2.0.0
  */
@@ -447,6 +463,7 @@ export const complete: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -464,6 +481,7 @@ export const complete: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -496,6 +514,7 @@ export const complete: {
  * @see {@link fail} for completing an entry with a typed failure
  * @see {@link failCause} for completing an entry with a failure `Cause`
  *
+ * @stability stable
  * @category completion
  * @since 2.0.0
  */
@@ -522,6 +541,7 @@ export const completeEffect: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -548,6 +568,7 @@ export const completeEffect: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -574,6 +595,7 @@ export const completeEffect: {
  * @see {@link completeEffect} for completing an entry from an effect result
  * @see {@link succeed} for completing an entry successfully
  *
+ * @stability stable
  * @category completion
  * @since 2.0.0
  */
@@ -591,6 +613,7 @@ export const fail: {
    * @see {@link completeEffect} for completing an entry from an effect result
    * @see {@link succeed} for completing an entry successfully
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -608,6 +631,7 @@ export const fail: {
    * @see {@link completeEffect} for completing an entry from an effect result
    * @see {@link succeed} for completing an entry successfully
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -630,6 +654,7 @@ export const fail: {
  * @see {@link completeEffect} for completing an entry from an effect result
  * @see {@link succeed} for completing an entry successfully
  *
+ * @stability stable
  * @category completion
  * @since 2.0.0
  */
@@ -647,6 +672,7 @@ export const failCause: {
    * @see {@link completeEffect} for completing an entry from an effect result
    * @see {@link succeed} for completing an entry successfully
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -664,6 +690,7 @@ export const failCause: {
    * @see {@link completeEffect} for completing an entry from an effect result
    * @see {@link succeed} for completing an entry successfully
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -687,6 +714,7 @@ export const failCause: {
  * @see {@link fail} for completing an entry with a typed failure
  * @see {@link failCause} for completing an entry with a failure `Cause`
  *
+ * @stability stable
  * @category completion
  * @since 2.0.0
  */
@@ -704,6 +732,7 @@ export const succeed: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -721,6 +750,7 @@ export const succeed: {
    * @see {@link fail} for completing an entry with a typed failure
    * @see {@link failCause} for completing an entry with a failure `Cause`
    *
+   * @stability stable
    * @category completion
    * @since 2.0.0
    */
@@ -740,6 +770,7 @@ export const succeed: {
  * an `uninterruptible` flag used by batching and caching internals, and the
  * `completeUnsafe` callback used by resolvers to supply the final `Exit`.
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -766,6 +797,7 @@ export interface Entry<out R> {
  * most application code receives entries from a `RequestResolver` instead of
  * constructing them directly.
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */

package/src/RequestResolver.ts

@@ -7,6 +7,7 @@
  * resolver shapes and tools for controlling batching, grouping, delays,
  * tracing, caching, racing, hooks around resolver execution, and persistence.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import type { NonEmptyArray } from "./Array.ts"
@@ -75,6 +76,7 @@ const TypeId = "~effect/RequestResolver"
  * await Effect.runPromise(program) // => "User 1"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -108,6 +110,7 @@ export interface RequestResolver<in A extends Request.Any> extends RequestResolv
 /**
  * Namespace containing type-level helpers associated with `RequestResolver`.
  *
+ * @stability stable
  * @since 2.0.0
  */
 export declare namespace RequestResolver {
@@ -149,6 +152,7 @@ const RequestResolverProto = {
  *
  * @see {@link RequestResolver} for the type narrowed by this guard
  *
+ * @stability stable
  * @category guards
  * @since 2.0.0
  */
@@ -179,6 +183,7 @@ export const isRequestResolver = (u: unknown): u is RequestResolver<any> => hasP
  * @see {@link make} for constructing a resolver from a batch runner
  * @see {@link makeGrouped} for constructing a resolver that groups requests by key
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -231,6 +236,7 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
  * await Effect.runPromise(getUserEffect) // => "User 123"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -289,6 +295,7 @@ export const make = <A extends Request.Any>(
  * result // => ["User 1 with role admin", "User 2 with role admin"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -343,6 +350,7 @@ const hashGroupKey = <A, K>(get: (entry: Request.Entry<A>) => K) => {
  * await Effect.runPromise(getSquareEffect) // => 25
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -388,6 +396,7 @@ export const fromFunction = <A extends Request.Any>(
  * await Effect.runPromise(batchedEffect) // => [2, 4, 6]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -434,6 +443,7 @@ export const fromFunctionBatched = <A extends Request.Any>(
  * await Effect.runPromise(getUserEffect) // => "User 123 from API"
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -500,6 +510,7 @@ export const fromEffect = <A extends Request.Any>(
  * await Effect.runPromise(program) // => ["User 1", "Post 2"]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -584,6 +595,7 @@ export const fromEffectTagged = <A extends Request.Any & { readonly _tag: string
  * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
  * ```
  *
+ * @stability stable
  * @category delays & timeouts
  * @since 4.0.0
  */
@@ -623,6 +635,7 @@ export const setDelayEffect: {
    * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
    * ```
    *
+   * @stability stable
    * @category delays & timeouts
    * @since 4.0.0
    */
@@ -662,6 +675,7 @@ export const setDelayEffect: {
    * Array.of(delayRan, RequestResolver.isRequestResolver(resolverWithCustomDelay)) // => [true, true]
    * ```
    *
+   * @stability stable
    * @category delays & timeouts
    * @since 4.0.0
    */
@@ -703,6 +717,7 @@ export const setDelayEffect: {
  * await Effect.runPromise(program) // => "data"
  * ```
  *
+ * @stability stable
  * @category delays & timeouts
  * @since 4.0.0
  */
@@ -735,6 +750,7 @@ export const setDelay: {
    * await Effect.runPromise(program) // => "data"
    * ```
    *
+   * @stability stable
    * @category delays & timeouts
    * @since 4.0.0
    */
@@ -767,6 +783,7 @@ export const setDelay: {
    * await Effect.runPromise(program) // => "data"
    * ```
    *
+   * @stability stable
    * @category delays & timeouts
    * @since 4.0.0
    */
@@ -824,6 +841,7 @@ export const setDelay: {
  * result // => "data"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -872,6 +890,7 @@ export const around: {
    * result // => "data"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -923,6 +942,7 @@ export const around: {
    * result // => "data"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -961,6 +981,7 @@ export const around: {
  *
  * @see {@link make} for constructing a resolver that executes batches and completes request entries
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -1016,6 +1037,7 @@ export const never: RequestResolver<never> = make(() => Effect.never)
  * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1070,6 +1092,7 @@ export const batchN: {
    * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1124,6 +1147,7 @@ export const batchN: {
    * Array.of(result[0], result[11]) // => ["data-0", "data-11"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1193,6 +1217,7 @@ export const batchN: {
  * result // => ["User 1", "User 2", "User 3"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1254,6 +1279,7 @@ export const grouped: {
    * result // => ["User 1", "User 2", "User 3"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1315,6 +1341,7 @@ export const grouped: {
    * result // => ["User 1", "User 2", "User 3"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1374,6 +1401,7 @@ export const grouped: {
  * await Effect.runPromise(program) // => "fast-1"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 2.0.0
  */
@@ -1424,6 +1452,7 @@ export const race: {
    * await Effect.runPromise(program) // => "fast-1"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1474,6 +1503,7 @@ export const race: {
    * await Effect.runPromise(program) // => "fast-1"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 2.0.0
    */
@@ -1526,6 +1556,7 @@ export const race: {
  * await Effect.runPromise(effect) // => "data-123"
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1570,6 +1601,7 @@ export const withSpan: {
    * await Effect.runPromise(effect) // => "data-123"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1617,6 +1649,7 @@ export const withSpan: {
    * await Effect.runPromise(effect) // => "data-123"
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1678,6 +1711,7 @@ export const withSpan: {
  * @see {@link persisted} for storing persistable request results outside process memory
  * @see {@link Cache.Cache} for operations available on the returned cache
  *
+ * @stability stable
  * @category caching
  * @since 4.0.0
  */
@@ -1706,6 +1740,7 @@ export const asCache: {
    * @see {@link persisted} for storing persistable request results outside process memory
    * @see {@link Cache.Cache} for operations available on the returned cache
    *
+   * @stability stable
    * @category caching
    * @since 4.0.0
    */
@@ -1752,6 +1787,7 @@ export const asCache: {
    * @see {@link persisted} for storing persistable request results outside process memory
    * @see {@link Cache.Cache} for operations available on the returned cache
    *
+   * @stability stable
    * @category caching
    * @since 4.0.0
    */
@@ -1798,6 +1834,12 @@ export const asCache: {
     requireServicesAt: options.requireServicesAt ?? "lookup" as ServiceMode
   }) as any)
 
+interface CacheEntry<A extends Request.Any> {
+  readonly entry: Request.Entry<A>
+  exit: Request.Result<A> | undefined
+  pending: Array<Request.Entry<A>>
+}
+
 /**
  * Adds a bounded in-memory cache to a request resolver.
  *
@@ -1822,6 +1864,7 @@ export const asCache: {
  * @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
  *
+ * @stability stable
  * @category caching
  * @since 4.0.0
  */
@@ -1850,6 +1893,7 @@ export const withCache: {
    * @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
    *
+   * @stability stable
    * @category caching
    * @since 4.0.0
    */
@@ -1883,6 +1927,7 @@ export const withCache: {
    * @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
    *
+   * @stability stable
    * @category caching
    * @since 4.0.0
    */
@@ -1923,6 +1968,7 @@ export const withCache: {
      * @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
      *
+     * @stability stable
      * @category caching
      * @since 4.0.0
      */
@@ -1950,13 +1996,11 @@ export const withCache: {
      * @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
      *
+     * @stability stable
      * @category caching
      * @since 4.0.0
      */
-    {
-      readonly entry: Request.Entry<A>;
-      exit: Request.Result<A> | undefined;
-    }>()
+    CacheEntry<A>>()
     return makeWith({
       ...self,
       runAll(entries, key) {
@@ -1974,7 +2018,7 @@ export const withCache: {
       preCheck(entry) {
         const ocached = MutableHashMap.get(cache, entry.request)
         if (ocached._tag === "None") {
-          const cached = { entry, exit: undefined as Request.Result<A> | undefined }
+          const cached: CacheEntry<A> = { entry, exit: undefined, pending: [] }
           MutableHashMap.set(cache, entry.request, cached)
           const prevComplete = entry.completeUnsafe
           entry.completeUnsafe = function(exit) {
@@ -1988,7 +2032,12 @@ export const withCache: {
             } else {
               cached.exit = exit as any
             }
+            const pending = cached.pending
+            cached.pending = []
             prevComplete(exit)
+            for (const pendingEntry of pending) {
+              pendingEntry.completeUnsafe(exit)
+            }
           }
           return true
         }
@@ -2001,11 +2050,7 @@ export const withCache: {
           entry.completeUnsafe(cached.exit as any)
         } else {
           cached.entry.uninterruptible = true
-          const prevComplete = cached.entry.completeUnsafe
-          cached.entry.completeUnsafe = function(exit) {
-            prevComplete(exit)
-            entry.completeUnsafe(exit)
-          }
+          cached.pending.push(entry)
         }
         return false
       }
@@ -2032,6 +2077,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
  *
+ * @stability unstable
  * @category caching
  * @since 4.0.0
  */
@@ -2056,6 +2102,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
    *
+   * @stability unstable
    * @category caching
    * @since 4.0.0
    */
@@ -2090,6 +2137,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
    *
+   * @stability unstable
    * @category caching
    * @since 4.0.0
    */
@@ -2140,6 +2188,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
      *
+     * @stability unstable
      * @category caching
      * @since 4.0.0
      */

package/src/Resource.ts

@@ -6,6 +6,7 @@
  * schedule. Resource acquisition runs in a scope, so replacements and final
  * cleanup release the resources owned by previous values.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Context from "./Context.ts"
@@ -35,6 +36,7 @@ const TypeId = "~effect/Resource" as const
  * @see {@link get} for reading the currently stored acquisition result
  * @see {@link refresh} for forcing a new acquisition
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -56,6 +58,7 @@ export interface Resource<in out A, in out E = never> extends Pipeable {
  *
  * This predicate narrows the input to `Resource<unknown, unknown>`.
  *
+ * @stability stable
  * @category guards
  * @since 4.0.0
  */
@@ -93,6 +96,7 @@ const makeUnsafe = <A, E>(
  *
  * @see {@link auto} for schedule-driven automatic refreshes
  * @see {@link refresh} to manually trigger a resource refresh
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -122,6 +126,7 @@ export const manual = <A, E, R>(
  * @see {@link manual} for caller-controlled refresh timing
  * @see {@link refresh} to trigger a refresh explicitly
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -148,6 +153,7 @@ export const auto = <A, E, R, Out, E2, R2>(
  *
  * @see {@link refresh} to re-run acquisition and update the stored value before a later read
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -177,6 +183,7 @@ export const get = <A, E>(self: Resource<A, E>): Effect.Effect<A, E> =>
  * @see {@link manual} for resources refreshed only by caller action
  * @see {@link auto} for schedule-driven automatic refreshes
  *
+ * @stability stable
  * @category resource management
  * @since 2.0.0
  */