effect 4.0.1 → 4.0.2

package/src/Cache.ts

@@ -6,6 +6,7 @@
  * by capacity and optional time-to-live rules. This module includes helpers for
  * reading, setting, refreshing, invalidating, and inspecting cache contents.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Context from "./Context.ts"
@@ -105,6 +106,7 @@ const TypeId = "~effect/Cache"
  * actual // => "User-123"
  * ```
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -129,9 +131,14 @@ export interface Cache<in out Key, in out A, in out E = never, out R = never> ex
  *
  * An `expiresAt` value of `undefined` means the entry does not expire.
  *
+ * Pass the current fiber to `await` when calling it from inside
+ * `Effect.withFiber`, so the waiter is counted and its cleanup registered in
+ * that same step. Without it, `await` resolves the fiber itself.
+ *
  * @see {@link Cache} for the public cache API that manages entries through
  * combinators
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -139,7 +146,7 @@ export interface Entry<A, E> {
   expiresAt: number | undefined
   awaiters: number
   readonly fiber: Fiber.Fiber<A, E>
-  await(this: Entry<A, E>): Effect.Effect<A, E>
+  await(this: Entry<A, E>, fiber?: Fiber.Fiber<unknown, unknown>): Effect.Effect<A, E>
 }
 
 /**
@@ -184,6 +191,7 @@ export interface Entry<A, E> {
  * ```
  *
  * @see {@link make} for a simpler cache constructor with a fixed time-to-live for all entries
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -282,6 +290,7 @@ export const makeWith = <
  * actual // => [{ name: "Ada", email: "ada@example.com" }, { name: "Ada", email: "ada@example.com" }, true]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -414,6 +423,7 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * actual // => { results: [5, 5, 5], lookupCount: 1 }
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -510,6 +520,7 @@ export const get: {
    * actual // => { results: [5, 5, 5], lookupCount: 1 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -606,6 +617,7 @@ export const get: {
    * actual // => { results: [5, 5, 5], lookupCount: 1 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -620,7 +632,7 @@ export const get: {
         if (!hasExpired(oentry.value, fiber)) {
           // Move the entry to the end of the map to keep it fresh
           MutableHashMap.set(self.map, key, oentry.value)
-          return oentry.value.await()
+          return oentry.value.await(fiber)
         }
       }
       const entry = new EntryImpl(fiber, self.lookup(key))
@@ -648,7 +660,7 @@ export const get: {
       if (Number.isFinite(self.capacity)) {
         checkCapacity(self)
       }
-      return entry.await()
+      return entry.await(fiber)
     })
 )
 
@@ -667,11 +679,14 @@ class EntryImpl<A, E> implements Entry<A, E> {
     this.expiresAt = undefined
   }
 
-  await(): Effect.Effect<A, E> {
+  await(fiber?: Fiber.Fiber<unknown, unknown>): Effect.Effect<A, E> {
+    if (fiber === undefined) return core.withFiber((fiber) => this.await(fiber))
     const exit = this.fiber.pollUnsafe()
     if (exit) return exit
     this.awaiters++
-    return effect.onExit(effect.fiberJoin(this.fiber), () => {
+    // Register cleanup in the same evaluation as the increment, before interruption
+    // can prevent the returned join effect from starting.
+    effect.onExitUnsafe(fiber, () => {
       this.awaiters--
       if (this.awaiters > 0 || this.fiber.pollUnsafe()) return effect.void
       // Detach before interrupting so new lookups do not join the abandoned fiber
@@ -679,6 +694,7 @@ class EntryImpl<A, E> implements Entry<A, E> {
       this.onInterrupt?.()
       return effect.fiberInterrupt(this.fiber)
     })
+    return effect.fiberJoin(this.fiber)
   }
 }
 
@@ -806,6 +822,7 @@ const checkCapacity = <K, A, E, R>(self: Cache<K, A, E, R>) => {
  * actual // => [Option.some(42), 42]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -909,6 +926,7 @@ export const getOption: {
    * actual // => [Option.some(42), 42]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1012,6 +1030,7 @@ export const getOption: {
    * actual // => [Option.some(42), 42]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1021,7 +1040,7 @@ export const getOption: {
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<Option.Option<A>, E> =>
     core.withFiber((fiber) => {
       const entry = getImpl(self, key, fiber)
-      return entry ? effect.asSome(entry.await()) : effect.succeedNone
+      return entry ? effect.asSome(entry.await(fiber)) : effect.succeedNone
     })
 )
 
@@ -1057,6 +1076,7 @@ const getImpl = <Key, A, E, R>(
  * @see {@link get} for triggering or awaiting the cache lookup
  * @see {@link getOption} for reading an existing entry as an optional effect
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1074,6 +1094,7 @@ export const getSuccess: {
    * @see {@link get} for triggering or awaiting the cache lookup
    * @see {@link getOption} for reading an existing entry as an optional effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1091,6 +1112,7 @@ export const getSuccess: {
    * @see {@link get} for triggering or awaiting the cache lookup
    * @see {@link getOption} for reading an existing entry as an optional effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1214,6 +1236,7 @@ export const getSuccess: {
  * actual // => [2, 2, false, true]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1325,6 +1348,7 @@ export const set: {
    * actual // => [2, 2, false, true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1436,6 +1460,7 @@ export const set: {
    * actual // => [2, 2, false, true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1554,6 +1579,7 @@ export const set: {
  * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1652,6 +1678,7 @@ export const has: {
    * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1750,6 +1777,7 @@ export const has: {
    * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1809,6 +1837,7 @@ export const has: {
  * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1859,6 +1888,7 @@ export const invalidate: {
    * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1909,6 +1939,7 @@ export const invalidate: {
    * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1980,6 +2011,7 @@ export const invalidate: {
  * actual // => [true, false, false, true, false, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2046,6 +2078,7 @@ export const invalidateWhen: {
    * actual // => [true, false, false, true, false, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2112,6 +2145,7 @@ export const invalidateWhen: {
    * actual // => [true, false, false, true, false, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2124,7 +2158,7 @@ export const invalidateWhen: {
       if (oentry === undefined) {
         return effect.succeed(false)
       }
-      return oentry.await().pipe(
+      return oentry.await(fiber).pipe(
         effect.map((value) => {
           if (f(value)) {
             const current = MutableHashMap.get(self.map, key)
@@ -2237,6 +2271,7 @@ export const invalidateWhen: {
  * actual // => ["value-for-newKey", true]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2337,6 +2372,7 @@ export const refresh: {
    * actual // => ["value-for-newKey", true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2437,6 +2473,7 @@ export const refresh: {
    * actual // => ["value-for-newKey", true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2473,7 +2510,7 @@ export const refresh: {
           checkCapacity(self)
         }
       })
-      return entry.await()
+      return entry.await(fiber)
     })
 )
 
@@ -2522,6 +2559,7 @@ export const refresh: {
  * actual // => [3, true, 0, false, false, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2568,6 +2606,7 @@ export const invalidateAll = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.E
  * actual // => [0, 2, 1]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2603,6 +2642,7 @@ export const size = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<num
  * actual // => ["cache", "hello", "world"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2647,6 +2687,7 @@ export const keys = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<Ite
  * actual // => [1, 2, 3]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2665,6 +2706,7 @@ export const values = <Key, A, E, R>(self: Cache<Key, A, E, R>): Effect.Effect<I
  * @see {@link keys} for retrieving only cached keys
  * @see {@link values} for retrieving only cached values
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */