effect 4.0.5 → 4.0.6

package/dist/Stream.js

@@ -530,7 +530,12 @@ export const sync = evaluate => fromChannel(Channel.sync(() => Arr.of(evaluate()
  * @category constructors
  * @since 2.0.0
  */
-export const suspend = stream => fromChannel(Channel.suspend(() => stream().channel));
+export const suspend = stream => {
+  const suspended = fromChannel(Channel.suspend(() => stream().channel));
+  suspendedStreams.set(suspended, stream);
+  return suspended;
+};
+const suspendedStreams = /*#__PURE__*/new WeakMap();
 /**
  * Terminates with the specified error.
  *
@@ -929,9 +934,10 @@ export const fromPubSubTake = pubsub => fromChannel(Channel.fromPubSubTake(pubsu
  *
  * **Details**
  *
- * The stream reads from a `ReadableStreamDefaultReader`, maps read failures
- * with `onError`, and closes the reader when the stream finalizes. By default
- * the reader is canceled; set `releaseLockOnEnd` to release the lock instead.
+ * The stream reads from a `ReadableStreamDefaultReader` and maps read failures
+ * 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** (Creating a stream from a ReadableStream)
  *
@@ -1056,6 +1062,11 @@ export const fromSubscription = pubsub => fromChannel(Channel.fromSubscriptionAr
 /**
  * Creates a stream from an event listener.
  *
+ * **Gotchas**
+ *
+ * Event listeners cannot backpressure the source. When a bounded `bufferSize`
+ * is full, additional events are dropped rather than suspending the listener.
+ *
  * **Example** (Creating a stream from an event listener)
  *
  * ```ts import.meta.vitest
@@ -1371,6 +1382,11 @@ export const as = /*#__PURE__*/dual(2, (self, value) => map(self, () => value));
 /**
  * Maps both the failure and success channels of a stream.
  *
+ * **Details**
+ *
+ * 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 the failure and success channels of a stream)
  *
  * ```ts import.meta.vitest
@@ -2148,13 +2164,30 @@ export const concat = /*#__PURE__*/dual(2, (self, that) => {
 // The operands of each `concat` result, so a chain of `concat` calls can run as
 // a single layer instead of one layer per call
 const concatParts = /*#__PURE__*/new WeakMap();
-// Yields the channel of each non-`concat` stream in a chain, in order
+// Yields the channel of each non-`concat` stream in a chain, in order. A
+// `suspend` part is evaluated when it is reached and its result joins the chain
 function* concatChannels(self, that) {
   const stack = [that, self];
   while (stack.length > 0) {
     const stream = stack.pop();
     const parts = concatParts.get(stream);
-    if (parts === undefined) yield stream.channel;else stack.push(parts[1], parts[0]);
+    if (parts !== undefined) {
+      stack.push(parts[1], parts[0]);
+      continue;
+    }
+    const evaluate = suspendedStreams.get(stream);
+    if (evaluate === undefined) {
+      yield stream.channel;
+      continue;
+    }
+    // Evaluated here rather than in an effect, so retrying an interrupted pull
+    // cannot evaluate it twice. `Channel.empty` keeps a yield point
+    try {
+      stack.push(evaluate());
+    } catch (defect) {
+      stack.push(die(defect));
+    }
+    yield Channel.empty;
   }
 }
 /**
@@ -2487,15 +2520,22 @@ export const crossWith = /*#__PURE__*/dual(3, (left, right, f) => flatMap(left,
  * @category zipping
  * @since 2.0.0
  */
-export const zipWith = /*#__PURE__*/dual(3, (left, right, f) => zipWithArray(left, right, zipArrays(f)));
-const zipArrays = f => (leftArr, rightArr) => {
-  const minLength = Math.min(leftArr.length, rightArr.length);
-  const result = [];
-  for (let i = 0; i < minLength; i++) {
-    result.push(f(leftArr[i], rightArr[i]));
-  }
-  return [result, leftArr.slice(minLength), rightArr.slice(minLength)];
-};
+export const zipWith = /*#__PURE__*/dual(3, (left, right, f) => suspend(() => {
+  // Track consumed elements with cursors instead of slicing leftovers
+  let leftIndex = 0;
+  let rightIndex = 0;
+  return zipWithArray(left, right, (leftArr, rightArr) => {
+    const length = Math.min(leftArr.length - leftIndex, rightArr.length - rightIndex);
+    const output = Arr.makeBy(length, i => f(leftArr[leftIndex + i], rightArr[rightIndex + i]));
+    leftIndex += length;
+    rightIndex += length;
+    const leftDone = leftIndex === leftArr.length;
+    const rightDone = rightIndex === rightArr.length;
+    if (leftDone) leftIndex = 0;
+    if (rightDone) rightIndex = 0;
+    return [output, leftDone ? [] : leftArr, rightDone ? [] : rightArr];
+  });
+}));
 /**
  * Zips two streams by applying a function to non-empty arrays of elements.
  *
@@ -2538,28 +2578,14 @@ export const zipWithArray = /*#__PURE__*/dual(3, (left, right, f) => fromChannel
     const fiberRight = yield* Effect.forkIn(pullRight, scope);
     return yield* Fiber.joinAll([fiberLeft, fiberRight]);
   });
-  let state = {
-    _tag: "PullBoth"
-  };
+  let leftArray;
+  let rightArray;
   const pull = Effect.gen(function* () {
-    const [left, right] = state._tag === "PullBoth" ? yield* pullBoth : state._tag === "PullLeft" ? [yield* pullLeft, state.rightArray] : [state.leftArray, yield* pullRight];
-    const result = f(left, right);
-    if (Arr.isReadonlyArrayNonEmpty(result[1])) {
-      state = {
-        _tag: "PullRight",
-        leftArray: result[1]
-      };
-    } else if (Arr.isReadonlyArrayNonEmpty(result[2])) {
-      state = {
-        _tag: "PullLeft",
-        rightArray: result[2]
-      };
-    } else {
-      state = {
-        _tag: "PullBoth"
-      };
-    }
-    return result[0];
+    const [left, right] = leftArray ? [leftArray, rightArray ?? (yield* pullRight)] : rightArray ? [yield* pullLeft, rightArray] : yield* pullBoth;
+    const [output, leftoverLeft, leftoverRight] = f(left, right);
+    leftArray = Arr.isReadonlyArrayNonEmpty(leftoverLeft) ? leftoverLeft : undefined;
+    rightArray = Arr.isReadonlyArrayNonEmpty(leftoverRight) ? leftoverRight : undefined;
+    return output;
   });
   return pull;
 }))));
@@ -2618,13 +2644,7 @@ export const zip = /*#__PURE__*/dual(2, (self, that) => zipWith(self, that, (a,
  * @category zipping
  * @since 2.0.0
  */
-export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left, right, (leftArr, rightArr) => {
-  const minLength = Math.min(leftArr.length, rightArr.length);
-  const output = leftArr.slice(0, minLength);
-  const leftoverLeft = leftArr.slice(minLength);
-  const leftoverRight = rightArr.slice(minLength);
-  return [output, leftoverLeft, leftoverRight];
-}));
+export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWith(left, right, a => a));
 /**
  * Zips this stream with another point-wise, keeping only right values and ending when either stream ends.
  *
@@ -2648,13 +2668,7 @@ export const zipLeft = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left,
  * @category zipping
  * @since 2.0.0
  */
-export const zipRight = /*#__PURE__*/dual(2, (left, right) => zipWithArray(left, right, (leftArr, rightArr) => {
-  const minLength = Math.min(leftArr.length, rightArr.length);
-  const output = rightArr.slice(0, minLength);
-  const leftoverLeft = leftArr.slice(minLength);
-  const leftoverRight = rightArr.slice(minLength);
-  return [output, leftoverLeft, leftoverRight];
-}));
+export const zipRight = /*#__PURE__*/dual(2, (left, right) => zipWith(left, right, (_, a) => a));
 /**
  * Zips this stream with another point-wise and emits tuples of elements from
  * both streams, flattening the left tuple.
@@ -3449,6 +3463,12 @@ export const catchCause = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Ch
  *
  * 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
@@ -3502,6 +3522,13 @@ export {
 /**
  * Switches over to the stream produced by the provided function if this one fails.
  *
+ * **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.
+ *
  * **Example** (Catching stream failures)
  *
  * ```ts import.meta.vitest
@@ -3642,6 +3669,12 @@ export const tapDefect = /*#__PURE__*/dual(2, (self, f) => tapCause(self, cause
  * stream. Non-matching failures propagate downstream, so the error type is
  * preserved unless the filter narrows it.
  *
+ * **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 matching failures)
  *
  * ```ts import.meta.vitest
@@ -3682,6 +3715,12 @@ export const catchIf = /*#__PURE__*/dual(args => isStream(args[0]), (self, predi
  * Successful filter results are passed to `f`. Failed filter results go to
  * `orElse` when provided; otherwise the filter failure is 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 predicate or refinement based recovery
  * @see {@link catchTag} for `_tag` based recovery from one tagged error
  * @see {@link catchTags} for `_tag` based recovery from multiple tagged errors
@@ -3701,6 +3740,12 @@ export const catchFilter = /*#__PURE__*/dual(args => isStream(args[0]), (self, f
  * Use when you need to handle a specific error case from a stream whose error
  * type is a tagged union with a readonly `_tag` field.
  *
+ * **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 tagged failures)
  *
  * ```ts import.meta.vitest
@@ -3733,6 +3778,12 @@ export const catchTag = /*#__PURE__*/dual(args => isStream(args[0]), (self, k, f
 /**
  * Switches to a recovery stream based on matching `_tag` 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** (Catching tagged failures with handlers)
  *
  * ```ts import.meta.vitest
@@ -3787,6 +3838,12 @@ export const catchTags = /*#__PURE__*/dual(args => isStream(args[0]), (self, cas
  *
  * 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** (Catching a tagged error reason)
  *
  * ```ts import.meta.vitest
@@ -3829,6 +3886,12 @@ export const catchReason = /*#__PURE__*/dual(args => isStream(args[0]), (self, e
 /**
  * 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** (Catching tagged error reasons)
  *
  * ```ts import.meta.vitest
@@ -3930,6 +3993,11 @@ export const unwrapReason = /*#__PURE__*/dual(2, (self, errorTag) => catchFilter
 /**
  * Transforms the errors emitted by this stream using `f`.
  *
+ * **Details**
+ *
+ * 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 stream errors)
  *
  * ```ts import.meta.vitest
@@ -4033,6 +4101,12 @@ export const orElseIfEmpty = /*#__PURE__*/dual(2, (self, orElse) => fromChannel(
 /**
  * Returns a stream that emits a fallback value when this stream 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** (Recovering with a fallback value)
  *
  * ```ts import.meta.vitest
@@ -4093,6 +4167,13 @@ export const orDie = self => fromChannel(Channel.orDie(self.channel));
  * The `log` option controls whether the failure is logged before the stream
  * terminates.
  *
+ * **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** (Ignoring stream failures)
  *
  * ```ts import.meta.vitest
@@ -4174,6 +4255,12 @@ export const ignoreCause = /*#__PURE__*/dual(args => isStream(args[0]), (self, o
  * The schedule is reset as soon as the first element passes through the
  * stream again.
  *
+ * **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.
+ *
  * **Example** (Retrying stream failures)
  *
  * ```ts import.meta.vitest
@@ -5225,7 +5312,9 @@ export const mapAccum = /*#__PURE__*/dual(args => isStream(args[0]), (self, init
   for (let index = 0; index < arr.length; index++) {
     const [newState, values] = f(state, arr[index]);
     state = newState;
-    acc.push(...values);
+    for (let i = 0; i < values.length; i++) {
+      acc.push(values[i]);
+    }
   }
   return [state, Arr.isArrayNonEmpty(acc) ? Arr.of(acc) : emptyArr];
 }, options?.onHalt ? {
@@ -6499,12 +6588,7 @@ export const changesWithEffect = /*#__PURE__*/dual(2, (self, f) => transformPull
  * @category text
  * @since 2.0.0
  */
-export const decodeText = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => suspend(() => {
-  const decoder = new TextDecoder(options?.encoding);
-  return map(self, chunk => decoder.decode(chunk, {
-    stream: true
-  }));
-}));
+export const decodeText = /*#__PURE__*/dual(args => isStream(args[0]), (self, options) => self.channel.pipe(Channel.pipeTo(Channel.decodeText(options?.encoding)), fromChannel));
 /**
  * Encodes a stream of strings into UTF-8 `Uint8Array` chunks.
  *
@@ -6949,7 +7033,8 @@ export const ensuring = /*#__PURE__*/dual(2, (self, finalizer) => fromChannel(Ch
 /**
  * Provides a layer or context to the stream, removing the corresponding
  * service requirements. Use `options.local` to build the layer every time; by
- * default, layers are shared between provide calls.
+ * default, a layer already built by an enclosing provide or runtime is reused;
+ * sibling provide calls build their own copies.
  *
  * **Example** (Providing stream requirements)
  *
@@ -7806,14 +7891,14 @@ export const toReadableStreamWith = /*#__PURE__*/dual(args => isStream(args[0]),
   const onAbort = () => fiber.interruptUnsafe();
   return new ReadableStream({
     start(controller) {
-      fiber = Effect.runFork(Effect.provideContext(runForEachArray(self, chunk => latch.whenOpen(Effect.sync(() => {
+      fiber = Effect.runFork(Effect.provideContext(Channel.runForEach(Channel.transformPull(self.channel, pull => Effect.succeed(latch.whenOpen(pull))), chunk => Effect.sync(() => {
         latch.closeUnsafe();
         for (let i = 0; i < chunk.length; i++) {
           controller.enqueue(chunk[i]);
         }
         currentResolve();
         currentResolve = undefined;
-      }))), context));
+      })), context));
       fiber.addObserver(exit => {
         signal?.removeEventListener("abort", onAbort);
         if (cancelled) return;