effect 4.0.0-rc.112 → 4.0.0-rc.113

package/dist/Stream.js

@@ -12,6 +12,7 @@
  */
 // @effect-diagnostics returnEffectInGen:off
 import * as Arr from "./Array.js";
+import * as ByteSize from "./ByteSize.js";
 import * as Cause from "./Cause.js";
 import * as Channel from "./Channel.js";
 import { Clock } from "./Clock.js";
@@ -23,6 +24,7 @@ import * as ExecutionPlan from "./ExecutionPlan.js";
 import * as Exit from "./Exit.js";
 import * as Fiber from "./Fiber.js";
 import { constant, constTrue, constVoid, dual, identity } from "./Function.js";
+import * as Count from "./internal/count.js";
 import * as internalExecutionPlan from "./internal/executionPlan.js";
 import * as internal from "./internal/stream.js";
 import { addSpanStackTrace } from "./internal/tracer.js";
@@ -601,6 +603,8 @@ export const failCauseSync = evaluate => fromChannel(Channel.failCauseSync(evalu
  * **Details**
  *
  * The `maxChunkSize` parameter controls how many values are pulled per chunk.
+ * Finite fractional values are rounded down, while `NaN` and non-positive
+ * values are treated as `1`.
  *
  * **Example** (Consuming values from an iterator)
  *
@@ -632,7 +636,9 @@ export const fromIteratorSucceed = (iterator, maxChunkSize) => fromChannel(Chann
  *
  * **Details**
  *
- * - `chunkSize`: Maximum number of values emitted per chunk.
+ * - `chunkSize`: Maximum number of values emitted per chunk. Finite fractional
+ *   values are rounded down, while `NaN` and non-positive values are treated as
+ *   `1`.
  *
  * **Example** (Creating a stream from an iterable)
  *
@@ -1039,8 +1045,10 @@ export const fromSubscription = pubsub => fromChannel(Channel.fromSubscriptionAr
  * @since 3.1.0
  */
 export const fromEventListener = (target, type, options) => callback(queue => {
+  const once = typeof options === "object" && options.once;
   function emit(event) {
     Queue.offerUnsafe(queue, event);
+    if (once) Queue.endUnsafe(queue);
   }
   return Effect.acquireRelease(Effect.sync(() => target.addEventListener(type, emit, options)), () => Effect.sync(() => target.removeEventListener(type, emit, options)));
 }, {
@@ -1156,7 +1164,8 @@ export const iterate = (value, next) => unfold(value, a => Effect.succeed([a, ne
  * **Details**
  *
  * If the provided `min` is greater than `max`, the stream will not emit any
- * values.
+ * values. Finite fractional `chunkSize` values are rounded down, while `NaN`
+ * and non-positive values are treated as `1`.
  *
  * **Example** (Creating a numeric range)
  *
@@ -1175,7 +1184,7 @@ export const iterate = (value, next) => unfold(value, a => Effect.succeed([a, ne
  * @since 2.0.0
  */
 export const range = (min, max, chunkSize = Channel.DefaultChunkSize) => min > max ? empty : fromPull(Effect.sync(() => {
-  const size = Math.max(1, chunkSize);
+  const size = Count.normalizeNonEmpty(chunkSize);
   let start = min;
   let done = false;
   return Effect.suspend(() => {
@@ -3269,6 +3278,30 @@ export const bufferArray = /*#__PURE__*/dual(2, (self, options) => fromChannel(C
  * @since 2.0.0
  */
 export const catchCause = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Channel.catchCause(cause => f(cause).channel), fromChannel));
+/**
+ * Recovers from defects using the provided function.
+ *
+ * **Details**
+ *
+ * Typed failures and interruptions are not caught.
+ *
+ * **Example** (Recovering from a defect)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.die("boom").pipe(
+ *   Stream.catchDefect((defect) => Stream.succeed(`recovered: ${defect}`))
+ * )
+ *
+ * const result = Effect.runSync(Stream.runCollect(stream))
+ * result // => ["recovered: boom"]
+ * ```
+ *
+ * @category error handling
+ * @since 4.0.0
+ */
+export const catchDefect = /*#__PURE__*/dual(2, (self, f) => self.channel.pipe(Channel.catchDefect(defect => f(defect).channel), fromChannel));
 /**
  * Runs an effect when the stream fails without changing its values or error,
  * unless the tap effect itself fails.
@@ -3972,7 +4005,12 @@ export const withExecutionPlan = /*#__PURE__*/dual(args => isStream(args[0]), (s
   return loop;
 }));
 /**
- * Takes the first `n` elements from this stream, returning `Stream.empty` when `n < 1`.
+ * Takes the first `n` elements from this stream.
+ *
+ * **Details**
+ *
+ * Finite fractional values of `n` are rounded down. `NaN` and non-positive
+ * values return `Stream.empty` without evaluating the source stream.
  *
  * **Example** (Taking values from the left)
  *
@@ -3993,7 +4031,10 @@ export const withExecutionPlan = /*#__PURE__*/dual(args => isStream(args[0]), (s
  * @category filtering
  * @since 2.0.0
  */
-export const take = /*#__PURE__*/dual(2, (self, n) => n < 1 ? empty : takeUntil(self, (_, i) => i === n - 1));
+export const take = /*#__PURE__*/dual(2, (self, n) => {
+  const count = Count.normalize(n);
+  return count === 0 ? empty : takeUntil(self, (_, i) => i === count - 1);
+});
 /**
  * Emits byte chunks until the configured limit would be exceeded, then drops
  * the crossing chunk and switches to a fallback stream.
@@ -4001,13 +4042,13 @@ export const take = /*#__PURE__*/dual(2, (self, n) => n < 1 ? empty : takeUntil(
  * **Example** (Truncating at a byte limit)
  *
  * ```ts import.meta.vitest
- * import { Effect, Stream } from "effect"
+ * import { ByteSize, Effect, Stream } from "effect"
  *
  * const program = Stream.make(
  *   new Uint8Array([1, 2]),
  *   new Uint8Array([3, 4, 5])
  * ).pipe(
- *   Stream.limitBytes(4, () => Stream.empty),
+ *   Stream.limitBytes(ByteSize.bytes(4), () => Stream.empty),
  *   Stream.runCollect,
  *   Effect.map((chunks) => chunks.map((chunk) => [...chunk]))
  * )
@@ -4019,7 +4060,7 @@ export const take = /*#__PURE__*/dual(2, (self, n) => n < 1 ? empty : takeUntil(
  * @since 4.0.0
  */
 export const limitBytes = /*#__PURE__*/dual(3, (self, bytes, onLimitReached) => suspend(() => {
-  const limit = BigInt(bytes);
+  const limit = ByteSize.fromInputUnsafe(bytes);
   let size = BigInt(0);
   let limitReached = false;
   return concat(takeWhile(self, chunk => {
@@ -4035,6 +4076,11 @@ export const limitBytes = /*#__PURE__*/dual(3, (self, bytes, onLimitReached) =>
 /**
  * Keeps the last `n` elements from this stream.
  *
+ * **Details**
+ *
+ * Finite fractional values of `n` are rounded down. `NaN` and non-positive
+ * values return `Stream.empty` without evaluating the source stream.
+ *
  * **Example** (Taking elements from the right)
  *
  * ```ts import.meta.vitest
@@ -4054,17 +4100,21 @@ export const limitBytes = /*#__PURE__*/dual(3, (self, bytes, onLimitReached) =>
  * @category filtering
  * @since 2.0.0
  */
-export const takeRight = /*#__PURE__*/dual(2, (self, n) => mapAccumArray(self, MutableList.make, (list, arr) => {
-  MutableList.appendAll(list, arr);
-  if (list.length > n) {
-    MutableList.takeNVoid(list, list.length - n);
-  }
-  return [list, emptyArr];
-}, {
-  onHalt(list) {
-    return MutableList.takeAll(list);
-  }
-}));
+export const takeRight = /*#__PURE__*/dual(2, (self, n) => {
+  const count = Count.normalize(n);
+  if (count === 0) return empty;
+  return mapAccumArray(self, MutableList.make, (list, arr) => {
+    MutableList.appendAll(list, arr);
+    if (list.length > count) {
+      MutableList.takeNVoid(list, list.length - count);
+    }
+    return [list, emptyArr];
+  }, {
+    onHalt(list) {
+      return MutableList.takeAll(list);
+    }
+  });
+});
 /**
  * Takes elements until the predicate matches.
  *
@@ -4263,6 +4313,11 @@ export const takeWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => takeUnt
 /**
  * Drops the first `n` elements from this stream.
  *
+ * **Details**
+ *
+ * Finite fractional values of `n` are rounded down. `NaN` and non-positive
+ * values return the source stream unchanged.
+ *
  * **Example** (Dropping values from the left)
  *
  * ```ts import.meta.vitest
@@ -4282,16 +4337,20 @@ export const takeWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => takeUnt
  * @category filtering
  * @since 2.0.0
  */
-export const drop = /*#__PURE__*/dual(2, (self, n) => transformPull(self, (pull, _scope) => Effect.sync(() => {
-  let dropped = 0;
-  const pump = pull.pipe(Effect.flatMap(chunk => {
-    if (dropped >= n) return Effect.succeed(chunk);
-    dropped += chunk.length;
-    if (dropped <= n) return pump;
-    return Effect.succeed(chunk.slice(n - dropped));
+export const drop = /*#__PURE__*/dual(2, (self, n) => {
+  const count = Count.normalize(n);
+  if (count === 0) return self;
+  return transformPull(self, (pull, _scope) => Effect.sync(() => {
+    let dropped = 0;
+    const pump = pull.pipe(Effect.flatMap(chunk => {
+      if (dropped >= count) return Effect.succeed(chunk);
+      dropped += chunk.length;
+      if (dropped <= count) return pump;
+      return Effect.succeed(chunk.slice(count - dropped));
+    }));
+    return pump;
   }));
-  return pump;
-})));
+});
 /**
  * Drops elements until the specified predicate evaluates to `true`, then drops
  * that matching element.
@@ -4450,7 +4509,9 @@ export const dropWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => transfo
  *
  * **Details**
  *
- * Keeps the last `n` elements in memory to drop them on completion.
+ * Keeps the last `n` elements in memory to drop them on completion. Finite
+ * fractional values of `n` are rounded down. `NaN` and non-positive values
+ * return the source stream unchanged.
  *
  * **Example** (Dropping values from the right)
  *
@@ -4472,12 +4533,13 @@ export const dropWhileEffect = /*#__PURE__*/dual(2, (self, predicate) => transfo
  * @since 2.0.0
  */
 export const dropRight = /*#__PURE__*/dual(2, (self, n) => {
-  if (n <= 0) return self;
+  const count = Count.normalize(n);
+  if (count === 0) return self;
   return transformPull(self, (pull, _scope) => Effect.sync(() => {
     const list = MutableList.make();
     const emit = Effect.flatMap(pull, arr => {
       MutableList.appendAllUnsafe(list, arr);
-      const toTake = list.length - n;
+      const toTake = list.length - count;
       const items = MutableList.takeN(list, toTake);
       return Arr.isArrayNonEmpty(items) ? Effect.succeed(items) : emit;
     });
@@ -4513,7 +4575,8 @@ export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel
  *
  * **Details**
  *
- * The size is clamped to at least 1.
+ * Finite fractional sizes are rounded down. `NaN` and non-positive sizes are
+ * treated as `1`.
  *
  * **Example** (Rechunking stream elements)
  *
@@ -4536,7 +4599,7 @@ export const chunks = self => self.channel.pipe(Channel.map(Arr.of), fromChannel
  * @since 2.0.0
  */
 export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
-  target = Math.max(1, target);
+  target = Count.normalizeNonEmpty(target);
   return transformPull(self, (pull, _scope) => Effect.sync(() => {
     let chunk = Arr.empty();
     let index = 0;
@@ -4548,7 +4611,9 @@ export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
           if (chunk.length === 0 && arr.length === target) {
             return Effect.succeed(arr);
           } else if (chunk.length + arr.length < target) {
-            chunk.push(...arr);
+            for (let i = 0; i < arr.length; i++) {
+              chunk.push(arr[i]);
+            }
             return loop();
           }
           current = arr;
@@ -4578,6 +4643,11 @@ export const rechunk = /*#__PURE__*/dual(2, (self, target) => {
 /**
  * Emits a sliding window of `n` elements.
  *
+ * **Details**
+ *
+ * Finite fractional window sizes are rounded down. `NaN` and non-positive
+ * sizes are treated as `1`.
+ *
  * **Example** (Emitting sliding windows)
  *
  * ```ts import.meta.vitest
@@ -4600,6 +4670,11 @@ export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(sel
 /**
  * Emits sliding windows of `chunkSize` elements, advancing by `stepSize`.
  *
+ * **Details**
+ *
+ * Finite fractional window and step sizes are rounded down. `NaN` and
+ * non-positive sizes are treated as `1`.
+ *
  * **Example** (Emitting sliding windows with a step size)
  *
  * ```ts import.meta.vitest
@@ -4619,47 +4694,47 @@ export const sliding = /*#__PURE__*/dual(2, (self, chunkSize) => slidingSize(sel
  * @category grouping
  * @since 2.0.0
  */
-export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => transformPull(self, (upstream, _scope) => Effect.sync(() => {
-  let cause = null;
-  const list = MutableList.make();
-  let emitted = false;
-  let skip = 0;
-  const pull = Effect.matchCauseEffect(upstream, {
-    onSuccess(arr) {
-      MutableList.appendAllUnsafe(list, arr);
-      if (skip > 0) {
-        const length = list.length;
-        MutableList.takeNVoid(list, skip);
-        skip = Math.max(0, skip - length);
-      }
-      if (list.length < chunkSize) return pull;
-      emitted = true;
-      const chunks = [];
-      while (list.length >= chunkSize) {
-        if (chunkSize === stepSize) {
-          chunks.push(MutableList.takeN(list, chunkSize));
-        } else {
-          chunks.push(MutableList.toArrayN(list, chunkSize));
-          if (chunkSize === 1 && stepSize <= 0) {
-            MutableList.take(list);
+export const slidingSize = /*#__PURE__*/dual(3, (self, chunkSize, stepSize) => {
+  const windowSize = Count.normalizeNonEmpty(chunkSize);
+  const step = Count.normalizeNonEmpty(stepSize);
+  return transformPull(self, (upstream, _scope) => Effect.sync(() => {
+    let cause = null;
+    const list = MutableList.make();
+    let emitted = false;
+    let skip = 0;
+    const pull = Effect.matchCauseEffect(upstream, {
+      onSuccess(arr) {
+        MutableList.appendAllUnsafe(list, arr);
+        if (skip > 0) {
+          const length = list.length;
+          MutableList.takeNVoid(list, skip);
+          skip = Math.max(0, skip - length);
+        }
+        if (list.length < windowSize) return pull;
+        emitted = true;
+        const chunks = [];
+        while (list.length >= windowSize) {
+          if (windowSize === step) {
+            chunks.push(MutableList.takeN(list, windowSize));
           } else {
+            chunks.push(MutableList.toArrayN(list, windowSize));
             const length = list.length;
-            MutableList.takeNVoid(list, stepSize);
-            skip = Math.max(0, stepSize - length);
+            MutableList.takeNVoid(list, step);
+            skip = Math.max(0, step - length);
           }
         }
+        return Effect.succeed(chunks);
+      },
+      onFailure(cause_) {
+        if (emitted) MutableList.takeNVoid(list, windowSize - step);
+        if (list.length === 0) return Effect.failCause(cause_);
+        cause = cause_;
+        return Effect.succeed(Arr.of(MutableList.takeAll(list)));
       }
-      return Effect.succeed(chunks);
-    },
-    onFailure(cause_) {
-      if (emitted) MutableList.takeNVoid(list, chunkSize - stepSize);
-      if (list.length === 0) return Effect.failCause(cause_);
-      cause = cause_;
-      return Effect.succeed(Arr.of(MutableList.takeAll(list)));
-    }
-  });
-  return Effect.suspend(() => cause ? Effect.failCause(cause) : pull);
-})));
+    });
+    return Effect.suspend(() => cause ? Effect.failCause(cause) : pull);
+  }));
+});
 /**
  * Splits the stream into non-empty groups whenever the predicate matches.
  *
@@ -5242,6 +5317,8 @@ export const throttle = /*#__PURE__*/dual(2, (self, options) => throttleEffect(s
  * **Details**
  *
  * The final array may be smaller if there are not enough elements to fill it.
+ * Finite fractional sizes are rounded down. `NaN` and non-positive sizes are
+ * treated as `1`.
  *
  * **Example** (Grouping elements by size)
  *
@@ -5267,6 +5344,11 @@ export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)
  * Partitions the stream into arrays, emitting when the chunk size is reached
  * or the duration passes.
  *
+ * **Details**
+ *
+ * Finite fractional chunk sizes are rounded down. `NaN` and non-positive sizes
+ * are treated as `1`.
+ *
  * **Example** (Grouping elements by size or time)
  *
  * ```ts import.meta.vitest
@@ -5286,7 +5368,7 @@ export const grouped = /*#__PURE__*/dual(2, (self, n) => chunks(rechunk(self, n)
  * @category grouping
  * @since 2.0.0
  */
-export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) => aggregateWithin(self, Sink.take(chunkSize), Schedule.spaced(duration)));
+export const groupedWithin = /*#__PURE__*/dual(3, (self, chunkSize, duration) => aggregateWithin(self, Sink.take(Count.normalizeNonEmpty(chunkSize)), Schedule.spaced(duration)));
 /**
  * Groups elements into keyed substreams using an effectful classifier.
  *
@@ -5622,7 +5704,8 @@ export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fr
  * With the default suspend strategy, the source can only advance `capacity`
  * chunks ahead of the slowest downstream stream. If a downstream stream is
  * interrupted, it unsubscribes from the broadcast so it no longer contributes
- * backpressure.
+ * backpressure. Finite fractional values of `n` are rounded down. `NaN` and
+ * non-positive values create no downstream streams.
  *
  * **Example** (Broadcasting to two consumers)
  *
@@ -5651,10 +5734,11 @@ export const aggregateWithin = /*#__PURE__*/dual(3, (self, sink, schedule) => fr
  * @since 4.0.0
  */
 export const broadcastN = /*#__PURE__*/dual(2, /*#__PURE__*/Effect.fnUntraced(function* (self, options) {
+  const n = Count.normalize(options.n);
   const pubsub = yield* makePubSub(options);
-  const streams = new Array(options.n);
+  const streams = new Array(n);
   const parentScope = yield* Scope.Scope;
-  for (let i = 0; i < options.n; i++) {
+  for (let i = 0; i < n; i++) {
     const scope = Scope.forkUnsafe(parentScope);
     const subscription = yield* PubSub.subscribe(pubsub).pipe(Effect.provideService(Scope.Scope, scope));
     streams[i] = Channel.fromEffectTake(PubSub.take(subscription)).pipe(Channel.onExit(exit => Scope.close(scope, exit)), fromChannel);
@@ -7214,6 +7298,11 @@ export const mkString = self => Channel.runFold(self.channel, () => "", (acc, ch
 /**
  * Concatenates the stream's `Uint8Array` chunks into a single `ArrayBuffer`.
  *
+ * **Gotchas**
+ *
+ * This materializes the full content in memory. The source stream must not
+ * reuse or mutate emitted buffers, which are retained until collection completes.
+ *
  * **Example** (Joining byte chunks into an ArrayBuffer)
  *
  * ```ts import.meta.vitest
@@ -7230,11 +7319,6 @@ export const mkString = self => Channel.runFold(self.channel, () => "", (acc, ch
  * await Effect.runPromise(program) // => [1, 2, 3, 4]
  * ```
  *
- * **Gotchas**
- *
- * This materializes the full content in memory. The source stream must not
- * reuse or mutate emitted buffers, which are retained until collection completes.
- *
  * @category destructors
  * @since 4.0.0
  */
@@ -7242,6 +7326,11 @@ export const mkArrayBuffer = self => Effect.map(Channel.mkUint8Array(self.channe
 /**
  * Concatenates the stream's `Uint8Array` chunks into a single `Uint8Array`.
  *
+ * **Gotchas**
+ *
+ * This materializes the full content in memory. The source stream must not
+ * reuse or mutate emitted buffers, which are retained until collection completes.
+ *
  * **Example** (Joining Uint8Array chunks)
  *
  * ```ts import.meta.vitest
@@ -7256,11 +7345,6 @@ export const mkArrayBuffer = self => Effect.map(Channel.mkUint8Array(self.channe
  * await Effect.runPromise(program)
  * ```
  *
- * **Gotchas**
- *
- * This materializes the full content in memory. The source stream must not
- * reuse or mutate emitted buffers, which are retained until collection completes.
- *
  * @category destructors
  * @since 4.0.0
  */