@fncts/io 0.0.10 → 0.0.11

package/Sink/api.d.ts

@@ -18,90 +18,116 @@ import { Ref } from "@fncts/io/Ref";
 import { Duration } from "@fncts/base/data/Duration";
 import { MergeDecision } from "../Channel/internal/MergeDecision.js";
 /**
+ * Like {@link zip }, but keeps only the result from this sink
  * @tsplus fluent fncts.io.Sink apFirst
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function apFirst<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, Z>;
 /**
+ * Like {@link zipC }, but keeps only the result from this sink
  * @tsplus fluent fncts.io.Sink apFirstC
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function apFirstC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, Z>;
 /**
+ * Like {@link zip }, but keeps only the result from the `that` sink
  * @tsplus fluent fncts.io.Sink apSecond
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function apSecond<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, Z1>;
+export declare function apSecond<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z1>;
 /**
+ * Like {@link zipC }, but keeps only the result from the `that` sink
  * @tsplus fluent fncts.io.Sink apSecondC
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function apSecondC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, Z1>;
+export declare function apSecondC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z1>;
 /**
+ * Replaces this sink's result with the provided value.
  * @tsplus fluent fncts.io.Sink as
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function as<R, E, In, L, Z, Z1>(self: Sink<R, E, In, L, Z>, z: Lazy<Z1>): Sink<R, E, In, L, Z1>;
+export declare function as<R, E, In, L, Z, Z1>(self: Sink<R, E, In, L, Z>, z: Lazy<Z1>, __tsplusTrace?: string): Sink<R, E, In, L, Z1>;
 /**
+ * Repeatedly runs the sink and accumulates its results into a chunk
  * @tsplus fluent fncts.io.Sink collectAll
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function collectAll<R, E, In extends L, L, Z>(self: Sink<R, E, In, L, Z>, __tsplusTrace?: string): Sink<R, E, In, L, Conc<Z>>;
 /**
+ * Repeatedly runs the sink for as long as its results satisfy the predicate
+ * `p`. The sink's results will be accumulated using the stepping function
+ * `f`.
  * @tsplus fluent fncts.io.Sink collectAllWhileWith
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function collectAllWhileWith<R, E, In extends L, L, Z, S>(self: Sink<R, E, In, L, Z>, z: Lazy<S>, p: Predicate<Z>, f: (s: S, z: Z) => S, __tsplusTrace?: string): Sink<R, E, In, L, S>;
 /**
+ * Collects the leftovers from the stream when the sink succeeds and returns
+ * them as part of the sink's result
  * @tsplus getter fncts.io.Sink collectLeftover
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function collectLeftover<R, E, In, L, Z>(self: Sink<R, E, In, L, Z>, __tsplusTrace?: string): Sink<R, E, In, never, readonly [Z, Conc<L>]>;
 /**
+ * Transforms this sink's input elements.
  * @tsplus fluent fncts.io.Sink contramap
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function contramap<R, E, In, L, Z, In1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => In): Sink<R, E, In1, L, Z>;
+export declare function contramap<R, E, In, L, Z, In1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => In, __tsplusTrace?: string): Sink<R, E, In1, L, Z>;
 /**
+ * Transforms this sink's input chunks. `f` must preserve chunking-invariance
  * @tsplus fluent fncts.io.Sink contramapChunks
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function contramapChunks<R, E, In, L, Z, In1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => Conc<In>): Sink<R, E, In1, L, Z>;
+export declare function contramapChunks<R, E, In, L, Z, In1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => Conc<In>, __tsplusTrace?: string): Sink<R, E, In1, L, Z>;
 /**
+ * Effectfully transforms this sink's input chunks. `f` must preserve
+ * chunking-invariance
  * @tsplus fluent fncts.io.Sink contramapChunksIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function contramapChunksIO<R, E, In, L, Z, R1, E1, In1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => IO<R1, E1, Conc<In>>): Sink<R & R1, E | E1, In1, L, Z>;
+export declare function contramapChunksIO<R, E, In, L, Z, R1, E1, In1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => IO<R1, E1, Conc<In>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In1, L, Z>;
 /**
+ * Effectfully transforms this sink's input elements.
  * @tsplus fluent fncts.io.Sink contramapIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function contramapIO<R, E, In, L, Z, R1, E1, In1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => IO<R1, E1, In>): Sink<R & R1, E | E1, In1, L, Z>;
+export declare function contramapIO<R, E, In, L, Z, R1, E1, In1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => IO<R1, E1, In>, __tsplusTrace?: string): Sink<R & R1, E | E1, In1, L, Z>;
 /**
+ * Transforms both inputs and result of this sink using the provided
+ * functions.
  * @tsplus fluent fncts.io.Sink dimap
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function dimap<R, E, In, L, Z, In1, Z1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => In, g: (z: Z) => Z1): Sink<R, E, In1, L, Z1>;
+export declare function dimap<R, E, In, L, Z, In1, Z1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => In, g: (z: Z) => Z1, __tsplusTrace?: string): Sink<R, E, In1, L, Z1>;
 /**
+ * Transforms both input chunks and result of this sink using the provided
+ * functions.
  * @tsplus fluent fncts.io.Sink dimapChunks
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function dimapChunks<R, E, In, L, Z, In1, Z1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => Conc<In>, g: (z: Z) => Z1): Sink<R, E, In1, L, Z1>;
+export declare function dimapChunks<R, E, In, L, Z, In1, Z1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => Conc<In>, g: (z: Z) => Z1, __tsplusTrace?: string): Sink<R, E, In1, L, Z1>;
 /**
+ * Effectfully transforms both input chunks and result of this sink using the
+ * provided functions. `f` and `g` must preserve chunking-invariance
  * @tsplus fluent fncts.io.Sink dimapChunksIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function dimapChunksIO<R, E, In, L, Z, R1, E1, In1, R2, E2, Z1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => IO<R1, E1, Conc<In>>, g: (z: Z) => IO<R2, E2, Z1>): Sink<R & R1 & R2, E | E1 | E2, In1, L, Z1>;
+export declare function dimapChunksIO<R, E, In, L, Z, R1, E1, In1, R2, E2, Z1>(self: Sink<R, E, In, L, Z>, f: (chunk: Conc<In1>) => IO<R1, E1, Conc<In>>, g: (z: Z) => IO<R2, E2, Z1>, __tsplusTrace?: string): Sink<R & R1 & R2, E | E1 | E2, In1, L, Z1>;
 /**
+ * Effectfully transforms both inputs and result of this sink using the
+ * provided functions.
  * @tsplus fluent fncts.io.Sink dimapIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function dimapIO<R, E, In, L, Z, R1, E1, In1, R2, E2, Z1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => IO<R1, E1, In>, g: (z: Z) => IO<R2, E2, Z1>): Sink<R & R1 & R2, E | E1 | E2, In1, L, Z1>;
+export declare function dimapIO<R, E, In, L, Z, R1, E1, In1, R2, E2, Z1>(self: Sink<R, E, In, L, Z>, f: (inp: In1) => IO<R1, E1, In>, g: (z: Z) => IO<R2, E2, Z1>, __tsplusTrace?: string): Sink<R & R1 & R2, E | E1 | E2, In1, L, Z1>;
 /**
+ * Returns a lazily constructed sink that may require effects for its
+ * creation.
  * @tsplus static fncts.io.SinkOps defer
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function defer<R, E, In, L, Z>(sink: Lazy<Sink<R, E, In, L, Z>>): Sink<R, E, In, L, Z>;
+export declare function defer<R, E, In, L, Z>(sink: Lazy<Sink<R, E, In, L, Z>>, __tsplusTrace?: string): Sink<R, E, In, L, Z>;
 /**
  * A sink that ignores all of its inputs.
  * @tsplus static fncts.io.SinkOps drain
@@ -109,137 +135,190 @@ export declare function defer<R, E, In, L, Z>(sink: Lazy<Sink<R, E, In, L, Z>>):
  */
 export declare const drain: Sink<unknown, never, unknown, never, void>;
 /**
+ * Drops incoming elements until the predicate `p` is satisfied.
+ * @tsplus static fncts.io.SinkOps dropUntil
+ * @tsplus location "@fncts/io/Sink/api"
+ */
+export declare function makeDropUntil<In>(p: Predicate<In>, __tsplusTrace?: string): Sink<unknown, never, In, In, void>;
+/**
+ * Drops incoming elements until the effectful predicate `p` is satisfied.
+ * @tsplus static fncts.io.SinkOps dropUntilIO
+ * @tsplus location "@fncts/io/Sink/api"
+ */
+export declare function makeDropUntilIO<R, E, In>(p: (inp: In) => IO<R, E, boolean>, __tsplusTrace?: string): Sink<R, E, In, In, void>;
+/**
+ * Drops incoming elements as long as the predicate `p` is satisfied.
  * @tsplus static fncts.io.SinkOps dropWhile
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function dropWhile<Err, In>(predicate: Predicate<In>): Sink<unknown, never, In, In, any>;
+export declare function makeDropWhile<Err, In>(predicate: Predicate<In>, __tsplusTrace?: string): Sink<unknown, never, In, In, any>;
 /**
+ * Drops incoming elements as long as the effectful predicate `p` is
+ * satisfied.
+ * @tsplus static fncts.io.SinkOps dropWhileIO
+ * @tsplus location "@fncts/io/Sink/api"
+ */
+export declare function dropWhileIO<R, E, In>(p: (inp: In) => IO<R, E, boolean>, __tsplusTrace?: string): Sink<R, E, In, In, void>;
+/**
+ * Accesses the whole environment of the sink.
  * @tsplus static fncts.io.SinkOps environment
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function environment<R>(__tsplusTrace?: string): Sink<R, never, unknown, never, Environment<R>>;
 /**
+ * Accesses the environment of the sink.
  * @tsplus static fncts.io.SinkOps environmentWith
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function environmentWith<R, Z>(f: (r: Environment<R>) => Z, __tsplusTrace?: string): Sink<R, never, unknown, never, Z>;
 /**
+ * Accesses the environment of the sink in the context of an effect.
  * @tsplus static fncts.io.SinkOps environmentWithIO
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function environmentWithIO<R, R1, E, Z>(f: (r: Environment<R>) => IO<R1, E, Z>, __tsplusTrace?: string): Sink<R & R1, E, unknown, never, Z>;
 /**
+ * Accesses the environment of the sink in the context of a sink.
  * @tsplus static fncts.io.SinkOps environmentWithSink
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function environmentWithSink<R, R1, E, In, L, Z>(f: (r: Environment<R>) => Sink<R1, E, In, L, Z>, __tsplusTrace?: string): Sink<R & R1, E, In, L, Z>;
 /**
+ * A sink that always fails with the specified error.
  * @tsplus static fncts.io.SinkOps fail
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fail<E>(e: Lazy<E>): Sink<unknown, E, unknown, never, never>;
+export declare function fail<E>(e: Lazy<E>, __tsplusTrace?: string): Sink<unknown, E, unknown, never, never>;
 /**
+ * Creates a sink halting with a specified cause.
  * @tsplus static fncts.io.SinkOps failCause
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function failCause<E>(cause: Lazy<Cause<E>>, __tsplusTrace?: string): Sink<unknown, E, unknown, never, never>;
 /**
+ * Creates a sink halting with a specified cause.
  * @tsplus static fncts.io.SinkOps failCauseNow
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function failCauseNow<E>(cause: Cause<E>, __tsplusTrace?: string): Sink<unknown, E, unknown, never, never>;
 /**
+ * A sink that always fails with the specified error.
  * @tsplus static fncts.io.SinkOps failNow
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function failNow<E>(e: E, __tsplusTrace?: string): Sink<unknown, E, unknown, never, never>;
 /**
+ * Filters the sink's input with the given predicate
  * @tsplus static fncts.io.SinkOps filterInput
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function filterInput<R, E, In, L, Z>(self: Sink<R, E, In, L, Z>, p: Predicate<In>, __tsplusTrace?: string): Sink<R, E, In, L, Z>;
 /**
+ * Filters the sink's input with the given IO predicate
  * @tsplus static fncts.io.SinkOps filterInputIO
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function filterInputIO<R, E, In, L, Z, R1, E1>(self: Sink<R, E, In, L, Z>, p: (inp: In) => IO<R1, E1, boolean>, __tsplusTrace?: string): Sink<R & R1, E | E1, In, L, Z>;
 /**
+ * Creates a sink that produces values until one verifies the predicate `f`.
  * @tsplus fluent fncts.io.Sink findIO
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function findIO<R, E, In extends L, L, Z, R1, E1>(self: Sink<R, E, In, L, Z>, f: (z: Z) => IO<R1, E1, boolean>, __tsplusTrace?: string): Sink<R & R1, E | E1, In, L, Maybe<Z>>;
 /**
+ * Runs this sink until it yields a result, then uses that result to create
+ * another sink from the provided function which will continue to run until it
+ * yields a result.
+ *
+ * This function essentially runs sinks in sequence.
  * @tsplus fluent fncts.io.Sink flatMap
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function flatMap<R, E, In, L, Z, R1, E1, In1 extends In, L1, Z1>(self: Sink<R, E, In, L, Z>, f: (z: Z) => Sink<R1, E1, In1, L1, Z1>, __tsplusTrace?: string): Sink<R & R1, E | E1, In1, L | L1, Z1>;
 /**
+ * Creates a sink from a {@link Channel }
  * @tsplus static fncts.io.SinkOps fromChannel
  * @tsplus static fncts.io.SinkOps __call
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function fromChannel<R, E, In, L, Z>(channel: Channel<R, never, Conc<In>, unknown, E, Conc<L>, Z>): Sink<R, E, In, L, Z>;
 /**
+ * Creates a sink from a chunk processing function.
  * @tsplus static fncts.io.SinkOps fromPush
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function fromPush<R, E, In, L, Z, R1>(push: IO<Has<Scope> & R, never, (_: Maybe<Conc<In>>) => IO<R1, readonly [Either<E, Z>, Conc<L>], void>>, __tsplusTrace?: string): Sink<R & R1, E, In, L, Z>;
 /**
+ * Create a sink which enqueues each element into the specified queue.
  * @tsplus static fncts.io.SinkOps fromQueue
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fromQueue<In>(queue: Lazy<Queue.Enqueue<In>>): Sink<unknown, never, In, never, void>;
+export declare function fromQueue<In>(queue: Lazy<Queue.Enqueue<In>>, __tsplusTrace?: string): Sink<unknown, never, In, never, void>;
 /**
+ * Create a sink which enqueues each element into the specified queue. The
+ * queue will be shutdown once the stream is closed.
  * @tsplus static fncts.io.SinkOps fromQueueWithShutdown
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fromQueueWithShutdown<In>(queue: Lazy<Queue.Enqueue<In>>): Sink<unknown, never, In, never, void>;
+export declare function fromQueueWithShutdown<In>(queue: Lazy<Queue.Enqueue<In>>, __tsplusTrace?: string): Sink<unknown, never, In, never, void>;
 /**
+ * Create a sink which publishes each element to the specified hub.
  * @tsplus static fncts.io.SinkOps fromHub
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fromHub<In>(hub: Lazy<Hub<In>>): Sink<unknown, never, In, never, void>;
+export declare function fromHub<In>(hub: Lazy<Hub<In>>, __tsplusTrace?: string): Sink<unknown, never, In, never, void>;
 /**
+ * Create a sink which publishes each element to the specified hub. The hub
+ * will be shutdown once the stream is closed.
  * @tsplus static fncts.io.SinkOps fromHubWithShutdown
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fromHubWithShutdown<In>(hub: Lazy<Hub<In>>): Sink<unknown, never, In, never, void>;
+export declare function fromHubWithShutdown<In>(hub: Lazy<Hub<In>>, __tsplusTrace?: string): Sink<unknown, never, In, never, void>;
 /**
+ * Creates a single-value sink produced from an effect
  * @tsplus static fncts.io.SinkOps fromIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function fromIO<R, E, Z>(b: Lazy<IO<R, E, Z>>): Sink<R, E, unknown, never, Z>;
+export declare function fromIO<R, E, Z>(b: Lazy<IO<R, E, Z>>, __tsplusTrace?: string): Sink<R, E, unknown, never, Z>;
 /**
+ * Creates a sink halting with the specified unchecked value.
  * @tsplus static fncts.io.SinkOps halt
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function halt(defect: Lazy<unknown>, __tsplusTrace?: string): Sink<unknown, never, unknown, never, never>;
 /**
+ * Creates a sink halting with the specified unchecked value.
  * @tsplus static fncts.io.SinkOps haltNow
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function haltNow(defect: unknown, __tsplusTrace?: string): Sink<unknown, never, unknown, never, never>;
 /**
+ * Creates a sink containing the first value.
  * @tsplus static fncts.io.SinkOps head
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function head<In>(__tsplusTrace?: string): Sink<unknown, never, In, In, Maybe<In>>;
 /**
+ * Drains the remaining elements from the stream after the sink finishes
  * @tsplus getter fncts.io.Sink ignoreLeftover
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function ignoreLeftover<R, E, In, L, Z>(self: Sink<R, E, In, L, Z>, __tsplusTrace?: string): Sink<R, E, In, never, Z>;
 /**
+ * Creates a sink containing the last value.
  * @tsplus static fncts.io.SinkOps last
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function last<In>(__tsplusTrace?: string): Sink<unknown, never, In, In, Maybe<In>>;
 /**
+ * Creates a sink that does not consume any input but provides the given chunk
+ * as its leftovers
  * @tsplus static fncts.io.SinkOps leftover
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function leftover<L>(c: Lazy<Conc<L>>, __tsplusTrace?: string): Sink<unknown, never, unknown, L, void>;
 /**
+ * Logs the specified message at the current log level.
  * @tsplus static fncts.io.SinkOps log
  * @tsplus location "@fncts/io/Sink/api"
  */
