effect 4.0.4 → 4.0.6

package/dist/Effect.js

@@ -1,7 +1,8 @@
+/// <reference lib="esnext.disposable" preserve="true" />
 import * as Context from "./Context.js";
 import * as Duration from "./Duration.js";
 import * as Exit from "./Exit.js";
-import { constant, dual } from "./Function.js";
+import { dual } from "./Function.js";
 import * as core from "./internal/core.js";
 import * as internal from "./internal/effect.js";
 import * as internalExecutionPlan from "./internal/executionPlan.js";
@@ -422,8 +423,9 @@ export const whileLoop = internal.whileLoop;
  *
  * **Details**
  *
- * An optional `AbortSignal` can be provided to allow for interruption of the
- * wrapped `Promise` API.
+ * If `evaluate` declares a parameter, it receives an `AbortSignal` that is
+ * aborted if the effect is interrupted. Zero-argument thunks do not allocate
+ * an `AbortController`.
  *
  * **Gotchas**
  *
@@ -433,6 +435,13 @@ export const whileLoop = internal.whileLoop;
  * Interruption aborts the provided `AbortSignal`, but the underlying
  * asynchronous operation only stops if it observes that signal.
  *
+ * The parameter check reads the `length` property of `evaluate`, which does
+ * not count a rest parameter or any parameter from the first default value
+ * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+ * receive `undefined` instead of a signal, as do wrappers that forward
+ * arguments through rest parameters. Declare the signal as an ordinary
+ * parameter: `(signal) => ...`.
+ *
  * **Example** (Wrapping a non-rejecting Promise)
  *
  * ```ts import.meta.vitest
@@ -474,9 +483,10 @@ export const promise = internal.promise;
  * Passing `{ try, catch }` uses `catch` to map failures to an error of type
  * `E`.
  *
- * The thunk receives an `AbortSignal` that is aborted if the effect is
- * interrupted. The underlying asynchronous operation only stops if it observes
- * that signal.
+ * If the thunk declares a parameter, it receives an `AbortSignal` that is
+ * aborted if the effect is interrupted. The underlying asynchronous operation
+ * only stops if it observes that signal. Zero-argument thunks do not allocate
+ * an `AbortController`.
  *
  * **Gotchas**
  *
@@ -484,6 +494,13 @@ export const promise = internal.promise;
  * defect. Return the error value you want in the error channel instead of
  * throwing it.
  *
+ * The parameter check reads the thunk's `length` property, which does not
+ * count a rest parameter or any parameter from the first default value
+ * onward. `(...args) => ...` and `(signal = fallback) => ...` therefore
+ * receive `undefined` instead of a signal, as do wrappers that forward
+ * arguments through rest parameters. Declare the signal as an ordinary
+ * parameter: `(signal) => ...`.
+ *
  * **Example** (Wrapping a fetch request that may fail)
  *
  * ```ts import.meta.vitest
@@ -750,10 +767,20 @@ undefined_ as undefined };
  *
  * **Details**
  *
- * The registration function receives a `resume` callback and, when requested,
- * an `AbortSignal`. Call `resume` at most once with the effect that should
- * complete the fiber; later calls are ignored. Return an optional cleanup
- * effect from the registration function to run if the fiber is interrupted.
+ * The registration function receives a `resume` callback and, if it declares
+ * a second parameter, an `AbortSignal` that is aborted if the fiber is
+ * interrupted. Call `resume` at most once with the effect that should complete
+ * the fiber; later calls are ignored. Return an optional cleanup effect from
+ * the registration function to run if the fiber is interrupted.
+ *
+ * **Gotchas**
+ *
+ * The parameter check reads the registration function's `length` property,
+ * which must be at least `2` and does not count a rest parameter or any
+ * parameter from the first default value onward. `(...args) => ...` and
+ * `(resume, signal = fallback) => ...` therefore receive `undefined` instead
+ * of a signal, as do wrappers that forward arguments through rest parameters.
+ * Declare both as ordinary parameters: `(resume, signal) => ...`.
  *
  * **Example** (Integrating callback APIs)
  *
