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

package/dist/Stream.d.ts

@@ -11,6 +11,7 @@
  * @since 2.0.0
  */
 import * as Arr from "./Array.ts";
+import * as ByteSize from "./ByteSize.ts";
 import * as Cause from "./Cause.ts";
 import * as Channel from "./Channel.ts";
 import * as Context from "./Context.ts";
@@ -18,7 +19,6 @@ import * as Duration from "./Duration.ts";
 import * as Effect from "./Effect.ts";
 import * as ExecutionPlan from "./ExecutionPlan.ts";
 import * as Exit from "./Exit.ts";
-import type { SizeInput } from "./FileSystem.ts";
 import type * as Filter from "./Filter.ts";
 import type { LazyArg } from "./Function.ts";
 import type { TypeLambda } from "./HKT.ts";
@@ -747,6 +747,8 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => St
  * **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)
  *
@@ -778,7 +780,9 @@ export declare const fromIteratorSucceed: <A>(iterator: IterableIterator<A>, max
  *
  * **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)
  *
@@ -1164,7 +1168,7 @@ export declare const fromSubscription: <A>(pubsub: PubSub.Subscription<A>) => St
  * @category models
  * @since 3.4.0
  */
-export interface EventListener<A> {
+export interface EventListener<A = unknown> {
     addEventListener(event: string, f: (event: A) => void, options?: {
         readonly capture?: boolean;
         readonly passive?: boolean;
@@ -1207,7 +1211,7 @@ export interface EventListener<A> {
  * @category constructors
  * @since 3.1.0
  */
-export declare const fromEventListener: <A = unknown>(target: EventListener<A>, type: string, options?: boolean | {
+export declare const fromEventListener: <A = unknown>(target: EventListener, type: string, options?: boolean | {
     readonly capture?: boolean;
     readonly passive?: boolean;
     readonly once?: boolean;
@@ -1301,7 +1305,8 @@ export declare const iterate: <A>(value: A, next: (value: A) => A) => Stream<A>;
  * **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)
  *
@@ -6018,6 +6023,79 @@ export declare const catchCause: {
      */
     <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, f: (cause: Cause.Cause<E>) => Stream<A2, E2, R2>): Stream<A | A2, E2, R | R2>;
 };
+/**
+ * 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 declare const catchDefect: {
+    /**
+     * 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
+     */
+    <A2, E2, R2>(f: (defect: unknown) => Stream<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A | A2, E | E2, R | R2>;
+    /**
+     * 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
+     */
+    <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, f: (defect: unknown) => Stream<A2, E2, R2>): Stream<A | A2, E | E2, R | R2>;
+};
 /**
  * Runs an effect when the stream fails without changing its values or error,
  * unless the tap effect itself fails.
@@ -7764,7 +7842,12 @@ export declare const withExecutionPlan: {
     }): Stream<A, E | PolicyE, R2 | Exclude<R, Provides> | RX>;
 };
 /**
- * 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)
  *
@@ -7787,7 +7870,12 @@ export declare const withExecutionPlan: {
  */
 export declare const take: {
     /**
-     * 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)
      *
@@ -7810,7 +7898,12 @@ export declare const take: {
      */
     (n: number): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R>;
     /**
-     * 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)
      *
@@ -7840,13 +7933,13 @@ export declare const take: {
  * **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]))
  * )
@@ -7865,13 +7958,13 @@ export declare const limitBytes: {
      * **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]))
      * )
@@ -7882,7 +7975,7 @@ export declare const limitBytes: {
      * @category filtering
      * @since 4.0.0
      */
-    <E, R>(bytes: SizeInput, onLimitReached: LazyArg<Stream<Uint8Array, E, R>>): (self: Stream<Uint8Array, E, R>) => Stream<Uint8Array, E, R>;
+    <E, R>(bytes: ByteSize.Input, onLimitReached: LazyArg<Stream<Uint8Array, E, R>>): (self: Stream<Uint8Array, E, R>) => Stream<Uint8Array, E, R>;
     /**
      * Emits byte chunks until the configured limit would be exceeded, then drops
      * the crossing chunk and switches to a fallback stream.
@@ -7890,13 +7983,13 @@ export declare const limitBytes: {
      * **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]))
      * )
@@ -7907,11 +8000,16 @@ export declare const limitBytes: {
      * @category filtering
      * @since 4.0.0
      */
-    <E, R>(self: Stream<Uint8Array, E, R>, bytes: SizeInput, onLimitReached: LazyArg<Stream<Uint8Array, E, R>>): Stream<Uint8Array, E, R>;
+    <E, R>(self: Stream<Uint8Array, E, R>, bytes: ByteSize.Input, onLimitReached: LazyArg<Stream<Uint8Array, E, R>>): Stream<Uint8Array, E, R>;
 };
 /**
  * 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
@@ -7935,6 +8033,11 @@ export declare const takeRight: {
     /**
      * 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
@@ -7958,6 +8061,11 @@ export declare const takeRight: {
     /**
      * 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
@@ -8448,6 +8556,11 @@ export declare const takeWhileEffect: {
 /**
  * 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
@@ -8471,6 +8584,11 @@ export declare const drop: {
     /**
      * 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
@@ -8494,6 +8612,11 @@ export declare const drop: {
     /**
      * 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
@@ -8882,7 +9005,9 @@ export declare const dropWhileEffect: {
  *
  * **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)
  *
@@ -8909,7 +9034,9 @@ export declare const dropRight: {
      *
      * **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)
      *
@@ -8936,7 +9063,9 @@ export declare const dropRight: {
      *
      * **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)
      *
@@ -8988,7 +9117,8 @@ export declare const chunks: <A, E, R>(self: Stream<A, E, R>) => Stream<Arr.NonE
  *
  * **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)
  *
@@ -9016,7 +9146,8 @@ export declare const rechunk: {
      *
      * **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)
      *
@@ -9044,7 +9175,8 @@ export declare const rechunk: {
      *
      * **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)
      *
@@ -9071,6 +9203,11 @@ export declare const rechunk: {
 /**
  * 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
@@ -9093,6 +9230,11 @@ export declare const sliding: {
     /**
      * 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
@@ -9115,6 +9257,11 @@ export declare const sliding: {
     /**
      * 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
@@ -9138,6 +9285,11 @@ export declare const sliding: {
 /**
  * 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
@@ -9161,6 +9313,11 @@ export declare const slidingSize: {
     /**
      * 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
@@ -9184,6 +9341,11 @@ export declare const slidingSize: {
     /**
      * 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
@@ -10502,6 +10664,8 @@ export declare const throttle: {
  * **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)
  *
@@ -10529,6 +10693,8 @@ export declare const grouped: {
      * **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)
      *
@@ -10556,6 +10722,8 @@ export declare const grouped: {
      * **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)
      *
@@ -10582,6 +10750,11 @@ export declare const grouped: {
  * 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
@@ -10606,6 +10779,11 @@ export declare const groupedWithin: {
      * 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
@@ -10630,6 +10808,11 @@ export declare const groupedWithin: {
      * 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
@@ -11127,7 +11310,8 @@ export declare const aggregateWithin: {
  * 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)
  *
@@ -11166,7 +11350,8 @@ export declare const broadcastN: {
      * 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)
      *
@@ -11214,7 +11399,8 @@ export declare const broadcastN: {
      * 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)
      *
@@ -14791,6 +14977,11 @@ export declare const mkString: <E, R>(self: Stream<string, E, R>) => Effect.Effe
 /**
  * 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
@@ -14807,11 +14998,6 @@ export declare const mkString: <E, R>(self: Stream<string, E, R>) => Effect.Effe
  * 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
  */
@@ -14819,6 +15005,11 @@ export declare const mkArrayBuffer: <E, R>(self: Stream<Uint8Array, E, R>) => Ef
 /**
  * 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
@@ -14833,11 +15024,6 @@ export declare const mkArrayBuffer: <E, R>(self: Stream<Uint8Array, E, R>) => Ef
  * 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
  */