@@ -250,6 +329,12 @@ export declare function log(message: Lazy<string>, __tsplusTrace?: string): Sink
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeCollectAll<In>(): Sink<unknown, never, In, never, Conc<In>>;
+/**
+ * A sink that collects first `n` elements into a chunk. Note that the chunk
+ * is preallocated and must fit in memory.
+ * @tsplus static fncts.io.SinkOps collectAllN
+ * @tsplus location "@fncts/io/Sink/api"
+ */
 export declare function makeCollectAllN<In>(n: Lazy<number>): Sink<unknown, never, In, In, Conc<In>>;
 /**
  * A sink that executes the provided effectful function for every element fed to it.
@@ -258,6 +343,8 @@ export declare function makeCollectAllN<In>(n: Lazy<number>): Sink<unknown, neve
  */
 export declare function makeForeach<R, Err, In>(f: (inp: In) => IO<R, Err, any>, __tsplusTrace?: string): Sink<R, Err, In, In, void>;
 /**
+ * A sink that executes the provided effectful function for every chunk fed to
+ * it.
  * @tsplus static fncts.io.SinkOps foreachChunk
  * @tsplus location "@fncts/io/Sink/api"
  */
@@ -270,80 +357,146 @@ export declare function makeForeachChunk<R, E, In>(f: (inp: Conc<In>) => IO<R, E
  */
 export declare function makeForeachWhile<R, Err, In>(f: (_: In) => IO<R, Err, boolean>, __tsplusTrace?: string): Sink<R, Err, In, In, void>;
 /**
+ * A sink that executes the provided effectful function for every chunk fed to
+ * it until `f` evaluates to `false`.
  * @tsplus static fncts.io.SinkOps foreachChunkWhile
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeForeachChunkWhile<R, E, In>(f: (chunk: Conc<In>) => IO<R, E, boolean>, __tsplusTrace?: string): Sink<R, E, In, In, void>;
 /**
+ * A sink that folds its inputs with the provided function, termination
+ * predicate and initial state.
  * @tsplus static fncts.io.SinkOps fold
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeFold<In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: In) => S, __tsplusTrace?: string): Sink<unknown, never, In, In, S>;
 /**
+ * Creates a sink that folds elements of type `In` into a structure of type
+ * `S` until `max` elements have been folded.
+ *
+ * Like {@link foldWeighted }, but with a constant cost function of 1.
  * @tsplus static fncts.io.SinkOps foldUntil
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeFoldUntil<In, S>(z: Lazy<S>, max: Lazy<number>, f: (s: S, inp: In) => S, __tsplusTrace?: string): Sink<unknown, never, In, In, S>;
 /**
+ * A sink that folds its input chunks with the provided function, termination
+ * predicate and initial state. `contFn` condition is checked only for the
+ * initial value and at the end of processing of each chunk. `f` and `contFn`
+ * must preserve chunking-invariance.
  * @tsplus static fncts.io.SinkOps foldChunks
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldChunks<In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: Conc<In>) => S): Sink<unknown, never, In, never, S>;
+export declare function makeFoldChunks<In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: Conc<In>) => S, __tsplusTrace?: string): Sink<unknown, never, In, never, S>;
 /**
+ * A sink that effectfully folds its input chunks with the provided function,
+ * termination predicate and initial state. `contFn` condition is checked only
+ * for the initial value and at the end of processing of each chunk. `f` and
+ * `contFn` must preserve chunking-invariance.
  * @tsplus static fncts.io.SinkOps foldChunksIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldChunksIO<Env, Err, In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: Conc<In>) => IO<Env, Err, S>): Sink<Env, Err, In, In, S>;
+export declare function makeFoldChunksIO<Env, Err, In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: Conc<In>) => IO<Env, Err, S>, __tsplusTrace?: string): Sink<Env, Err, In, In, S>;
 /**
+ * A sink that folds its inputs with the provided function and initial state.
  * @tsplus static fncts.io.SinkOps foldLeft
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeFoldLeft<In, S>(z: Lazy<S>, f: (s: S, inp: In) => S): Sink<unknown, never, In, never, S>;
 /**
+ * A sink that folds its input chunks with the provided function and initial
+ * state. `f` must preserve chunking-invariance.
  * @tsplus static fncts.io.SinkOps foldLeftChunks
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeFoldLeftChunks<In, S>(z: Lazy<S>, f: (s: S, inp: Conc<In>) => S): Sink<unknown, never, In, never, S>;
 /**
+ * A sink that effectfully folds its input chunks with the provided function
+ * and initial state. `f` must preserve chunking-invariance.
  * @tsplus static fncts.io.SinkOps foldLeftChunksIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldLeftChunksIO<R, E, In, S>(z: Lazy<S>, f: (s: S, inp: Conc<In>) => IO<R, E, S>): Sink<R, E, In, In, S>;
+export declare function makeFoldLeftChunksIO<R, E, In, S>(z: Lazy<S>, f: (s: S, inp: Conc<In>) => IO<R, E, S>, __tsplusTrace?: string): Sink<R, E, In, In, S>;
 /**
+ * A sink that effectfully folds its inputs with the provided function and
+ * initial state.
  * @tsplus static fncts.io.SinkOps foldLeftIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldLeftIO<R, E, In, S>(z: Lazy<S>, f: (s: S, inp: In) => IO<R, E, S>): Sink<R, E, In, In, S>;
+export declare function makeFoldLeftIO<R, E, In, S>(z: Lazy<S>, f: (s: S, inp: In) => IO<R, E, S>, __tsplusTrace?: string): Sink<R, E, In, In, S>;
 /**
+ * A sink that effectfully folds its inputs with the provided function,
+ * termination predicate and initial state.
  * @tsplus static fncts.io.SinkOps foldIO
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function makeFoldIO<R, E, In, S>(z: Lazy<S>, contFn: Predicate<S>, f: (s: S, inp: In) => IO<R, E, S>): Sink<R, E, In, In, S>;
 /**
+ * Creates a sink that effectfully folds elements of type `In` into a
+ * structure of type `S` until `max` elements have been folded.
+ *
+ * Like {@link makeFoldWeightedIO }, but with a constant cost function of 1.
  * @tsplus static fncts.io.SinkOps foldUntilIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldUntilIO<R, E, In, S>(z: Lazy<S>, max: Lazy<number>, f: (s: S, inp: In) => IO<R, E, S>): Sink<R, E, In, In, S>;
+export declare function makeFoldUntilIO<R, E, In, S>(z: Lazy<S>, max: Lazy<number>, f: (s: S, inp: In) => IO<R, E, S>, __tsplusTrace?: string): Sink<R, E, In, In, S>;
 /**
+ * Creates a sink that folds elements of type `In` into a structure of type
+ * `S`, until `max` worth of elements (determined by the `costFn`) have been
+ * folded.
+ *
+ * The `decompose` function will be used for decomposing elements that cause
+ * an `S` aggregate to cross `max` into smaller elements.
+ *
+ *
+ * Be vigilant with this function, it has to generate "simpler" values or the
+ * fold may never end. A value is considered indivisible if `decompose` yields
+ * the empty chunk or a single-valued chunk. In these cases, there is no other
+ * choice than to yield a value that will cross the threshold.
+ *
+ * The {@link makeFoldWeightedDecomposeIO } allows the decompose function to return a
+ * `IO` value, and consequently it allows the sink to fail.
  * @tsplus static fncts.io.SinkOps foldWeightedDecompose
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldWeightedDecompose<In, S>(z: Lazy<S>, costFn: (s: S, inp: In) => number, max: Lazy<number>, decompose: (inp: In) => Conc<In>, f: (s: S, inp: In) => S): Sink<unknown, never, In, In, S>;
+export declare function makeFoldWeightedDecompose<In, S>(z: Lazy<S>, costFn: (s: S, inp: In) => number, max: Lazy<number>, decompose: (inp: In) => Conc<In>, f: (s: S, inp: In) => S, __tsplusTrace?: string): Sink<unknown, never, In, In, S>;
 /**
+ * Creates a sink that effectfully folds elements of type `In` into a
+ * structure of type `S`, until `max` worth of elements (determined by the
+ * `costFn`) have been folded.
+ *
+ * The `decompose` function will be used for decomposing elements that cause
+ * an `S` aggregate to cross `max` into smaller elements. Be vigilant with
+ * this function, it has to generate "simpler" values or the fold may never
+ * end. A value is considered indivisible if `decompose` yields the empty
+ * chunk or a single-valued chunk. In these cases, there is no other choice
+ * than to yield a value that will cross the threshold.
  * @tsplus static fncts.io.SinkOps foldWeightedDecomposeIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldWeightedDecomposeIO<R, E, In, S, R1, E1, R2, E2>(z: Lazy<S>, costFn: (s: S, inp: In) => IO<R1, E1, number>, max: Lazy<number>, decompose: (inp: In) => IO<R2, E2, Conc<In>>, f: (s: S, inp: In) => IO<R, E, S>): Sink<R & R1 & R2, E | E1 | E2, In, In, S>;
+export declare function makeFoldWeightedDecomposeIO<R, E, In, S, R1, E1, R2, E2>(z: Lazy<S>, costFn: (s: S, inp: In) => IO<R1, E1, number>, max: Lazy<number>, decompose: (inp: In) => IO<R2, E2, Conc<In>>, f: (s: S, inp: In) => IO<R, E, S>, __tsplusTrace?: string): Sink<R & R1 & R2, E | E1 | E2, In, In, S>;
 /**
+ * Creates a sink that folds elements of type `In` into a structure of type
+ * `S`, until `max` worth of elements (determined by the `costFn`) have been
+ * folded.
+ * @note   Elements that have an individual cost larger than `max` will force the
+  sink to cross the `max` cost. See {@link makeFoldWeightedDecompose } for a variant
+  that can handle these cases.
  * @tsplus static fncts.io.SinkOps foldWeighted
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldWeighted<In, S>(z: Lazy<S>, costFn: (s: S, inp: In) => number, max: Lazy<number>, f: (s: S, inp: In) => S): Sink<unknown, never, In, In, S>;
+export declare function makeFoldWeighted<In, S>(z: Lazy<S>, costFn: (s: S, inp: In) => number, max: Lazy<number>, f: (s: S, inp: In) => S, __tsplusTrace?: string): Sink<unknown, never, In, In, S>;
 /**
+ * Creates a sink that effectfully folds elements of type `In` into a
+ * structure of type `S`, until `max` worth of elements (determined by the
+ * `costFn`) have been folded.
+ * @note   Elements that have an individual cost larger than `max` will force the
+  sink to cross the `max` cost. See {@link makeFoldWeightedDecomposeIO } for a
+  variant that can handle these cases.
  * @tsplus static fncts.io.SinkOps foldWeightedIO
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function makeFoldWeightedIO<R, E, In, S, R1, E1>(z: Lazy<S>, costFn: (s: S, inp: In) => IO<R, E, number>, max: Lazy<number>, f: (s: S, inp: In) => IO<R1, E1, S>): Sink<R & R1, E | E1, In, In, S>;
+export declare function makeFoldWeightedIO<R, E, In, S, R1, E1>(z: Lazy<S>, costFn: (s: S, inp: In) => IO<R, E, number>, max: Lazy<number>, f: (s: S, inp: In) => IO<R1, E1, S>, __tsplusTrace?: string): Sink<R & R1, E | E1, In, In, S>;
 /**
  * Transforms this sink's result.
  * @tsplus fluent fncts.io.Sink map
@@ -373,69 +526,91 @@ export declare function mapIO_<R, E, In, L, Z, R1, E1, Z1>(self: Sink<R, E, In,
  */
 export declare function matchSink_<R, E, In, L, Z, R1, E1, In1 extends In, L1, Z1, R2, E2, In2 extends In, L2, Z2>(self: Sink<R, E, In, L, Z>, onFailure: (e: E) => Sink<R1, E1, In1, L1, Z1>, onSuccess: (z: Z) => Sink<R2, E2, In2, L2, Z2>, __tsplusTrace?: string): Sink<R & R1 & R2, E1 | E2, In1 & In2, L | L1 | L2, Z1 | Z2>;
 /**
+ * Switch to another sink in case of failure
  * @tsplus fluent fncts.io.Sink orElse
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function orElse<R, E, In, L, Z, R1, E1, In1, L1, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z | Z1>;
 /**
+ * Provides the sink with its required environment, which eliminates its
+ * dependency on `R`.
  * @tsplus fluent fncts.io.Sink provideEnvironment
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function provideEnvironment<R, E, In, L, Z>(self: Sink<R, E, In, L, Z>, r: Lazy<Environment<R>>, __tsplusTrace?: string): Sink<unknown, E, In, L, Z>;
 /**
+ * Runs both sinks in parallel on the input, returning the result or the
+ * error from the one that finishes first.
  * @tsplus fluent fncts.io.Sink race
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function race<R, E, In, L, Z, R1, E1, In1, L1, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, Z | Z1>;
+export declare function race<R, E, In, L, Z, R1, E1, In1, L1, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z | Z1>;
 /**
+ * Runs both sinks in parallel on the input, returning the result or the error
+ * from the one that finishes first.
  * @tsplus fluent fncts.io.Sink raceBoth
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function raceBoth<R, E, In, L, Z, R1, E1, In1, L1, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, capacity?: Lazy<number>): Sink<R & R1, E | E1, In & In1, L | L1, Either<Z, Z1>>;
+export declare function raceBoth<R, E, In, L, Z, R1, E1, In1, L1, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, capacity?: Lazy<number>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Either<Z, Z1>>;
 /**
+ * Runs both sinks in parallel on the input, using the specified merge
+ * function as soon as one result or the other has been computed.
  * @tsplus fluent fncts.io.Sink raceWith
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function raceWith<R, E, In, L, Z, R1, E1, In1, L1, Z1, R2, E2, Z2, R3, E3, Z3>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, leftDone: (exit: Exit<E, Z>) => MergeDecision<R1, E1, Z1, E2, Z2>, rightDone: (exit: Exit<E1, Z1>) => MergeDecision<R, E, Z, E3, Z3>, capacity?: Lazy<number>, __tsplusTrace?: string): Sink<R & R1 & R2 & R3, E2 | E3, In & In1, L | L1, Z2 | Z3>;
 /**
+ * Accesses the specified service in the environment of the effect.
  * @tsplus static fncts.io.SinkOps service
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function service<S>(/** @tsplus auto */ tag: Tag<S>): Sink<Has<S>, never, unknown, never, S>;
 /**
+ * Accesses the specified service in the environment of the sink.
  * @tsplus static fncts.io.SinkOps serviceWith
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function serviceWith<S, Z>(f: (service: S) => Z, 
 /** @tsplus auto */ tag: Tag<S>): Sink<Has<S>, never, unknown, never, Z>;
 /**
+ * Accesses the specified service in the environment of the sink in the
+ * context of an effect.
  * @tsplus static fncts.io.SinkOps serviceWithIO
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function serviceWithIO<S, R, E, Z>(f: (service: S) => IO<R, E, Z>, 
 /** @tsplus auto */ tag: Tag<S>): Sink<Has<S> & R, E, unknown, never, Z>;
 /**
+ * Accesses the specified service in the environment of the sink in the
+ * context of a sink.
  * @tsplus static fncts.io.SinkOps serviceWithSink
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function serviceWithSink<S, R, E, In, L, Z>(f: (service: S) => Sink<R, E, In, L, Z>, 
 /** @tsplus auto */ tag: Tag<S>): Sink<Has<S> & R, E, In, L, Z>;
 /**
+ * Splits the sink on the specified predicate, returning a new sink that
+ * consumes elements until an element after the first satisfies the specified
+ * predicate.
  * @tsplus fluent fncts.io.Sink splitWhere
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function splitWhere<R, E, In, L extends In, Z>(self: Sink<R, E, In, L, Z>, p: Predicate<In>): Sink<R, E, In, In, Z>;
+export declare function splitWhere<R, E, In, L extends In, Z>(self: Sink<R, E, In, L, Z>, p: Predicate<In>, __tsplusTrace?: string): Sink<R, E, In, In, Z>;
 /**
+ * A sink that immediately ends with the specified value.
  * @tsplus static fncts.io.SinkOps succeed
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function succeed<Z>(z: Lazy<Z>, __tsplusTrace?: string): Sink<unknown, never, unknown, never, Z>;
 /**
+ * A sink that immediately ends with the specified value.
  * @tsplus static fncts.io.SinkOps succeedNow
  * @tsplus location "@fncts/io/Sink/api"
  */
 export declare function succeedNow<Z>(z: Z, __tsplusTrace?: string): Sink<unknown, never, unknown, never, Z>;
 /**
+ * Summarize a sink by running an effect when the sink starts and again when
+ * it completes
  * @tsplus fluent fncts.io.Sink summarized
  * @tsplus location "@fncts/io/Sink/api"
  */