@@ -1298,7 +1325,9 @@ export const fromResult = internal.fromResult;
  * `Option.some` becomes a successful effect with the contained value, while
  * `Option.none` becomes a failed effect. By default the failure is a
  * `NoSuchElementError`, but you can provide an `onNone` callback to customize
- * the error value.
+ * the error value. For `Option.none`, `onNone` is evaluated on each execution,
+ * not when the effect is constructed. It is never called for `Option.some`.
+ * If `onNone` throws, the effect dies with the thrown value as a defect.
  *
  * **Example** (Converting an Option into an Effect)
  *
@@ -1648,9 +1677,12 @@ export const tap = internal.tap;
  *
  * **Gotchas**
  *
- * `result` only captures typed, recoverable failures. Defects and
- * interruptions are not captured inside the `Result` and still fail the
- * effect.
+ * `result` only captures typed, recoverable failures. If the cause contains a
+ * defect, nothing is captured and every typed error is converted to a defect,
+ * preserving reason order and interrupts. A cause with only interruptions
+ * still fails the effect, but an interruption alongside a typed error does not
+ * prevent capture. The first typed error becomes a `Result.Failure` and the
+ * interruption is discarded.
  *
  * **Example** (Capturing success or failure as Result)
  *
@@ -1691,9 +1723,12 @@ export const result = internal.result;
  *
  * **Gotchas**
  *
- * `option` only captures typed, recoverable failures as `Option.none`.
- * Defects and interruptions are not captured inside the `Option` and still
- * fail the effect.
+ * `option` only captures typed, recoverable failures as `Option.none`. If the
+ * cause contains a defect, nothing is captured and every typed error is
+ * converted to a defect, preserving reason order and interrupts. A cause with
+ * only interruptions still fails the effect, but an interruption alongside a
+ * typed error does not prevent capture. The effect succeeds with
+ * `Option.none()` and the interruption is discarded.
  *
  * `option` also discards typed failure values. Use `result` if the failure
  * value matters.
@@ -2047,6 +2082,11 @@ export {
  * `catch` only handles recoverable errors. It will not recover from
  * unrecoverable defects.
  *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the handler does not run and the failure is propagated with every
+ * typed error converted to a defect. An interruption alongside a typed error
+ * does not prevent recovery.
+ *
  * @see {@link catchCause} for a version that can recover from both recoverable and unrecoverable errors.
  *
  * @stability stable
@@ -2068,6 +2108,12 @@ catch_ as catch };
  * The error type must have a readonly `_tag` field. `catchTag` matches that
  * field and only handles errors with the requested tag.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling a tagged error)
  *
  * ```ts import.meta.vitest
@@ -2119,6 +2165,12 @@ export const catchTag = internal.catchTag;
  * The error type must have a readonly `_tag` field to use `catchTags`. This
  * field is used to identify and match errors.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling multiple tagged errors)
  *
  * ```ts import.meta.vitest
@@ -2165,6 +2217,12 @@ export const catchTags = internal.catchTags;
  * Use this to handle nested error causes without removing the parent error
  * from the error channel. The handler receives the unwrapped reason.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling an error reason)
  *
  * ```ts import.meta.vitest
@@ -2206,6 +2264,12 @@ export const catchReason = internal.catchReason;
 /**
  * Catches multiple reasons within a tagged error using an object of handlers.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Handling multiple error reasons)
  *
  * ```ts import.meta.vitest
@@ -2344,6 +2408,12 @@ export const catchCause = internal.catchCause;
  * they often indicate serious issues. In some cases, such as dynamically loaded
  * plugins, controlled recovery may be needed.
  *
+ * **Gotchas**
+ *
+ * `catchDefect` recovers any cause that contains a defect, including causes
+ * that also contain typed errors. Typed error handlers such as `catch` skip
+ * those causes, so defects always take precedence.
+ *
  * **Example** (Recovering from defects)
  *
  * ```ts import.meta.vitest
@@ -2384,6 +2454,12 @@ export const catchDefect = internal.catchDefect;
  * matching. Non-matching errors re-fail with the original cause. Defects and
  * interrupts are not caught.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Recovering when a predicate matches)
  *
  * ```ts import.meta.vitest
