effect 4.0.0 → 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,26 +632,23 @@ 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))
+      entry.onInterrupt = () => removeEntry(self, key, entry)
       let skipCache = false
       entry.fiber.addObserver((exit) => {
+        // Release the key once the lookup can no longer be interrupted.
+        entry.onInterrupt = undefined
         if (effect.exitHasInterrupts(exit)) {
-          const current = MutableHashMap.get(self.map, key)
-          if (Option.isSome(current) && current.value === entry) {
-            MutableHashMap.remove(self.map, key)
-          }
+          removeEntry(self, key, entry)
           return
         }
         const ttl = self.timeToLive(exit, key)
         if (Duration.isZero(ttl)) {
           skipCache = true
-          const current = MutableHashMap.get(self.map, key)
-          if (Option.isSome(current) && current.value === entry) {
-            MutableHashMap.remove(self.map, key)
-          }
+          removeEntry(self, key, entry)
         } else if (Duration.isFinite(ttl)) {
           entry.expiresAt = fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
         }
@@ -651,7 +660,7 @@ export const get: {
       if (Number.isFinite(self.capacity)) {
         checkCapacity(self)
       }
-      return entry.await()
+      return entry.await(fiber)
     })
 )
 
@@ -659,6 +668,7 @@ class EntryImpl<A, E> implements Entry<A, E> {
   expiresAt: number | undefined
   awaiters: number
   fiber: Fiber.Fiber<A, E>
+  onInterrupt: (() => void) | undefined
 
   constructor(
     parent: Fiber.Fiber<unknown, unknown>,
@@ -669,15 +679,29 @@ 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
+      // while its finalizers run.
+      this.onInterrupt?.()
       return effect.fiberInterrupt(this.fiber)
     })
+    return effect.fiberJoin(this.fiber)
+  }
+}
+
+const removeEntry = <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, entry: Entry<A, E>): void => {
+  const current = MutableHashMap.get(self.map, key)
+  if (Option.isSome(current) && current.value === entry) {
+    MutableHashMap.remove(self.map, key)
   }
 }
 
@@ -798,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
  */
@@ -901,6 +926,7 @@ export const getOption: {
    * actual // => [Option.some(42), 42]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1004,6 +1030,7 @@ export const getOption: {
    * actual // => [Option.some(42), 42]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1013,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
     })
 )
 
@@ -1049,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
  */
@@ -1066,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
    */
@@ -1083,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
    */
@@ -1206,6 +1236,7 @@ export const getSuccess: {
  * actual // => [2, 2, false, true]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1317,6 +1348,7 @@ export const set: {
    * actual // => [2, 2, false, true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1428,6 +1460,7 @@ export const set: {
    * actual // => [2, 2, false, true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1546,6 +1579,7 @@ export const set: {
  * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1644,6 +1678,7 @@ export const has: {
    * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1742,6 +1777,7 @@ export const has: {
    * actual // => ["apple: true", "banana: true", "cherry: false", "date: false"]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1801,6 +1837,7 @@ export const has: {
  * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1851,6 +1888,7 @@ export const invalidate: {
    * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1901,6 +1939,7 @@ export const invalidate: {
    * actual // => { beforeInvalidation: true, afterInvalidation: false, lookupCount: 2 }
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1972,6 +2011,7 @@ export const invalidate: {
  * actual // => [true, false, false, true, false, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2038,6 +2078,7 @@ export const invalidateWhen: {
    * actual // => [true, false, false, true, false, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2104,6 +2145,7 @@ export const invalidateWhen: {
    * actual // => [true, false, false, true, false, false]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2116,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)
@@ -2229,6 +2271,7 @@ export const invalidateWhen: {
  * actual // => ["value-for-newKey", true]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2329,6 +2372,7 @@ export const refresh: {
    * actual // => ["value-for-newKey", true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2429,6 +2473,7 @@ export const refresh: {
    * actual // => ["value-for-newKey", true]
    * ```
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -2438,25 +2483,23 @@ export const refresh: {
   <Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect.Effect<A, E, R> =>
     core.withFiber((fiber) => {
       const entry = new EntryImpl(fiber, self.lookup(key))
+      entry.onInterrupt = () => removeEntry(self, key, entry)
       const existing = getImpl(self, key, fiber, false) !== undefined
       if (!existing) {
         MutableHashMap.set(self.map, key, entry)
         checkCapacity(self)
       }
       entry.fiber.addObserver((exit) => {
+        // Release the key once the lookup can no longer be interrupted.
+        entry.onInterrupt = undefined
         if (effect.exitHasInterrupts(exit)) {
-          const current = MutableHashMap.get(self.map, key)
-          if (Option.isSome(current) && current.value === entry) {
-            MutableHashMap.remove(self.map, key)
-          }
+          removeEntry(self, key, entry)
           return
         }
         const ttl = self.timeToLive(exit, key)
         if (Duration.isZero(ttl)) {
-          const current = MutableHashMap.get(self.map, key)
-          if (existing || (Option.isSome(current) && current.value === entry)) {
-            MutableHashMap.remove(self.map, key)
-          }
+          if (existing) MutableHashMap.remove(self.map, key)
+          else removeEntry(self, key, entry)
           return effect.void
         }
         entry.expiresAt = Duration.isFinite(ttl)
@@ -2467,7 +2510,7 @@ export const refresh: {
           checkCapacity(self)
         }
       })
-      return entry.await()
+      return entry.await(fiber)
     })
 )
 
@@ -2516,6 +2559,7 @@ export const refresh: {
  * actual // => [3, true, 0, false, false, false]
  * ```
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -2562,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
  */
@@ -2597,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
  */
@@ -2641,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
  */
@@ -2659,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
  */