Module stream 

Async stream processing primitives.

This module provides the Stream trait and related combinators for processing asynchronous sequences of values.

Core Traits

• Stream: The async equivalent of Iterator, producing values over time
• StreamExt: Extension trait providing combinator methods

Combinators

Transformation

• Map: Transforms each item with a closure
• Filter: Yields only items matching a predicate
• FilterMap: Combines filter and map in one step
• Then: Async map (runs future per item)
• Enumerate: Adds index to items
• Inspect: Runs closure on items without consuming

Selection

• Take: Limits stream to n items
• TakeWhile: Limits stream while predicate is true
• Skip: Skips n items
• SkipWhile: Skips while predicate is true
• Fuse: Fuses the stream

Combination

• Chain: Yields all items from one stream then another
• Zip: Pairs items from two streams
• Merge: Interleaves items from multiple streams

Splitting

• Partition: Splits one stream into two by a predicate, with a bounded per-lane buffer and an explicit head-of-line backpressure contract

Stateful

• Scan: Yields intermediate accumulator values (like Iterator::scan)
• Peekable: Look at the next item without consuming it

Rate Control

• Throttle: Rate-limits to at most one item per period
• Debounce: Suppresses rapid bursts, yielding after a quiet period

Buffering

• Buffered: Runs multiple futures while preserving order
• BufferUnordered: Runs multiple futures without ordering guarantees
• TryBuffered: Ordered buffering of fallible futures, stopping at the first Err
• Chunks: Groups items into fixed-size batches
• ReadyChunks: Returns immediately available items

The three future-buffering combinators expose deterministic pressure telemetry via telemetry_snapshot(id), returning a StreamTelemetrySnapshot in the same idiom as SyncTelemetrySnapshot.

Terminal Operations

• Collect: Collects all items into a collection
• StreamExt::collect_into: Collects into a caller-supplied collection, reusing its allocation
• Fold: Reduces items into a single value
• ForEach: Executes a closure for each item
• Count: Counts the number of items
• Any: Checks if any item matches a predicate
• All: Checks if all items match a predicate

Bounded Concurrency

These take a Cx and run each item as a region task, so in-flight work is drained rather than dropped on cancellation or error. Prefer BufferUnordered when the per-item work is pure and holds no obligation — it is lighter and needs no Send + 'static bounds.

• for_each_concurrent: Applies an async function with at most limit items in flight
• try_for_each_concurrent: Same, stopping at the first failure and draining the rest

Error Handling

• TryCollect: Collects items from a stream of Results
• TryFold: Folds a stream of Results
• TryForEach: Executes a fallible closure for each item

Examples

use asupersync::stream::{iter, StreamExt};

async fn example() {
    let sum = iter(vec![1, 2, 3, 4, 5])
        .filter(|x| *x % 2 == 0)
        .map(|x| x * 2)
        .fold(0, |acc, x| acc + x)
        .await;
    assert_eq!(sum, 12); // (2*2) + (4*2) = 12
}

Structs

All

A future that checks if all items in a stream match a predicate.

Any

A future that checks if any item in a stream matches a predicate.

BroadcastStream

Stream wrapper for broadcast receiver.

BufferUnordered

A stream that buffers and polls futures, yielding results as they complete.

Buffered

A stream that buffers and polls futures, preserving order.

Chain

A stream that yields items from the first stream then the second.

Chunks

A stream that yields items in fixed-size chunks.

Collect

A future that collects all items from a stream into a collection.

Count

A future that counts the items in a stream.

Debounce

A stream that debounces items, emitting only after a quiet period.

Enumerate

Stream for the enumerate method.

Filter

A stream that yields only items matching a predicate.

FilterMap

A stream that yields only items matching an async predicate.

Fold

A future that folds all items from a stream into a single value.

ForEach

A future that executes a closure for each item in a stream.

ForEachAsync

A future that executes an async closure for each item in a stream.

Fuse

Stream for the fuse method.

Inspect

Stream for the inspect method.

Iter

A stream that yields items from an iterator.

Map

A stream that transforms each item using a function.

Merge

A stream that merges multiple streams.

Next

A future that returns the next item from a stream.

Partition

One half of a partition.

Peekable

A stream that supports peeking at the next element without consuming it.

ReadyChunks

A stream that yields chunks of immediately available items.

ReceiverStream

Stream wrapper for mpsc::Receiver.

Scan

A stream that yields intermediate accumulator values.

SinkStream

Sink wrapper for mpsc sender.

Skip

Stream for the skip method.

SkipWhile

Stream for the skip_while method.

StreamTelemetrySnapshot

Redacted, deterministic pressure telemetry for future-buffering stream combinators.

Take

Stream for the take method.

TakeWhile

Stream for the take_while method.

Then

Stream for the then method.

Throttle

A stream that yields at most one item per time period.

TryBuffered

A stream that buffers fallible futures in order and short-circuits on Err.

TryCollect

A future that collects items from a stream of Results.

TryFold

A future that folds items from a stream of Results.

TryForEach

A future that executes a fallible closure for each item.

WatchStream

Stream that yields when watch value changes.

Zip

A stream that zips two streams into pairs.

Enums

BroadcastStreamRecvError

Error from broadcast stream.

TryStreamError

Error returned by try-stream terminal combinators.

Traits

Stream

Asynchronous iterator producing a sequence of values.

StreamExt

Extension trait providing combinator methods for streams.

Functions

for_each_concurrent

Applies f to every item of stream, keeping at most limit items in flight.

forward

Forward stream to channel.

into_sink

Convert a stream into a channel sender.

iter

Convert an iterator into a stream.

merge

Merge multiple streams into a single stream.

partition

Splits stream into two streams by predicate.

try_for_each_concurrent

Applies fallible f to every item of stream, keeping at most limit items in flight, and stops at the first failure.