@@ -2433,6 +2509,12 @@ export const catchIf = internal.catchIf;
  * `orElse` when provided. Without `orElse`, the original failure cause is
  * preserved.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * @see {@link catchIf} for predicate-based recovery from typed errors
  * @see {@link catchTag} for recovering from a single tagged error
  * @see {@link catchTags} for recovering from several tagged errors
@@ -2561,6 +2643,9 @@ export const catchCauseFilter = internal.catchCauseFilter;
  * Only the failure channel is transformed. The success channel and requirements
  * are preserved.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Transforming the error channel)
  *
  * ```ts import.meta.vitest
@@ -2604,6 +2689,9 @@ export const mapError = internal.mapError;
  * the error and the success values without altering the overall success or
  * failure status of the effect.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Transforming success and failure channels)
  *
  * ```ts import.meta.vitest
@@ -2924,7 +3012,9 @@ export const eventually = internal.eventually;
  * applied. For example, `Schedule.recurs(3)` allows up to three retries after
  * the initial attempt.
  *
- * Defects and interruptions are not retried.
+ * Defects take precedence over typed errors. A failure whose cause contains a
+ * defect is not retried and is propagated with every typed error converted to a
+ * defect. A typed error alongside an interruption is retried.
  *
  * **Example** (Retrying with a schedule)
  *
@@ -2972,6 +3062,14 @@ export const retry = internalSchedule.retry;
  * If the retries are exhausted and the effect still fails, it runs a fallback
  * effect instead.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. A failure whose cause contains a
+ * defect is not retried and is propagated with every typed error converted to a
+ * defect. A typed error alongside an interruption is retried. When the cause
+ * contains a defect, `orElse` does not run.
+ * This applies to source failures only; policy failures propagate unchanged.
+ *
  * **Example** (Falling back after retries are exhausted)
  *
  * ```ts import.meta.vitest
@@ -3017,8 +3115,8 @@ export const retryOrElse = internalSchedule.retryOrElse;
  * **Details**
  *
  * Use `sandbox` when downstream error handling needs to distinguish typed
- * failures, defects, and interruptions. Use `unsandbox` to restore the original
- * typed error channel after cause-level handling.
+ * failures, defects, and interruptions. Use `Effect.catch(Effect.failCause)` to
+ * restore the original typed error channel after cause-level handling.
  *
  * **Example** (Exposing failures as causes)
  *
@@ -3054,6 +3152,13 @@ export const sandbox = internal.sandbox;
  * Use the `log` option to emit the full {@link Cause} when the effect fails,
  * and `message` to prepend a custom log message.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors. If the cause also contains a
+ * defect, the failure is not ignored and is propagated with every typed error
+ * converted to a defect. An interruption alongside a typed error does not
+ * prevent the error from being ignored.
+ *
  * **Example** (Discarding success and failure values)
  *
  * ```ts import.meta.vitest
@@ -3219,6 +3324,12 @@ export const withErrorReporting = internal.withErrorReporting;
  *
  * Defects and interruptions are not recovered by this operator.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Replacing failures with a value)
  *
  * ```ts import.meta.vitest
@@ -3847,6 +3958,12 @@ export const when = internal.when;
  * to process the result if the effect succeeds, or handle the error if the
  * effect fails.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Matching success and failure values)
  *
  * ```ts import.meta.vitest
