effect 4.0.1 → 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
    */
@@ -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,7 +387,7 @@ 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,
@@ -440,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>>,
@@ -452,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
   }
@@ -476,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
  */
@@ -497,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
    */
@@ -518,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
    */
@@ -551,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) {
@@ -578,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
  */
@@ -599,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
    */
@@ -620,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
    */
@@ -660,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
  */
@@ -681,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
    */
@@ -702,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
    */
@@ -734,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
          */
@@ -754,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
          */
@@ -793,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
  */
@@ -814,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
    */
@@ -835,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
    */
@@ -867,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
  */
@@ -891,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
    */
@@ -915,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
    */
@@ -954,6 +993,7 @@ export const invalidate: {
  *
  * @see {@link invalidate} for unconditional removal by key
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -978,6 +1018,7 @@ export const invalidateWhen: {
    *
    * @see {@link invalidate} for unconditional removal by key
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1002,6 +1043,7 @@ export const invalidateWhen: {
    *
    * @see {@link invalidate} for unconditional removal by key
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -1052,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
  */
@@ -1072,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
    */
@@ -1092,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
    */
@@ -1120,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
        */
@@ -1139,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
        */
@@ -1186,6 +1233,7 @@ export const refresh: {
  *
  * @see {@link invalidate} for removing one cached entry
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -1224,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
  */
@@ -1244,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
  */
@@ -1281,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
  */
@@ -1304,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
    */

package/src/Semaphore.ts

@@ -8,6 +8,7 @@
  * work that should only run immediately, and resizing support for an existing
  * semaphore.
  *
+ * @stability stable
  * @since 4.0.0
  */
 import type * as Effect from "./Effect.ts"
@@ -51,6 +52,7 @@ import type * as Option from "./Option.ts"
  * @see {@link make} for creating a semaphore inside Effect code
  * @see {@link makeUnsafe} for creating a semaphore synchronously
  *
+ * @stability stable
  * @category models
  * @since 4.0.0
  */
@@ -206,6 +208,7 @@ export interface Semaphore {
  * await Effect.runPromise(program) // => [1, 2, 3, 4, 5]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -359,6 +362,7 @@ class SemaphoreImpl implements Semaphore {
  * await Effect.runPromise(program) // => [1, 2, 3, 4]
  * ```
  *
+ * @stability stable
  * @category constructors
  * @since 4.0.0
  */
@@ -381,6 +385,7 @@ export const make = (permits: number): Effect.Effect<Semaphore> => internal.sync
  * @see {@link make} for creating a semaphore with an initial permit count
  * @see {@link release} for returning permits without changing semaphore capacity
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -402,6 +407,7 @@ export const resize: {
    * @see {@link make} for creating a semaphore with an initial permit count
    * @see {@link release} for returning permits without changing semaphore capacity
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -423,6 +429,7 @@ export const resize: {
    * @see {@link make} for creating a semaphore with an initial permit count
    * @see {@link release} for returning permits without changing semaphore capacity
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -448,6 +455,7 @@ export const resize: {
  * @see {@link take} for manually acquiring permits
  * @see {@link release} for manually returning permits
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -471,6 +479,7 @@ export const withPermits: {
    * @see {@link take} for manually acquiring permits
    * @see {@link release} for manually returning permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -494,6 +503,7 @@ export const withPermits: {
    * @see {@link take} for manually acquiring permits
    * @see {@link release} for manually returning permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -517,6 +527,7 @@ export const withPermits: {
  * @see {@link take} for manually acquiring permits
  * @see {@link release} for manually returning permits
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -535,6 +546,7 @@ export const withPermit: {
    * @see {@link take} for manually acquiring permits
    * @see {@link release} for manually returning permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -553,6 +565,7 @@ export const withPermit: {
    * @see {@link take} for manually acquiring permits
    * @see {@link release} for manually returning permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -580,6 +593,7 @@ export const withPermit: {
  *
  * @see {@link withPermits} for the variant that waits until permits are available
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -602,6 +616,7 @@ export const withPermitsIfAvailable: {
    *
    * @see {@link withPermits} for the variant that waits until permits are available
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -624,6 +639,7 @@ export const withPermitsIfAvailable: {
    *
    * @see {@link withPermits} for the variant that waits until permits are available
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -651,6 +667,7 @@ export const withPermitsIfAvailable: {
  * @see {@link takeIfAvailable} for manually acquiring permits without waiting
  * @see {@link release} for returning manually acquired permits
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -673,6 +690,7 @@ export const take: {
    * @see {@link takeIfAvailable} for manually acquiring permits without waiting
    * @see {@link release} for returning manually acquired permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -695,6 +713,7 @@ export const take: {
    * @see {@link takeIfAvailable} for manually acquiring permits without waiting
    * @see {@link release} for returning manually acquired permits
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -720,6 +739,7 @@ export const take: {
  * @see {@link release} for returning manually acquired permits
  * @see {@link withPermitsIfAvailable} for automatic acquisition and release around an effect
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -743,6 +763,7 @@ export const takeIfAvailable: {
    * @see {@link release} for returning manually acquired permits
    * @see {@link withPermitsIfAvailable} for automatic acquisition and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -766,6 +787,7 @@ export const takeIfAvailable: {
    * @see {@link release} for returning manually acquired permits
    * @see {@link withPermitsIfAvailable} for automatic acquisition and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -797,6 +819,7 @@ export const takeIfAvailable: {
  * @see {@link releaseAll} for returning every currently taken permit
  * @see {@link withPermits} for automatic acquire and release around an effect
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */
@@ -826,6 +849,7 @@ export const release: {
    * @see {@link releaseAll} for returning every currently taken permit
    * @see {@link withPermits} for automatic acquire and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -855,6 +879,7 @@ export const release: {
    * @see {@link releaseAll} for returning every currently taken permit
    * @see {@link withPermits} for automatic acquire and release around an effect
    *
+   * @stability stable
    * @category combinators
    * @since 4.0.0
    */
@@ -880,6 +905,7 @@ export const release: {
  * @see {@link release} for releasing a known permit count
  * @see {@link withPermits} for automatic acquire and release around an effect
  *
+ * @stability stable
  * @category combinators
  * @since 4.0.0
  */