@typed/fx 2.0.0-beta.4 → 2.0.0-beta.6

package/dist/Sink/combinators.js

@@ -2,6 +2,7 @@ import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
 import * as Semaphore from "effect/Semaphore";
 import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
 import { dual, flow, identity } from "effect/Function";
 import * as MutableRef from "effect/MutableRef";
 import * as Option from "effect/Option";
@@ -34,6 +35,15 @@ class MapSink {
 /**
  * Transforms values before they reach the sink using a pure function.
  *
+ * @remarks
+ * ## Why
+ * Contramapping adapts a consumer to a new input without changing the producer or allocating an
+ * intermediate Fx.
+ *
+ * ## Ownership and lifetime
+ * Mapping is synchronous, preserves one-for-one input order, and acquires no resources. Thrown
+ * exceptions are defects. The wrapped sink still owns its callback effects and service needs.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -61,12 +71,49 @@ class MapSink {
 export function map(sink, f) {
     return MapSink.make(sink, f);
 }
-/** Alias for `map`: transforms input values before they reach the sink. @since 1.0.0 @category combinators */
+/**
+ * Alias for `map`, named for the input-side direction of the transformation.
+ *
+ * @remarks
+ * ## Why
+ * `mapInput` makes contravariant Sink pipelines easier to read beside output-mapping APIs.
+ *
+ * ## Ownership and lifetime
+ * It is exactly `map`: synchronous, one-for-one, ordered, and resource-free.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const numbers = Sink.make(Effect.logError, (value: number) => Effect.log(value))
+ * const strings = Sink.mapInput(numbers, Number)
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const mapInput = map;
 /**
  * Maps the error channel of a sink using the provided function.
  * Failures are mapped via `Cause.map`; defects and interrupts are preserved.
  *
+ * @remarks
+ * ## Why
+ * A producer's typed error can be translated into the vocabulary expected by an existing consumer
+ * without losing Cause structure.
+ *
+ * ## Ownership and lifetime
+ * Mapping is synchronous and resource-free. Success order is unchanged; only `Fail` reasons are
+ * mapped, while defects and interruption reasons pass through untouched.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target: Sink.Sink<number, string> = Sink.make(Effect.logError, Effect.log)
+ * const acceptsNumbers = Sink.mapError(target, (error: number) => `code:${error}`)
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */
@@ -121,6 +168,14 @@ class FilterMapSink {
 /**
  * Filters and transforms values before they reach the sink using a function that returns an `Option`.
  *
+ * @remarks
+ * ## Why
+ * Selection and transformation happen at the consumer boundary without constructing another Fx.
+ *
+ * ## Ownership and lifetime
+ * Inputs are inspected synchronously in arrival order. `Some` invokes the wrapped sink once;
+ * `None` invokes it zero times. The adapter acquires no resources and failures pass through.
+ *
  * @example
  * ```ts
  * import { Effect, Option } from "effect"
@@ -149,12 +204,42 @@ class FilterMapSink {
 export function filterMap(sink, f) {
     return FilterMapSink.make(sink, f);
 }
+/**
+ * Forwards `Some` values and discards `None` values.
+ *
+ * @remarks
+ * ## Why
+ * `compact` consumes optional producer output with the same zero-or-one cardinality as `filterMap`.
+ *
+ * ## Ownership and lifetime
+ * Option inspection is synchronous and resource-free. Present values retain arrival order; failure
+ * causes pass through unchanged.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const sink = Sink.compact(Sink.make(Effect.logError, (n: number) => Effect.log(n)))
+ * sink.onSuccess(Option.some(1))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export function compact(sink) {
     return filterMap(sink, identity);
 }
 /**
  * Filters values before they reach the sink using a predicate function.
  *
+ * @remarks
+ * ## Why
+ * Predicate filtering narrows consumer traffic without changing the producer.
+ *
+ * ## Ownership and lifetime
+ * The predicate runs synchronously in arrival order. Matching values invoke the wrapped sink once;
+ * non-matches invoke it zero times. The adapter acquires no resources.
+ *
  * @example
  * ```ts
  * import { Effect } from "effect"
@@ -181,12 +266,48 @@ export function compact(sink) {
 export function filter(sink, f) {
     return filterMap(sink, Option.liftPredicate(f));
 }
+/**
+ * Runs a producer-style callback with a sink that can complete the surrounding Effect early.
+ *
+ * @remarks
+ * ## Why
+ * Consumer combinators can stop upstream work after a bound or predicate without representing
+ * normal completion as failure.
+ *
+ * ## Ownership and lifetime
+ * The returned Effect owns the callback fiber. Completion, `earlyExit`, or interruption aborts that
+ * fiber through the supplied signal; deliveries after exit are ignored. The callback's services are
+ * combined with the wrapped sink's services.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const base = Sink.make(Effect.logError, Effect.log)
+ * const program = Sink.withEarlyExit(base, (sink) => sink.onSuccess("done").pipe(Effect.andThen(sink.earlyExit)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ */
 export function withEarlyExit(sink, f) {
     return Effect.contextWith((services) => Effect.callback(function (resume, signal) {
         let exited = false;
+        let exitRequested = false;
+        let resumed = false;
+        let producerFiber;
+        const finish = () => {
+            if (resumed || producerFiber === undefined)
+                return;
+            resumed = true;
+            resume(Fiber.interrupt(producerFiber));
+        };
         const earlyExit = Effect.sync(() => {
+            if (exited)
+                return;
             exited = true;
-            resume(Effect.void);
+            exitRequested = true;
+            finish();
         });
         const onSuccess = (a) => {
             if (exited)
@@ -203,12 +324,63 @@ export function withEarlyExit(sink, f) {
             onFailure,
             earlyExit,
         };
-        f(sinkWithEarlyExit, { signal, scheduler: this }).pipe(Effect.flatMap(() => earlyExit), (_) => Effect.runForkWith(services)(_, { scheduler: this, signal }));
+        producerFiber = f(sinkWithEarlyExit, { signal, scheduler: this }).pipe(Effect.flatMap(() => earlyExit), (_) => Effect.runForkWith(services)(_, { scheduler: this, signal }));
+        if (exitRequested)
+            finish();
     }));
 }
+/**
+ * Runs a callback with an early-exit sink and a private Effect `Ref` initialized to `state`.
+ *
+ * @remarks
+ * ## Why
+ * It supports stateful consumer protocols while keeping their state local to one run.
+ *
+ * ## Ownership and lifetime
+ * Each execution creates one Ref and owns it until exit or interruption. Ref operations are lazy
+ * atomic Effects: serialized callback execution preserves producer order, while concurrent execution
+ * is ordered by scheduling. No state is shared across `withState` executions.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const base = Sink.make(Effect.logError, Effect.log)
+ * const program = Sink.withState(base, 0, ({ state, earlyExit }) => Ref.set(state, 1).pipe(Effect.andThen(earlyExit)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ */
 export function withState(sink, state, f) {
     return withEarlyExit(sink, (sink, params) => f({ ...sink, state: Ref.makeUnsafe(state) }, params));
 }
+/**
+ * Runs a callback with private state whose effectful reads and writes are serialized.
+ *
+ * @remarks
+ * ## Why
+ * Overlapping asynchronous callbacks need a lock to prevent multiple updates from reading the same
+ * prior state.
+ *
+ * ## Ownership and lifetime
+ * Each execution owns one mutable cell and one single-permit semaphore. Modify Effects serialize in
+ * semaphore-acquisition order, release the permit on completion or interruption, and expose their
+ * typed errors and services. Constructing an Effect does not acquire the permit; running it does.
+ * Exit aborts the surrounding callback fiber.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const base = Sink.make(Effect.logError, Effect.log)
+ * const program = Sink.withStateSemaphore(base, 0, (state) =>
+ *   state.updateEffect((n) => Effect.succeed(n + 1)).pipe(Effect.andThen(state.earlyExit)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ */
 export function withStateSemaphore(sink, state, f) {
     return withEarlyExit(sink, (sink, params) => {
         const stateRef = MutableRef.make(state);
@@ -223,6 +395,29 @@ export function withStateSemaphore(sink, state, f) {
         return f({ ...sink, modifyEffect, updateEffect, get }, params);
     });
 }
+/**
+ * Threads pure state through successful inputs and forwards one derived value per input.
+ *
+ * @remarks
+ * ## Why
+ * `loop` implements an ordered consumer-side state machine without exposing mutable state to the
+ * producer.
+ *
+ * ## Ownership and lifetime
+ * Each adapted sink owns its seed. Updates are synchronous and follow callback invocation order;
+ * every input produces exactly one downstream success. Failures bypass the state machine. Reusing
+ * the same sink for another producer run continues from its retained seed; create a new sink to reset.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const totals = Sink.loop(Sink.make(Effect.logError, Effect.log), 0, (sum, n: number) => [sum + n, sum + n])
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const loop = dual(3, function loop(sink, seed, f) {
     return new LoopSink(sink, seed, f);
 });
@@ -246,6 +441,30 @@ class LoopSink {
         return this.sink.onSuccess(c);
     }
 }
+/**
+ * Threads pure state through failure causes and forwards one transformed cause per failure.
+ *
+ * @remarks
+ * ## Why
+ * Stateful error translation can retain retry or protocol context while preserving full Cause
+ * information.
+ *
+ * ## Ownership and lifetime
+ * Each adapted sink owns its seed. Failure callbacks update it synchronously in invocation order;
+ * successes pass through unchanged. Reusing the sink continues from its retained seed; create a new
+ * sink to reset. No resources are acquired.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target: Sink.Sink<number, string> = Sink.make(Effect.logError, Effect.log)
+ * const counted = Sink.loopCause(target, 0, (n, cause: Cause.Cause<string>) => [cause, n + 1])
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const loopCause = dual(3, function loopCause(sink, seed, f) {
     return new LoopCauseSink(sink, seed, f);
 });
@@ -269,6 +488,29 @@ class LoopCauseSink {
         return this.sink.onSuccess(value);
     }
 }
+/**
+ * Threads pure state through successes and optionally forwards a derived value.
+ *
+ * @remarks
+ * ## Why
+ * It combines consumer-side state, filtering, and mapping in one ordered transition.
+ *
+ * ## Ownership and lifetime
+ * Each adapted sink owns its seed. Every input updates state synchronously; `Some` emits once and
+ * `None` emits nothing. Failures pass through. Reusing the sink continues from its retained seed;
+ * create a new sink to reset. The adapter acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const everyOther = Sink.filterMapLoop(target, false, (skip, n: number) => [skip ? Option.none() : Option.some(n), !skip])
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const filterMapLoop = dual(3, function filterMapLoop(sink, seed, f) {
     return new FilterMapLoopSink(sink, seed, f);
 });
@@ -294,6 +536,29 @@ class FilterMapLoopSink {
         return Effect.void;
     }
 }
+/**
+ * Threads pure state through failures and optionally forwards a transformed cause.
+ *
+ * @remarks
+ * ## Why
+ * Stateful failure suppression and translation can be expressed without discarding Cause structure.
+ *
+ * ## Ownership and lifetime
+ * Each adapted sink owns its seed. Failure callbacks update state synchronously in invocation order;
+ * `Some` forwards once and `None` suppresses the failure. Successes pass through unchanged. Reusing
+ * the sink continues from its retained seed; create a new sink to reset.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target: Sink.Sink<number, string> = Sink.make(Effect.logError, Effect.log)
+ * const first = Sink.filterMapLoopCause(target, true, (keep, cause: Cause.Cause<string>) => [keep ? Option.some(cause) : Option.none(), false])
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const filterMapLoopCause = dual(3, function filterMapLoopCause(sink, seed, f) {
     return new FilterMapLoopCauseSink(sink, seed, f);
 });
@@ -319,6 +584,32 @@ class FilterMapLoopCauseSink {
         return this.sink.onSuccess(value);
     }
 }
+/**
+ * Threads state through an effectful success transformation and forwards one value on success.
+ *
+ * @remarks
+ * ## Why
+ * Stateful consumer transitions can consult Effect services or fail without moving the state
+ * machine into the producer.
+ *
+ * ## Ownership and lifetime
+ * Callback invocation constructs a transition Effect from the seed visible at that moment. The
+ * adapter does not serialize those Effects: overlapping callbacks can read the same seed, and
+ * successful transitions commit in completion order. A failure is sent to the wrapped sink and does
+ * not commit. The sink instance retains its last committed seed when reused by another producer run;
+ * construct a new adapted sink to reset it. Transition services and interruption remain typed.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const totals = Sink.loopEffect(target, 0, (sum, n: number) => Effect.succeed([sum + n, sum + n] as const))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const loopEffect = dual(3, function loopEffect(sink, seed, f) {
     return new LoopEffectSink(sink, seed, f);
 });
@@ -346,6 +637,32 @@ class LoopEffectSink {
         });
     }
 }
+/**
+ * Threads state through an effectful success transition and optionally forwards its value.
+ *
+ * @remarks
+ * ## Why
+ * One transition can perform service-backed work, update state, and decide whether the consumer
+ * should observe a value.
+ *
+ * ## Ownership and lifetime
+ * Callback invocation constructs a transition Effect from the seed visible at that moment. The
+ * adapter does not serialize those Effects: overlapping callbacks can read the same seed, and
+ * successful transitions commit in completion order. `Some` then invokes the wrapped sink once,
+ * `None` not at all, and failure invokes its failure callback without committing. The sink instance
+ * retains its seed across producer runs; construct a new one to reset it.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const sink = Sink.filterMapLoopEffect(target, 0, (count, n: number) => Effect.succeed([Option.some(n), count + 1] as const))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const filterMapLoopEffect = dual(3, function filterMapLoopEffect(sink, seed, f) {
     return new FilterMapLoopEffectSink(sink, seed, f);
 });
@@ -375,6 +692,32 @@ class FilterMapLoopEffectSink {
         });
     }
 }
+/**
+ * Threads state through an effectful failure transformation.
+ *
+ * @remarks
+ * ## Why
+ * Failure handling can consult services and retain state while preserving the original Cause when
+ * the handler itself fails.
+ *
+ * ## Ownership and lifetime
+ * Callback invocation constructs a transition Effect from the seed visible at that moment. The
+ * adapter does not serialize those Effects: overlapping failures can read the same seed, and
+ * successful transitions commit in completion order. A transition failure is combined with the
+ * original cause and does not commit. Success values bypass the state machine. The sink instance
+ * retains its seed across producer runs; construct a new one to reset it.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const sink = Sink.loopCauseEffect(target, 0, (count, cause) => Effect.succeed([cause, count + 1] as const))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const loopCauseEffect = dual(3, function loopCauseEffect(sink, seed, f) {
     return new LoopCauseEffectSink(sink, seed, f);
 });
@@ -402,6 +745,32 @@ class LoopCauseEffectSink {
         return this.sink.onSuccess(value);
     }
 }
+/**
+ * Threads state through an effectful failure transition and optionally forwards a cause.
+ *
+ * @remarks
+ * ## Why
+ * It supports service-backed, stateful failure suppression or translation at the consumer boundary.
+ *
+ * ## Ownership and lifetime
+ * Callback invocation constructs a transition Effect from the seed visible at that moment. The
+ * adapter does not serialize those Effects: overlapping failures can read the same seed, and
+ * successful transitions commit in completion order. `Some` forwards one cause, `None` suppresses
+ * it, and transition failure is forwarded without committing. Successes pass through. The sink
+ * instance retains its seed across producer runs; construct a new one to reset it.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target: Sink.Sink<number, string> = Sink.make(Effect.logError, Effect.log)
+ * const sink = Sink.filterMapLoopCauseEffect(target, false, (seen, cause: Cause.Cause<string>) =>
+ *   Effect.succeed([seen ? Option.none() : Option.some(cause), true] as const))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export function filterMapLoopCauseEffect(sink, seed, f) {
     return new FilterMapLoopCauseEffectSink(sink, seed, f);
 }
@@ -431,6 +800,30 @@ class FilterMapLoopCauseEffectSink {
         return this.sink.onSuccess(value);
     }
 }
+/**
+ * Runs a producer callback through a bounded view of a sink.
+ *
+ * @remarks
+ * ## Why
+ * Consumers can skip an initial prefix and stop after a fixed number of values, allowing the
+ * surrounding producer work to finish early.
+ *
+ * ## Ownership and lifetime
+ * Each execution owns fresh counters and an early-exit callback. Successes remain ordered; at most
+ * `take` values are delivered after `skip` values. Failures always pass through. Reaching the bound
+ * completes and aborts the callback fiber; negative bounds are not normalized.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const program = Sink.slice(target, { skip: 1, take: 2 }, (bounded) => bounded.onSuccess("kept"))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ */
 export const slice = dual(3, function slice(sink, bounds, f) {
     return withEarlyExit(sink, (s) => f(new SliceSink(s, bounds)));
 });
@@ -461,6 +854,30 @@ class SliceSink {
         return this.sink.earlyExit;
     }
 }
+/**
+ * Runs an Effect for each input and forwards its successful value to the sink.
+ *
+ * @remarks
+ * ## Why
+ * Consumer-side adaptation can use services and typed failure without creating an intermediate Fx.
+ *
+ * ## Ownership and lifetime
+ * One transition Effect runs per callback invocation. Its success is forwarded once; its complete
+ * failure Cause is sent to `onFailure`. Calls themselves are not serialized by this adapter, so
+ * ordering follows the invoking producer. Services join the sink requirements; interruption is local
+ * to each callback Effect.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const numbers = Sink.mapEffect(Sink.make(Effect.logError, Effect.log), (text: string) =>
+ *   Effect.succeed(Number(text)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const mapEffect = dual(2, function mapEffect(sink, f) {
     return new MapEffectSink(sink, f);
 });
@@ -480,8 +897,51 @@ class MapEffectSink {
         return Effect.matchCauseEffect(this.f(value), this.sink);
     }
 }
-/** Alias for `mapEffect`: transforms input with an effect before the sink. @since 1.0.0 @category combinators */
+/**
+ * Alias for `mapEffect`, named for the input-side direction of the effectful transformation.
+ *
+ * @remarks
+ * ## Why
+ * The name highlights that Sink composition is contravariant in successful input.
+ *
+ * ## Ownership and lifetime
+ * It is exactly `mapEffect`: one Effect per input, with the same failures, services, ordering, and
+ * interruption behavior.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const sink = Sink.mapInputEffect(Sink.make(Effect.logError, Effect.log), (n: number) => Effect.succeed(String(n)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const mapInputEffect = mapEffect;
+/**
+ * Runs an Effect for each input and forwards its optional successful value.
+ *
+ * @remarks
+ * ## Why
+ * Service-backed validation, selection, and transformation can happen in one consumer adapter.
+ *
+ * ## Ownership and lifetime
+ * Each input runs one Effect. `Some` invokes the sink once, `None` zero times, and failure is routed
+ * as a Cause. Invocation order and concurrency are controlled by the producer; services and
+ * interruption remain explicit in the returned sink.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const sink = Sink.filterMapEffect(Sink.make(Effect.logError, Effect.log), (n: number) =>
+ *   Effect.succeed(n > 0 ? Option.some(n) : Option.none()))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const filterMapEffect = dual(2, function filterMapEffect(sink, f) {
     return new FilterMapEffectSink(sink, f);
 });
@@ -509,6 +969,28 @@ class FilterMapEffectSink {
         });
     }
 }
+/**
+ * Runs an effectful predicate and forwards inputs for which it succeeds with `true`.
+ *
+ * @remarks
+ * ## Why
+ * A consumer can filter using service-backed or asynchronous policy without changing the producer.
+ *
+ * ## Ownership and lifetime
+ * Each input runs one predicate Effect. `true` forwards once, `false` not at all, and predicate
+ * failure reaches the sink's failure callback. The producer controls callback ordering and
+ * concurrency; predicate services and interruption remain typed.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const positive = Sink.filterEffect(Sink.make(Effect.logError, Effect.log), (n: number) => Effect.succeed(n > 0))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const filterEffect = dual(2, function filterEffect(sink, f) {
     return new FilterEffectSink(sink, f);
 });
@@ -536,6 +1018,29 @@ class FilterEffectSink {
         });
     }
 }
+/**
+ * Runs an effectful observation before forwarding each successful input unchanged.
+ *
+ * @remarks
+ * ## Why
+ * Logging, metrics, and other observations can be attached at the consumer boundary without
+ * changing the value type.
+ *
+ * ## Ownership and lifetime
+ * The tap Effect completes before the value is forwarded. If it fails, its Cause is delivered and
+ * the value is not forwarded. The producer controls call order and concurrency; tap services and
+ * interruption are reflected by the returned sink.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const observed = Sink.tapEffect(Sink.make(Effect.logError, Effect.log), (n: number) => Effect.log(`saw ${n}`))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export const tapEffect = dual(2, function tapEffect(sink, f) {
     return new TapEffectSink(sink, f);
 });
@@ -558,11 +1063,37 @@ class TapEffectSink {
         });
     }
 }
+/**
+ * Exchanges a sink's typed success and failure channels.
+ *
+ * @remarks
+ * ## Why
+ * Error-oriented consumers can be reused as value consumers, and vice versa, without changing the
+ * producer-side protocol.
+ *
+ * ## Ownership and lifetime
+ * A successful input becomes `Cause.fail` downstream. For an incoming Cause, the first typed `Fail`
+ * reason becomes a success and every remaining reason is discarded, including later failures,
+ * defects, or interruption reasons. A Cause with no typed failure passes through intact. The adapter
+ * is synchronous, ordered, and resource-free; use `exit` when the whole Cause must remain observable.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const errorsAsValues = Sink.flip(Sink.make(Effect.logError, (value: number) => Effect.log(value)))
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
 export const flip = (sink) => new FlipSink(sink);
 class FlipSink {
     sink;
     constructor(sink) {
         this.sink = sink;
+        this.onSuccess = this.onSuccess.bind(this);
+        this.onFailure = this.onFailure.bind(this);
     }
     onSuccess(value) {
         return this.sink.onFailure(Cause.fail(value));
@@ -574,11 +1105,34 @@ class FlipSink {
         return this.sink.onSuccess(fail.error);
     }
 }
+/**
+ * Materializes both sink channels as successful Effect `Exit` values.
+ *
+ * @remarks
+ * ## Why
+ * A single infallible consumer can record or inspect success and the complete failure Cause as data.
+ *
+ * ## Ownership and lifetime
+ * Every input produces exactly one downstream success: `Exit.succeed` for values or
+ * `Exit.failCause` for failures. Order is preserved and the adapter acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const exits = Sink.exit(Sink.make(Effect.logError, Effect.log))
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
 export const exit = (sink) => new ExitSink(sink);
 class ExitSink {
     sink;
     constructor(sink) {
         this.sink = sink;
+        this.onSuccess = this.onSuccess.bind(this);
+        this.onFailure = this.onFailure.bind(this);
     }
     onSuccess(value) {
         return this.sink.onSuccess(Exit.succeed(value));
@@ -587,6 +1141,30 @@ class ExitSink {
         return this.sink.onSuccess(Exit.failCause(cause));
     }
 }
+/**
+ * Runs a producer callback until the first matching value has been forwarded.
+ *
+ * @remarks
+ * ## Why
+ * Unlike a filtering operation, `dropAfter` includes the boundary value and then terminates
+ * producer work normally.
+ *
+ * ## Ownership and lifetime
+ * Values are forwarded in order through the first predicate match, then early exit completes and
+ * aborts the callback fiber. Callback failure is caught and sent to the original sink. The predicate
+ * is synchronous; thrown exceptions are defects.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const target = Sink.make(Effect.logError, Effect.log)
+ * const program = Sink.dropAfter(target, (n: number) => n >= 10, (limited) => limited.onSuccess(10))
+ * ```
+ *
+ * @since 1.0.0
+ * @category lifecycle
+ */
 export const dropAfter = dual(3, function dropAfter(sink, predicate, f) {
     return withEarlyExit(sink, (s) => f(new DropAfterSink(s, predicate)).pipe(Effect.catchCause(sink.onFailure)));
 });
@@ -609,6 +1187,29 @@ class DropAfterSink {
         return this.sink.onSuccess(value);
     }
 }
+/**
+ * Suppresses failure causes made entirely of interruption reasons.
+ *
+ * @remarks
+ * ## Why
+ * Some terminal consumers treat expected cancellation as silent completion while still needing
+ * typed failures and defects.
+ *
+ * ## Ownership and lifetime
+ * Successes pass through unchanged. A pure interruption Cause invokes no downstream callback;
+ * mixed or non-interruption causes are preserved. The adapter does not change fiber ownership or
+ * cleanup and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const quietCancellation = Sink.skipInterrupt(Sink.make(Effect.logError, Effect.log))
+ * ```
+ *
+ * @since 1.0.0
+ * @category errors
+ */
 export const skipInterrupt = (sink) => {
     return {
         onSuccess: (value) => sink.onSuccess(value),
@@ -622,6 +1223,27 @@ export const skipInterrupt = (sink) => {
  * Reduces values into a single result using a pure function. Pass a `Ref<B>`
  * (e.g. from `Ref.make(initial)`); after running, read the result with `Ref.get(ref)`.
  *
+ * @remarks
+ * ## Why
+ * An existing Ref provides an explicit, independently readable result location for consumer-side
+ * aggregation.
+ *
+ * ## Ownership and lifetime
+ * The caller owns the Ref. Each success returns a lazy atomic `Ref.update`; invoking `onSuccess`
+ * does not update immediately. If the producer executes callback Effects serially, values reduce in
+ * that execution order. Concurrent execution is still atomic but may be scheduled in a different
+ * order than callback invocation. Failures are ignored and a thrown reducer exception is a defect.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const program = Effect.gen(function* () {
+ *   const total = yield* Ref.make(0)
+ *   return Sink.reduce(total, (sum, n: number) => sum + n)
+ * })
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */
@@ -636,6 +1258,28 @@ export function reduce(ref, f) {
  * after running, read the result with `Ref.get(ref)`. If the reducer effect fails,
  * the ref is left unchanged (Sink onSuccess is typed as never failing).
  *
+ * @remarks
+ * ## Why
+ * Aggregation may require Effect services or asynchronous work while the result remains explicitly
+ * available through a caller-owned Ref.
+ *
+ * ## Ownership and lifetime
+ * The caller owns the Ref. Each success returns a lazy read/reduce/write Effect; invocation alone does
+ * no work. The three steps are not one atomic operation. Serialized producers preserve execution
+ * order, while overlapping executions can read the same value and commit in completion order.
+ * Reducer failures, producer failures, and interrupted writes are ignored. Use
+ * `withStateSemaphore` when the whole effectful transition must be serialized.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const program = Effect.gen(function* () {
+ *   const total = yield* Ref.make(0)
+ *   return Sink.reduceEffect(total, (sum, n: number) => Effect.succeed(sum + n))
+ * })
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */
@@ -652,6 +1296,26 @@ export function reduceEffect(ref, f) {
  * Collects all values into an array. Pass a `Ref<ReadonlyArray<A>>` (e.g. `Ref.make([])`);
  * after running, read the result with `Ref.get(ref)`.
  *
+ * @remarks
+ * ## Why
+ * Collection remains an explicit consumer concern and the accumulated result can be read without
+ * changing the producer.
+ *
+ * ## Ownership and lifetime
+ * The caller owns the Ref. Each success returns a lazy atomic `Ref.update` that allocates a new array.
+ * Serialized producers collect in callback-Effect execution order. Concurrent updates remain atomic,
+ * but execution scheduling—not invocation order—determines array order. Failures are ignored.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const program = Effect.gen(function* () {
+ *   const values = yield* Ref.make<ReadonlyArray<number>>([])
+ *   return Sink.collect(values)
+ * })
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */
@@ -665,6 +1329,25 @@ export function collect(ref) {
  * Keeps only the first value. Pass a `Ref<Option.Option<A>>` (e.g. `Ref.make(Option.none())`);
  * after running, read the result with `Ref.get(ref)`.
  *
+ * @remarks
+ * ## Why
+ * The first observed value can be retained in a caller-owned location without stopping the producer.
+ *
+ * ## Ownership and lifetime
+ * The caller owns the Ref. Each success returns a lazy atomic update. The first update Effect to
+ * execute while the Ref is `None` stores its value; that is the first callback only when the producer
+ * executes callback Effects serially. Later updates leave `Some` unchanged. Failures are ignored.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const program = Effect.gen(function* () {
+ *   const first = yield* Ref.make<Option.Option<number>>(Option.none())
+ *   return Sink.head(first)
+ * })
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */
@@ -678,6 +1361,25 @@ export function head(ref) {
  * Keeps only the last value. Pass a `Ref<Option.Option<A>>` (e.g. `Ref.make(Option.none())`);
  * after running, read the result with `Ref.get(ref)`.
  *
+ * @remarks
+ * ## Why
+ * The latest observed value can be retained independently of producer completion.
+ *
+ * ## Ownership and lifetime
+ * The caller owns the Ref. Each success returns a lazy atomic `Ref.set`. With serialized callback
+ * Effects the last callback wins; with concurrent execution the last set to execute wins, which may
+ * differ from invocation order. Failures are ignored and the sink acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Option, Ref } from "effect"
+ * import * as Sink from "@typed/fx/Sink"
+ * const program = Effect.gen(function* () {
+ *   const latest = yield* Ref.make<Option.Option<number>>(Option.none())
+ *   return Sink.last(latest)
+ * })
+ * ```
+ *
  * @since 1.0.0
  * @category combinators
  */