Async Iterators & for-await-of

An async iterator is an object whose next() returns a promise of { value, done } , letting you pull values that arrive over time — one awaited step at a time — using the for-await-of loop.

Learn Async Iterators & for-await-of in our free JavaScript course — an interactive lesson with runnable examples, a practice exercise and a quick reference.

Part of the free JavaScript course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

They power streaming: reading a file line by line, paginating an API, or consuming a live feed without ever loading everything into memory at once.

What You'll Learn in This Lesson

📚 Prerequisites: Make sure you know async/await and promises . Async iterators glue those together with looping.

📬 Real-World Analogy: A regular array is like a stack of mail already on your desk — all there, read it whenever. An async iterator is like checking your mailbox: each trip might involve a wait for the next letter to arrive, and you only hold one letter at a time. for-await-of is you walking to the mailbox over and over until there is nothing left.

1️⃣ The Protocol — Symbol.asyncIterator

An object is async iterable if it has a method keyed by Symbol.asyncIterator that returns an async iterator — an object with a next() method that returns a promise of { value, done } . The for-await-of loop awaits each of those promises for you.

Here it is written out by hand so you can see exactly what the loop is driving:

2️⃣ Async Generators — the Easy Way

Writing the protocol by hand is tedious. async function* builds the whole thing for you: each yield produces a value, and because the function is async you can await between yields. Calling it returns a ready-to-loop async iterable.

This is the real streaming pattern — here a generator emits a tick every short delay, exactly how you might stream rows from a database cursor:

💡 Tip: The values are produced lazily . The generator is paused at each yield until the loop asks for the next one, so nothing runs ahead of what you consume.

🎯 Your Turn #1 — Loop an Async Generator

Replace the blank with the correct loop keyword to consume the async generator.

3️⃣ Real Use — Paginating an API Lazily

The killer app for async generators is pagination . Wrap the "fetch a page, yield each item, advance the cursor" loop in an async generator and the caller just writes a single for-await-of — completely unaware of pages, cursors, or network waits.

Below, a Map-backed source stands in for the network so you can watch the same pattern stream every item across "pages" — with no DOM or fetch required:

🎯 Your Turn #2 — Yield Values

Make the generator emit the squares 1, 4, 9 by replacing the blank with yield .

🧠 Quick Recall

Predict the output before revealing the answer.

1 false — next() returns a promise of { value, done } , and the first call yields 1 with done: false .

A TypeError — a plain for-of cannot drive an async iterable. You must use for await .

Symbol.asyncIterator — the sync version is Symbol.iterator .

Common Errors & Fixes

• 1️⃣ Using for-of on an async iterable
• 2️⃣ Forgetting for-await must be inside an async function
• 3️⃣ Mixing up the two symbols
• 4️⃣ Buffering an endless stream into an array

🎯 Mini Challenge — Async Filter

Build an async generator onlyEven that wraps another async iterable and yields only its even numbers. This is how you compose streaming pipelines.

Quick Reference — Async Iteration

Concept

Syntax

Async iterable hook

[Symbol.asyncIterator]() {}

Async generator

async function* g() {}

Produce a value

yield value;

Consume a stream

for await (const x of s) {}

Manual step

await it.next()

📚 Keep Learning

• • MDN — for await...of
• • MDN — AsyncGenerator
• • MDN — Symbol.asyncIterator

Frequently Asked Questions

🎉 Lesson Complete — Async Iterators!

• ✅ Async iterables expose Symbol.asyncIterator
• ✅ async function* is the easy way to build one
• ✅ for await (const x of s) consumes a stream lazily
• ✅ Perfect for pagination, file/line streaming, and live feeds

Up next: AbortController & Cancelling Async Work — stop work you no longer need. ⏹️

Practice quiz

Continue this course

• Previous: Promise Combinators
• Next: AbortController & Cancelling Async Work

Related lessons

• async/await