gossamer/async_iterator

JavaScript AsyncIterator binding for interop with APIs that produce or consume async iterators. Treated as a transit type: pass an async iterator across the FFI boundary and bridge to AsyncYielder for Gleam-side iteration via to_async_yielder.

The iterator protocol (next, return, throw) is intentionally not exposed publicly — observable mutation lives on the JavaScript side. Build async iterators on the Gleam side by composing an AsyncYielder and bridging via from_async_yielder.

Rejections from the underlying iterator’s next() propagate as promise rejections; use promise.rescue at the call site if you need to handle them.

Types

AsyncIterator

</>

A pull-based iterator that yields values asynchronously. Each call to next returns a promise.

See AsyncIterator on MDN.

pub type AsyncIterator(a)

Values

each

</>

pub fn each(
  over iterator: AsyncIterator(a),
  with fun: fn(a) -> b,
) -> promise.Promise(Nil)

Consumes the iterator, calling fun on each yielded value. A Promise returned by the callback is awaited before the next element is pulled. Equivalent to JavaScript’s for await...of loop.

from_async_yielder

</>

pub fn from_async_yielder(
  yielder: async_yielder.AsyncYielder(a),
) -> AsyncIterator(a)

Creates an async iterator from an AsyncYielder. The yielder is consumed lazily as values are pulled from the iterator.

to_async_yielder

</>

pub fn to_async_yielder(
  iterator: AsyncIterator(a),
) -> async_yielder.AsyncYielder(a)

Wraps the iterator as an AsyncYielder. The iterator is consumed lazily as values are pulled from the yielder; pair with async_yielder.to_list for eager materialization.

Warning: the returned yielder shares the iterator’s state, so it is single-pass. Pulling from it (or any yielder derived from it) advances the underlying iterator, so it can’t be replayed like an ordinary AsyncYielder.