@@ -446,6 +621,7 @@ export declare function summarized<R, E, In, L, Z, R1, E1, B, C>(self: Sink<R, E
  */
 export declare function timed<R, E, In, L, Z>(self: Sink<R, E, In, L, Z>, __tsplusTrace?: string): Sink<R, E, In, L, readonly [Z, Duration]>;
 /**
+ * Creates a sink produced from an effect.
  * @tsplus static fncts.io.SinkOps unwrap
  * @tsplus location "@fncts/io/Sink/api"
  */
@@ -455,17 +631,22 @@ export declare function unwrap<R, E, R1, E1, In, L, Z>(io: Lazy<IO<R, E, Sink<R1
  * @tsplus static fncts.io.SinkOps unwrapScoped
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function unwrapScoped<R, E, R1, E1, In, L, Z>(scoped: Lazy<IO<Has<Scope> & R, E, Sink<R1, E1, In, L, Z>>>): Sink<R & R1, E | E1, In, L, Z>;
+export declare function unwrapScoped<R, E, R1, E1, In, L, Z>(scoped: Lazy<IO<Has<Scope> & R, E, Sink<R1, E1, In, L, Z>>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In, L, Z>;
 /**
+ * Feeds inputs to this sink until it yields a result, then switches over to
+ * the provided sink until it yields a result, finally combining the two
+ * results into a tuple.
  * @tsplus fluent fncts.io.Sink zip
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function zip<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, readonly [Z, Z1]>;
+export declare function zip<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, readonly [Z, Z1]>;
 /**
+ * Runs both sinks in parallel on the input and combines the results in a
+ * tuple.
  * @tsplus fluent fncts.io.Sink zipC
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function zipC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>): Sink<R & R1, E | E1, In & In1, L | L1, readonly [Z, Z1]>;
+export declare function zipC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1>(self: Sink<R, E, In, L, Z>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, readonly [Z, Z1]>;
 /**
  * Feeds inputs to this sink until it yields a result, then switches over to
  * the provided sink until it yields a result, finally combining the two
@@ -473,11 +654,11 @@ export declare function zipC<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends
  * @tsplus fluent fncts.io.Sink zipWith
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function zipWith<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1, Z2>(self: Lazy<Sink<R, E, In, L, Z>>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, f: (z: Z, z1: Z1) => Z2): Sink<R & R1, E | E1, In & In1, L | L1, Z2>;
+export declare function zipWith<R, E, In, L, Z, R1, E1, In1 extends In, L1 extends L, Z1, Z2>(self: Lazy<Sink<R, E, In, L, Z>>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, f: (z: Z, z1: Z1) => Z2, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z2>;
 /**
  * Runs both sinks in parallel on the input and combines the results using the
  * provided function.
  * @tsplus fluent fncts.io.Sink zipWithC
  * @tsplus location "@fncts/io/Sink/api"
  */
-export declare function zipWithC<R, E, In, L, Z, R1, E1, In1, L1, Z1, Z2>(self: Lazy<Sink<R, E, In, L, Z>>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, f: (z: Z, z1: Z1) => Z2): Sink<R & R1, E | E1, In & In1, L | L1, Z2>;
+export declare function zipWithC<R, E, In, L, Z, R1, E1, In1, L1, Z1, Z2>(self: Lazy<Sink<R, E, In, L, Z>>, that: Lazy<Sink<R1, E1, In1, L1, Z1>>, f: (z: Z, z1: Z1) => Z2, __tsplusTrace?: string): Sink<R & R1, E | E1, In & In1, L | L1, Z2>;