effect 4.0.0 → 4.0.2

package/src/ScopedCache.ts

@@ -8,6 +8,7 @@
  * share one in-progress effect, and entries can expire, be refreshed, be
  * invalidated, or be evicted by capacity limits.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import * as Arr from "./Array.ts"
@@ -26,6 +27,7 @@ import * as MutableHashMap from "./MutableHashMap.ts"
 import * as Option from "./Option.ts"
 import type { Pipeable } from "./Pipeable.ts"
 import * as Predicate from "./Predicate.ts"
+import { UnhandledLogLevel } from "./References.ts"
 import * as Scope from "./Scope.ts"
 
 const TypeId = "~effect/ScopedCache"
@@ -49,6 +51,7 @@ const TypeId = "~effect/ScopedCache"
  * @see {@link make} for creating a scoped cache with a fixed time-to-live
  * @see {@link makeWith} for creating a scoped cache with dynamic time-to-live
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -73,6 +76,7 @@ export interface ScopedCache<in out Key, in out A, in out E = never, out R = nev
  * `Closed` means the owning scope has closed and the cache can no longer
  * perform lookup operations.
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -99,6 +103,7 @@ export type State<K, A, E> = {
  *
  * @see {@link State} for the open/closed cache state that stores entries by key
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -129,6 +134,7 @@ export interface Entry<A, E> {
  *
  * @see {@link make} for creating a scoped cache with one fixed time-to-live
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -191,6 +197,7 @@ export const makeWith = <
  *
  * @see {@link makeWith} for computing time-to-live from each lookup result and key
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -251,6 +258,7 @@ const defaultTimeToLive = <A, E>(_: Exit.Exit<A, E>, _key: unknown): Duration.Du
  * @see {@link getSuccess} for inspecting an already-completed successful entry
  * @see {@link refresh} for forcing a new lookup
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -275,6 +283,7 @@ export const get: {
    * @see {@link getSuccess} for inspecting an already-completed successful entry
    * @see {@link refresh} for forcing a new lookup
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -299,6 +308,7 @@ export const get: {
    * @see {@link getSuccess} for inspecting an already-completed successful entry
    * @see {@link refresh} for forcing a new lookup
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -317,7 +327,7 @@ export const get: {
           // Move the entry to the end of the map to keep it fresh
           MutableHashMap.remove(state.map, key)
           MutableHashMap.set(state.map, key, oentry.value)
-          return awaitEntry(oentry.value, restore)
+          return awaitEntry(self, key, oentry.value, restore)
         }
         const scope = Scope.makeUnsafe()
         const deferred = Deferred.makeUnsafe</**
@@ -340,6 +350,7 @@ export const get: {
          * @see {@link getSuccess} for inspecting an already-completed successful entry
          * @see {@link refresh} for forcing a new lookup
          *
+         * @stability stable
          * @category combinators
          * @since 4.0.0
          */
@@ -363,6 +374,7 @@ export const get: {
          * @see {@link getSuccess} for inspecting an already-completed successful entry
          * @see {@link refresh} for forcing a new lookup
          *
+         * @stability stable
          * @category combinators
          * @since 4.0.0
          */
@@ -375,46 +387,51 @@ export const get: {
         }
         MutableHashMap.set(state.map, key, entry)
         return checkCapacity(fiber, state.map, self.capacity).pipe(
-          Option.isSome(oentry) ? effect.flatMap(() => Scope.close(oentry.value.scope, effect.exitVoid)) : identity,
+          Option.isSome(oentry) ? effect.flatMap(() => closeEvicted(oentry.value)) : identity,
           effect.flatMap(() => {
             entry.fiber = effect.forkUnsafe(
               fiber,
               effect.onExit(effect.suspend(() => Scope.provide(self.lookup(key), scope)), (exit) => {
-                Deferred.doneUnsafe(deferred, exit)
                 if (effect.exitHasInterrupts(exit)) {
-                  if (self.state._tag === "Open") {
-                    const current = MutableHashMap.get(self.state.map, key)
-                    if (Option.isSome(current) && current.value === entry) MutableHashMap.remove(self.state.map, key)
-                  }
+                  removeEntry(self, key, entry)
+                  Deferred.doneUnsafe(deferred, exit)
                   return Scope.close(scope, exit)
                 }
-                const ttl = self.timeToLive(exit, key)
-                if (Duration.isFinite(ttl)) {
-                  entry.expiresAt = fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
+                try {
+                  const ttl = self.timeToLive(exit, key)
+                  if (Duration.isFinite(ttl)) {
+                    entry.expiresAt = fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() + Duration.toMillis(ttl)
+                  }
+                } finally {
+                  Deferred.doneUnsafe(deferred, exit)
                 }
                 return effect.void
               }),
               true,
               true
             )
-            return awaitEntry(entry, restore)
+            return awaitEntry(self, key, entry, restore)
           })
         )
       })
     )
 )
 
-const awaitEntry = <A, E>(
+const awaitEntry = <Key, A, E, R>(
+  self: ScopedCache<Key, A, E, R>,
+  key: Key,
   entry: Entry<A, E>,
   restore: <X, Y, Z>(effect: Effect.Effect<X, Y, Z>) => Effect.Effect<X, Y, Z>
 ): Effect.Effect<A, E> => {
-  const fiber = entry.fiber
-  if (fiber === undefined || Deferred.isDoneUnsafe(entry.deferred)) return restore(Deferred.await(entry.deferred))
+  if (Deferred.isDoneUnsafe(entry.deferred)) return restore(Deferred.await(entry.deferred))
   entry.awaiters++
   // Install cleanup before restore so a pending interrupt cannot skip the decrement.
   return effect.onExit(restore(Deferred.await(entry.deferred)), () => {
     entry.awaiters--
-    if (entry.awaiters > 0 || Deferred.isDoneUnsafe(entry.deferred)) return effect.void
+    const fiber = entry.fiber
+    if (entry.awaiters > 0 || fiber === undefined || Deferred.isDoneUnsafe(entry.deferred)) return effect.void
+    // Detach before interruption so callers arriving during finalization start fresh.
+    removeEntry(self, key, entry)
     return effect.flatMap(effect.fiberInterrupt(fiber), () => {
       const exit = fiber.pollUnsafe()!
       return Exit.isFailure(exit) && Cause.hasDies(exit.cause) ? effect.failCause(exit.cause) : effect.void
@@ -422,6 +439,12 @@ const awaitEntry = <A, E>(
   })
 }
 
+const removeEntry = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>, key: Key, entry: Entry<A, E>): void => {
+  if (self.state._tag !== "Open") return
+  const current = MutableHashMap.get(self.state.map, key)
+  if (Option.isSome(current) && current.value === entry) MutableHashMap.remove(self.state.map, key)
+}
+
 const hasExpired = <A, E>(entry: Entry<A, E>, fiber: Fiber.Fiber<unknown, unknown>): boolean => {
   if (entry.expiresAt === undefined) {
     return false
@@ -429,6 +452,16 @@ const hasExpired = <A, E>(entry: Entry<A, E>, fiber: Fiber.Fiber<unknown, unknow
   return fiber.getRef(effect.ClockRef).currentTimeMillisUnsafe() >= entry.expiresAt
 }
 
+// Expiry and capacity eviction report cleanup failures without failing unrelated readers.
+const closeEvicted = <A, E>(entry: Entry<A, E>): Effect.Effect<void> =>
+  effect.catchCause(Scope.close(entry.scope, effect.exitVoid), reportUnhandledError)
+
+const reportUnhandledError = <E>(cause: Cause.Cause<E>): Effect.Effect<void> =>
+  core.withFiber((fiber) => {
+    const level = fiber.getRef(UnhandledLogLevel)
+    return level ? effect.logWithLevel(level)("Unhandled error in ScopedCache finalizer", cause) : effect.void
+  })
+
 const checkCapacity = <K, A, E>(
   parent: Fiber.Fiber<unknown, unknown>,
   map: MutableHashMap.MutableHashMap<K, Entry<A, E>>,
@@ -441,7 +474,7 @@ const checkCapacity = <K, A, E>(
   const fibers = Arr.empty<Fiber.Fiber<unknown, unknown>>()
   for (const [key, entry] of map) {
     MutableHashMap.remove(map, key)
-    fibers.push(effect.forkUnsafe(parent as any, Scope.close(entry.scope, effect.exitVoid), true))
+    fibers.push(effect.forkUnsafe(parent as any, closeEvicted(entry), true))
     diff--
     if (diff === 0) break
   }
@@ -465,6 +498,7 @@ const checkCapacity = <K, A, E>(
  * @see {@link get} for running the lookup on missing or expired keys
  * @see {@link getSuccess} for inspecting only already-completed successful entries
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -486,6 +520,7 @@ export const getOption: {
    * @see {@link get} for running the lookup on missing or expired keys
    * @see {@link getSuccess} for inspecting only already-completed successful entries
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -507,6 +542,7 @@ export const getOption: {
    * @see {@link get} for running the lookup on missing or expired keys
    * @see {@link getSuccess} for inspecting only already-completed successful entries
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -518,7 +554,7 @@ export const getOption: {
       core.withFiber((fiber) =>
         effect.flatMap(
           getImpl(self, key, fiber),
-          (entry) => entry ? effect.asSome(awaitEntry(entry, restore)) : effect.succeedNone
+          (entry) => entry ? effect.asSome(awaitEntry(self, key, entry, restore)) : effect.succeedNone
         )
       )
     )
@@ -540,7 +576,7 @@ const getImpl = <Key, A, E, R>(
   } else if (hasExpired(oentry.value, fiber)) {
     MutableHashMap.remove(state.map, key)
     return effect.as(
-      Scope.close(oentry.value.scope, effect.exitVoid),
+      closeEvicted(oentry.value),
       undefined
     )
   } else if (isRead) {
@@ -567,6 +603,7 @@ const getImpl = <Key, A, E, R>(
  * @see {@link get} for awaiting or starting the lookup effect
  * @see {@link getOption} for awaiting an already-cached entry without starting a lookup
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -588,6 +625,7 @@ export const getSuccess: {
    * @see {@link get} for awaiting or starting the lookup effect
    * @see {@link getOption} for awaiting an already-cached entry without starting a lookup
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -609,6 +647,7 @@ export const getSuccess: {
    * @see {@link get} for awaiting or starting the lookup effect
    * @see {@link getOption} for awaiting an already-cached entry without starting a lookup
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -649,6 +688,7 @@ export const getSuccess: {
  * @see {@link get} for reading or computing a cached value
  * @see {@link refresh} for replacing an entry by running the lookup function
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -670,6 +710,7 @@ export const set: {
    * @see {@link get} for reading or computing a cached value
    * @see {@link refresh} for replacing an entry by running the lookup function
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -691,6 +732,7 @@ export const set: {
    * @see {@link get} for reading or computing a cached value
    * @see {@link refresh} for replacing an entry by running the lookup function
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -723,6 +765,7 @@ export const set: {
          * @see {@link get} for reading or computing a cached value
          * @see {@link refresh} for replacing an entry by running the lookup function
          *
+         * @stability stable
          * @category combinators
          * @since 4.0.0
          */
@@ -743,6 +786,7 @@ export const set: {
          * @see {@link get} for reading or computing a cached value
          * @see {@link refresh} for replacing an entry by running the lookup function
          *
+         * @stability stable
          * @category combinators
          * @since 4.0.0
          */
@@ -782,6 +826,7 @@ export const set: {
  * @see {@link getOption} for reading an existing cached entry
  * @see {@link get} for running the lookup on missing or expired keys
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -803,6 +848,7 @@ export const has: {
    * @see {@link getOption} for reading an existing cached entry
    * @see {@link get} for running the lookup on missing or expired keys
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -824,6 +870,7 @@ export const has: {
    * @see {@link getOption} for reading an existing cached entry
    * @see {@link get} for running the lookup on missing or expired keys
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -856,6 +903,7 @@ export const has: {
  * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate
  * @see {@link invalidateAll} for removing every cached entry
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -880,6 +928,7 @@ export const invalidate: {
    * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate
    * @see {@link invalidateAll} for removing every cached entry
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -904,6 +953,7 @@ export const invalidate: {
    * @see {@link invalidateWhen} for invalidating only when a cached value matches a predicate
    * @see {@link invalidateAll} for removing every cached entry
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -943,6 +993,7 @@ export const invalidate: {
  *
  * @see {@link invalidate} for unconditional removal by key
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -967,6 +1018,7 @@ export const invalidateWhen: {
    *
    * @see {@link invalidate} for unconditional removal by key
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -991,6 +1043,7 @@ export const invalidateWhen: {
    *
    * @see {@link invalidate} for unconditional removal by key
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1004,7 +1057,7 @@ export const invalidateWhen: {
           if (entry === undefined) {
             return effect.succeed(false)
           }
-          return awaitEntry(entry, restore).pipe(
+          return awaitEntry(self, key, entry, restore).pipe(
             effect.flatMap((value) => {
               if (self.state._tag === "Closed") {
                 return effect.succeed(false)
@@ -1041,6 +1094,7 @@ export const invalidateWhen: {
  * @see {@link get} for reusing an unexpired entry before running the lookup
  * @see {@link invalidate} for removing an entry without recomputing it
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1061,6 +1115,7 @@ export const refresh: {
    * @see {@link get} for reusing an unexpired entry before running the lookup
    * @see {@link invalidate} for removing an entry without recomputing it
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1081,6 +1136,7 @@ export const refresh: {
    * @see {@link get} for reusing an unexpired entry before running the lookup
    * @see {@link invalidate} for removing an entry without recomputing it
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1109,6 +1165,7 @@ export const refresh: {
        * @see {@link get} for reusing an unexpired entry before running the lookup
        * @see {@link invalidate} for removing an entry without recomputing it
        *
+       * @stability stable
        * @category combinators
        * @since 4.0.0
        */
@@ -1128,6 +1185,7 @@ export const refresh: {
        * @see {@link get} for reusing an unexpired entry before running the lookup
        * @see {@link invalidate} for removing an entry without recomputing it
        *
+       * @stability stable
        * @category combinators
        * @since 4.0.0
        */
@@ -1175,6 +1233,7 @@ export const refresh: {
  *
  * @see {@link invalidate} for removing one cached entry
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1213,6 +1272,7 @@ const invalidateAllImpl = <Key, A, E>(
  * The size reflects the current number of entries stored, not the number
  * of valid entries.
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1233,6 +1293,7 @@ export const size = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effe
  * @see {@link entries} for retrieving successful cached key-value pairs
  * @see {@link values} for retrieving only successfully cached values
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1270,6 +1331,7 @@ export const keys = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Effe
  * @see {@link entries} for retrieving successful cached key-value pairs
  * @see {@link keys} for retrieving only cached keys
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1293,6 +1355,7 @@ export const values = <Key, A, E, R>(self: ScopedCache<Key, A, E, R>): Effect.Ef
  * @see {@link keys} for retrieving only cached keys
  * @see {@link values} for retrieving only cached values
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */

package/src/ScopedRef.ts

@@ -7,6 +7,7 @@
  * value. Reads can be effectful or synchronous, and updates are synchronized so
  * only one replacement happens at a time.
  *
+ * @stability stable
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
@@ -32,6 +33,7 @@ const TypeId = "~effect/ScopedRef"
  * later replace it with another acquired value while ensuring the previous
  * value is released.
  *
+ * @stability stable
  * @category models
  * @since 2.0.0
  */
@@ -78,6 +80,7 @@ const isClosed = (scope: Scope.Scope): boolean => scope.state._tag === "Closed"
  * resources that must be released.
  *
  * @see {@link make} for creating a `ScopedRef` from a value that does not require resource acquisition
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -106,6 +109,7 @@ export const fromAcquire: <A, E, R>(
  *
  * @see {@link get} for Effect-wrapped access in Effect programs
  *
+ * @stability stable
  * @category getters
  * @since 4.0.0
  */
@@ -121,6 +125,7 @@ export const getUnsafe = <A>(self: ScopedRef<A>): A => self.backing.backing.ref.
  *
  * @see {@link getUnsafe} for reading the current value synchronously when an unsafe read is acceptable
  *
+ * @stability stable
  * @category getters
  * @since 2.0.0
  */
@@ -148,6 +153,7 @@ export const get = <A>(self: ScopedRef<A>): Effect.Effect<A> => Effect.sync(() =
  * @see {@link fromAcquire} for creating a `ScopedRef` from an effect that acquires the initial value
  * @see {@link set} for replacing the current value with a newly acquired value
  *
+ * @stability stable
  * @category constructors
  * @since 2.0.0
  */
@@ -169,6 +175,7 @@ export const make = <A>(evaluate: LazyArg<A>): Effect.Effect<ScopedRef<A>, never
  * changed to the new value, with old resources released, or until the attempt
  * to acquire a new value fails.
  *
+ * @stability stable
  * @category mutations
  * @since 2.0.0
  */
@@ -188,6 +195,7 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
+   * @stability stable
    * @category mutations
    * @since 2.0.0
    */
@@ -207,6 +215,7 @@ export const set: {
    * changed to the new value, with old resources released, or until the attempt
    * to acquire a new value fails.
    *
+   * @stability stable
    * @category mutations
    * @since 2.0.0
    */