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

package/dist/Sink.d.ts

@@ -193,6 +193,12 @@ export declare const isSink: (u: unknown) => u is Sink<unknown, never, 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
  */
@@ -278,7 +284,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
@@ -495,6 +501,14 @@ export declare const ignoreLeftover: <A, In, L, E, R>(self: Sink<A, In, L, E, R>
 /**
  * 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
  */
@@ -503,6 +517,21 @@ export declare const drain: Sink<void, unknown>;
  * 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
  */
@@ -510,12 +539,20 @@ export declare const fold: <S, In, E = never, R = never>(s: LazyArg<S>, contFn:
 /**
  * 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
  */
@@ -536,6 +573,13 @@ export declare const foldUntil: <S, In, E = never, R = never>(s: LazyArg<S>, max
 /**
  * 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
  */
@@ -543,6 +587,13 @@ export declare const every: <In>(predicate: Predicate<In>) => Sink<boolean, 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
  */
@@ -550,6 +601,20 @@ export declare const some: <In>(predicate: Predicate<In>) => Sink<boolean, In, I
 /**
  * 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
  */
@@ -557,6 +622,20 @@ export declare 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
      */
@@ -564,6 +643,20 @@ export declare 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
      */
@@ -572,6 +665,13 @@ export declare 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
  */
@@ -579,6 +679,13 @@ export declare 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
      */
@@ -586,6 +693,13 @@ export declare 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
      */
@@ -759,6 +873,20 @@ export declare 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
  */
@@ -766,6 +894,20 @@ export declare 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
      */
@@ -773,6 +915,20 @@ export declare 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
      */
@@ -840,9 +996,18 @@ export declare 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
@@ -853,9 +1018,18 @@ export declare 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
@@ -866,9 +1040,18 @@ export declare 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
@@ -936,6 +1119,12 @@ export declare const reduceEffect: <S, In, E, R>(initial: LazyArg<S>, f: (s: S,
 /**
  * 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
  */
@@ -943,6 +1132,22 @@ export declare const head: <In>() => Sink<Option.Option<In>, In, In>;
 /**
  * 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
  */
@@ -950,6 +1155,20 @@ export declare const last: <In>() => Sink<Option.Option<In>, In>;
 /**
  * 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
  */
@@ -957,6 +1176,20 @@ export declare 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
      */
@@ -964,6 +1197,20 @@ export declare 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
      */
@@ -972,6 +1219,19 @@ export declare 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
  */
@@ -986,6 +1246,10 @@ export declare const sum: Sink<number, number>;
 /**
  * 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
  */
@@ -993,6 +1257,13 @@ export declare const count: Sink<number, unknown>;
 /**
  * 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
  */
@@ -1377,12 +1648,20 @@ export declare 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
  */
@@ -1390,12 +1669,20 @@ export declare 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
      */
@@ -1403,12 +1690,20 @@ export declare 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
      */
@@ -1422,6 +1717,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
  */