effect 4.0.5 → 4.0.6

package/src/Ref.ts

@@ -1081,110 +1081,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

package/src/RequestResolver.ts

@@ -172,7 +172,9 @@ export const isRequestResolver = (u: unknown): u is RequestResolver<any> => hasP
  *
  * `batchKey` groups request entries, `delay` schedules batch execution,
  * `collectWhile` can end collection early, and `runAll` receives a non-empty
- * batch for one key.
+ * batch for one key. The batch runs with the context of the caller that created
+ * it, even when a later caller ends collection. Each entry retains its own
+ * caller context in `entry.context`.
  *
  * **Gotchas**
  *
@@ -209,6 +211,17 @@ const defaultKey = (_request: unknown): unknown => defaultKeyObject
 /**
  * Constructs a request resolver with the specified method to run requests.
  *
+ * **Details**
+ *
+ * `runAll` runs with the context of the caller that created the batch, including
+ * when `collectWhile` ends collection early (for example with `batchN`).
+ *
+ * **Gotchas**
+ *
+ * Different caller contexts do not split batches. Use `entry.context` for
+ * per-entry services, or `makeGrouped` to separate requests by the services
+ * that affect the backend operation, such as tenant or authorization settings.
+ *
  * **Example** (Creating a request resolver)
  *
  * ```ts import.meta.vitest
@@ -256,6 +269,14 @@ export const make = <A extends Request.Any>(
  * **Details**
  *
  * The key can use the Equal trait to determine if two keys are equal.
+ * Each batch runs with the context of the caller that created that batch,
+ * whether collection ends after the delay or at a `collectWhile` cutoff.
+ *
+ * **Gotchas**
+ *
+ * Caller services that are not included in the key do not split batches. Include
+ * tenant or authorization settings in the key when they affect the backend
+ * operation, or read each caller's services from `entry.context`.
  *
  * **Example** (Grouping requests by key)
  *
@@ -411,6 +432,15 @@ export const fromFunctionBatched = <A extends Request.Any>(
 /**
  * Constructs a request resolver from an effectual function.
  *
+ * **Details**
+ *
+ * Each entry's effect runs with its own caller context. Services provided around
+ * `runAll` are not visible to it; provide them inside `f` instead. Entries with
+ * different caller contexts can still share a batch.
+ *
+ * With `withSpan`, spans created inside `f` are children of the caller's span,
+ * not the resolver span. The resolver span still links to each caller's span.
+ *
  * **Example** (Creating a resolver from an effectful function)
  *
  * ```ts import.meta.vitest
@@ -451,7 +481,11 @@ export const fromEffect = <A extends Request.Any>(
       let done = 0
       for (let i = 0; i < entries.length; i++) {
         const entry = entries[i]
-        const fiber = effect.forkUnsafe(parent as any, f(entry), true)
+        const fiber = effect.forkUnsafe(
+          parent as any,
+          effect.setContext(f(entry), entry.context),
+          true
+        )
         fiber.addObserver((exit) => {
           entry.completeUnsafe(exit)
           done++
@@ -1671,7 +1705,7 @@ export const withSpan: {
           links.push({ span: span.value, attributes: {} })
         }
         return Effect.withSpan(self.runAll(entries, key), name, {
-          ...options,
+          ...opts,
           links,
           attributes: {
             batchSize: entries.length,
@@ -1938,63 +1972,7 @@ export const withCache: {
 }): Effect.Effect<RequestResolver<A>> =>
   Effect.sync(() => {
     const strategy = options.strategy ?? "lru"
-    const cache = MutableHashMap.empty</**
-     * Adds a bounded in-memory cache to a request resolver.
-     *
-     * **When to use**
-     *
-     * Use to reuse completed results for repeated equal request values while still
-     * passing a `RequestResolver` to `Effect.request`.
-     *
-     * **Details**
-     *
-     * Running the returned effect creates the cache and returns a wrapped resolver.
-     * The cache stores completed success or failure results by request equality up
-     * to `capacity`. The `strategy` option controls eviction order and defaults to
-     * `"lru"`; `"fifo"` keeps insertion order.
-     *
-     * **Gotchas**
-     *
-     * Entries do not expire by time, and completed failures without interruptions
-     * are cached the same as successes. Results containing interruptions are not
-     * cached. Request equality controls cache hits.
-     *
-     * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
-     * @see {@link persisted} for backing persistable requests with the configured persistence store
-     *
-     * @stability stable
-     * @category caching
-     * @since 4.0.0
-     */
-    A, /**
-     * Adds a bounded in-memory cache to a request resolver.
-     *
-     * **When to use**
-     *
-     * Use to reuse completed results for repeated equal request values while still
-     * passing a `RequestResolver` to `Effect.request`.
-     *
-     * **Details**
-     *
-     * Running the returned effect creates the cache and returns a wrapped resolver.
-     * The cache stores completed success or failure results by request equality up
-     * to `capacity`. The `strategy` option controls eviction order and defaults to
-     * `"lru"`; `"fifo"` keeps insertion order.
-     *
-     * **Gotchas**
-     *
-     * Entries do not expire by time, and completed failures without interruptions
-     * are cached the same as successes. Results containing interruptions are not
-     * cached. Request equality controls cache hits.
-     *
-     * @see {@link asCache} for exposing the resolver as a `Cache` with time-to-live and service lookup controls
-     * @see {@link persisted} for backing persistable requests with the configured persistence store
-     *
-     * @stability stable
-     * @category caching
-     * @since 4.0.0
-     */
-    CacheEntry<A>>()
+    const cache = MutableHashMap.empty<A, CacheEntry<A>>()
     return makeWith({
       ...self,
       runAll(entries, key) {
@@ -2012,6 +1990,9 @@ export const withCache: {
       preCheck(entry) {
         const ocached = MutableHashMap.get(cache, entry.request)
         if (ocached._tag === "None") {
+          if (self.preCheck !== undefined && !self.preCheck(entry)) {
+            return false
+          }
           const cached: CacheEntry<A> = { entry, exit: undefined, pending: [] }
           MutableHashMap.set(cache, entry.request, cached)
           const prevComplete = entry.completeUnsafe
@@ -2162,31 +2143,7 @@ export const persisted: {
     }
   ) {
     const store = yield* (yield* Persistence.Persistence).make(options as any)
-    return makeWith</**
-     * Wraps a request resolver with persistent storage for persistable requests.
-     *
-     * **When to use**
-     *
-     * Use to keep a `RequestResolver` interface while reusing completed
-     * `Persistable` request results through a `Persistence` store.
-     *
-     * **Details**
-     *
-     * Cached results are loaded from the configured persistence store before
-     * running the underlying resolver. Missing entries are resolved normally and
-     * written back to the store. Entries marked stale by `staleWhileRevalidate`
-     * receive the stored result and are also resolved again so the refreshed result
-     * can be written back to the store. Creating the persisted resolver requires
-     * `Persistence.Persistence` and `Scope`.
-     *
-     * @see {@link withCache} for in-memory resolver caching that does not require persistable request values or a persistence store
-     * @see {@link asCache} for exposing resolver results through a `Cache` instead of returning another resolver
-     *
-     * @stability unstable
-     * @category caching
-     * @since 4.0.0
-     */
-    A>({
+    return makeWith<A>({
       ...self,
       runAll: Effect.fnUntraced(function*(entries, key) {
         const results = yield* (store.getMany(Iterable.map(entries, (_) => _.request)).pipe(
@@ -2205,6 +2162,8 @@ export const persisted: {
             exit === undefined ||
             (options.staleWhileRevalidate && options.staleWhileRevalidate(exit as any, entry.request))
           ) {
+            // Deliver stale results before tracking refresh completions for persistence.
+            if (exit !== undefined) entry.completeUnsafe(exit as any)
             const prevComplete = entry.completeUnsafe
             entry.completeUnsafe = function(exit) {
               completed.add(entry)
@@ -2212,7 +2171,7 @@ export const persisted: {
               prevComplete(exit)
             }
             leftover.push(entry)
-            if (exit === undefined) continue
+            continue
           }
           entry.completeUnsafe(exit as any)
         }
@@ -2231,6 +2190,6 @@ export const persisted: {
           Effect.provideContext(entries[0].context)
         ) as Effect.Effect<void, Request.Error<A>>)
       })
-    });
+    })
   })
 )

package/src/Resource.ts

@@ -136,7 +136,7 @@ export const auto = <A, E, R, Out, E2, R2>(
 ): Effect.Effect<Resource<A, E>, never, R | R2 | Scope.Scope> =>
   Effect.tap(
     manual(acquire),
-    (self) => Effect.forkScoped(Effect.repeat(refresh(self), policy))
+    (self) => Effect.forkScoped(Effect.schedule(Effect.ignoreCause(refresh(self)), policy))
   )
 
 /**

package/src/Runtime.ts

@@ -126,9 +126,9 @@ export const defaultTeardown: Teardown = <E, A>(
  *
  * **Details**
  *
- * The runner executes Effect programs as main entry points. The provided
- * function receives a forked fiber and a teardown callback so it can install
- * platform-specific signal handling, fiber observers, and final exit behavior.
+ * The setup function runs before user code and receives the main fiber and a
+ * teardown callback to install platform-specific signal handlers, observers,
+ * and exit behavior.
  *
  * Most applications should use a platform-provided runner, such as
  * `NodeRuntime.runMain`, rather than constructing one directly.
@@ -208,23 +208,24 @@ export const makeRunMain = (
     readonly disableErrorReporting?: boolean | undefined
     readonly teardown?: Teardown | undefined
   }) => {
-    const fiber = options?.disableErrorReporting === true
-      ? Effect.runFork(effect)
-      : Effect.runFork(
-        Effect.tapCause(effect, (cause) => {
-          if (Cause.hasInterruptsOnly(cause)) return Effect.void
-          const isReported = getErrorReported(Cause.squash(cause))
-          return isReported ? Effect.logError(cause) : Effect.void
-        })
-      )
-    try {
-      const keepAlive = globalThis.setInterval(constVoid, 2_147_483_647)
-      fiber.addObserver(() => {
-        clearInterval(keepAlive)
+    const main = options?.disableErrorReporting === true
+      ? effect
+      : Effect.tapCause(effect, (cause) => {
+        if (Cause.hasInterruptsOnly(cause)) return Effect.void
+        const isReported = getErrorReported(Cause.squash(cause))
+        return isReported ? Effect.logError(cause) : Effect.void
       })
-    } catch {}
     const teardown = options?.teardown ?? defaultTeardown
-    return f({ fiber, teardown })
+    Effect.runFork(Effect.withFiber((fiber) => {
+      try {
+        const keepAlive = globalThis.setInterval(constVoid, 2_147_483_647)
+        fiber.addObserver(() => {
+          clearInterval(keepAlive)
+        })
+      } catch {}
+      f({ fiber, teardown })
+      return main
+    }))
   })
 
 declare global {

package/src/Schedule.ts

@@ -717,101 +717,9 @@ export const concatResult: {
     > {
       if (currentStep) return currentStep(now, input)
       return toStep<
-        /**
-         * Returns a schedule that runs `self` to completion, then runs `other`, and
-         * preserves which schedule produced each output.
-         *
-         * **Details**
-         *
-         * The resulting schedule emits a `Result` to indicate which phase produced
-         * each output: outputs from `self` are emitted as `Failure`, and outputs from
-         * `other` are emitted as `Success`.
-         *
-         * **Example** (Tracking sequential schedule phases)
-         *
-         * ```ts import.meta.vitest
-         * import { Schedule } from "effect"
-         *
-         * const schedule = Schedule.concatResult(Schedule.recurs(1), Schedule.recurs(2))
-         * Schedule.isSchedule(schedule) // => true
-         * ```
-         *
-         * @stability stable
-         * @category sequencing
-         * @since 4.0.0
-         */
         Result.Result<Output2, Output>,
-        /**
-         * Returns a schedule that runs `self` to completion, then runs `other`, and
-         * preserves which schedule produced each output.
-         *
-         * **Details**
-         *
-         * The resulting schedule emits a `Result` to indicate which phase produced
-         * each output: outputs from `self` are emitted as `Failure`, and outputs from
-         * `other` are emitted as `Success`.
-         *
-         * **Example** (Tracking sequential schedule phases)
-         *
-         * ```ts import.meta.vitest
-         * import { Schedule } from "effect"
-         *
-         * const schedule = Schedule.concatResult(Schedule.recurs(1), Schedule.recurs(2))
-         * Schedule.isSchedule(schedule) // => true
-         * ```
-         *
-         * @stability stable
-         * @category sequencing
-         * @since 4.0.0
-         */
         Input & Input2,
-        /**
-         * Returns a schedule that runs `self` to completion, then runs `other`, and
-         * preserves which schedule produced each output.
-         *
-         * **Details**
-         *
-         * The resulting schedule emits a `Result` to indicate which phase produced
-         * each output: outputs from `self` are emitted as `Failure`, and outputs from
-         * `other` are emitted as `Success`.
-         *
-         * **Example** (Tracking sequential schedule phases)
-         *
-         * ```ts import.meta.vitest
-         * import { Schedule } from "effect"
-         *
-         * const schedule = Schedule.concatResult(Schedule.recurs(1), Schedule.recurs(2))
-         * Schedule.isSchedule(schedule) // => true
-         * ```
-         *
-         * @stability stable
-         * @category sequencing
-         * @since 4.0.0
-         */
         Error | Error2,
-        /**
-         * Returns a schedule that runs `self` to completion, then runs `other`, and
-         * preserves which schedule produced each output.
-         *
-         * **Details**
-         *
-         * The resulting schedule emits a `Result` to indicate which phase produced
-         * each output: outputs from `self` are emitted as `Failure`, and outputs from
-         * `other` are emitted as `Success`.
-         *
-         * **Example** (Tracking sequential schedule phases)
-         *
-         * ```ts import.meta.vitest
-         * import { Schedule } from "effect"
-         *
-         * const schedule = Schedule.concatResult(Schedule.recurs(1), Schedule.recurs(2))
-         * Schedule.isSchedule(schedule) // => true
-         * ```
-         *
-         * @stability stable
-         * @category sequencing
-         * @since 4.0.0
-         */
         Env | Env2
       >(currentSide === 0 ? left : right).pipe(
         effect.flatMap((step) => {
@@ -827,8 +735,8 @@ export const concatResult: {
           currentStep = step
           return currentStep(now, input)
         })
-      );
-    };
+      )
+    }
   })))
 
 /**