effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Sink.ts

@@ -235,6 +235,12 @@ export const isSink = (u: unknown): u is Sink<unknown, never, unknown, unknown,
 /**
  * Creates a sink from a `Channel`.
  *
+ * **When to use**
+ *
+ * Use to create a `Sink` from a `Channel` that processes non-empty arrays of
+ * input values.
+ *
+ * @see {@link toChannel} for converting a `Sink` back to a `Channel`
  * @category constructors
  * @since 2.0.0
  */
@@ -442,7 +448,7 @@ export declare namespace make {
  *
  * **When to use**
  *
- * Use this when the effect needs to provide both the result value and optional
+ * Use when the effect needs to provide both the result value and optional
  * leftovers.
  *
  * @category constructors
@@ -697,6 +703,14 @@ export const ignoreLeftover = <A, In, L, E, R>(self: Sink<A, In, L, E, R>): Sink
 /**
  * Drains elements from the stream by ignoring all inputs.
  *
+ * **When to use**
+ *
+ * Use to consume all upstream input and complete with void when the input
+ * values and any aggregate result are not needed.
+ *
+ * @see {@link count} for consuming all input while returning the number of elements
+ * @see {@link forEach} for consuming all input while running an effect for each element
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -711,6 +725,21 @@ export const drain: Sink<void, unknown> = fromTransform((upstream) =>
  * A sink that folds its inputs with the provided function, termination
  * predicate and initial state.
  *
+ * **When to use**
+ *
+ * Use to accumulate stream input element by element with an effectful step and
+ * stop based on the accumulated state.
+ *
+ * **Details**
+ *
+ * The initial state is evaluated lazily. Each input element is folded with the
+ * effectful function, and the sink continues while `contFn` returns `true`. If
+ * the sink stops in the middle of a pulled array, the remaining elements from
+ * that array are returned as leftovers.
+ *
+ * @see {@link foldArray} for folding each pulled non-empty input array at once
+ * @see {@link foldUntil} for folding until a fixed maximum number of elements is consumed
+ *
  * @category folding
  * @since 2.0.0
  */
@@ -741,12 +770,20 @@ export const fold = <S, In, E = never, R = never>(
 /**
  * Folds non-empty input arrays into state with an effectful function.
  *
+ * **When to use**
+ *
+ * Use to update state with an effectful function once per pulled non-empty
+ * input array when batch-level processing is the natural unit.
+ *
  * **Details**
  *
  * The initial state is evaluated lazily. After each pulled array is folded,
  * the sink continues while `contFn` returns `true`; otherwise it completes
  * with the current state.
  *
+ * @see {@link fold} for folding element by element and returning leftovers when stopping mid-array
+ * @see {@link reduceWhileArrayEffect} for array-level effectful reducing that checks the predicate before consuming input
+ *
  * @category folding
  * @since 4.0.0
  */
@@ -797,6 +834,13 @@ export const foldUntil = <S, In, E = never, R = never>(
 /**
  * A sink that returns whether all elements satisfy the specified predicate.
  *
+ * **When to use**
+ *
+ * Use to reduce a stream to a boolean that is true only when every input
+ * satisfies a pure predicate.
+ *
+ * @see {@link some} for the dual any-match check
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -810,6 +854,13 @@ export const every = <In>(predicate: Predicate<In>): Sink<boolean, In, In> =>
 /**
  * A sink that returns whether an element satisfies the specified predicate.
  *
+ * **When to use**
+ *
+ * Use to reduce a stream to a boolean that is true when any input satisfies a
+ * pure predicate.
+ *
+ * @see {@link every} for the all-match check
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -823,6 +874,20 @@ export const some = <In>(predicate: Predicate<In>): Sink<boolean, In, In> =>
 /**
  * Transforms this sink's result.
  *
+ * **When to use**
+ *
+ * Use to compute a new result from the original sink result while preserving
+ * the sink's input consumption behavior.
+ *
+ * **Details**
+ *
+ * The transformed sink preserves the original sink's input type, leftovers,
+ * errors, and requirements.
+ *
+ * @see {@link mapEffect} for effectful result transformations
+ * @see {@link as} for replacing the result with a constant value
+ * @see {@link mapEnd} for transforming both the result and leftovers
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -830,6 +895,20 @@ export const map: {
   /**
    * Transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use to compute a new result from the original sink result while preserving
+   * the sink's input consumption behavior.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input type, leftovers,
+   * errors, and requirements.
+   *
+   * @see {@link mapEffect} for effectful result transformations
+   * @see {@link as} for replacing the result with a constant value
+   * @see {@link mapEnd} for transforming both the result and leftovers
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -837,6 +916,20 @@ export const map: {
   /**
    * Transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use to compute a new result from the original sink result while preserving
+   * the sink's input consumption behavior.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input type, leftovers,
+   * errors, and requirements.
+   *
+   * @see {@link mapEffect} for effectful result transformations
+   * @see {@link as} for replacing the result with a constant value
+   * @see {@link mapEnd} for transforming both the result and leftovers
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -850,6 +943,13 @@ export const map: {
 /**
  * Set the sink's result to a constant value.
  *
+ * **When to use**
+ *
+ * Use to keep a sink's input consumption, errors, requirements, and leftovers
+ * while replacing only its result with a known value.
+ *
+ * @see {@link map} for computing the replacement from the original result
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -857,6 +957,13 @@ export const as: {
   /**
    * Set the sink's result to a constant value.
    *
+   * **When to use**
+   *
+   * Use to keep a sink's input consumption, errors, requirements, and leftovers
+   * while replacing only its result with a known value.
+   *
+   * @see {@link map} for computing the replacement from the original result
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -864,6 +971,13 @@ export const as: {
   /**
    * Set the sink's result to a constant value.
    *
+   * **When to use**
+   *
+   * Use to keep a sink's input consumption, errors, requirements, and leftovers
+   * while replacing only its result with a known value.
+   *
+   * @see {@link map} for computing the replacement from the original result
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -1108,6 +1222,20 @@ export const mapEffectEnd: {
 /**
  * Effectfully transforms this sink's result.
  *
+ * **When to use**
+ *
+ * Use when transforming a sink result itself is effectful, can fail, or needs
+ * services.
+ *
+ * **Details**
+ *
+ * The transformed sink preserves the original sink's input consumption and
+ * leftovers while adding the errors and requirements of the transformation.
+ *
+ * @see {@link map} for pure result transformations
+ * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+ * @see {@link flatMap} for continuing with another sink based on the result
+ *
  * @category mapping
  * @since 2.0.0
  */
@@ -1115,6 +1243,20 @@ export const mapEffect: {
   /**
    * Effectfully transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use when transforming a sink result itself is effectful, can fail, or needs
+   * services.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input consumption and
+   * leftovers while adding the errors and requirements of the transformation.
+   *
+   * @see {@link map} for pure result transformations
+   * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+   * @see {@link flatMap} for continuing with another sink based on the result
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -1122,6 +1264,20 @@ export const mapEffect: {
   /**
    * Effectfully transforms this sink's result.
    *
+   * **When to use**
+   *
+   * Use when transforming a sink result itself is effectful, can fail, or needs
+   * services.
+   *
+   * **Details**
+   *
+   * The transformed sink preserves the original sink's input consumption and
+   * leftovers while adding the errors and requirements of the transformation.
+   *
+   * @see {@link map} for pure result transformations
+   * @see {@link mapEffectEnd} for effectfully transforming both the result and leftovers
+   * @see {@link flatMap} for continuing with another sink based on the result
+   *
    * @category mapping
    * @since 2.0.0
    */
@@ -1232,9 +1388,18 @@ export const take = <In>(n: number): Sink<Array<In>, In, In> =>
  * another sink from the provided function which will continue to run until it
  * yields a result.
  *
+ * **When to use**
+ *
+ * Use to compose sinks when the next sink depends on the result produced by the
+ * previous sink.
+ *
  * **Details**
  *
- * This function essentially runs sinks in sequence.
+ * Leftovers from the first sink are fed to the sink returned by `f` before more
+ * upstream input is pulled.
+ *
+ * @see {@link map} for transforming the result without switching sinks
+ * @see {@link mapEffect} for effectfully transforming the result without switching sinks
  *
  * @category sequencing
  * @since 2.0.0
@@ -1245,9 +1410,18 @@ export const flatMap: {
    * another sink from the provided function which will continue to run until it
    * yields a result.
    *
+   * **When to use**
+   *
+   * Use to compose sinks when the next sink depends on the result produced by the
+   * previous sink.
+   *
    * **Details**
    *
-   * This function essentially runs sinks in sequence.
+   * Leftovers from the first sink are fed to the sink returned by `f` before more
+   * upstream input is pulled.
+   *
+   * @see {@link map} for transforming the result without switching sinks
+   * @see {@link mapEffect} for effectfully transforming the result without switching sinks
    *
    * @category sequencing
    * @since 2.0.0
@@ -1258,9 +1432,18 @@ export const flatMap: {
    * another sink from the provided function which will continue to run until it
    * yields a result.
    *
+   * **When to use**
+   *
+   * Use to compose sinks when the next sink depends on the result produced by the
+   * previous sink.
+   *
    * **Details**
    *
-   * This function essentially runs sinks in sequence.
+   * Leftovers from the first sink are fed to the sink returned by `f` before more
+   * upstream input is pulled.
+   *
+   * @see {@link map} for transforming the result without switching sinks
+   * @see {@link mapEffect} for effectfully transforming the result without switching sinks
    *
    * @category sequencing
    * @since 2.0.0
@@ -1492,6 +1675,12 @@ const head_ = reduceWhile(Option.none<unknown>, Option.isNone, (_, in_) => Optio
 /**
  * Creates a sink containing the first value.
  *
+ * **Details**
+ *
+ * Returns `Option.some(first)` for non-empty input, or `Option.none` when the
+ * upstream ends without input. The first element is consumed; later elements
+ * from the same pulled array are emitted as leftovers.
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1502,6 +1691,22 @@ const last_ = reduceArray(Option.none<unknown>, (_, arr) => Arr.last(arr))
 /**
  * Creates a sink containing the last value.
  *
+ * **When to use**
+ *
+ * Use when consuming all upstream input and only the final element is needed.
+ *
+ * **Details**
+ *
+ * Returns `Option.some(last)` with the final input value, or `Option.none` when
+ * the upstream ends without input.
+ *
+ * **Gotchas**
+ *
+ * This sink produces a result only when the upstream ends, so it does not
+ * complete for a stream that does not end.
+ *
+ * @see {@link head} for taking the first input value instead
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1510,6 +1715,20 @@ export const last = <In>(): Sink<Option.Option<In>, In> => last_ as any
 /**
  * Creates a sink containing the first matching value.
  *
+ * **When to use**
+ *
+ * Use to scan stream input until the first matching element is found and return
+ * that element as an `Option`.
+ *
+ * **Details**
+ *
+ * Returns `Option.none` if the upstream stream ends before a match is found.
+ * Refinement predicates narrow the returned value type. The matching input is
+ * consumed; any later elements from the same pulled array are returned as
+ * leftovers.
+ *
+ * @see {@link findEffect} for an effectful predicate that can fail or require services
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -1517,6 +1736,20 @@ export const find: {
   /**
    * Creates a sink containing the first matching value.
    *
+   * **When to use**
+   *
+   * Use to scan stream input until the first matching element is found and return
+   * that element as an `Option`.
+   *
+   * **Details**
+   *
+   * Returns `Option.none` if the upstream stream ends before a match is found.
+   * Refinement predicates narrow the returned value type. The matching input is
+   * consumed; any later elements from the same pulled array are returned as
+   * leftovers.
+   *
+   * @see {@link findEffect} for an effectful predicate that can fail or require services
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -1524,6 +1757,20 @@ export const find: {
   /**
    * Creates a sink containing the first matching value.
    *
+   * **When to use**
+   *
+   * Use to scan stream input until the first matching element is found and return
+   * that element as an `Option`.
+   *
+   * **Details**
+   *
+   * Returns `Option.none` if the upstream stream ends before a match is found.
+   * Refinement predicates narrow the returned value type. The matching input is
+   * consumed; any later elements from the same pulled array are returned as
+   * leftovers.
+   *
+   * @see {@link findEffect} for an effectful predicate that can fail or require services
+   *
    * @category constructors
    * @since 4.0.0
    */
@@ -1538,6 +1785,19 @@ export const find: {
 /**
  * Creates a sink containing the first matching value.
  *
+ * **When to use**
+ *
+ * Use when deciding whether an input matches requires an effect, can fail, or
+ * needs services.
+ *
+ * **Details**
+ *
+ * Returns `Option.some` with the first input whose predicate result is `true`,
+ * or `Option.none` if the upstream stream ends first. If the predicate effect
+ * fails, the sink fails with the same error.
+ *
+ * @see {@link find} for the synchronous predicate variant
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1566,6 +1826,10 @@ export const sum: Sink<number, number> = reduceArray(() => 0, (s, arr) => {
 /**
  * A sink that counts the number of elements fed to it.
  *
+ * **When to use**
+ *
+ * Use to consume input and return only the number of elements received.
+ *
  * @category constructors
  * @since 2.0.0
  */
@@ -1574,6 +1838,13 @@ export const count: Sink<number, unknown> = reduceArray(() => 0, (s, arr) => s +
 /**
  * Accumulates incoming elements into an array.
  *
+ * **When to use**
+ *
+ * Use to collect all upstream input elements into a single array when you need
+ * a sink result containing the complete input.
+ *
+ * @see {@link take} for collecting only a fixed number of input elements
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -2196,12 +2467,20 @@ export const orElse: {
 /**
  * Handles failures from this sink by inspecting the full `Cause`.
  *
+ * **When to use**
+ *
+ * Use to recover from a sink failure based on the full `Cause` instead of only
+ * the typed error value.
+ *
  * **Details**
  *
  * When this sink fails, the handler effect is run and its success value
  * becomes the sink result. If the handler fails, the returned sink fails with
  * that error.
  *
+ * @see {@link catch_ catch} for recovering from typed errors only
+ * @see {@link orElse} for recovering by switching to another sink
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2209,12 +2488,20 @@ export const catchCause: {
   /**
    * Handles failures from this sink by inspecting the full `Cause`.
    *
+   * **When to use**
+   *
+   * Use to recover from a sink failure based on the full `Cause` instead of only
+   * the typed error value.
+   *
    * **Details**
    *
    * When this sink fails, the handler effect is run and its success value
    * becomes the sink result. If the handler fails, the returned sink fails with
    * that error.
    *
+   * @see {@link catch_ catch} for recovering from typed errors only
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -2222,12 +2509,20 @@ export const catchCause: {
   /**
    * Handles failures from this sink by inspecting the full `Cause`.
    *
+   * **When to use**
+   *
+   * Use to recover from a sink failure based on the full `Cause` instead of only
+   * the typed error value.
+   *
    * **Details**
    *
    * When this sink fails, the handler effect is run and its success value
    * becomes the sink result. If the handler fails, the returned sink fails with
    * that error.
    *
+   * @see {@link catch_ catch} for recovering from typed errors only
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */
@@ -2265,6 +2560,14 @@ export {
   /**
    * Handles typed errors from this sink with an effectful fallback value.
    *
+   * **When to use**
+   *
+   * Use to recover from a typed sink failure by producing the replacement
+   * result with an `Effect`.
+   *
+   * @see {@link catchCause} for recovering from the full failure cause
+   * @see {@link orElse} for recovering by switching to another sink
+   *
    * @category error handling
    * @since 4.0.0
    */

package/src/Stdio.ts

@@ -1,19 +1,32 @@
 /**
- * The `Stdio` module defines the service interface used by Effect programs to
- * interact with process standard I/O. It models command-line arguments,
- * standard output, standard error, and standard input as Effects, Sinks, and
- * Streams so programs can depend on console I/O through `Context` instead of
- * directly coupling to a specific runtime.
- *
- * Use this module when building command-line programs, tests, or platform
- * integrations that need to read bytes from stdin, write text or bytes to
- * stdout/stderr, or provide deterministic replacements for those capabilities.
- * The `layerTest` helper is useful for tests because it supplies inert defaults
- * and lets individual fields be overridden.
- *
- * Standard I/O operations are platform capabilities and may fail with
- * `PlatformError`; handle those failures in the Effect error channel rather than
- * assuming writes or reads are infallible.
+ * Service contract for process standard input, output, error output, and
+ * command-line arguments.
+ *
+ * `Stdio` lets command-line programs depend on standard I/O through the Effect
+ * environment instead of reading from or writing to global process handles
+ * directly. The service exposes arguments as an `Effect`, stdout and stderr as
+ * `Sink`s that accept strings or bytes, and stdin as a byte `Stream`.
+ *
+ * **Mental model**
+ *
+ * Application code describes what it needs from standard I/O, and a runtime
+ * layer supplies the concrete streams. Platform packages provide real process
+ * implementations, while tests can use `Stdio.layerTest` to replace only the
+ * fields that matter for a scenario and keep the rest inert.
+ *
+ * **Common tasks**
+ *
+ * - Read command-line arguments from the service's `args` effect.
+ * - Write text or bytes by running values into the service's `stdout()` or
+ *   `stderr()` sinks.
+ * - Consume `stdin` as a stream of `Uint8Array` chunks.
+ * - Build deterministic tests with `Stdio.layerTest`.
+ *
+ * **Gotchas**
+ *
+ * Standard I/O is a platform capability. Reads and writes can fail with
+ * `PlatformError`, so handle failures in the Effect error channel instead of
+ * assuming the process streams are always available.
  *
  * @since 4.0.0
  */
@@ -27,6 +40,10 @@ import * as Stream from "./Stream.ts"
 /**
  * String literal type used as the unique brand for the `Stdio` service.
  *
+ * **When to use**
+ *
+ * Use to type the runtime identifier stored on `Stdio` service implementations.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -35,6 +52,10 @@ export type TypeId = "~effect/Stdio"
 /**
  * Runtime identifier stored on `Stdio` service implementations.
  *
+ * **When to use**
+ *
+ * Use to mark and recognize concrete `Stdio` service values at runtime.
+ *
  * @category type IDs
  * @since 4.0.0
  */
@@ -43,6 +64,11 @@ export const TypeId: TypeId = "~effect/Stdio"
 /**
  * Service interface for process standard I/O.
  *
+ * **When to use**
+ *
+ * Use to depend on command-line arguments and standard I/O through the Effect
+ * environment.
+ *
  * **Details**
  *
  * The service provides command-line arguments, sinks for standard output and
@@ -66,6 +92,14 @@ export interface Stdio {
 /**
  * Context service tag for the `Stdio` service.
  *
+ * **When to use**
+ *
+ * Use when an effect needs command-line arguments or standard I/O streams
+ * supplied by its environment.
+ *
+ * @see {@link make} for constructing a `Stdio` service directly
+ * @see {@link layerTest} for a test layer with defaults and overrides
+ *
  * @category services
  * @since 4.0.0
  */
@@ -75,6 +109,19 @@ export const Stdio: Context.Service<Stdio, Stdio> = Context.Service<Stdio>(TypeI
  * Creates a `Stdio` service implementation from the provided fields and
  * attaches the `Stdio` type identifier.
  *
+ * **When to use**
+ *
+ * Use to assemble a concrete `Stdio` service when you already have
+ * implementations for command-line arguments, standard output, standard error,
+ * and standard input.
+ *
+ * **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.
+ *
+ * @see {@link layerTest} for a test layer with default fields that can be overridden
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -86,12 +133,19 @@ export const make = (options: Omit<Stdio, TypeId>): Stdio => ({
 /**
  * Creates a test layer for `Stdio`.
  *
+ * **When to use**
+ *
+ * Use to provide deterministic standard I/O in tests while overriding only the
+ * command-line arguments, input stream, or output sinks relevant to the case.
+ *
  * **Details**
  *
  * Any provided fields override defaults. By default, arguments are empty,
  * standard output and error are draining sinks, and standard input is an empty
  * stream.
  *
+ * @see {@link make} for constructing a `Stdio` service directly without a `Layer` or defaults
+ *
  * @category layers
  * @since 4.0.0
  */