effect 4.0.5 → 4.0.6

package/dist/Channel.js

@@ -20,7 +20,7 @@ import * as Exit from "./Exit.js";
 import * as Fiber from "./Fiber.js";
 import { constant, constTrue, constVoid, dual, identity as identity_ } from "./Function.js";
 import * as Count from "./internal/count.js";
-import { ClockRef, endSpan } from "./internal/effect.js";
+import { ClockRef, endSpan, findRecoverableError } from "./internal/effect.js";
 import { addSpanStackTrace } from "./internal/tracer.js";
 import * as Iterable from "./Iterable.js";
 import * as Latch from "./Latch.js";
@@ -215,7 +215,9 @@ export const DefaultChunkSize = 4096;
 const asyncQueue = (scope, f, options) => Queue.make({
   capacity: options?.bufferSize,
   strategy: options?.strategy
-}).pipe(Effect.tap(queue => Scope.addFinalizer(scope, Queue.shutdown(queue))), Effect.tap(queue => Scope.provide(f(queue), scope).pipe(Effect.catchCause(cause => Queue.failCause(queue, cause)), Effect.forkIn(scope))));
+}).pipe(Effect.tap(queue => Scope.addFinalizer(scope, Queue.shutdown(queue))), Effect.tap(queue => Scope.provide(f(queue), scope).pipe(Effect.catchCause(cause => Queue.failCause(queue, cause)), Effect.forkIn(scope, {
+  startImmediately: true
+}))));
 /**
  * Creates a `Channel` that interacts with a callback function using a queue.
  *
@@ -1299,6 +1301,12 @@ export const fromSchedule = schedule => fromPull(Effect.map(Schedule.toStepWithS
 /**
  * Creates a channel from a lazily supplied Web `ReadableStream`.
  *
+ * **Details**
+ *
+ * Read failures are mapped with `onError`. Finalization cancels the reader and
+ * releases its lock, or only releases the lock when `releaseLockOnEnd` is set.
+ * A rejected cancel hook becomes a defect.
+ *
  * **Example** (Reading from a Web stream)
  *
  * ```ts import.meta.vitest
@@ -1341,7 +1349,11 @@ export const pullIntoWritableStream = options => Effect.acquireUseRelease(Effect
     try: () => writer.close(),
     catch: options.onError
   }), Cause.done(done))) : loop;
-  return Effect.onError(withClose, cause => Pull.isDoneCause(cause) ? Effect.void : Effect.promise(() => writer.abort(cause).catch(constVoid)));
+  return Effect.onError(withClose, cause => {
+    if (Pull.isDoneCause(cause)) return Effect.void;
+    options.onAbort?.(cause);
+    return Effect.promise(() => writer.abort(cause).catch(constVoid));
+  });
 }, writer => Effect.sync(() => writer.releaseLock()));
 /**
  * Creates a channel that writes upstream values to a lazily supplied Web
@@ -1420,7 +1432,12 @@ export const fromTransformStream = options => fromTransform((upstream, scope) =>
     pull: upstream,
     writable: transform.writable,
     onError: options.onError,
-    closeOnDone: options.closeOnDone
+    closeOnDone: options.closeOnDone,
+    // Aborting errors the readable, so record the failure first. Otherwise a
+    // pending read reports the abort reason instead.
+    onAbort: cause => {
+      exit.current = Exit.failCause(cause);
+    }
   }).pipe(Effect.catchCause(cause => {
     if (!Pull.isDoneCause(cause)) {
       exit.current = Exit.failCause(cause);
@@ -1453,7 +1470,10 @@ const readableStreamToPullUnsafe = options => {
       }
     });
   });
-  return Effect.as(Scope.addFinalizer(options.scope, options.releaseLockOnEnd ? Effect.sync(() => reader.releaseLock()) : Effect.promise(() => reader.cancel().catch(constVoid))), pull);
+  return Effect.as(Scope.addFinalizer(options.scope, options.releaseLockOnEnd ? Effect.sync(() => reader.releaseLock()) : Effect.promise(() => reader.cancel().catch(error =>
+  // `closed` resolves only when the cancel hook failed. An errored
+  // stream rejects it with an error that was already reported.
+  reader.closed.then(() => Promise.reject(error), constVoid))).pipe(Effect.ensuring(Effect.sync(() => reader.releaseLock())))), pull);
 };
 /**
  * Creates a channel that pulls values from an `AsyncIterable`.
@@ -1616,7 +1636,7 @@ const mapEffectSequential = (self, f) => fromTransform((upstream, scope) => {
 const mapEffectConcurrent = (self, f, options) => fromTransformBracket(Effect.fnUntraced(function* (upstream, scope, forkedScope) {
   let i = 0;
   const pull = yield* toTransform(self)(upstream, scope);
-  const concurrencyN = options.concurrency === "unbounded" ? Number.MAX_SAFE_INTEGER : options.concurrency;
+  const concurrencyN = options.concurrency === "unbounded" ? Number.MAX_SAFE_INTEGER : Math.min(options.concurrency, Number.MAX_SAFE_INTEGER);
   const queue = yield* Queue.bounded(0);
   yield* Scope.addFinalizer(forkedScope, Queue.shutdown(queue));
   const runFork = Effect.runForkWith(yield* Effect.context());
@@ -2044,16 +2064,19 @@ export const drain = self => transformPull(self, pull => Effect.succeed(Effect.f
  */
 export const repeat = /*#__PURE__*/dual(2, (self, schedule) => Schedule.toStepWithMetadata(typeof schedule === "function" ? schedule(identity_) : schedule).pipe(Effect.map(step => {
   let meta = Schedule.CurrentMetadata.defaultValue();
-  return repeatLoop(provideServiceEffect(self, Schedule.CurrentMetadata, Effect.sync(() => meta)), done => step(done).pipe(Effect.map(meta_ => {
+  return repeatLoop(provideServiceEffect(self, Schedule.CurrentMetadata, Effect.sync(() => meta)), exit => Exit.isFailure(exit) ? Effect.failCause(exit.cause) : step(exit.value).pipe(Effect.map(meta_ => {
     meta = meta_;
-  }), Pull.catchDone(() => Cause.done(done))));
+  }), Pull.catchDone(() => Cause.done(exit.value))));
 }), unwrap));
