effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/Sink.d.ts

@@ -39,7 +39,7 @@ declare const TypeId = "~effect/Sink";
  *
  * **Example** (Running a sink with a stream)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Sink, Stream } from "effect"
  *
  * // Create a simple sink that always succeeds with a value
@@ -47,10 +47,7 @@ declare const TypeId = "~effect/Sink";
  *
  * // Use the sink to consume a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).then(console.log)
- * // Output: 42
+ * await Effect.runPromise(Stream.run(stream, sink)) // => 42
  * ```
  *
  * @category models
@@ -153,14 +150,14 @@ export declare namespace Sink {
  *
  * **Example** (Checking for a sink)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Sink } from "effect"
  *
  * const sink = Sink.never
  * const notStream = { data: [1, 2, 3] }
  *
- * console.log(Sink.isSink(sink)) // true
- * console.log(Sink.isSink(notStream)) // false
+ * Sink.isSink(sink) // => true
+ * Sink.isSink(notStream) // => false
  * ```
  *
  * @category guards
@@ -175,11 +172,55 @@ export declare const isSink: (u: unknown) => u is Sink<unknown, never, unknown,
  * Use to create a `Sink` from a `Channel` that processes non-empty arrays of
  * input values.
  *
+ * **Example** (Using channel completion as the sink result)
+ *
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Sink, Stream } from "effect"
+ *
+ * const channel = Channel.identity<readonly [number, ...Array<number>], never, void>().pipe(
+ *   Channel.drain,
+ *   Channel.mapDone(() => ["consumed"] as const)
+ * )
+ * const sink = Sink.fromChannel(channel)
+ *
+ * await Effect.runPromise(Stream.run(Stream.make(1, 2, 3), sink)) // => "consumed"
+ * ```
+ *
  * @see {@link toChannel} for converting a `Sink` back to a `Channel`
  * @category constructors
  * @since 2.0.0
  */
 export declare const fromChannel: <L, In, E, A, R>(channel: Channel.Channel<never, E, End<A, L>, NonEmptyReadonlyArray<In>, never, void, R>) => Sink<A, In, L, E, R>;
+/**
+ * Creates a sink that writes its input to a Web `WritableStream`.
+ *
+ * **Example** (Collecting values in a Web stream)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Sink, Stream } from "effect"
+ *
+ * const written: Array<number> = []
+ * const sink = Sink.fromWritableStream({
+ *   evaluate: () => new WritableStream<number>({
+ *     write(value) {
+ *       written.push(value)
+ *     }
+ *   }),
+ *   onError: (cause) => new Error(String(cause))
+ * })
+ *
+ * await Effect.runPromise(Stream.run(Stream.make(1, 2, 3), sink))
+ * written // => [1, 2, 3]
+ * ```
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const fromWritableStream: <A, E>(options: {
+    readonly evaluate: LazyArg<WritableStream<A>>;
+    readonly onError: (error: unknown) => E;
+    readonly closeOnDone?: boolean | undefined;
+}) => Sink<void, A, never, E>;
 /**
  * Creates a `Sink` from a low-level transform function.
  *
@@ -196,14 +237,16 @@ export declare const fromTransform: <In, A, E, R, L = never>(transform: (upstrea
 /**
  * Creates a `Channel` from a Sink.
  *
- * **Example** (Converting a sink to a channel)
+ * **Example** (Running a sink as a channel)
  *
- * ```ts
- * import { Sink } from "effect"
+ * ```ts import.meta.vitest
+ * import { Channel, Effect, Sink, Stream } from "effect"
  *
- * // Create a sink and extract its channel
- * const sink = Sink.succeed(42)
- * const channel = Sink.toChannel(sink)
+ * const channel = Stream.toChannel(Stream.make(1, 2, 3)).pipe(
+ *   Channel.pipeTo(Sink.toChannel(Sink.sum))
+ * )
+ *
+ * await Effect.runPromise(Channel.runDone(channel)) // => [6]
  * ```
  *
  * @category constructors
@@ -308,7 +351,7 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Sink<void, A>;
  *
  * **Example** (Succeeding with a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Sink, Stream } from "effect"
  *
  * // Create a sink that always yields the same value
@@ -316,10 +359,7 @@ export declare const fromPubSub: <A>(pubsub: PubSub.PubSub<A>) => Sink<void, A>;
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).then(console.log)
- * // Output: 42
+ * await Effect.runPromise(Stream.run(stream, sink)) // => 42
  * ```
  *
  * @category constructors
@@ -345,18 +385,15 @@ export declare const suspend: <A, In, L, E, R>(evaluate: LazyArg<Sink<A, In, L,
  *
  * **Example** (Failing with an error)
  *
- * ```ts
- * import { Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Sink, Stream } from "effect"
  *
  * // Create a sink that always fails
- * const sink = Sink.fail(new Error("Sink failed"))
+ * const sink = Sink.fail("Sink failed")
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).catch(console.log)
- * // Output: Error: Sink failed
+ * await Effect.runPromiseExit(Stream.run(stream, sink)) // => Exit.fail("Sink failed")
  * ```
  *
  * @category constructors
@@ -368,18 +405,15 @@ export declare const fail: <E>(e: E) => Sink<never, unknown, never, E>;
  *
  * **Example** (Failing with a lazy error)
  *
- * ```ts
- * import { Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Sink, Stream } from "effect"
  *
  * // Create a sink that fails with a lazy error
- * const sink = Sink.failSync(() => new Error("Lazy error"))
+ * const sink = Sink.failSync(() => "Lazy error")
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).catch(console.log)
- * // Output: Error: Lazy error
+ * await Effect.runPromiseExit(Stream.run(stream, sink)) // => Exit.fail("Lazy error")
  * ```
  *
  * @category constructors
@@ -391,18 +425,15 @@ export declare const failSync: <E>(evaluate: LazyArg<E>) => Sink<never, unknown,
  *
  * **Example** (Failing with a cause)
  *
- * ```ts
- * import { Cause, Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit, Sink, Stream } from "effect"
  *
  * // Create a sink that fails with a specific cause
- * const sink = Sink.failCause(Cause.fail(new Error("Custom cause")))
+ * const sink = Sink.failCause(Cause.fail("Custom cause"))
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).catch(console.log)
- * // Output: Error: Custom cause
+ * await Effect.runPromiseExit(Stream.run(stream, sink)) // => Exit.fail("Custom cause")
  * ```
  *
  * @category constructors
@@ -414,18 +445,15 @@ export declare const failCause: <E>(cause: Cause.Cause<E>) => Sink<never, unknow
  *
  * **Example** (Failing with a lazy cause)
  *
- * ```ts
- * import { Cause, Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Cause, Effect, Exit, Sink, Stream } from "effect"
  *
  * // Create a sink that fails with a lazy cause
- * const sink = Sink.failCauseSync(() => Cause.fail(new Error("Lazy cause")))
+ * const sink = Sink.failCauseSync(() => Cause.fail("Lazy cause"))
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).catch(console.log)
- * // Output: Error: Lazy cause
+ * await Effect.runPromiseExit(Stream.run(stream, sink)) // => Exit.fail("Lazy cause")
  * ```
  *
  * @category constructors
@@ -437,18 +465,15 @@ export declare const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Si
  *
  * **Example** (Dying with a defect)
  *
- * ```ts
- * import { Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Exit, Sink, Stream } from "effect"
  *
  * // Create a sink that dies with a defect
- * const sink = Sink.die(new Error("Defect error"))
+ * const sink = Sink.die("Defect error")
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program).catch(console.log)
- * // Output: Error: Defect error
+ * await Effect.runPromiseExit(Stream.run(stream, sink)) // => Exit.die("Defect error")
  * ```
  *
  * @category constructors
@@ -964,7 +989,7 @@ export declare const mapLeftover: {
  * If more elements are pulled than needed, the remaining elements from the same
  * array are returned as leftovers.
  *
- * @category collecting
+ * @category constructors
  * @since 2.0.0
  */
 export declare const take: <In>(n: number) => Sink<Array<In>, In, In>;