@@ -3899,6 +4016,12 @@ export const match = internal.match;
  * the handlers immediately without fiber scheduling. For unresolved effects,
  * it falls back to the regular `match` behavior.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Pattern matching eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -4087,6 +4210,12 @@ export const matchCauseEffect = internal.matchCauseEffect;
  * performing logging, recovery, notification, or other effectful work. The
  * returned effect succeeds or fails according to the handler that is run.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Matching success and failure with effectful handlers)
  *
  * ```ts import.meta.vitest
@@ -4301,9 +4430,9 @@ export const context = internal.context;
  */
 export const contextWith = internal.contextWith;
 /**
- * Provides dependencies to an effect using layers or a context. Use `options.local`
- * to build the layer every time; by default, layers are shared between provide
- * calls.
+ * Provides dependencies to an effect using layers or a context. A layer already
+ * built by an enclosing `provide` or runtime is reused. Sibling `provide` calls
+ * build their own copies. Use `options.local` to build a fresh layer subtree.
  *
  * **Example** (Providing dependencies with a layer)
  *
@@ -5767,6 +5896,10 @@ export const forever = internal.forever;
  * The source effect is always evaluated once before the schedule is stepped.
  * The schedule controls additional repetitions, not the initial execution.
  *
+ * If the effect or policy fails with a cause that contains a defect, the
+ * failure is propagated with every typed error converted to a defect.
+ * An interruption alongside a typed error does not block the typed error path.
+ *
  * **Example** (Repeating successful effects with a schedule)
  *
  * ```ts import.meta.vitest
@@ -5834,6 +5967,13 @@ export const repeat = internalSchedule.repeat;
  * otherwise it receives `None`. If the schedule completes normally, the
  * returned effect succeeds with the schedule's output.
  *
+ * **Gotchas**
+ *
+ * Defects take precedence over typed errors from either the effect or policy.
+ * If the cause contains a defect, `orElse` does not run and every typed error
+ * is converted to a defect. An interruption alongside a typed error does not
+ * prevent `orElse` from running.
+ *
  * **Example** (Recovering after repetition stops)
  *
  * ```ts import.meta.vitest
@@ -6540,8 +6680,8 @@ export const requestUnsafe = internalRequest.requestUnsafe;
  * You can use the `forkChild` method whenever you want to execute an effect in a
  * new fiber, concurrently and without "blocking" the fiber executing other
  * effects. Using fibers can be tricky, so instead of using this method
- * directly, consider other higher-level methods, such as `raceWith`,
- * `zipPar`, and so forth.
+ * directly, consider higher-level methods such as `Effect.race`,
+ * `Effect.raceFirst`, or `Effect.all` with a concurrency option.
  *
  * The fiber returned by this method has methods to interrupt the fiber and to
  * wait for it to finish executing the effect. See `Fiber` for more
@@ -6630,9 +6770,14 @@ export const forkIn = internal.forkIn;
  */
 export const forkScoped = internal.forkScoped;
 /**
- * Forks the effect into a new fiber attached to the global scope. Because the
- * new fiber is attached to the global scope, when the fiber executing the
- * returned effect terminates, the forked fiber will continue running.
+ * Forks the effect into a new fiber with no parent and no scope, so its lifetime
+ * is independent of the forking fiber.
+ *
+ * **Details**
+ *
+ * The detached fiber inherits the forking fiber's context. It continues running
+ * until it completes or is explicitly interrupted through the returned handle,
+ * even after the forking fiber terminates.
  *
  * **Example** (Forking a detached fiber)
  *
@@ -6736,11 +6881,11 @@ export const fiberId = internal.fiberId;
  * import { Effect, Fiber } from "effect"
  * const output: Array<unknown> = []
  *
- * //      ┌─── Effect<number, never, never>
+ * //      ┌─── Effect<string, never, never>
  * //      ▼
  * const program = Effect.sync(() => { output.push("running...") }).pipe(Effect.as("done"))
  *
- * //      ┌─── RuntimeFiber<number, never>
+ * //      ┌─── Fiber<string, never>
  * //      ▼
  * const fiber = Effect.runFork(program)
  *
@@ -7045,9 +7190,10 @@ export const runPromiseExitWith = internal.runPromiseExitWith;
  *
  * **Details**
  *
- * If the effect fails, dies, is interrupted, or performs asynchronous work,
- * `runSync` throws a `FiberFailure` instead of returning a value. Use
- * `runSyncExit` when you want the failure captured as an `Exit`.
+ * If the effect fails, dies, or is interrupted, `runSync` throws the squashed
+ * cause instead of returning a value. Typed errors can be thrown directly,
+ * including non-Error values. Asynchronous work throws `Cause.AsyncFiberError`.
+ * Use `runSyncExit` when you want the failure captured as an `Exit`.
  *
  * **Example** (Running a synchronous effect)
  *
@@ -8120,36 +8266,31 @@ export const trackDuration = /*#__PURE__*/dual(args => isEffect(args[0]), (self,
     return Metric.update(metric, input);
   });
 }));
-// -----------------------------------------------------------------------------
-// Transactions
-// -----------------------------------------------------------------------------
 /**
  * Service that holds the current transaction state.
  *
  * **Details**
  *
- * It includes a journal that stores non-committed changes to `TxRef` values and
- * a retry flag that records whether the transaction should be retried.
+ * Nested {@link tx} calls reuse this same service instance. Yield it inside a
+ * transaction body to read {@link TransactionMeta} fields such as `attempt`
+ * and `retryReason`.
  *
- * **Example** (Building transactions)
+ * **Example** (Reading transaction metadata)
  *
  * ```ts import.meta.vitest
  * import { Effect } from "effect"
  *
