effect 4.0.0-beta.99 → 4.0.0-rc.109

package/src/Sink.ts

@@ -46,7 +46,7 @@ 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
@@ -54,10 +54,7 @@ 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
@@ -194,14 +191,14 @@ const SinkProto = {
  *
  * **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
@@ -217,6 +214,20 @@ export const isSink = (u: unknown): u is Sink<unknown, never, unknown, 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
@@ -239,6 +250,43 @@ export const fromChannel = <L, In, E, A, R>(
     ) as Effect.Effect<End<A, 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 const fromWritableStream = <A, E>(options: {
+  readonly evaluate: LazyArg<WritableStream<A>>
+  readonly onError: (error: unknown) => E
+  readonly closeOnDone?: boolean | undefined
+}): Sink<void, A, never, E> =>
+  fromChannel(
+    Channel.mapDone(
+      Channel.fromWritableStream<never, E, A>(options),
+      (_) => [_]
+    )
+  )
+
 /**
  * Creates a `Sink` from a low-level transform function.
  *
@@ -265,14 +313,16 @@ export const fromTransform = <In, A, E, R, L = never>(
 /**
  * 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
@@ -494,7 +544,7 @@ export const fromPubSub = <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
@@ -502,10 +552,7 @@ export const fromPubSub = <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
@@ -536,18 +583,15 @@ export const suspend = <A, In, L, E, R>(evaluate: LazyArg<Sink<A, In, L, E, R>>)
  *
  * **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
@@ -560,18 +604,15 @@ export const fail = <E>(e: E): Sink<never, unknown, never, E> => fromEffectEnd(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
@@ -585,18 +626,15 @@ export const failSync = <E>(evaluate: LazyArg<E>): Sink<never, unknown, never, E
  *
  * **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
@@ -610,18 +648,15 @@ export const failCause = <E>(cause: Cause.Cause<E>): Sink<never, unknown, never,
  *
  * **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
@@ -635,18 +670,15 @@ export const failCauseSync = <E>(evaluate: LazyArg<Cause.Cause<E>>): Sink<never,
  *
  * **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
@@ -1325,7 +1357,7 @@ export 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 const take = <In>(n: number): Sink<Array<In>, In, In> =>
@@ -1459,7 +1491,7 @@ export 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 const reduceWhile = <S, In>(
@@ -1495,7 +1527,7 @@ export const reduceWhile = <S, In>(
  * 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 const reduceWhileEffect = <S, In, E, R>(
@@ -1536,7 +1568,7 @@ export const reduceWhileEffect = <S, In, E, R>(
  * 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 const reduceWhileArray = <S, In>(
@@ -1551,11 +1583,9 @@ export const reduceWhileArray = <S, In>(
     }
     return upstream.pipe(
       Effect.flatMap((arr) => {
-        for (let i = 0; i < arr.length; i++) {
-          state = f(state, arr)
-          if (!contFn(state)) {
-            return Cause.done()
-          }
+        state = f(state, arr)
+        if (!contFn(state)) {
+          return Cause.done()
         }
         return Effect.void
       }),
@@ -1568,7 +1598,7 @@ export const reduceWhileArray = <S, In>(
  * 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 const reduceWhileArrayEffect = <S, In, E, R>(
@@ -1599,7 +1629,7 @@ export const reduceWhileArrayEffect = <S, In, E, R>(
  * 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 const reduce = <S, In>(initial: LazyArg<S>, f: (s: S, input: In) => S): Sink<S, In> =>
@@ -1614,7 +1644,7 @@ export const reduce = <S, In>(initial: LazyArg<S>, f: (s: S, input: In) => S): S
  * 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 const reduceArray = <S, In>(
@@ -1637,7 +1667,7 @@ export const reduceArray = <S, In>(
  * 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 const reduceEffect = <S, In, E, R>(
@@ -2079,21 +2109,16 @@ export const takeUntilEffect = <In, E, R>(
  *
  * **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
@@ -2109,22 +2134,16 @@ export const forEach = <In, X, E, R>(
  *
  * **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
@@ -2192,24 +2211,20 @@ export const forEachWhileArray = <In, E, R>(
  *
  * **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
@@ -2265,7 +2280,7 @@ export const summarized: {
 export const withDuration = <A, In, L, E, R>(
   self: Sink<A, In, L, E, R>
 ): Sink<[A, Duration.Duration], In, L, E, R> =>
-  summarized(self, Clock.currentTimeNanos, (start, end) => Duration.nanos(end - start))
+  summarized(self, Clock.monotonicTimeNanos, (start, end) => Duration.nanos(end - start))
 
 /**
  * A sink that drains all input and returns the elapsed duration.
@@ -2283,7 +2298,7 @@ export const timed: Sink<Duration.Duration, unknown> = map(withDuration(drain),
  * Services contained in the provided context are removed from the sink's
  * service requirements.
  *
- * @category services
+ * @category providing services
  * @since 2.0.0
  */
 export const provideContext: {
@@ -2295,7 +2310,7 @@ export 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>>
@@ -2307,7 +2322,7 @@ export 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>>
@@ -2329,7 +2344,7 @@ export 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 const provideService: {
@@ -2341,7 +2356,7 @@ export 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>>
@@ -2353,7 +2368,7 @@ export 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>(
@@ -2514,7 +2529,7 @@ export const catchCause: {
 const catch_: {
   <E, A2, E2, R2>(
     f: (error: Types.NoInfer<E>) => Effect.Effect<A2, E2, R2>
-  ): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In, L, E, R2 | R>
+  ): <A, In, L, R>(self: Sink<A, In, L, E, R>) => Sink<A2 | A, In, L, E2, R2 | R>
   <A, In, L, E, R, A2, E2, R2>(
     self: Sink<A, In, L, E, R>,
     f: (error: E) => Effect.Effect<A2, E2, R2>
@@ -2554,7 +2569,7 @@ export {
  * 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 const onExit: {
@@ -2566,7 +2581,7 @@ export 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>
@@ -2578,7 +2593,7 @@ export 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>(
@@ -2602,7 +2617,7 @@ export 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 const ensuring: {
@@ -2614,7 +2629,7 @@ export 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>
@@ -2626,7 +2641,7 @@ export 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>

package/src/Stdio.ts

@@ -57,12 +57,24 @@ export const TypeId: TypeId = "~effect/Stdio"
  * standard error, and a stream of standard input bytes. I/O operations can fail
  * with `PlatformError`.
  *
- * @category models
+ * @category services
  * @since 4.0.0
  */
 export interface Stdio {
   readonly [TypeId]: TypeId
   readonly args: Effect.Effect<ReadonlyArray<string>>
+  /**
+   * Whether standard input is attached to a terminal.
+   *
+   * @since 4.0.0
+   */
+  readonly stdinIsTerminal: Effect.Effect<boolean>
+  /**
+   * Whether standard output is attached to a terminal.
+   *
+   * @since 4.0.0
+   */
+  readonly stdoutIsTerminal: Effect.Effect<boolean>
   stdout(options?: {
     readonly endOnDone?: boolean | undefined
   }): Sink.Sink<void, string | Uint8Array, never, PlatformError>
@@ -98,16 +110,23 @@ export const Stdio: Context.Service<Stdio, Stdio> = Context.Service<Stdio>(TypeI
  *
  * **Details**
  *
- * The returned service reuses the supplied fields unchanged and only adds the
- * `Stdio` type identifier; it does not create a `Layer` or provide defaults.
+ * The returned service reuses the supplied fields unchanged and adds the
+ * `Stdio` type identifier. Omitted terminal-detection fields default to
+ * effects that succeed with `false`.
  *
  * @see {@link layerTest} for a test layer with default fields that can be overridden
  *
  * @category constructors
  * @since 4.0.0
  */
-export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
+export const make = (
+  options:
+    & Omit<Stdio, TypeId | "stdinIsTerminal" | "stdoutIsTerminal">
+    & Partial<Pick<Stdio, "stdinIsTerminal" | "stdoutIsTerminal">>
+): Stdio => ({
   [TypeId]: TypeId,
+  stdinIsTerminal: Effect.succeed(false),
+  stdoutIsTerminal: Effect.succeed(false),
   ...options
 })
 
@@ -123,7 +142,7 @@ export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
  *
  * Any provided fields override defaults. By default, arguments are empty,
  * standard output and error are draining sinks, and standard input is an empty
- * stream.
+ * stream, and terminal-detection effects succeed with `false`.
  *
  * @see {@link make} for constructing a `Stdio` service directly without a `Layer` or defaults
  *