pyfect-dev 0.1.0__py3-none-any.whl

pyfect/sink/_constructors.py

@@ -0,0 +1,187 @@
+"""Sink constructors: from transforms, channels, effects and stream
+pipelines; values and failures; and sinks writing to queues and pubsubs."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Never, overload
+
+from pyfect import effect as _effect
+from pyfect._core import Effect, _Locally, _Succeed, _Sync
+from pyfect._effect_args import require_effect
+from pyfect.cause import Cause
+from pyfect.channel import Channel
+from pyfect.channel._base import end_with, require_channel
+from pyfect.channel._loop import PullLoop
+from pyfect.errors import Done
+from pyfect.pull import catch_done
+from pyfect.scope import CloseableScope, Scope
+from pyfect.sink._combinators import map_end, with_duration
+from pyfect.sink._for_each import for_each_array
+from pyfect.sink._sink import AnySink, End, Sink, Upstream, require_sink
+
+if TYPE_CHECKING:
+    from pyfect.pubsub import PubSub
+    from pyfect.queue import Enqueue
+    from pyfect.stream import Stream
+
+type AnyEffect = Effect[Any, Any, Any]
+
+
+def _ignore(_: object) -> None:
+    return None
+
+
+_END_VOID: Effect[End[None]] = _Succeed((None, None))
+
+
+def from_transform[In, A, L = Never, E = Never, R = Never](
+    transform: Callable[[Upstream[In], CloseableScope], Effect[End[A, L], E, R]],
+) -> Sink[A, In, L, E, R]:
+    """A sink from ``transform(upstream, scope)``: an effect that pulls
+    non-empty tuples from ``upstream`` (which ends with ``Done()``) and
+    succeeds with the sink's ``End``. Resources go in ``scope``."""
+    return Sink(transform)
+
+
+def to_channel[A, In, L, E, R](
+    sink: Sink[A, In, L, E, R],
+) -> Channel[Never, E, End[A, L], tuple[In, ...], Never, None, R]:
+    """The channel that reads what the sink reads and ends with its
+    ``End``."""
+    require_sink(sink, "sink")
+
+    def transform(upstream: Any, scope: CloseableScope) -> AnyEffect:
+        return _Succeed(sink._transform(upstream, scope).flat_map(end_with))
+
+    built: Channel[Any, Any, Any, Any, Any, Any, Any] = Channel(transform)
+    return built
+
+
+def from_channel[A, In, L = Never, E = Never, R = Never](
+    channel: Channel[Never, E, End[A, L], tuple[In, ...], Never, None, R],
+) -> Sink[A, In, L, E, R]:
+    """The sink that feeds its input to ``channel`` and ends with the
+    ``End`` the channel ends with."""
+    require_channel(channel, "channel")
+
+    def transform(upstream: Upstream[Any], scope: CloseableScope) -> AnyEffect:
+        drained = channel._transform(upstream, scope).flat_map(lambda pull: PullLoop(pull, _ignore))
+        return catch_done(drained, _Succeed)
+
+    return Sink(transform)
+
+
+@overload
+def make[In, B, E = Never](
+    f: Callable[[Stream[In]], Effect[B, E, Scope]],
+) -> Sink[B, In, Never, E]: ...
+@overload
+def make[In, B, E = Never, R = Never](
+    f: Callable[[Stream[In]], Effect[B, E, Scope | R]],
+) -> Sink[B, In, Never, E, R]: ...
+def make(f: Callable[[Any], AnyEffect]) -> AnySink:
+    """A sink from a stream pipeline: ``f`` gets the sink's input as a
+    ``Stream`` and returns the effect whose value is the sink's (Effect's
+    ``Sink.make<In>()(...)``). The effect runs with the sink's ``Scope``::
+
+        sink.make(lambda s: s.run_sum())
+    """
+    from pyfect.stream import from_pull
+
+    def transform(upstream: Upstream[Any], scope: CloseableScope) -> AnyEffect:
+        run = f(from_pull(_Succeed(upstream))).map(lambda value: (value, None))
+        return _Locally(run, lambda ctx: ctx.add(Scope, scope))
+
+    return Sink(transform)
+
+
+def from_effect_end[A, L = Never, E = Never, R = Never](
+    eff: Effect[End[A, L], E, R],
+) -> Sink[A, object, L, E, R]:
+    """A sink that reads nothing and ends with what ``eff`` succeeds
+    with."""
+    require_effect(eff, "eff")
+    return Sink(lambda _upstream, _scope: eff)
+
+
+def from_effect[A, E = Never, R = Never](eff: Effect[A, E, R]) -> Sink[A, object, Never, E, R]:
+    """A sink that reads nothing and succeeds with ``eff``'s value."""
+    require_effect(eff, "eff")
+    return from_effect_end(eff.map(lambda value: (value, None)))
+
+
+def succeed[A, L = Never](value: A, leftover: tuple[L, ...] | None = None) -> Sink[A, object, L]:
+    """A sink that reads nothing and succeeds with ``value``, leaving
+    ``leftover`` over (an empty tuple is no leftover)."""
+    end: End[A, L] = (value, leftover or None)
+    return from_effect_end(_Succeed(end))
+
+
+def sync[A](thunk: Callable[[], A]) -> Sink[A]:
+    """A sink that reads nothing and succeeds with ``thunk()``, called
+    each time it runs."""
+    return from_effect_end(_Sync(lambda: (thunk(), None)))
+
+
+def suspend[A, In, L, E, R](thunk: Callable[[], Sink[A, In, L, E, R]]) -> Sink[A, In, L, E, R]:
+    """The sink ``thunk()`` returns, built each time it runs."""
+    return Sink(lambda upstream, scope: thunk()._transform(upstream, scope))
+
+
+def fail[E](error: E) -> Sink[Never, object, Never, E]:
+    """A sink that reads nothing and fails with ``error``."""
+    return from_effect_end(_effect.fail(error))
+
+
+def fail_sync[E](thunk: Callable[[], E]) -> Sink[Never, object, Never, E]:
+    """A sink that reads nothing and fails with ``thunk()``."""
+    return from_effect_end(_effect.fail_sync(thunk))
+
+
+def fail_cause[E](cause: Cause[E]) -> Sink[Never, object, Never, E]:
+    """A sink that reads nothing and fails with ``cause``."""
+    return from_effect_end(_effect.fail_cause(cause))
+
+
+def fail_cause_sync[E](thunk: Callable[[], Cause[E]]) -> Sink[Never, object, Never, E]:
+    """A sink that reads nothing and fails with the cause ``thunk()``."""
+    return from_effect_end(_effect.fail_cause_sync(thunk))
+
+
+def die(defect: BaseException) -> Sink[Never]:
+    """A sink that reads nothing and dies with ``defect``."""
+    return from_effect_end(_effect.die(defect))
+
+
+never: Sink[Never] = from_effect_end(_effect.never)
+"""A sink that reads nothing and never ends."""
+
+
+def _drain(upstream: Upstream[object], _scope: CloseableScope) -> Effect[End[None]]:
+    return catch_done(PullLoop(upstream, _ignore), lambda _: _END_VOID)
+
+
+drain: Sink[None] = Sink(_drain)
+"""A sink that reads all of its input and succeeds with ``None``."""
+
+timed: Sink[float] = map_end(with_duration(drain), lambda end: (end[0][1], None))
+"""A sink that reads all of its input and succeeds with how long that
+took, in seconds."""
+
+
+def from_queue[A](queue: Enqueue[A, Done]) -> Sink[None, A]:
+    """A sink that offers its input to ``queue`` and ends the queue when the
+    input ends."""
+
+    def transform(upstream: Upstream[A], _scope: CloseableScope) -> AnyEffect:
+        offered = PullLoop(upstream.flat_map(queue.offer_all), _ignore)
+        return catch_done(offered, lambda _: queue.end().and_then(_END_VOID))
+
+    return Sink(transform)
+
+
+def from_pubsub[A](pubsub: PubSub[A]) -> Sink[None, A]:
+    """A sink that publishes its input to ``pubsub``."""
+    return for_each_array(pubsub.publish_all)