@@ -1039,7 +1064,7 @@ export declare const flatMap: {
  * A sink that reduces input elements from the provided `initial` state with
  * `f` while the specified `predicate` returns `true`.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceWhile: <S, In>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: In) => S) => Sink<S, In, In>;
@@ -1047,7 +1072,7 @@ export declare const reduceWhile: <S, In>(initial: LazyArg<S>, predicate: Predic
  * A sink that effectfully reduces input elements from the provided `initial`
  * state with `f` while the specified `predicate` returns `true`.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceWhileEffect: <S, In, E, R>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, In, E, R>;
@@ -1055,7 +1080,7 @@ export declare const reduceWhileEffect: <S, In, E, R>(initial: LazyArg<S>, predi
  * A sink that reduces non-empty input arrays from the provided `initial` state
  * with `f` while the specified `predicate` returns `true`.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceWhileArray: <S, In>(initial: LazyArg<S>, contFn: Predicate<S>, f: (s: S, input: NonEmptyReadonlyArray<In>) => S) => Sink<S, In>;
@@ -1063,7 +1088,7 @@ export declare const reduceWhileArray: <S, In>(initial: LazyArg<S>, contFn: Pred
  * A sink that effectfully reduces non-empty input arrays from the provided
  * `initial` state with `f` while the specified `predicate` returns `true`.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceWhileArrayEffect: <S, In, E, R>(initial: LazyArg<S>, predicate: Predicate<S>, f: (s: S, input: NonEmptyReadonlyArray<In>) => Effect.Effect<S, E, R>) => Sink<S, In, never, E, R>;
@@ -1071,7 +1096,7 @@ export declare const reduceWhileArrayEffect: <S, In, E, R>(initial: LazyArg<S>,
  * A sink that reduces its inputs using the provided function `f` starting from
  * the provided `initial` state.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduce: <S, In>(initial: LazyArg<S>, f: (s: S, input: In) => S) => Sink<S, In>;
@@ -1079,7 +1104,7 @@ export declare const reduce: <S, In>(initial: LazyArg<S>, f: (s: S, input: In) =
  * A sink that reduces its inputs using the provided function `f` starting from
  * the specified `initial` state.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceArray: <S, In>(initial: LazyArg<S>, f: (s: S, input: NonEmptyReadonlyArray<In>) => S) => Sink<S, In>;
@@ -1087,7 +1112,7 @@ export declare const reduceArray: <S, In>(initial: LazyArg<S>, f: (s: S, input:
  * A sink that reduces its inputs using the provided effectful function `f`
  * starting from the specified `initial` state.
  *
- * @category reducing
+ * @category folding
  * @since 4.0.0
  */
 export declare const reduceEffect: <S, In, E, R>(initial: LazyArg<S>, f: (s: S, input: In) => Effect.Effect<S, E, R>) => Sink<S, In, never, E, R>;
@@ -1364,21 +1389,16 @@ export declare const takeUntilEffect: <In, E, R>(predicate: (input: In) => Effec
  *
  * **Example** (Running effects for each item)
  *
- * ```ts
- * import { Console, Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Sink, Stream } from "effect"
  *
- * // Create a sink that logs each item
- * const sink = Sink.forEach((item: number) => Console.log(`Processing: ${item}`))
+ * const processed: Array<number> = []
+ * const sink = Sink.forEach((item: number) => Effect.sync(() => processed.push(item)))
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program)
- * // Output:
- * // Processing: 1
- * // Processing: 2
- * // Processing: 3
+ * await Effect.runPromise(Stream.run(stream, sink))
+ * processed // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -1391,22 +1411,16 @@ export declare const forEach: <In, X, E, R>(f: (input: In) => Effect.Effect<X, E
  *
  * **Example** (Running effects for each chunk)
  *
- * ```ts
- * import { Console, Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Sink, Stream } from "effect"
  *
- * // Create a sink that processes chunks
- * const sink = Sink.forEachArray((chunk: ReadonlyArray<number>) =>
- *   Console.log(
- *     `Processing chunk of ${chunk.length} items: [${chunk.join(", ")}]`
- *   )
- * )
+ * const processed: Array<Array<number>> = []
+ * const sink = Sink.forEachArray((chunk: ReadonlyArray<number>) => Effect.sync(() => processed.push([...chunk])))
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3, 4, 5)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program)
- * // Output: Processing chunk of 5 items: [1, 2, 3, 4, 5]
+ * await Effect.runPromise(Stream.run(stream, sink))
+ * processed // => [[1, 2, 3, 4, 5]]
  * ```
  *
  * @category constructors
@@ -1443,24 +1457,20 @@ export declare const forEachWhileArray: <In, E, R>(f: (input: NonEmptyReadonlyAr
  *
  * **Example** (Unwrapping a sink effect)
  *
- * ```ts
- * import { Console, Effect, Sink, Stream } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Sink, Stream } from "effect"
  *
  * // Create a sink from an effect that produces a sink
+ * const processed: Array<number> = []
  * const sinkEffect = Effect.succeed(
- *   Sink.forEach((item: number) => Console.log(`Item: ${item}`))
+ *   Sink.forEach((item: number) => Effect.sync(() => processed.push(item)))
  * )
  * const sink = Sink.unwrap(sinkEffect)
  *
  * // Use it with a stream
  * const stream = Stream.make(1, 2, 3)
- * const program = Stream.run(stream, sink)
- *
- * Effect.runPromise(program)
- * // Output:
- * // Item: 1
- * // Item: 2
- * // Item: 3
+ * await Effect.runPromise(Stream.run(stream, sink))
+ * processed // => [1, 2, 3]
  * ```
  *
  * @category constructors
@@ -1511,7 +1521,7 @@ export declare const timed: Sink<Duration.Duration, unknown>;
  * Services contained in the provided context are removed from the sink's
  * service requirements.
  *
- * @category services
+ * @category providing services
  * @since 2.0.0
  */
 export declare const provideContext: {
@@ -1523,7 +1533,7 @@ export declare const provideContext: {
      * Services contained in the provided context are removed from the sink's
      * service requirements.
      *
-     * @category services
+     * @category providing services
      * @since 2.0.0
      */
     <Provided>(context: Context.Context<Provided>): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E, Exclude<R, Provided>>;
@@ -1535,7 +1545,7 @@ export declare const provideContext: {
      * Services contained in the provided context are removed from the sink's
      * service requirements.
      *
-     * @category services
+     * @category providing services
      * @since 2.0.0
      */
     <A, In, L, E, R, Provided>(self: Sink<A, In, L, E, R>, context: Context.Context<Provided>): Sink<A, In, L, E, Exclude<R, Provided>>;
@@ -1548,7 +1558,7 @@ export declare const provideContext: {
  * The service identified by `key` is removed from the sink's service
  * requirements.
  *
- * @category services
+ * @category providing services
  * @since 4.0.0
  */
 export declare const provideService: {
@@ -1560,7 +1570,7 @@ export declare const provideService: {
      * The service identified by `key` is removed from the sink's service
      * requirements.
      *
-     * @category services
+     * @category providing services
      * @since 4.0.0
      */
     <I, S>(key: Context.Key<I, S>, value: Types.NoInfer<S>): <A, In, L, E, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E, Exclude<R, I>>;
@@ -1572,7 +1582,7 @@ export declare const provideService: {
      * The service identified by `key` is removed from the sink's service
      * requirements.
      *
-     * @category services
+     * @category providing services
      * @since 4.0.0
      */
     <A, In, L, E, R, I, S>(self: Sink<A, In, L, E, R>, key: Context.Key<I, S>, value: Types.NoInfer<S>): Sink<A, In, L, E, Exclude<R, I>>;
@@ -1709,7 +1719,7 @@ catch_ as catch };
  * The effect receives the sink's `Exit` for the result value. The original
  * sink result and leftovers are preserved unless the finalizer itself fails.
  *
- * @category Finalization
+ * @category resource management
  * @since 4.0.0
  */
 export declare const onExit: {
@@ -1721,7 +1731,7 @@ export declare const onExit: {
      * The effect receives the sink's `Exit` for the result value. The original
      * sink result and leftovers are preserved unless the finalizer itself fails.
      *
-     * @category Finalization
+     * @category resource management
      * @since 4.0.0
      */
     <A, E, X, E2, R2>(f: (exit: Exit.Exit<A, E>) => Effect.Effect<X, E2, R2>): <In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E | E2, R2 | R>;
@@ -1733,7 +1743,7 @@ export declare const onExit: {
      * The effect receives the sink's `Exit` for the result value. The original
      * sink result and leftovers are preserved unless the finalizer itself fails.
      *
-     * @category Finalization
+     * @category resource management
      * @since 4.0.0
      */
     <A, In, L, E, R, X, E2, R2>(self: Sink<A, In, L, E, R>, f: (exit: Exit.Exit<A, E>) => Effect.Effect<X, E2, R2>): Sink<A, In, L, E | E2, R | R2>;
@@ -1746,7 +1756,7 @@ export declare const onExit: {
  * The original sink result and leftovers are preserved unless the finalizer
  * itself fails.
  *
- * @category Finalization
+ * @category resource management
  * @since 2.0.0
  */
 export declare const ensuring: {
@@ -1758,7 +1768,7 @@ export declare const ensuring: {
      * The original sink result and leftovers are preserved unless the finalizer
      * itself fails.
      *
-     * @category Finalization
+     * @category resource management
      * @since 2.0.0
      */
     <X, E2, R2>(effect: Effect.Effect<X, E2, R2>): <A, E, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A, In, L, E | E2, R2 | R>;
@@ -1770,7 +1780,7 @@ export declare const ensuring: {
      * The original sink result and leftovers are preserved unless the finalizer
      * itself fails.
      *
-     * @category Finalization
+     * @category resource management
      * @since 2.0.0
      */
     <A, In, L, E, R, X, E2, R2>(self: Sink<A, In, L, E, R>, effect: Effect.Effect<X, E2, R2>): Sink<A, In, L, E | E2, R | R2>;