-const repeatLoop = (self, onDone) => fromTransform((upstream, scope) => Effect.sync(() => {
+const repeatLoop = (self, onExit) => fromTransform((upstream, scope) => Effect.sync(() => {
   let currentPull;
   const makePull = () => {
     const runScope = Scope.forkUnsafe(scope);
     return Effect.flatMap(toTransform(self)(upstream, runScope), pull => {
-      currentPull = Pull.catchDone(pull, done => Scope.close(runScope, Exit.void).pipe(Effect.flatMap(() => onDone(done)), Effect.flatMap(makePull)));
+      currentPull = Effect.catchCause(pull, cause => {
+        const exit = Pull.doneExitFromCause(cause);
+        return Scope.close(runScope, exit).pipe(Effect.flatMap(() => onExit(exit, scope)), Effect.flatMap(makePull));
+      });
       return currentPull;
     });
   };
@@ -2066,7 +2089,7 @@ const repeatLoop = (self, onDone) => fromTransform((upstream, scope) => Effect.s
  * @category repetition
  * @since 4.0.0
  */
-export const forever = self => repeatLoop(self, () => Effect.void);
+export const forever = self => repeatLoop(self, exit => Exit.isFailure(exit) ? Effect.failCause(exit.cause) : Effect.void);
 /**
  * Runs a schedule step for each output element while preserving the emitted
  * elements.
@@ -2542,6 +2565,12 @@ export const catchCause = /*#__PURE__*/dual(2, (self, f) => fromTransform((upstr
  *
  * Typed failures and interruptions are not caught.
  *
+ * **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 a defect)
  *
  * ```ts import.meta.vitest
@@ -2631,11 +2660,18 @@ export const catchCauseFilter = /*#__PURE__*/dual(3, (self, filter, f) => catchC
   const result = filter(cause);
   return Result.isFailure(result) ? failCause(result.failure) : f(result.success, cause);
 }));
-const catch_ = /*#__PURE__*/dual(2, (self, f) => catchCauseFilter(self, Cause.findError, e => f(e)));
+const catch_ = /*#__PURE__*/dual(2, (self, f) => catchCauseFilter(self, findRecoverableError, e => f(e)));
 export {
 /**
  * Recovers from typed channel errors by running a fallback channel.
  *
+ * **Gotchas**
+ *
+ * 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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -2669,6 +2705,12 @@ export const tapError = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pu
  * are handled by `orElse` when provided. Without `orElse`, non-matching errors
  * are re-failed.
  *
+ * **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 catch_ catch} for recovering from every typed channel error
  * @see {@link catchFilter} for selecting typed errors with a `Filter`
  * @see {@link catchTag} for selecting tagged typed errors
@@ -2695,6 +2737,12 @@ export const catchIf = /*#__PURE__*/dual(args => isChannel(args[0]), (self, pred
  * filter results are handled by `orElse` when provided. Without `orElse`,
  * failed filter results are re-failed.
  *
+ * **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 selecting typed errors with a predicate
  * @see {@link catchTag} for selecting tagged typed errors
  * @see {@link catchCauseFilter} for selecting full causes with a `Filter`
@@ -2716,6 +2764,12 @@ export const catchFilter = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * errors are handled by `orElse` when provided. Without `orElse`,
  * non-matching errors are re-failed.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -2727,6 +2781,12 @@ export const catchTag = /*#__PURE__*/dual(args => isChannel(args[0]), (self, k,
 /**
  * Catches a specific reason within a tagged error.
  *
+ * **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 from nested reasons)
  *
  * ```ts import.meta.vitest
@@ -2772,6 +2832,12 @@ export const catchReason = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
 /**
  * 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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -2823,15 +2889,18 @@ export const catchReasons = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  */
 export const unwrapReason = /*#__PURE__*/dual(2, (self, errorTag) => catchFilter(self, error => isTagged(error, errorTag) && hasProperty(error, "reason") ? Result.succeed(error.reason) : Result.fail(error), fail));
 /**
- * Returns a new channel, which is the same as this one, except the failure
- * value of the returned channel is created by applying the specified function
- * to the failure value of this channel.
+ * Transforms the typed errors of a channel using the specified function.
+ *
+ * **Details**
+ *
+ * Maps every typed error in the cause, preserving defects, interrupts and
+ * reason order. Unlike typed recovery, mapping does not convert errors to defects.
  *
  * @stability stable
  * @category error handling
  * @since 2.0.0
  */
-export const mapError = /*#__PURE__*/dual(2, (self, f) => catch_(self, err => fail(f(err))));
+export const mapError = /*#__PURE__*/dual(2, (self, f) => transformPull(self, pull => Effect.succeed(Effect.mapError(pull, err => Cause.isDone(err) ? err : f(err)))));
 /**
  * Converts all errors in the channel to defects (unrecoverable failures).
  * This is useful when you want to treat errors as programming errors.
@@ -2867,6 +2936,13 @@ export const orDie = self => catch_(self, die);
  *
  * Use the `log` option to emit the full {@link Cause} when the channel fails.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -2904,6 +2980,12 @@ export const ignoreCause = /*#__PURE__*/dual(args => isChannel(args[0]), (self,
  * Returns a new channel that retries this channel according to the specified
  * schedule whenever it fails.
  *
+ * **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.
+ *
  * @stability stable
  * @category error handling
  * @since 4.0.0
@@ -2917,14 +2999,17 @@ export const retry = /*#__PURE__*/dual(2, (self, schedule) => suspend(() => {
     return Effect.void;
   });
   const resolvedSchedule = typeof schedule === "function" ? schedule(identity_) : schedule;
-  const loop = catch_(withReset, Effect.fnUntraced(function* (error) {
-    if (!step) {
-      step = yield* Schedule.toStepWithMetadata(resolvedSchedule);
-    }
-    meta = yield* step(error);
-    return loop;
-  }, (effect, error) => Pull.catchDone(effect, () => Effect.succeed(fail(error))), unwrap));
-  return loop;
+  return repeatLoop(withReset, (exit, scope) => {
+    if (Exit.isSuccess(exit)) return Cause.done(exit.value);
+    const error = findRecoverableError(exit.cause);
+    if (Result.isFailure(error)) return Effect.failCause(error.failure);
+    return Effect.gen(function* () {
+      if (!step) {
+        step = yield* Schedule.toStepWithMetadata(resolvedSchedule);
+      }
+      meta = yield* step(error.success);
+    }).pipe(Pull.catchDone(() => Effect.fail(error.success)), Scope.provide(scope));
+  });
 }));
 /**
  * Maps each output element to a channel and emits values from the most recent
@@ -3011,7 +3096,7 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
   const concurrencyN = concurrency === "unbounded" ? Number.MAX_SAFE_INTEGER : Math.max(1, concurrency);
   const semaphore = switch_ ? undefined : Semaphore.makeUnsafe(concurrencyN);
   const doneLatch = yield* Latch.make(true);
-  const fibers = new Set();
+  const fibers = new Map();
   const queue = yield* Queue.bounded(bufferSize);
   yield* Scope.addFinalizer(forkedScope, Queue.shutdown(queue));
   const pull = yield* toTransform(channels)(upstream, scope);
@@ -3030,10 +3115,14 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
       const childScope = Scope.forkUnsafe(forkedScope);
       const childPull = yield* toTransform(channel)(upstream, childScope);
       while (fibers.size >= concurrencyN) {
-        const fiber = Iterable.headUnsafe(fibers);
+        const [fiber, fiberScope] = Iterable.headUnsafe(fibers);
         fibers.delete(fiber);
         if (fibers.size === 0) yield* doneLatch.open;
         yield* Fiber.interrupt(fiber);
+        // A worker interrupted before it starts never closes its own
+        // scope. Finalizer failures of replaced workers are discarded
+        // either way.
+        yield* Effect.ignoreCause(Scope.close(fiberScope, Exit.interrupt()));
       }
       const fiber = yield* childPull.pipe(Effect.tap(() => Effect.yieldNow), Effect.flatMap(value => Queue.offer(queue, value)), Effect.forever({
         disableYield: true
@@ -3051,7 +3140,7 @@ export const mergeAll = /*#__PURE__*/dual(2, (channels, {
         if (fibers.size === 0) yield* doneLatch.open;
       })), Effect.forkChild);
       doneLatch.closeUnsafe();
-      fibers.add(fiber);
+      fibers.set(fiber, childScope);
     }
   }).pipe(Effect.catchCause(cause => {
     const halt = Pull.filterDone(cause);
@@ -3256,8 +3345,9 @@ export const splitLines = () => fromTransform((upstream, _scope) => Effect.sync(
  * **Details**
  *
  * Input chunks are decoded with streaming enabled so multi-byte characters may
- * span `Uint8Array` boundaries. The optional `encoding` and `options` are
- * passed to `TextDecoder`.
+ * span `Uint8Array` boundaries. On normal completion, incomplete trailing
+ * characters become U+FFFD or, with `fatal: true`, a defect. The optional
+ * `encoding` and `options` are passed to `TextDecoder`.
  *
  * @stability stable
  * @category decoding
@@ -3268,7 +3358,12 @@ export const decodeText = (encoding, options) => fromTransform((upstream, _scope
   const streamOptions = {
     stream: true
   };
-  return Effect.map(upstream, Arr.map(line => decoder.decode(line, streamOptions)));
+  let pull = upstream.pipe(Effect.map(Arr.map(bytes => decoder.decode(bytes, streamOptions))), Pull.catchDone(leftover => {
+    pull = Cause.done(leftover);
+    const last = decoder.decode();
+    return last.length > 0 ? Effect.succeed(Arr.of(last)) : pull;
+  }));
+  return Effect.suspend(() => pull);
 }));
 /**
  * Encodes incoming string chunks into `Uint8Array` values using `TextEncoder`.