pyfect/sink/_context.py

@@ -0,0 +1,87 @@
+"""Services for sinks: the curried providers (used with ``.pipe``, since
+they remove what they provide from ``R``) and ``unwrap``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from typing import Any, Never, overload
+
+from pyfect._core import Effect, _Locally
+from pyfect._effect_args import require_effect
+from pyfect.context import Context, TagLike, tag_class
+from pyfect.scope import CloseableScope, Scope
+from pyfect.sink._combinators import transform_effect
+from pyfect.sink._sink import AnySink, Sink, Upstream, require_sink
+
+type Sink_ = Sink[Any, Any, Any, Any, Any]
+
+
+class _ProvideService[S, T]:
+    __slots__ = ("service", "tag")
+
+    def __init__(self, tag: type[Any], service: S) -> None:
+        self.tag = tag
+        self.service = service
+
+    @overload
+    def __call__[A, In, L, E](self, sink: Sink[A, In, L, E, T]) -> Sink[A, In, L, E]: ...
+    @overload
+    def __call__[A, In, L, E, R](self, sink: Sink[A, In, L, E, T | R]) -> Sink[A, In, L, E, R]: ...
+    def __call__(self, sink: AnySink) -> Sink_:
+        require_sink(sink, "sink")
+        tag, service = self.tag, self.service
+        return transform_effect(sink, lambda eff: _Locally(eff, lambda ctx: ctx.add(tag, service)))
+
+
+def provide_service[S, T](tag: TagLike[S, T], service: S) -> _ProvideService[S, T]:
+    """Provide one service to a sink and remove it from ``R``::
+
+    sink.pipe(provide_service(Database, InMemoryDb()))
+    """
+    return _ProvideService(tag_class(tag), service)
+
+
+class _ProvideContext[RO]:
+    __slots__ = ("ctx",)
+
+    def __init__(self, ctx: Context[RO]) -> None:
+        self.ctx = ctx
+
+    @overload
+    def __call__[A, In, L, E](self, sink: Sink[A, In, L, E, RO]) -> Sink[A, In, L, E]: ...
+    @overload
+    def __call__[A, In, L, E, R](self, sink: Sink[A, In, L, E, RO | R]) -> Sink[A, In, L, E, R]: ...
+    def __call__(self, sink: AnySink) -> Sink_:
+        require_sink(sink, "sink")
+        ctx = self.ctx
+        return transform_effect(sink, lambda eff: _Locally(eff, lambda current: current.merge(ctx)))
+
+
+def provide_context[RO](ctx: Context[RO]) -> _ProvideContext[RO]:
+    """Provide every service of ``ctx`` to a sink and remove them from
+    ``R``::
+
+    sink.pipe(provide_context(ctx))
+    """
+    return _ProvideContext(ctx)
+
+
+@overload
+def unwrap[A, In, L, EE = Never, RR = Never](
+    eff: Effect[Sink[A, In, L, EE, RR], EE, Scope],
+) -> Sink[A, In, L, EE, RR]: ...
+@overload
+def unwrap[A, In, L, EE = Never, RR = Never](
+    eff: Effect[Sink[A, In, L, EE, RR], EE, Scope | RR],
+) -> Sink[A, In, L, EE, RR]: ...
+def unwrap(eff: Effect[AnySink, Any, Any]) -> Sink_:
+    """The sink ``eff`` succeeds with, built each time it runs. ``eff``
+    runs with the sink's ``Scope``, so its resources live as long as the
+    sink's run."""
+    require_effect(eff, "eff")
+
+    def transform(upstream: Upstream[Any], scope: CloseableScope) -> Effect[Any, Any, Any]:
+        built: Effect[AnySink, Any, Any] = _Locally(eff, lambda ctx: ctx.add(Scope, scope))
+        return built.flat_map(lambda sink: sink._transform(upstream, scope))
+
+    return Sink(transform)