- * // Transaction class for software transactional memory operations
- * const txEffect = Effect.gen(function*() {
+ * const program = Effect.tx(Effect.gen(function*() {
  *   const tx = yield* Effect.Transaction
- *   // Use transaction for coordinated state changes
- *   return "Transaction complete"
- * })
+ *   return [tx.attempt, tx.retryReason, tx.elapsed, tx.elapsedSincePrevious]
+ * }))
  *
- * const runnable = Effect.provideService(txEffect, Effect.Transaction, {
- *   retry: false,
- *   journal: new Map()
- * })
- * Effect.runSync(runnable) // => "Transaction complete"
+ * Effect.runSync(program) // => [1, undefined, 0, 0]
  * ```
  *
+ * @see {@link tx} for the outermost transaction boundary that creates this service
+ * @see {@link TransactionMeta} for the journal and attempt metadata
+ *
  * @stability stable
  * @category transactions
  * @since 4.0.0
@@ -8203,41 +8344,64 @@ export class Transaction extends /*#__PURE__*/Context.Service()("effect/Effect/T
  * @since 4.0.0
  */
 export const tx = effect => withFiber(fiber => {
-  let state = Context.getOrUndefined(fiber.context, Transaction);
+  const state = Context.getOrUndefined(fiber.context, Transaction);
   if (state && !completedTransactions.has(state)) {
     return effect;
   }
+  const clock = fiber.getRef(internal.ClockRef);
+  const now = clock.currentTimeMillisUnsafe();
   // Create transaction state only at the outermost boundary
-  state = {
+  const mutable = {
     journal: new Map(),
-    retry: false
+    retry: false,
+    attempt: 1,
+    retryReason: undefined,
+    start: now,
+    now,
+    elapsed: 0,
+    elapsedSincePrevious: 0
   };
   let result;
-  return uninterruptibleMask(restore => flatMap(whileLoop({
-    while: () => !result,
-    body: constant(restore(effect).pipe(provideService(Transaction, state), tapCause(cause => {
-      if (!state.retry) return void_;
+  return uninterruptibleMask(restore => {
+    const run = restore(effect).pipe(provideService(Transaction, mutable), tapCause(cause => {
+      if (!mutable.retry) return void_;
       // txRetry interrupts the body; any other reason in the cause is a real failure.
       // Roll back now so the step below fails instead of waiting or rerunning.
-      if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(state));
-      return restore(awaitPendingTransaction(state));
-    }), exit)),
-    step(exit) {
-      if (state.retry || !isTransactionConsistent(state)) {
-        return clearTransaction(state);
-      }
-      if (Exit.isSuccess(exit)) {
-        commitTransaction(fiber, state);
+      if (!internal.hasInterruptsOnly(cause)) return sync(() => clearTransaction(mutable));
+      return restore(awaitPendingTransaction(mutable));
+    }), exit);
+    return flatMap(whileLoop({
+      while: () => !result,
+      body: () => {
+        if (mutable.attempt > 1) {
+          stampTransaction(mutable, clock.currentTimeMillisUnsafe());
+        }
+        return run;
+      },
+      step(exit) {
+        if (mutable.retry || !isTransactionConsistent(mutable)) {
+          mutable.attempt++;
+          mutable.retryReason = mutable.retry ? "retry" : "conflict";
+          return clearTransaction(mutable);
+        }
+        if (Exit.isSuccess(exit)) {
+          commitTransaction(fiber, mutable);
+        }
+        clearTransaction(mutable);
+        completedTransactions.add(mutable);
+        result = exit;
       }
-      clearTransaction(state);
-      completedTransactions.add(state);
-      result = exit;
-    }
-  }), () => result));
+    }), () => result);
+  });
 });
 // Child fibers inherit the boundary's state, so mark it completed once the
 // boundary finishes and let later `tx` calls start a fresh boundary.
 const completedTransactions = /*#__PURE__*/new WeakSet();
+const stampTransaction = (state, now) => {
+  state.elapsedSincePrevious = now - state.now;
+  state.now = now;
+  state.elapsed = now - state.start;
+};
 const isTransactionConsistent = state => {
   for (const [ref, {
     version
@@ -8329,7 +8493,8 @@ function clearTransaction(state) {
  * @since 4.0.0
  */
 export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
-  state.retry = true;
+  const mutable = state;
+  mutable.retry = true;
   return interrupt;
 });
 /**
@@ -8339,7 +8504,7 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * **Details**
  *
  * The original function is called with the supplied arguments plus a final
- * callback. A non-null callback error fails the returned effect, while a
+ * callback. A truthy callback error fails the returned effect, while a
  * successful callback value becomes the effect success. Use `onError` to map
  * callback errors and `onSyncError` to turn synchronous throws into typed
  * failures; otherwise synchronous throws become defects.
@@ -8386,16 +8551,24 @@ export const txRetry = /*#__PURE__*/flatMap(Transaction, state => {
  * @since 4.0.0
  */
 export const effectify = (fn, onError, onSyncError) => (...args) => callback(resume => {
+  let synchronous = true;
+  let pending;
   try {
     fn(...args, (err, result) => {
-      if (err) {
-        resume(onError ? suspend(() => fail(onError(err, args))) : fail(err));
+      const effect = err ? onError ? suspend(() => fail(onError(err, args))) : fail(err) : succeed(result);
+      if (synchronous) {
+        // Keep the first callback result until registration succeeds.
+        pending ??= effect;
       } else {
-        resume(succeed(result));
+        resume(effect);
       }
     });
   } catch (err) {
-    resume(onSyncError ? fail(onSyncError(err, args)) : die(err));
+    pending = onSyncError ? fail(onSyncError(err, args)) : die(err);
+  }
+  synchronous = false;
+  if (pending) {
+    resume(pending);
   }
 });
 // -----------------------------------------------------------------------------
@@ -8544,6 +8717,9 @@ export const mapEager = internal.mapEager;
  * transform. Failure effects apply the mapping function immediately, and
  * pending effects fall back to regular `mapError` behavior.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping errors eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -8587,6 +8763,9 @@ export const mapErrorEager = internal.mapErrorEager;
  * `onFailure` immediately. Pending effects fall back to regular `mapBoth`
  * behavior.
  *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
+ *
  * **Example** (Mapping both channels eagerly when possible)
  *
  * ```ts import.meta.vitest
@@ -8668,6 +8847,12 @@ export const flatMapEager = internal.flatMapEager;
  * Failure effects apply the catch function immediately, and pending effects
  * fall back to regular `catch` behavior.
  *
+ * **Gotchas**
+ *
+ * If the cause contains a defect, the handler is skipped and every typed error
+ * is converted to a defect, preserving reason order and interrupts. An
+ * interruption alongside a typed error does not prevent recovery.
+ *
  * **Example** (Catching failures eagerly when possible)
  *
  * ```ts import.meta.vitest