effect 4.0.5 → 4.0.7

package/src/Pool.ts

@@ -463,7 +463,7 @@ export const get = <A, E>(self: Pool<A, E>): Effect.Effect<A, E, Scope.Scope> =>
   core.withFiber((fiber) => {
     const state = self.state
     if (state.isShuttingDown) return internal.interrupt
-    if (state.availableHead?.exit._tag === "Success") {
+    if (state.waiters.size === 0 && state.availableHead?.exit._tag === "Success") {
       state.usage++
       if (self.config.isFixed || targetSize(self) <= activeSize(self)) {
         return leaseItem(self, state.availableHead, fiber)
@@ -570,7 +570,7 @@ export const use: {
   core.withFiber((fiber) => {
     const state = self.state
     if (state.isShuttingDown) return internal.interrupt
-    if (state.availableHead?.exit._tag === "Success") {
+    if (state.waiters.size === 0 && state.availableHead?.exit._tag === "Success") {
       state.usage++
       if (self.config.isFixed || targetSize(self) <= activeSize(self)) {
         return useItem(self, state.availableHead, f, fiber)
@@ -611,12 +611,18 @@ const getSlowWith = <A, E, X, R>(
   internal.uninterruptibleMask((restore) => {
     const state = self.state
     state.usage++
+    const waiter = makeWaiter<A, E>()
     const wait: Effect.Effect<X, any, R> = internal.flatMap(
       internal.onError(
-        restore(waitForItem(self)),
+        restore(waitForItem(self, waiter)),
         () =>
-          internal.sync(() => {
+          core.withFiber((fiber) => {
             state.usage--
+            // Only a woken waiter is still registered here: one cancelled while
+            // asleep already left. It passes its wake on, so the capacity it was
+            // woken for is not stranded.
+            if (state.waiters.delete(waiter)) wakeWaiters(self, fiber, 1)
+            return internal.void
           })
       ),
       () => loop
@@ -626,6 +632,12 @@ const getSlowWith = <A, E, X, R>(
         state.usage--
         return internal.interrupt
       }
+      // A borrower that has not waited yet queues behind the borrowers already
+      // waiting. Waiters keep their place until they take an item, so this
+      // also holds while a woken waiter has yet to run.
+      if (state.waiters.size > 0 && !state.waiters.has(waiter)) {
+        return wait
+      }
       // Replace failed slots only when the pool cannot grow.
       const item = firstHealthyAvailable(self) ??
         (targetSize(self) <= activeSize(self) ? state.availableHead : undefined)
@@ -636,6 +648,7 @@ const getSlowWith = <A, E, X, R>(
         removeFailedItem(self, item)
         return loop
       }
+      state.waiters.delete(waiter)
       return lease(self, item, fiber, restore)
     })
     const loop: Effect.Effect<X, any, R> = internal.suspend(() => {
@@ -718,19 +731,49 @@ const firstHealthyAvailable = <A, E>(self: Pool<A, E>): PoolItem<A, E> | undefin
   return item
 }
 
-const waitForItem = <A, E>(self: Pool<A, E>): Effect.Effect<void, E> =>
+/**
+ * A borrower's entry in `State.waiters`. It stays registered from the first
+ * wait until the borrower takes an item or leaves, so the borrower keeps its
+ * place in the queue across wakes.
+ *
+ * `resume` is set while the borrower is asleep. A registered waiter without
+ * one has been woken and has yet to take an item, wait again or leave.
+ */
+interface Waiter<A, E> {
+  (failure?: Exit.Failure<A, E>): void
+  resume: ((effect: Effect.Effect<void, E>) => void) | undefined
+}
+
+const makeWaiter = <A, E>(): Waiter<A, E> => {
+  const waiter = ((failure?: Exit.Failure<A, E>) => {
+    const resume = waiter.resume
+    if (resume === undefined) return
+    waiter.resume = undefined
+    resume(failure ?? internal.void)
+  }) as Waiter<A, E>
+  waiter.resume = undefined
+  return waiter
+}
+
+const waitForItem = <A, E>(self: Pool<A, E>, waiter: Waiter<A, E>): Effect.Effect<void, E> =>
   internal.callback((resume) => {
     const state = self.state
-    if (firstHealthyAvailable(self) !== undefined || state.isShuttingDown) {
+    if (
+      state.isShuttingDown ||
+      (state.waiters.size === 0 && firstHealthyAvailable(self) !== undefined)
+    ) {
       return resume(internal.void)
     }
-    const observer = (failure?: Exit.Failure<A, E>) => {
-      state.waiters.delete(observer)
-      resume(failure ?? internal.void)
-    }
-    state.waiters.add(observer)
+    waiter.resume = resume
+    // Re-adding a registered waiter keeps its position.
+    state.waiters.add(waiter)
     return internal.sync(() => {
-      state.waiters.delete(observer)
+      // Cancelled while asleep: leave at once, so no wake or failure is spent
+      // on it. Cancelled after a wake: stay until the wake is passed on.
+      if (waiter.resume !== undefined) {
+        waiter.resume = undefined
+        state.waiters.delete(waiter)
+      }
     })
   })
 
@@ -738,23 +781,36 @@ const wakeWaiters = <A, E>(self: Pool<A, E>, fiber: Fiber.Fiber<unknown, unknown
   const waiters = self.state.waiters
   if (waiters.size === 0) return
   fiber.currentDispatcher.scheduleTask(() => {
+    // Walk the live set, so a waiter that leaves during the walk does not use
+    // up a wake. Skip waiters already woken, and stop once nothing is left to
+    // take.
     let remaining = count
-    const toWake: Array<(failure?: Exit.Failure<A, E>) => void> = []
     for (const notify of waiters) {
-      if (remaining-- <= 0) break
-      toWake.push(notify)
-    }
-    for (let i = 0; i < toWake.length; i++) {
-      toWake[i]()
+      if (remaining <= 0 || self.state.availableHead === undefined) break
+      if ((notify as Waiter<A, E>).resume === undefined) continue
+      remaining--
+      notify()
     }
   }, 0)
 }
 
-const wakeAll = <A, E>(self: Pool<A, E>): Effect.Effect<void> =>
-  core.withFiber((fiber) => {
-    wakeWaiters(self, fiber, Number.POSITIVE_INFINITY)
-    return internal.void
-  })
+const firstSleepingWaiter = <A, E>(self: Pool<A, E>) => {
+  for (const notify of self.state.waiters) {
+    if ((notify as Waiter<A, E>).resume !== undefined) return notify
+  }
+  return undefined
+}
+
+// Wakes every waiter so it can retry after a failed acquisition. A waiter that
+// could not start a resize while another was running depends on this. Waking
+// a waiter that is already awake is a no-op.
+const wakeAll = <A, E>(self: Pool<A, E>, fiber: Fiber.Fiber<unknown, unknown>) => {
+  const waiters = self.state.waiters
+  if (waiters.size === 0) return
+  fiber.currentDispatcher.scheduleTask(() => {
+    for (const notify of Array.from(waiters)) notify()
+  }, 0)
+}
 
 // Reservations prevent reuse without extending the lifetime of borrowed items.
 const reservations = new WeakMap<PoolItem<unknown, unknown>, number>()
@@ -1005,22 +1061,38 @@ const resizeLoop = <A, E>(self: Pool<A, E>): Effect.Effect<void> =>
       return Effect.void
     }
     const toAcquire = target - active
-    const acquireOne = self.config.strategy === strategyNoop
-      ? allocate(self)
-      : Effect.flatMap(
-        self.config.strategy.reclaim(self),
-        (item) => item ? Effect.succeed(item) : allocate(self)
-      )
+    // Wake waiters as each item arrives. Waiting for the whole batch would
+    // leave acquired items idle behind a slow acquisition, with every borrower
+    // queued behind the waiters.
+    const acquireOne = Effect.tap(
+      self.config.strategy === strategyNoop
+        ? allocate(self)
+        : Effect.flatMap(
+          self.config.strategy.reclaim(self),
+          (item) =>
+            item
+              ? Effect.sync(() => {
+                // A reclaimed item rejoins circulation like a released one.
+                if (self.state.items.has(item) && !self.state.invalidated.has(item)) addAvailableFront(self, item)
+                return item
+              })
+              : allocate(self)
+        ),
+      (item) =>
+        core.withFiber((fiber) => {
+          // A failed acquisition wakes everyone so they can retry it. A new
+          // item can only serve as many waiters as it has slots.
+          if (item.exit._tag === "Failure") wakeAll(self, fiber)
+          else wakeWaiters(self, fiber, self.config.concurrency)
+          return internal.void
+        })
+    )
     if (toAcquire === 1) {
-      const acquired = Effect.tap(acquireOne, wakeAll(self))
       return self.config.isFixed
-        ? Effect.asVoid(acquired)
-        : Effect.flatMap(acquired, (item) => item.exit._tag === "Failure" ? Effect.void : resizeLoop(self))
+        ? Effect.asVoid(acquireOne)
+        : Effect.flatMap(acquireOne, (item) => item.exit._tag === "Failure" ? Effect.void : resizeLoop(self))
     }
-    const acquired = acquireOne.pipe(
-      Effect.replicateEffect(toAcquire, { concurrency: toAcquire }),
-      Effect.tap(wakeAll(self))
-    )
+    const acquired = Effect.replicateEffect(acquireOne, toAcquire, { concurrency: toAcquire })
     return self.config.isFixed
       ? Effect.asVoid(acquired)
       : Effect.flatMap(
@@ -1059,7 +1131,7 @@ const allocate = <A, E>(self: Pool<A, E>): Effect.Effect<PoolItem<A, E>> =>
           return self.config.strategy === strategyNoop ? Effect.succeed(item) : Effect.as(onAcquire, item)
         }
         // Deliver a waiting borrower its own failure; otherwise retain the slot.
-        const waiter = firstHealthyAvailable(self) === undefined ? self.state.waiters.values().next().value : undefined
+        const waiter = firstHealthyAvailable(self) === undefined ? firstSleepingWaiter(self) : undefined
         if (waiter !== undefined) {
           waiter(exit)
         } else {

package/src/PubSub.ts

@@ -1915,16 +1915,16 @@ export const takeUpTo: {
 } = dual(2, <A>(self: Subscription<A>, max: number): Effect.Effect<Array<A>> =>
   Effect.suspend(() => {
     if (self.shutdownFlag.current) return Effect.interrupt
-    max = Count.normalize(max)
+    let limit = Count.normalize(max)
     let replay: Array<A> | undefined = undefined
-    if (self.replayWindow.remaining >= max) {
-      return Effect.succeed(self.replayWindow.takeN(max))
+    if (self.replayWindow.remaining >= limit) {
+      return Effect.succeed(self.replayWindow.takeN(limit))
     } else if (self.replayWindow.remaining > 0) {
       replay = self.replayWindow.takeAll()
-      max = max - replay.length
+      limit = limit - replay.length
     }
     const as = self.pollers.length === 0
-      ? self.subscription.pollUpTo(max)
+      ? self.subscription.pollUpTo(limit)
       : []
     self.strategy.onPubSubEmptySpaceUnsafe(self.pubsub, self.subscribers)
     return replay ? Effect.succeed(replay.concat(as)) : Effect.succeed(as)
@@ -2051,7 +2051,9 @@ const takeRemainderLoop = <A>(
     return Effect.succeed(acc)
   }
   return Effect.flatMap(takeUpTo(self, max), (bs) => {
-    acc.push(...bs)
+    for (let i = 0; i < bs.length; i++) {
+      acc.push(bs[i])
+    }
     const remaining = min - bs.length
     if (remaining === 1) {
       return Effect.map(take(self), (b) => {
@@ -3127,14 +3129,13 @@ export class BackPressureStrategy<in out A> implements PubSub.Strategy<A> {
       if (publisher === MutableList.Empty) {
         keepPolling = false
       } else {
-        const [value, deferred] = publisher
+        const [value, deferred, last] = publisher
         const published = pubsub.publish(value)
-        if (published && publisher[2]) {
-          Deferred.doneUnsafe(deferred, Exit.succeed(true))
-        } else if (!published) {
-          MutableList.prepend(this.publishers, publisher)
-        }
+        if (!published) MutableList.prepend(this.publishers, publisher)
         this.completeSubscribersUnsafe(pubsub, subscribers)
+        // Resuming the publisher can synchronously end the PubSub, so notify
+        // waiting subscribers first.
+        if (published && last) Deferred.doneUnsafe(deferred, Exit.succeed(true))
       }
     }
   }
@@ -3449,7 +3450,10 @@ class ReplayBuffer<A> {
     }
     this.tail = this.tail.next
     if (this.size === this.capacity) {
-      this.head = this.head.next!
+      const dropped = this.head
+      this.head = dropped.next!
+      dropped.next = null
+      dropped.value = AbsentValue
     } else {
       this.size += 1
     }

package/src/Queue.ts

@@ -761,7 +761,10 @@ export const offer: {
 )
 
 /**
- * Adds a message to the queue synchronously. Returns `false` if the queue is done.
+ * Adds a message to the queue synchronously. Returns `false` without adding the
+ * message if the queue is closing or done, or if it is full with a non-sliding
+ * strategy (`"suspend"` or `"dropping"`). A queue with non-positive capacity can
+ * still accept a message when a taker is waiting.
  *
  * **When to use**
  *
@@ -929,42 +932,7 @@ export const offerAll: {
 } = dual(2, <A, E>(self: Enqueue<A, E>, messages: Iterable<A>): Effect<Array<A>> =>
   // Admitting what fits and registering the rest are one step, so no take can
   // free capacity between them
-  internalEffect.callback</**
-   * Adds multiple messages to the queue. Returns the remaining messages that
-   * were not added.
-   *
-   * **When to use**
-   *
-   * Use when producers can submit a batch at once and need to know which messages
-   * did not fit under the queue's capacity strategy.
-   *
-   * **Details**
-   *
-   * For bounded queues, this operation may suspend if the queue doesn't have
-   * enough capacity. The operation returns an array of messages that couldn't
-   * be added (empty array means all messages were successfully added).
-   *
-   * **Example** (Offering multiple values)
-   *
-   * ```ts import.meta.vitest
-   * import { Effect, Queue } from "effect"
-   *
-   * const program = Effect.gen(function*() {
-   *   const queue = yield* Queue.dropping<number>(3)
-   *
-   *   // Try to add more messages than capacity without suspending
-   *   const remaining1 = yield* Queue.offerAll(queue, [1, 2, 3, 4, 5])
-   *   return remaining1
-   * })
-   *
-   * await Effect.runPromise(program) // => [4, 5]
-   * ```
-   *
-   * @stability stable
-   * @category offering
-   * @since 2.0.0
-   */
-  Array<A>>((resume) => {
+  internalEffect.callback<Array<A>>((resume) => {
     const remaining = offerAllUnsafe(self, messages)
     if (remaining.length === 0 || self.strategy === "dropping") {
       return resume(core.exitSucceed(remaining))

package/src/Random.ts

@@ -392,7 +392,7 @@ export const withSeed: {
 } = dual(2, <A, E, R>(
   self: Effect.Effect<A, E, R>,
   seed: string | number
-) => Effect.provideService(self, Random, ISAAC_CSPRNG(seed)))
+) => Effect.suspend(() => Effect.provideService(self, Random, ISAAC_CSPRNG(seed))))
 
 /*///////////////////////////////////////////////////////////////////////////////////////////////////
 This is a derivative work copyright (c) 2025 Effectful Technologies Inc, under MIT license.

package/src/RcMap.ts

@@ -4,10 +4,12 @@
  * An `RcMap` runs a lookup effect the first time a key is requested, shares the
  * in-progress or acquired resource with other callers for the same key, and
  * tracks each caller through its current `Scope`. When the last scope for a key
- * closes, the resource can be released, kept alive for an idle time, or removed
- * by capacity limits or explicit invalidation. It is meant for resource
- * lifecycles such as clients, sessions, and connections, not as a general
- * mutable cache.
+ * closes, the resource is released immediately or kept alive until its idle
+ * time-to-live expires. Entries can also be explicitly invalidated. Capacity
+ * limits do not evict entries: idle entries count toward capacity, and a new
+ * key fails with `ExceededCapacityError` when the map is full. It is meant for
+ * resource lifecycles such as clients, sessions, and connections, not as a
+ * general mutable cache.
  *
  * @stability stable
  * @since 3.5.0
@@ -204,7 +206,8 @@ const makeUnsafe = <K, A, E>(options: {
  *
  * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
  *
- * - `capacity`: The maximum number of resources that can be held in the map.
+ * - `capacity`: The maximum number of entries, including idle entries. A new key
+ *   fails with `ExceededCapacityError` when full; existing entries are not evicted.
  * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
  *
  * **Example** (Creating a reference-counted map)
@@ -257,7 +260,8 @@ export const make: {
    *
    * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
    *
-   * - `capacity`: The maximum number of resources that can be held in the map.
+   * - `capacity`: The maximum number of entries, including idle entries. A new key
+   *   fails with `ExceededCapacityError` when full; existing entries are not evicted.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
    *
    * **Example** (Creating a reference-counted map)
@@ -316,7 +320,8 @@ export const make: {
    *
    * Complex keys can extend `Equal` and `Hash` to allow lookups by value.
    *
-   * - `capacity`: The maximum number of resources that can be held in the map.
+   * - `capacity`: The maximum number of entries, including idle entries. A new key
+   *   fails with `ExceededCapacityError` when full; existing entries are not evicted.
    * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
    *
    * **Example** (Creating a reference-counted map)
@@ -393,7 +398,8 @@ export const make: {
             Effect.sync(() => {
               MutableHashMap.clear(map)
             })
-          )
+          ),
+          Effect.flatMap(Exit.asVoidAll)
         )
       }),
       self

package/src/Record.ts

@@ -1784,6 +1784,11 @@ export const isSubrecord: {
 /**
  * Reduces a record to a single value by combining its entries with a specified function.
  *
+ * **Details**
+ *
+ * The reducer function receives the accumulator, the current value, and the
+ * key of the current entry.
+ *
  * **Example** (Reducing record values)
  *
  * ```ts import.meta.vitest
@@ -1792,6 +1797,18 @@ export const isSubrecord: {
  * Record.reduce({ a: 1, b: 2, c: 3 }, 0, (acc, value) => acc + value) // => 6
  * ```
  *
+ * **Example** (Using the key in the reducer)
+ *
+ * ```ts import.meta.vitest
+ * import { Record } from "effect"
+ *
+ * Record.reduce(
+ *   { a: 1, b: 2, c: 3 },
+ *   "",
+ *   (acc, value, key) => (acc === "" ? `${key}${value}` : `${acc}-${key}${value}`)
+ * ) // => "a1-b2-c3"
+ * ```
+ *
  * @stability stable
  * @category folding
  * @since 2.0.0
@@ -1800,6 +1817,11 @@ export const reduce: {
   /**
    * Reduces a record to a single value by combining its entries with a specified function.
    *
+   * **Details**
+   *
+   * The reducer function receives the accumulator, the current value, and the
+   * key of the current entry.
+   *
    * **Example** (Reducing record values)
    *
    * ```ts import.meta.vitest
@@ -1808,6 +1830,18 @@ export const reduce: {
    * Record.reduce({ a: 1, b: 2, c: 3 }, 0, (acc, value) => acc + value) // => 6
    * ```
    *
+   * **Example** (Using the key in the reducer)
+   *
+   * ```ts import.meta.vitest
+   * import { Record } from "effect"
+   *
+   * Record.reduce(
+   *   { a: 1, b: 2, c: 3 },
+   *   "",
+   *   (acc, value, key) => (acc === "" ? `${key}${value}` : `${acc}-${key}${value}`)
+   * ) // => "a1-b2-c3"
+   * ```
+   *
    * @stability stable
    * @category folding
    * @since 2.0.0
@@ -1816,6 +1850,11 @@ export const reduce: {
   /**
    * Reduces a record to a single value by combining its entries with a specified function.
    *
+   * **Details**
+   *
+   * The reducer function receives the accumulator, the current value, and the
+   * key of the current entry.
+   *
    * **Example** (Reducing record values)
    *
    * ```ts import.meta.vitest
@@ -1824,6 +1863,18 @@ export const reduce: {
    * Record.reduce({ a: 1, b: 2, c: 3 }, 0, (acc, value) => acc + value) // => 6
    * ```
    *
+   * **Example** (Using the key in the reducer)
+   *
+   * ```ts import.meta.vitest
+   * import { Record } from "effect"
+   *
+   * Record.reduce(
+   *   { a: 1, b: 2, c: 3 },
+   *   "",
+   *   (acc, value, key) => (acc === "" ? `${key}${value}` : `${acc}-${key}${value}`)
+   * ) // => "a1-b2-c3"
+   * ```
+   *
    * @stability stable
    * @category folding
    * @since 2.0.0

package/src/Ref.ts

@@ -12,7 +12,9 @@
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
+import * as Equal from "./Equal.ts"
 import { dual, identity } from "./Function.ts"
+import * as Hash from "./Hash.ts"
 import { PipeInspectableProto } from "./internal/core.ts"
 import * as MutableRef from "./MutableRef.ts"
 import type * as Option from "./Option.ts"
@@ -110,6 +112,12 @@ const RefProto = {
     _A: identity
   },
   ...PipeInspectableProto,
+  [Equal.symbol](that: unknown): boolean {
+    return this === that
+  },
+  [Hash.symbol](): number {
+    return Hash.random(this)
+  },
   toJSON(this: Ref<any>) {
     return {
       _id: "Ref",
@@ -1081,110 +1089,13 @@ export const modifySome: {
    */
   <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]): Effect.Effect<B>
 } = dual<
-  /**
-   * Computes a result atomically and optionally updates the value of the `Ref`.
-   *
-   * **When to use**
-   *
-   * Use to compute a return value while optionally updating a plain `Ref`.
-   *
-   * **Details**
-   *
-   * The callback receives the current value and returns `[result, nextValue]`,
-   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
-   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
-   * unchanged. The returned effect always succeeds with `result`.
-   *
-   * **Example** (Conditionally modifying a value)
-   *
-   * ```ts import.meta.vitest
-   * import { Effect, Option, Ref } from "effect"
-   *
-   * const program = Effect.gen(function*() {
-   *   const counter = yield* Ref.make(5)
-   *
-   *   const result1 = yield* Ref.modifySome(
-   *     counter,
-   *     (n) =>
-   *       n > 3
-   *         ? [`incremented ${n}`, Option.some(n + 10)]
-   *         : ["no change", Option.none()]
-   *   )
-   *   const current1 = yield* Ref.get(counter)
-   *   const result2 = yield* Ref.modifySome(
-   *     counter,
-   *     (n) =>
-   *       n < 10
-   *         ? [`decremented ${n}`, Option.some(n - 5)]
-   *         : ["no change", Option.none()]
-   *   )
-   *   const current2 = yield* Ref.get(counter)
-   *   return [result1, current1, result2, current2]
-   * })
-   *
-   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
-   * ```
-   *
-   * @see {@link modify} for always storing a new value
-   * @see {@link updateSome} for optional updates without a separate return value
-   *
-   * @stability stable
-   * @category mutations
-   * @since 2.0.0
-   */
-  <B, A>(pf: (a: A) => readonly [B, Option.Option<A>]) => (self: Ref<A>) => Effect.Effect<B>,
-  /**
-   * Computes a result atomically and optionally updates the value of the `Ref`.
-   *
-   * **When to use**
-   *
-   * Use to compute a return value while optionally updating a plain `Ref`.
-   *
-   * **Details**
-   *
-   * The callback receives the current value and returns `[result, nextValue]`,
-   * where `nextValue` is an `Option`. If `nextValue` is `Option.some(value)`,
-   * the `Ref` is updated to `value`; if it is `Option.none()`, the `Ref` is left
-   * unchanged. The returned effect always succeeds with `result`.
-   *
-   * **Example** (Conditionally modifying a value)
-   *
-   * ```ts import.meta.vitest
-   * import { Effect, Option, Ref } from "effect"
-   *
-   * const program = Effect.gen(function*() {
-   *   const counter = yield* Ref.make(5)
-   *
-   *   const result1 = yield* Ref.modifySome(
-   *     counter,
-   *     (n) =>
-   *       n > 3
-   *         ? [`incremented ${n}`, Option.some(n + 10)]
-   *         : ["no change", Option.none()]
-   *   )
-   *   const current1 = yield* Ref.get(counter)
-   *   const result2 = yield* Ref.modifySome(
-   *     counter,
-   *     (n) =>
-   *       n < 10
-   *         ? [`decremented ${n}`, Option.some(n - 5)]
-   *         : ["no change", Option.none()]
-   *   )
-   *   const current2 = yield* Ref.get(counter)
-   *   return [result1, current1, result2, current2]
-   * })
-   *
-   * await Effect.runPromise(program) // => ["incremented 5", 15, "no change", 15]
-   * ```
-   *
-   * @see {@link modify} for always storing a new value
-   * @see {@link updateSome} for optional updates without a separate return value
-   *
-   * @stability stable
-   * @category mutations
-   * @since 2.0.0
-   */
-  <A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option.Option<A>]) => Effect.Effect<B>
+  <B, A>(
+    pf: (a: A) => readonly [B, Option.Option<A>]
+  ) => (self: Ref<A>) => Effect.Effect<B>,
+  <A, B>(
+    self: Ref<A>,
+    pf: (a: A) => readonly [B, Option.Option<A>]
+  ) => Effect.Effect<B>
 >(2, (self, pf) =>
   modify(self, (value) => {
     const [b, option] = pf(value)

package/src/References.ts

@@ -563,12 +563,13 @@ export const TracerSpanLinks: Context.Reference<ReadonlyArray<SpanLink>> = refer
 export const TracerTimingEnabled: Context.Reference<boolean> = references.TracerTimingEnabled
 
 /**
- * Context reference for the log severity used when a pool finalizer reports an
- * unhandled error.
+ * Context reference for the log severity used to report errors that have no
+ * caller to receive them, such as pool finalizer failures or defects in
+ * background callbacks.
  *
  * **When to use**
  *
- * Use to choose whether and at which severity pool finalizer failures are
+ * Use to choose whether and at which severity these unhandled errors are
  * reported.
  *
  * **Details**
@@ -577,7 +578,7 @@ export const TracerTimingEnabled: Context.Reference<boolean> = references.Tracer
  *
  * **Gotchas**
  *
- * Providing `undefined` suppresses this report; it does not fall back to
+ * Providing `undefined` suppresses these reports; it does not fall back to
  * `CurrentLogLevel`.
  *
  * @see {@link CurrentLogLevel} for the default severity used by ordinary `Effect.log` calls