pyfect/sink/_folds.py

@@ -0,0 +1,336 @@
+"""Sinks that fold their input into a state: ``fold``, the ``reduce``
+family, and the folds with a fixed answer (``sum``, ``count``,
+``collect``, ``head``, ``last``, ``find``, ``every``, ``some``).
+
+The ``*_while`` folds stop reading as soon as the state fails the
+predicate; the item-by-item ones leave the rest of that chunk over.
+"""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, Never, TypeIs, overload
+
+from pyfect._core import Effect, _Gen, _Succeed, _Sync
+from pyfect.option import Option, Some
+from pyfect.pull import catch_done
+from pyfect.scope import CloseableScope
+from pyfect.sink._constructors import sync
+from pyfect.sink._sink import End, Sink, Upstream
+from pyfect.sink._steps import ENDED, VOID, read_until_done
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+
+
+def _rest(chunk: Chunk, start: int) -> Chunk | None:
+    return chunk[start:] or None
+
+
+# --- folds with an effect per item ---------------------------------------------
+
+
+def fold[S, In, E = Never, R = Never](
+    initial: Callable[[], S],
+    cont: Callable[[S], bool],
+    f: Callable[[S, In], Effect[S, E, R]],
+) -> Sink[S, In, In, E, R]:
+    """Fold each item into ``initial()`` with ``f`` while ``cont(state)``
+    holds; once it fails, end with the state and the rest of the chunk as
+    leftovers. ``cont`` is first asked after the first item."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+
+        def body() -> Generator[AnyEffect, Any, End[S, In]]:
+            nonlocal state
+            while True:
+                chunk = yield upstream
+                for i, item in enumerate(chunk):
+                    state = yield f(state, item)
+                    if not cont(state):
+                        return (state, _rest(chunk, i + 1))
+
+        return catch_done(_Gen(body), lambda _: _Sync(lambda: (state, None)))
+
+    return Sink(transform)
+
+
+def fold_array[S, In, E = Never, R = Never](
+    initial: Callable[[], S],
+    cont: Callable[[S], bool],
+    f: Callable[[S, tuple[In, ...]], Effect[S, E, R]],
+) -> Sink[S, In, Never, E, R]:
+    """``fold`` a chunk at a time; nothing is left over."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            def keep(next_state: S) -> AnyEffect:
+                nonlocal state
+                state = next_state
+                return VOID if cont(state) else ENDED
+
+            return f(state, chunk).flat_map(keep)
+
+        return read_until_done(upstream.flat_map(step), lambda: (state, None))
+
+    return Sink(transform)
+
+
+def fold_until[S, In, E = Never, R = Never](
+    initial: Callable[[], S], max: int, f: Callable[[S, In], Effect[S, E, R]]
+) -> Sink[S, In, In, E, R]:
+    """Fold at most ``max`` items into ``initial()`` with ``f``. With
+    ``max`` 0 or less the sink reads nothing."""
+    if max <= 0:
+        return sync(initial)
+
+    def start() -> tuple[S, int]:
+        return (initial(), 0)
+
+    def below_max(pair: tuple[S, int]) -> bool:
+        return pair[1] < max
+
+    def step(pair: tuple[S, int], item: In) -> Effect[tuple[S, int], E, R]:
+        return f(pair[0], item).map(lambda state: (state, pair[1] + 1))
+
+    return fold(start, below_max, step).map(lambda pair: pair[0])
+
+
+def _fold_bool[In](start: bool, predicate: Callable[[In], bool]) -> Sink[bool, In, In]:
+    """Fold to ``predicate(item)`` until it differs from ``start``."""
+
+    def step(_: bool, item: In) -> Effect[bool]:
+        return _Succeed(predicate(item))
+
+    return fold(lambda: start, lambda found: found == start, step)
+
+
+def every[In](predicate: Callable[[In], bool]) -> Sink[bool, In, In]:
+    """``True`` if ``predicate`` holds for every item; stops at the first
+    item it fails for."""
+    return _fold_bool(True, predicate)
+
+
+def some[In](predicate: Callable[[In], bool]) -> Sink[bool, In, In]:
+    """``True`` if ``predicate`` holds for some item; stops at the first
+    item it holds for."""
+    return _fold_bool(False, predicate)
+
+
+def reduce_while_effect[S, In, E = Never, R = Never](
+    initial: Callable[[], S],
+    predicate: Callable[[S], bool],
+    f: Callable[[S, In], Effect[S, E, R]],
+) -> Sink[S, In, In, E, R]:
+    """Reduce each item into ``initial()`` with ``f`` while
+    ``predicate(state)`` holds, asking it of ``initial()`` first; the rest
+    of the chunk is left over."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+        leftover: Chunk | None = None
+        if not predicate(state):
+            return _Succeed((state, None))
+
+        def step(chunk: Chunk) -> AnyEffect:
+            def body() -> Generator[AnyEffect, Any, AnyEffect]:
+                nonlocal state, leftover
+                for i, item in enumerate(chunk):
+                    state = yield f(state, item)
+                    if not predicate(state):
+                        leftover = _rest(chunk, i + 1)
+                        return ENDED
+                return VOID
+
+            return _Gen(body).flatten()
+
+        return read_until_done(upstream.flat_map(step), lambda: (state, leftover))
+
+    return Sink(transform)
+
+
+def reduce_effect[S, In, E = Never, R = Never](
+    initial: Callable[[], S], f: Callable[[S, In], Effect[S, E, R]]
+) -> Sink[S, In, Never, E, R]:
+    """Reduce every item into ``initial()`` with ``f``."""
+    reduced: Sink[S, In, Any, E, R] = reduce_while_effect(initial, lambda _: True, f)
+    return reduced
+
+
+def reduce_while_array_effect[S, In, E = Never, R = Never](
+    initial: Callable[[], S],
+    predicate: Callable[[S], bool],
+    f: Callable[[S, tuple[In, ...]], Effect[S, E, R]],
+) -> Sink[S, In, Never, E, R]:
+    """``reduce_while_effect`` a chunk at a time; nothing is left over."""
+
+    def transform(upstream: Upstream[In], scope: CloseableScope) -> AnyEffect:
+        state = initial()
+        if not predicate(state):
+            return _Succeed((state, None))
+        return fold_array(lambda: state, predicate, f)._transform(upstream, scope)
+
+    return Sink(transform)
+
+
+# --- pure folds -------------------------------------------------------------------
+
+
+def reduce_while[S, In](
+    initial: Callable[[], S], predicate: Callable[[S], bool], f: Callable[[S, In], S]
+) -> Sink[S, In, In]:
+    """Reduce each item into ``initial()`` with ``f`` while
+    ``predicate(state)`` holds, asking it of ``initial()`` first; the rest
+    of the chunk is left over."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+        leftover: Chunk | None = None
+        if not predicate(state):
+            return _Succeed((state, None))
+
+        def step(chunk: Chunk) -> AnyEffect:
+            nonlocal state, leftover
+            for i, item in enumerate(chunk):
+                state = f(state, item)
+                if not predicate(state):
+                    leftover = _rest(chunk, i + 1)
+                    return ENDED
+            return VOID
+
+        return read_until_done(upstream.flat_map(step), lambda: (state, leftover))
+
+    return Sink(transform)
+
+
+def reduce_while_array[S, In](
+    initial: Callable[[], S], predicate: Callable[[S], bool], f: Callable[[S, tuple[In, ...]], S]
+) -> Sink[S, In]:
+    """``reduce_while`` a chunk at a time; nothing is left over."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+        if not predicate(state):
+            return _Succeed((state, None))
+
+        def step(chunk: tuple[In, ...]) -> AnyEffect:
+            nonlocal state
+            state = f(state, chunk)
+            return VOID if predicate(state) else ENDED
+
+        return read_until_done(upstream.flat_map(step), lambda: (state, None))
+
+    return Sink(transform)
+
+
+def reduce_array[S, In](
+    initial: Callable[[], S], f: Callable[[S, tuple[In, ...]], S]
+) -> Sink[S, In]:
+    """Reduce every chunk into ``initial()`` with ``f``."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        state = initial()
+
+        def step(chunk: tuple[In, ...]) -> None:
+            nonlocal state
+            state = f(state, chunk)
+
+        return read_until_done(upstream.map(step), lambda: (state, None))
+
+    return Sink(transform)
+
+
+def reduce[S, In](initial: Callable[[], S], f: Callable[[S, In], S]) -> Sink[S, In]:
+    """Reduce every item into ``initial()`` with ``f``."""
+
+    def reduce_chunk(state: S, chunk: tuple[In, ...]) -> S:
+        for item in chunk:
+            state = f(state, item)
+        return state
+
+    return reduce_array(initial, reduce_chunk)
+
+
+def _add_up(total: Any, chunk: Chunk) -> Any:
+    return total + sum(chunk)
+
+
+def sum_[N: (int, float)]() -> Sink[N, N]:
+    """A sink adding up its input (``0`` for none). Effect's ``Sink.sum``,
+    a function here so the result has the input's type."""
+    summed: Sink[Any, Any] = reduce_array(int, _add_up)
+    return summed
+
+
+def _count(n: int, chunk: Chunk) -> int:
+    return n + len(chunk)
+
+
+count: Sink[int] = reduce_array(int, _count)
+"""A sink counting its input."""
+
+
+def _extend(items: list[Any], chunk: Chunk) -> list[Any]:
+    items.extend(chunk)
+    return items
+
+
+def collect[In]() -> Sink[list[In], In]:
+    """A sink collecting its input in a list."""
+    return reduce_array(list, _extend)
+
+
+def _nothing() -> Option[Any]:
+    return None
+
+
+def _not_found(found: Option[Any]) -> bool:
+    return found is None
+
+
+def _first(_: Option[Any], item: Any) -> Option[Any]:
+    return Some(item)
+
+
+def _last(_: Option[Any], chunk: Chunk) -> Option[Any]:
+    return Some(chunk[-1])
+
+
+def head[In]() -> Sink[Option[In], In, In]:
+    """``Some`` of the first item (the rest of its chunk is left over), or
+    ``None`` if there is none."""
+    return reduce_while(_nothing, _not_found, _first)
+
+
+def last[In]() -> Sink[Option[In], In]:
+    """``Some`` of the last item, or ``None`` if there is none."""
+    return reduce_array(_nothing, _last)
+
+
+@overload
+def find[In, B](refinement: Callable[[In], TypeIs[B]]) -> Sink[Option[B], In, In]: ...
+@overload
+def find[In](refinement: Callable[[In], bool]) -> Sink[Option[In], In, In]: ...
+def find(refinement: Callable[[Any], bool]) -> Sink[Option[Any], Any, Any]:
+    """``Some`` of the first item ``predicate`` holds for (the rest of its
+    chunk is left over), or ``None``."""
+
+    def check(found: Option[Any], item: Any) -> Option[Any]:
+        return Some(item) if refinement(item) else found
+
+    return reduce_while(_nothing, _not_found, check)
+
+
+def find_effect[In, E = Never, R = Never](
+    predicate: Callable[[In], Effect[bool, E, R]],
+) -> Sink[Option[In], In, In, E, R]:
+    """``find`` with an effectful ``predicate``."""
+
+    def check(found: Option[In], item: In) -> Effect[Option[In], E, R]:
+        return predicate(item).map(lambda ok: Some(item) if ok else found)
+
+    return reduce_while_effect(_nothing, _not_found, check)

