async-stream

async-stream is a Tokio-project crate that provides stream! and try_stream! procedural macros, letting Rust code write asynchronous streams using ordinary async/await and yield syntax instead of manually implementing the Stream trait’s poll_next state machine by hand.

The macros expand into an anonymous type implementing futures_core::Stream (Item = T for stream!, Item = Result<T, Error> for try_stream!, which additionally supports ? for early-return error propagation), and the crate works entirely on stable Rust with no unstable-feature requirements.

What You Get

• The stream! macro for defining a Stream<Item = T> using async/await and yield syntax
• The try_stream! macro for fallible streams (Item = Result<T, Error>) with ?-operator error propagation
• Full compatibility with the futures ecosystem (futures_core::Stream, combinators from futures_util)
• Zero unstable-feature requirements — works on stable Rust as of edition 2021, rust-version 1.65+
• A companion async-stream-impl proc-macro crate that does the actual macro expansion

Common Use Cases

• Implementing a custom async iterator/stream over a paginated API response without writing a manual poll_next state machine
• Building a streaming parser or line-by-line async reader that yields items incrementally as data arrives
• Wrapping a channel or event source (WebSocket messages, database rows) as a Stream consumable by futures/tokio-stream combinators
• Writing test fixtures that need to emit a scripted sequence of async values over time

Under The Hood

Architecture — The repo is a small Cargo workspace with two crates: async-stream (the public-facing crate, src/lib.rs, async_stream.rs, next.rs, yielder.rs) and async-stream-impl (the actual proc-macro crate that parses the macro body and rewrites yield expressions into calls against a hidden coroutine-like driver). The macro-generated code builds a state machine under the hood using a generator built from an async block plus a side-channel Yielder that captures each yielded value, which next.rs/yielder.rs then thread back through poll_next. Tech Stack — Pure Rust (edition 2021, MSRV 1.65), depending only on futures-core (for the Stream trait) and pin-project-lite (for safe pinning), with futures-util, tokio, tokio-test, rustversion, and trybuild as dev-dependencies for testing macro-expansion errors and stream behavior. Code Quality — The test suite includes 12+ integration test files under async-stream/tests/, including trybuild-based compile-fail tests that assert the macro produces sensible error messages for misuse (e.g. yield outside a stream block); the crate has been stable and essentially feature-complete for a couple of years with no active development but no open correctness issues either. API Design — The macro’s design goal is to make an async stream read like ordinary imperative Rust (a for loop with yield inside stream! { }) rather than requiring Pin/Poll/Context boilerplate, which is a significant developer-experience win for anyone who already understands async fn — the main friction is that pin_mut! (or Box::pin) is still required at the call site since the returned stream is !Unpin.