@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/streams/{pipeline.md → core/pipeline.md}

@@ -1,6 +1,14 @@
 ---
 id: pipeline
 title: "Pipeline"
+sidebar_label: "Pipeline"
+description: "The reusable stream transformation: its synchronous and asynchronous factories, andThen composition, and the two routes for applying one."
+keywords:
+  - "Stream Transformation"
+  - "Pipeline Composition"
+  - "Async Pipeline Stages"
+  - "Primitive Specialization"
+  - "Pipeline"
 ---
 
 `Pipeline[-In, +Out]` is a **reusable, composable stream transformation** that converts elements of type `In` into elements of type `Out`. Pipelines are first-class values: you can define them once, compose them with `andThen`, and apply them to any [Stream](./stream.md) via `stream.via(pipe)` or to any `Sink` via `pipe.andThenSink(sink)`.
@@ -96,7 +104,11 @@ These laws guarantee that pipelines compose predictably, regardless of how you p
 
 ## Construction
 
-Pipelines are built using factory methods on the `Pipeline` companion object. Each factory creates a pipeline that performs a specific transformation: mapping elements, filtering, collecting, or controlling flow. All factories support JVM primitive specialization through implicit `JvmType.Infer` parameters.
+Pipelines are built using factory methods on the `Pipeline` companion object. Each factory creates a pipeline that performs a specific transformation: mapping elements, filtering, collecting, or controlling flow. A factory that applies a user-supplied function to produce a new element type asks for `JvmType.Infer` evidence for the **result** type; the one exception is the `map` overload for a function returning `Nothing`, which takes a `DummyImplicit` and supplies the boxed lane itself. The input representation already belongs to the stream or sink at application time; callers do not supply redundant input evidence. Type-preserving factories, and the structural factories `buffer` and `chunked`, retain or rebuild that representation without call-site evidence.
+
+Three of those factories have asynchronous twins, and exactly three: `mapAsync`, `filterAsync`, and `collectAsync`. They are cross-platform, their callbacks return [`Async`](../../async.md), they are evaluated sequentially as the downstream pulls, and they work through both application routes. Other `*Async` operators such as `tapEachAsync` and `distinctByAsync` exist on `Stream` rather than on `Pipeline`; see [Asynchronous Stream Execution](../execution-and-compatibility/async-execution.md#async-operators) for the full stream-level list. `Writer`'s similarly named deferred methods are something else again — adaptation wrappers around its synchronous operations, described in [Writer — Asynchronous Writes](../primitives/writer.md#asynchronous-writes).
+
+Factory callbacks are protected as user callbacks: synchronous throws and failed callback effects are defects, not typed stream errors. When a pipeline is applied to a sink, both drain paths close the derived reader. Cancellation closes upstream and downstream state, and a cleanup failure is attached to an existing failure rather than hiding it.
 
 ### `Pipeline.map[A, B]` — Transform Each Element
 
@@ -104,7 +116,7 @@ Applies a function to every element, producing a new element type. Here is the s
 
 ```scala
 object Pipeline {
-  def map[A, B](f: A => B)(implicit jtA: JvmType.Infer[A], jtB: JvmType.Infer[B]): Pipeline[A, B]
+  def map[A, B](f: A => B)(implicit jtB: JvmType.Infer[B]): Pipeline[A, B]
 }
 ```
 
@@ -114,21 +126,44 @@ This is the most common pipeline constructor:
 import zio.blocks.streams.*
 
 val doubler = Pipeline.map[Int, Int](_ * 2)
-// doubler: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$MapPipeline@5751527e
+// doubler: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$MapPipeline@2bf42ef7
 val toStr = Pipeline.map[Int, String](_.toString)
-// toStr: Pipeline[Int, String] = zio.blocks.streams.Pipeline$MapPipeline@21969325
+// toStr: Pipeline[Int, String] = zio.blocks.streams.Pipeline$MapPipeline@29332a5b
 
 val result = Stream(1, 2, 3).via(doubler).runCollect
 // result: Either[Nothing, Chunk[Int]] = Right(IndexedSeq(2, 4, 6))
 ```
 
+### `Pipeline.mapAsync[A, B]` — Transform Each Element Asynchronously
+
+The asynchronous twin of `map`. The callback returns an `Async`, and each one is awaited before the next element is pulled, so at most one invocation is in flight and input order is preserved. Here is the signature:
+
+```scala
+object Pipeline {
+  def mapAsync[A, B](f: A => Async[B])(implicit jtB: JvmType.Infer[B]): Pipeline[A, B]
+}
+```
+
+Like `map`, it asks for `JvmType.Infer` evidence for its result type only. A failed or defective `Async` fails the stream as a defect rather than through its typed error channel, and cancellation of a suspended callback is propagated:
+
+```scala
+import zio.blocks.async.*
+import zio.blocks.streams.*
+
+val lookup = Pipeline.mapAsync[Int, String](id => Async.succeed(s"user-$id"))
+// lookup: Pipeline[Int, String] = zio.blocks.streams.Pipeline$$anon$4@117b2316
+
+val result = Stream(1, 2, 3).via(lookup).runCollectAsync
+// result: Async[Either[Nothing, Chunk[String]]] = zio.blocks.async.Async$slowPath$FoldCausePollable@2def46ea
+```
+
 ### `Pipeline.filter[A]` — Keep Matching Elements
 
 Keeps only elements that satisfy a predicate. Here is the signature:
 
 ```scala
 object Pipeline {
-  def filter[A](pred: A => Boolean)(implicit jtA: JvmType.Infer[A]): Pipeline[A, A]
+  def filter[A](pred: A => Boolean): Pipeline[A, A]
 }
 ```
 
@@ -138,19 +173,42 @@ Note that the output type is the same as the input type — filtering does not c
 import zio.blocks.streams.*
 
 val positives = Pipeline.filter[Int](_ > 0)
-// positives: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$FilterPipeline@2148b90d
+// positives: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$FilterPipeline@39c3da53
 
 val result = Stream(-2, -1, 0, 1, 2).via(positives).runCollect
 // result: Either[Nothing, Chunk[Int]] = Right(IndexedSeq(1, 2))
 ```
 
+### `Pipeline.filterAsync[A]` — Keep Matching Elements Asynchronously
+
+The asynchronous twin of `filter`. Elements are tested sequentially and in input order, and an element is emitted only when its `Async` yields `true`. Here is the signature:
+
+```scala
+object Pipeline {
+  def filterAsync[A](f: A => Async[Boolean]): Pipeline[A, A]
+}
+```
+
+Like `filter`, it is type-preserving and therefore takes no `JvmType.Infer` evidence — it keeps whatever representation the stream or sink supplies. A failed predicate effect is a defect, and cancellation of a suspended predicate is propagated:
+
+```scala
+import zio.blocks.async.*
+import zio.blocks.streams.*
+
+val allowed = Pipeline.filterAsync[Int](n => Async.succeed(n % 3 == 0))
+// allowed: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$$anon$2@7313125c
+
+val result = Stream(1, 2, 3, 4, 5, 6).via(allowed).runCollectAsync
+// result: Async[Either[Nothing, Chunk[Int]]] = zio.blocks.async.Async$slowPath$FoldCausePollable@76cf0fc6
+```
+
 ### `Pipeline.collect[A, B]` — Partial Function Transformation
 
 Applies a partial function: only elements for which the function is defined pass through, and they are transformed to the output type. This combines filtering and mapping in one step. Here is the signature:
 
 ```scala
 object Pipeline {
-  def collect[A, B](pf: PartialFunction[A, B])(implicit jtA: JvmType.Infer[A], jtB: JvmType.Infer[B]): Pipeline[A, B]
+  def collect[A, B](pf: PartialFunction[A, B])(implicit jtB: JvmType.Infer[B]): Pipeline[A, B]
 }
 ```
 
@@ -160,12 +218,37 @@ Use `collect` when you need to filter and transform simultaneously:
 import zio.blocks.streams.*
 
 val extractInts = Pipeline.collect[Any, Int] { case n: Int => n }
-// extractInts: Pipeline[Any, Int] = zio.blocks.streams.Pipeline$CollectPipeline@63a54682
+// extractInts: Pipeline[Any, Int] = zio.blocks.streams.Pipeline$CollectPipeline@5fa160de
 
 val result = Stream(1, "a", 2, "b", 3).via(extractInts).runCollect
 // result: Either[Nothing, Chunk[Int]] = Right(IndexedSeq(1, 2, 3))
 ```
 
+### `Pipeline.collectAsync[A, B]` — Asynchronous Filtering Transformation
+
+The asynchronous twin of `collect`, with one shape difference worth noticing: where `collect` takes a `PartialFunction[A, B]`, `collectAsync` takes a total function returning `Async[Option[B]]`. A `None` drops the element and a `Some` emits its value. Here is the signature:
+
+```scala
+object Pipeline {
+  def collectAsync[A, B](f: A => Async[Option[B]])(implicit jtB: JvmType.Infer[B]): Pipeline[A, B]
+}
+```
+
+Elements are evaluated sequentially and in input order, and like `collect` the factory asks for `JvmType.Infer` evidence for its result type:
+
+```scala
+import zio.blocks.async.*
+import zio.blocks.streams.*
+
+val parsePort = Pipeline.collectAsync[String, Int] { raw =>
+  Async.succeed(raw.toIntOption.filter(p => p > 0 && p <= 65535))
+}
+// parsePort: Pipeline[String, Int] = zio.blocks.streams.Pipeline$$anon$1@53159f19
+
+val result = Stream("80", "not-a-port", "8080", "99999").via(parsePort).runCollectAsync
+// result: Async[Either[Nothing, Chunk[Int]]] = zio.blocks.async.Async$slowPath$FoldCausePollable@7376af26
+```
+
 ### `Pipeline.take[A]` — First N Elements
 
 Passes through at most the first `n` elements, then stops. Here is the signature:
@@ -182,7 +265,7 @@ This naturally short-circuits — upstream stops producing once `n` elements hav
 import zio.blocks.streams.*
 
 val firstFive = Pipeline.take[Int](5)
-// firstFive: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$TakePipeline@53108fba
+// firstFive: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$TakePipeline@6dfe0469
 
 val result = Stream.range(0, 1000).via(firstFive).runCollect
 // result: Either[Nothing, Chunk[Int]] = Right(IndexedSeq(0, 1, 2, 3, 4))
@@ -204,7 +287,7 @@ Use `drop` to skip headers, metadata, or warm-up elements:
 import zio.blocks.streams.*
 
 val skipHeader = Pipeline.drop[String](1)
-// skipHeader: Pipeline[String, String] = zio.blocks.streams.Pipeline$DropPipeline@5e27a41e
+// skipHeader: Pipeline[String, String] = zio.blocks.streams.Pipeline$DropPipeline@586ae719
 
 val result = Stream("header", "row1", "row2").via(skipHeader).runCollect
 // result: Either[Nothing, Chunk[String]] = Right(IndexedSeq("row1", "row2"))
@@ -216,7 +299,7 @@ The identity pipeline that passes all elements through unchanged. This is the ne
 
 ```scala
 object Pipeline {
-  def identity[A](implicit jtA: JvmType.Infer[A]): Pipeline[A, A]
+  def identity[A]: Pipeline[A, A]
 }
 ```
 
@@ -226,7 +309,7 @@ You rarely construct `identity` explicitly, but it is important as a base case i
 import zio.blocks.streams.*
 
 val noOp = Pipeline.identity[Int]
-// noOp: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$MapPipeline@52ba998
+// noOp: Pipeline[Int, Int] = zio.blocks.streams.Pipeline$$anon$3@43ed8717
 
 // These are equivalent:
 // stream.via(noOp)  ==  stream
@@ -243,7 +326,7 @@ Pipelines compose into larger, more complex transformations using `andThen`. Bec
 Composes two pipelines into one, applying `this` first and `that` second. Here is the signature:
 
 ```scala
-trait Pipeline[-In, +Out] {
+abstract class Pipeline[-In, +Out] {
   def andThen[C](that: Pipeline[Out, C]): Pipeline[In, C]
 }
 ```
@@ -286,17 +369,19 @@ def buildPipeline(limit: Option[Int], onlyPositive: Boolean): Pipeline[Int, Int]
 
 Apply a pipeline to a stream using `via` to transform its output elements. This is the most direct way to use a pipeline: define it once and apply it to multiple streams without repeating the transformation logic.
 
+Applying an asynchronous pipeline stage to a synchronous stream makes the resulting stream asynchronous. There is nothing to annotate and no type that changes: `Stream[E, A]` carries no marker for which way it will materialize, so `syncStream.via(Pipeline.mapAsync(...))` has exactly the type `syncStream.via(Pipeline.map(...))` would have. What changes is how the description compiles — one asynchronous node makes the whole graph compile to an asynchronous reader, with the synchronous source lifted in place. On the JVM a blocking terminal still accepts the result; on Scala.js use an `*Async` terminal. See [Mixing synchronous and asynchronous stages](../execution-and-compatibility/async-execution.md#mixing-synchronous-and-asynchronous-stages) for how that widening works.
+
 ### `Stream#via[B]` — Apply a Pipeline to a Stream
 
 The primary way to use a pipeline is through `Stream.via`. Here is the signature:
 
 ```scala
-trait Stream[+E, +A] {
+abstract class Stream[+E, +A] {
   def via[B](pipe: Pipeline[A, B]): Stream[E, B]
 }
 ```
 
-Under the hood, `via` calls `pipe.applyToStream(this)`. Each pipeline type delegates to a specific `Stream` node — for example, `Pipeline.map` creates a `Stream.Mapped`, and `Pipeline.filter` creates a `Stream.Filtered`.
+Under the hood, `via` calls `pipe.applyToStream(this)`. Each pipeline type delegates to a specific `Stream` node — for example, `Pipeline.map` creates a `Stream.Mapped`, and `Pipeline.filter` creates a `Stream.Filtered`. Type-preserving stages propagate the incoming stream representation; transforming stages attach the `JvmType.Infer[B]` evidence for their result. Composition preserves this metadata stage by stage rather than rediscovering the original input type at the call site.
 
 The key advantage of `via` over inline methods is **reuse**: define the pipeline once and apply it to multiple streams:
 
@@ -307,7 +392,7 @@ import zio.blocks.streams.*
 val cleanSensorData: Pipeline[Double, Double] =
   Pipeline.filter[Double](d => !d.isNaN && !d.isInfinite)
     .andThen(Pipeline.filter(d => d >= -100.0 && d <= 100.0))
-// cleanSensorData: Pipeline[Double, Double] = zio.blocks.streams.Pipeline$Composed@1eea4c07
+// cleanSensorData: Pipeline[Double, Double] = zio.blocks.streams.Pipeline$Composed@1cfa8a20
 
 // Apply to different sensor streams
 val sensorStream1 = Stream(45.5, 67.2, Double.NaN, 23.1)
@@ -330,7 +415,7 @@ val sensor2Result = sensorStream2.via(cleanSensorData).runCollect
 You can also call `applyToStream` directly. This is equivalent to `via` but reads left-to-right from the pipeline's perspective. Here is the signature:
 
 ```scala
-trait Pipeline[-In, +Out] {
+abstract class Pipeline[-In, +Out] {
   def applyToStream[E](stream: Stream[E, In]): Stream[E, Out]
 }
 ```
@@ -346,7 +431,7 @@ Apply a pipeline to a sink using `andThenSink` to pre-process the sink's input e
 The dual of `via`: instead of transforming a stream's output, you pre-process a sink's input. Here is the signature:
 
 ```scala
-trait Pipeline[-In, +Out] {
+abstract class Pipeline[-In, +Out] {
   def andThenSink[E, Z](sink: Sink[E, Out, Z]): Sink[E, In, Z]
 }
 ```
@@ -358,19 +443,19 @@ import zio.blocks.streams.*
 
 // A pipeline that normalizes strings
 val normalize = Pipeline.map[String, String](_.trim.toLowerCase)
-// normalize: Pipeline[String, String] = zio.blocks.streams.Pipeline$MapPipeline@2a3c97bf
+// normalize: Pipeline[String, String] = zio.blocks.streams.Pipeline$MapPipeline@68b9a3a0
 
 // Apply to different sinks
 val collectNormalized = normalize.andThenSink(Sink.collectAll[String])
-// collectNormalized: Sink[Nothing, String, Chunk[String]] = zio.blocks.streams.Sink$Contramapped@7c1204c4
+// collectNormalized: Sink[Nothing, String, Chunk[String]] = zio.blocks.streams.Sink$Contramapped@793ea2aa
 val countNormalized   = normalize.andThenSink(Sink.count)
-// countNormalized: Sink[Nothing, String, Long] = zio.blocks.streams.Sink$Contramapped@3a99eae2
+// countNormalized: Sink[Nothing, String, Long] = zio.blocks.streams.Sink$Contramapped@1bae43d7
 
 val result = Stream("  Hello ", " WORLD  ").run(collectNormalized)
 // result: Either[Nothing, Chunk[String]] = Right(IndexedSeq("hello", "world"))
 ```
 
-### When to Use `andThenSink` vs `via`
+### When to Use `andThenSink` Vs `via`
 
 Both achieve the same result. Choose based on which side you want to reuse:
 
@@ -386,7 +471,7 @@ The laws guarantee equivalence: `stream.via(pipe).run(sink) == stream.run(pipe.a
 `andThenSink` is an alias for `applyToSink`. Here is the signature:
 
 ```scala
-trait Pipeline[-In, +Out] {
+abstract class Pipeline[-In, +Out] {
   def applyToSink[E, Z](sink: Sink[E, Out, Z]): Sink[E, In, Z]
 }
 ```
@@ -395,9 +480,11 @@ Prefer `andThenSink` for readability.
 
 ## JVM Primitive Specialization
 
-`Pipeline.map`, `Pipeline.filter`, `Pipeline.collect`, and `Pipeline.identity` all require `JvmType.Infer[A]` implicit parameters. These are resolved at compile time and enable unboxed, specialized code paths for primitive types (`Int`, `Long`, `Float`, `Double`, etc.). You never need to provide these explicitly — the compiler infers them automatically.
+`Pipeline.map`, `Pipeline.collect`, and their asynchronous counterparts `mapAsync` and `collectAsync` require `JvmType.Infer` for the transformed result type, except for the `map` overload whose function returns `Nothing`, which fixes the boxed lane itself and takes a `DummyImplicit` instead. It is resolved automatically and records which of the nine logical lanes that result belongs to: the eight JVM primitives, or the reference fallback. Those nine logical lanes compact into five interpreter storage lanes — int-like (`Boolean`, `Byte`, `Short`, `Char`, `Int`), `Long`, `Float`, `Double`, and reference — with operator tags selecting the identity-specific reads over them. Nine lanes therefore does not mean nine interpreter arrays; see [Zero-Boxing Streams](../execution-and-compatibility/zero-boxing.md) for how one is chosen. None of these factories request call-site evidence for the input type.
 
-`Pipeline.take` and `Pipeline.drop` do not require `JvmType.Infer` because they do not inspect or transform element values — they only count positions.
+Type-preserving factories such as `filter`, `filterAsync`, `identity`, `take`, `drop`, and `buffer` do not require `JvmType.Infer`: they preserve the representation supplied when the pipeline is applied.
+
+The rules hold identically through both application routes. On the stream route, result evidence is stored on the transformed stream node. On the sink route, mapping passes the same result evidence to the sink's contramap machinery, and structural pipelines use the generic run-via-sink route. So `stream.via(pipe)`, `pipe.andThenSink(sink)`, and `pipe.applyToSink(sink)` preserve the same specialization information as well as the same semantics.
 
 ## Integration
 
@@ -426,25 +513,9 @@ cd zio-blocks
 
 ### Basic Usage
 
-This example demonstrates all six Pipeline factory methods: `map`, `filter`, `collect`, `take`, `drop`, and `identity`. Here is the source code:
+This example demonstrates six of the Pipeline factory methods: `map`, `filter`, `collect`, `take`, `drop`, and `identity`. Here is the source code:
 
 ```scala title="streams-examples/src/main/scala/pipeline/PipelineBasicUsageExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package pipeline
 
 import zio.blocks.streams.*
@@ -508,22 +579,6 @@ sbt "streams-examples/runMain pipeline.PipelineBasicUsageExample"
 This example shows how to compose pipelines with `andThen`, apply them to multiple streams, and build pipelines conditionally. Here is the source code:
 
 ```scala title="streams-examples/src/main/scala/pipeline/PipelineCompositionExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package pipeline
 
 import zio.blocks.streams.*
@@ -618,22 +673,6 @@ sbt "streams-examples/runMain pipeline.PipelineCompositionExample"
 This example demonstrates applying pipelines to sinks with `andThenSink`, showing the equivalence between `stream.via(pipe).run(sink)` and `stream.run(pipe.andThenSink(sink))`. Here is the source code:
 
 ```scala title="streams-examples/src/main/scala/pipeline/PipelineSinkIntegrationExample.scala" 
-/*
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
 package pipeline
 
 import zio.blocks.streams.*
@@ -716,3 +755,100 @@ Run it with:
 ```bash
 sbt "streams-examples/runMain pipeline.PipelineSinkIntegrationExample"
 ```
+
+### Asynchronous Stages Through Both Routes
+
+This example builds `mapAsync`, `filterAsync`, and `collectAsync` into one composed pipeline value, then applies that same value through `stream.via(pipe)`, `pipe.andThenSink(sink)`, and `pipe.applyToSink(sink)` — showing that all three produce the same elements. Here is the source code:
+
+```scala title="streams-examples/src/main/scala/pipeline/PipelineAsyncExample.scala" 
+package pipeline
+
+import zio.blocks.async.*
+import zio.blocks.chunk.Chunk
+import zio.blocks.streams.*
+
+/**
+ * The three asynchronous `Pipeline` factories — `mapAsync`, `filterAsync` and
+ * `collectAsync` — built once as values and then applied through both routes:
+ * `stream.via(pipe)` and `pipe.andThenSink(sink)` (with `pipe.applyToSink` as
+ * the third spelling of the second route).
+ *
+ * The point of running both is that they agree. A pipeline is a description,
+ * not a stage bound to one side of the graph, so the same value produces the
+ * same elements whichever end it is attached to.
+ *
+ * JVM only, because it ends in `.block` to turn an `Async` into a value for
+ * `main`.
+ */
+object PipelineAsyncExample {
+
+  /** Each field of a raw record, as a trimmed reading. */
+  private val readings: Stream[Nothing, String] =
+    Stream(" 17 ", "  4", "31  ", " 8 ", "  ", "150")
+
+  /**
+   * `mapAsync` — one asynchronous callback per element, awaited before the next
+   * element is pulled. It asks for `JvmType.Infer` evidence for `Int`, its
+   * result type, and nothing for its input.
+   */
+  private val parse: Pipeline[String, Int] =
+    Pipeline
+      .mapAsync[String, String](raw => Async.succeed(raw.trim))
+      .andThen(Pipeline.mapAsync[String, Int](t => Async.succeed(if (t.isEmpty) 0 else t.toInt)))
+
+  /** `filterAsync` — type-preserving, so it needs no result evidence. */
+  private val inRange: Pipeline[Int, Int] =
+    Pipeline.filterAsync[Int](n => Async.succeed(n > 0 && n <= 100))
+
+  /**
+   * `collectAsync` — filter and transform in one callback. It returns
+   * `Async[Option[B]]` rather than a `PartialFunction`: a `None` drops the
+   * element, a `Some` emits its value.
+   */
+  private val tensDigit: Pipeline[Int, Int] =
+    Pipeline.collectAsync[Int, Int](n => Async.succeed(if (n >= 10) Some(n / 10) else None))
+
+  /** One composed value, applied unchanged through both routes below. */
+  private val pipe: Pipeline[String, Int] =
+    parse.andThen(inRange).andThen(tensDigit)
+
+  def main(args: Array[String]): Unit = {
+    val sink: Sink[Nothing, Int, Chunk[Int]] = Sink.collectAll[Int]
+
+    // Route 1 — attach the pipeline to the stream, then run a plain sink.
+    val viaStream = readings.via(pipe).runAsync(sink).block
+
+    // Route 2 — attach the pipeline to the sink, then run the plain stream.
+    val viaSink = readings.runAsync(pipe.andThenSink(sink)).block
+
+    // The third spelling: `andThenSink` is an alias for `applyToSink`.
+    val viaApplyToSink = readings.runAsync(pipe.applyToSink(sink)).block
+
+    report("stream.via(pipe)", viaStream)
+    report("pipe.andThenSink(sink)", viaSink)
+    report("pipe.applyToSink(sink)", viaApplyToSink)
+    println(s"routes agree: ${viaStream == viaSink && viaSink == viaApplyToSink}")
+  }
+
+  private def report[E, Z](label: String, result: Either[E, Z]): Unit =
+    result match {
+      case Right(value) => println(s"$label -> $value")
+      case Left(error)  => println(s"$label -> typed error: $error")
+    }
+}
+```
+
+([source](https://github.com/zio/zio-blocks/blob/main/streams-examples/src/main/scala/pipeline/PipelineAsyncExample.scala))
+
+Run it with:
+
+```bash
+sbt "streams-examples/runMain pipeline.PipelineAsyncExample"
+```
+
+## See Also
+
+- [Asynchronous Stream Execution](../execution-and-compatibility/async-execution.md#async-operators) — the stream-level `*Async` operators the three asynchronous factories delegate to, and how a mixed graph compiles
+- [Stream](./stream.md#integration-with-pipeline-and-sink) — the producer side of `via`
+- [Sink](./sink.md) — the consumer a pipeline can be attached to instead
+- [Zero-Boxing Streams](../execution-and-compatibility/zero-boxing.md) — the lanes `JvmType.Infer` selects between, and why transforming factories need the evidence