pyfect/sink/_for_each.py

@@ -0,0 +1,87 @@
+"""Sinks that run an effect on their input: ``for_each``,
+``for_each_array``, ``for_each_while`` and ``for_each_while_array``."""
+# pyright: reportPrivateUsage=false
+
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, Never
+
+from pyfect._core import Effect, _Gen
+from pyfect.scope import CloseableScope
+from pyfect.sink._sink import End, Sink, Upstream
+from pyfect.sink._steps import ENDED, VOID, read_until_done
+
+type AnyEffect = Effect[Any, Any, Any]
+type Chunk = tuple[Any, ...]
+
+
+def _no_value() -> End[None]:
+    return (None, None)
+
+
+def _until_done(step: AnyEffect) -> Effect[End[None], Any, Any]:
+    return read_until_done(step, _no_value)
+
+
+def for_each_array[In, E = Never, R = Never](
+    f: Callable[[tuple[In, ...]], Effect[object, E, R]],
+) -> Sink[None, In, Never, E, R]:
+    """A sink that runs ``f`` on each chunk of its input, in order."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        return _until_done(upstream.flat_map(f))
+
+    return Sink(transform)
+
+
+def for_each[In, E = Never, R = Never](
+    f: Callable[[In], Effect[object, E, R]],
+) -> Sink[None, In, Never, E, R]:
+    """A sink that runs ``f`` on each item of its input, in order."""
+
+    def each(chunk: Chunk) -> AnyEffect:
+        if len(chunk) == 1:
+            return f(chunk[0])
+
+        def body() -> Generator[AnyEffect, Any]:
+            for item in chunk:
+                yield f(item)
+
+        return _Gen(body)
+
+    return for_each_array(each)
+
+
+def _go_on(more: bool) -> AnyEffect:
+    return VOID if more else ENDED
+
+
+def for_each_while_array[In, E = Never, R = Never](
+    f: Callable[[tuple[In, ...]], Effect[bool, E, R]],
+) -> Sink[None, In, Never, E, R]:
+    """A sink that runs ``f`` on each chunk until it succeeds with
+    ``False``; the sink stops reading there."""
+
+    def transform(upstream: Upstream[In], _scope: CloseableScope) -> AnyEffect:
+        return _until_done(upstream.flat_map(f).flat_map(_go_on))
+
+    return Sink(transform)
+
+
+def for_each_while[In, E = Never, R = Never](
+    f: Callable[[In], Effect[bool, E, R]],
+) -> Sink[None, In, Never, E, R]:
+    """A sink that runs ``f`` on each item until it succeeds with
+    ``False``; the sink stops reading there."""
+
+    def each(chunk: Chunk) -> Effect[bool, Any, Any]:
+        def body() -> Generator[AnyEffect, Any, bool]:
+            for item in chunk:
+                if not (yield f(item)):
+                    return False
+            return True
+
+        return _Gen(body)
+
+    return for_each_while_array(each)