JavaScript · Lesson 9
Iterators, Generators, Map and Set
The iteration protocol behind for...of and spread, generator functions for lazy and infinite sequences, Map and Set as the right tools for lookups and uniqueness, WeakMap and WeakSet for data attached to objects, and a first look at async iteration.
In short
- Iterable:
[Symbol.iterator]()returns an iterator withnext() - Generators are lazy and one-shot; wrap them for reusable iterables
- Lazy pipelines handle huge and infinite sequences
- Map for lookups by data, Set for uniqueness and fast
has - WeakMap for per-object data;
for awaitfor paged sources
for...of, spread ([...x]), destructuring, Array.from, new Map(x), new Set(x) and
Promise.all all work on arrays, strings, Maps and Sets. They aren't special-cased for each type. They
all speak one small protocol, and any object that speaks it works with all of them. Generators are
the easy way to speak it. Map and Set are the collections built on it.
This lesson builds that picture, then shows where it pays off at work: lazy pipelines, lookups that don't break on odd keys, de-duplication, caches that don't leak memory, and paginated APIs.
Every snippet has a ▶ Try button. Predict the output first, then run it.
The protocol: iterable and iterator
Two roles, two methods:
- An iterable is any object with a
[Symbol.iterator]()method. Calling it returns an iterator. - An iterator is an object with a
next()method. Each call returns{ value, done }. Whendoneistrue, the sequence is over.
Here's the protocol written by hand, with no special syntax:
const countdown = {
from: 3,
[Symbol.iterator]() {
let n = this.from;
return {
next() {
return n > 0 ? { value: n--, done: false } : { value: undefined, done: true };
},
};
},
};
for (const n of countdown) console.log(n); // 3, 2, 1
console.log([...countdown]); // a fresh iterator each time, so it works again
const [first, second] = countdown;
console.log(first, second);
What for...of does, step by step:
- Calls
countdown[Symbol.iterator]()once to get an iterator. - Calls
iterator.next()and runs the loop body withvalue, until a result hasdone: true. - If you leave the loop early (
break,return, or an exception), it callsiterator.return()if the iterator has one. That's the hook for cleanup, and generators use it forfinallyblocks.
Symbol.iterator is a well-known symbol: a unique key the language itself looks up. Using a
symbol instead of a string name like "iterator" means it can never clash with an ordinary property.
Who speaks the protocol
| Built-in iterables | Consumers of iterables |
|---|---|
Arrays, strings, Maps, Sets, arguments, typed arrays | for...of, spread [...x] and f(...x) |
map.keys(), map.values(), map.entries() | array destructuring const [a, b] = x |
array.entries(), Object.entries(o) (an array) | Array.from(x), new Map(x), new Set(x) |
| generator objects | Promise.all(x), Object.fromEntries(x), yield* |
Plain objects are not iterable. for (const x of { a: 1 }) throws a TypeError. Iterate
Object.keys(o), Object.values(o) or Object.entries(o) instead:
const prices = { tea: 3, coffee: 4 };
try {
for (const p of prices) console.log(p);
} catch (e) {
console.log(e.name, '-', e.message);
}
for (const [item, price] of Object.entries(prices)) console.log(item, price);
Strings iterate by code point, not by UTF-16 unit. That's why spread is the safe way to split text that might contain emoji:
const s = 'hi👍';
console.log(s.length); // 4: the emoji is two UTF-16 units
console.log([...s].length); // 3: spread walks code points
console.log(s.split('').length); // 4: split('') cuts the emoji in half
for...of vs for...in
They look alike and do different things:
for...ofwalks the values of an iterable.for...inwalks the enumerable string keys of any object, including inherited ones. On an array, those keys are the indexes, as strings.
const langs = ['js', 'ts'];
for (const i in langs) console.log(typeof i, i); // string "0", string "1"
for (const lang of langs) console.log(lang); // js, ts
function Base() {}
Base.prototype.inherited = true;
const o = new Base();
o.own = 1;
for (const key in o) console.log('for...in sees', key); // own AND inherited
console.log('Object.keys sees', Object.keys(o)); // own only
Rule of thumb: use for...of for arrays and other iterables, and Object.entries(o) with for...of
for objects. for...in is rarely what you want in modern code. It's slower, it yields strings, and it
picks up anything someone added to a prototype.
Generators: functions that pause
Writing iterators by hand is tedious. A generator function (function*) writes them for you.
Calling it doesn't run the body. It returns a generator object, which is an iterator and an
iterable. Each next() runs the body until the next yield, then pauses there with all its local
variables intact.
function* steps() {
console.log(' start');
yield 'a';
console.log(' after a');
yield 'b';
console.log(' after b');
return 'the end';
}
const gen = steps(); // nothing printed yet: the body hasn't started
console.log('created');
let r = gen.next();
console.log(r.value, r.done);
r = gen.next();
console.log(r.value, r.done);
r = gen.next();
console.log(r.value, r.done); // the return value comes with done: true
r = gen.next();
console.log(r.value, r.done); // finished generators stay finished
Things to notice:
- Lazy. Code runs only when someone asks for the next value.
- The
returnvalue is not part of the sequence. It arrives withdone: true, andfor...of, spread andArray.fromignore it.[...steps()]is['a', 'b']. - One-shot. A generator object can be iterated once. Spreading it a second time gives
[].
Lazy and infinite sequences
Because nothing runs ahead, a generator can describe an infinite sequence. The consumer decides how many values to take:
function* naturals() {
for (let n = 1; ; n++) yield n;
}
function* take(iterable, count) {
if (count <= 0) return;
for (const x of iterable) {
yield x;
if (--count === 0) return; // stop BEFORE pulling one more value
}
}
console.log([...take(naturals(), 5)]);
Infinite sequences are rare in app code, but the same laziness is what makes big pipelines cheap: each value flows through every step before the next one is even produced, and no intermediate arrays are built.
function* naturals() {
for (let n = 1; ; n++) yield n;
}
function* take(iterable, count) {
if (count <= 0) return;
for (const x of iterable) {
yield x;
if (--count === 0) return;
}
}
function* map(iterable, fn) {
for (const x of iterable) yield fn(x);
}
function* filter(iterable, keep) {
for (const x of iterable) if (keep(x)) yield x;
}
let calls = 0;
const squares = map(naturals(), (n) => {
calls++;
return n * n;
});
const evenSquares = filter(squares, (n) => n % 2 === 0);
console.log([...take(evenSquares, 3)]); // 4, 16, 36
console.log('squared only', calls, 'numbers'); // 6, not infinity
Compare array.map(...).filter(...).slice(0, 3): each step builds a whole new array first. That's fine
for 100 items. For a million rows, or a stream with no end, laziness wins.
Iterator helpers: map, filter and take built in
Newer engines ship these methods on every built-in iterator: .map, .filter, .take, .drop,
.flatMap, .reduce, .toArray, .forEach, .some, .every, .find, plus Iterator.from(x) to
wrap any iterable. They're lazy like the generators above. They run in Node 22+, Chrome 122+,
Firefox 131+ and Safari 18.4+. On older targets, write the small generators yourself (you will, in the
exercises).
function* naturals() {
for (let n = 1; ; n++) yield n;
}
const firstEvenSquares = naturals()
.map((n) => n * n)
.filter((n) => n % 2 === 0)
.take(3)
.toArray();
console.log(firstEvenSquares);
console.log(Iterator.from(new Set(['a', 'b'])).map((s) => s.toUpperCase()).toArray());
yield*, return values and cleanup
yield* other yields every value of another iterable, which is handy for recursion:
const tree = { value: 1, children: [{ value: 2, children: [{ value: 3, children: [] }] }, { value: 4, children: [] }] };
function* walk(node) {
yield node.value;
for (const child of node.children) yield* walk(child);
}
console.log([...walk(tree)]);
When a consumer stops early, for...of calls the generator's return(), which resumes it as if the
yield were a return. Its finally blocks run. That's how a generator closes a file handle or a
connection it opened:
function* rows() {
console.log('open connection');
try {
yield 'row 1';
yield 'row 2';
yield 'row 3';
} finally {
console.log('close connection');
}
}
for (const row of rows()) {
console.log(row);
if (row === 'row 2') break; // close connection still runs
}
Making a reusable iterable
A generator object is one-shot. An object whose [Symbol.iterator] is a generator method is reusable,
because each loop calls the method and gets a fresh generator. This is the usual way to make your own
classes iterable:
class Playlist {
#songs = [];
add(song) {
this.#songs.push(song);
return this;
}
*[Symbol.iterator]() {
yield* this.#songs;
}
}
const list = new Playlist().add('Intro').add('Outro');
console.log([...list], [...list]); // works twice
function* once() {
yield 'x';
}
const gen = once();
console.log([...gen], [...gen]); // the second spread is empty
Two-way generators (briefly)
next(value) sends a value into the generator: it becomes the result of the paused yield
expression. The first next() only starts the body, so whatever you pass to it is dropped. This is how
libraries like redux-saga and co built async flows before async/await existed. You'll rarely write
it yourself, but interviewers like it:
function* conversation() {
const name = yield 'What is your name?';
const lang = yield `Hi ${name}. Favourite language?`;
return `${name} likes ${lang}`;
}
const chat = conversation();
console.log(chat.next().value);
console.log(chat.next('Ana').value);
console.log(chat.next('F#').value);
Map: a real dictionary
A plain object is a record with string keys and a prototype. Using it as a dictionary works until it
doesn't. A Map is built for the job:
Plain object {} | Map | |
|---|---|---|
| Key types | strings and symbols (numbers become strings) | anything: objects, numbers, NaN, functions |
| Order | integer-like keys first (ascending), then insertion order | insertion order, always |
| Size | Object.keys(o).length (O(n)) | map.size |
| Inherited keys | constructor, toString, __proto__ lurk on the prototype | none |
| Iterable | no (use Object.entries) | yes, as [key, value] pairs |
| JSON | JSON.stringify works | becomes {} unless you convert it |
| Frequent add and delete | slower in V8 | designed for it |
const byKey = new Map();
byKey.set(1, 'number one').set('1', 'string one');
const user = { id: 7 };
byKey.set(user, 'keyed by an object');
console.log(byKey.size, byKey.get(1), byKey.get('1'), byKey.get(user));
const obj = {};
obj[1] = 'number one';
obj['1'] = 'string one'; // same key: numbers become strings
obj[user] = 'keyed by an object'; // the key is the string "[object Object]"
console.log(Object.keys(obj));
const counts = {};
for (const word of ['to', 'be', 'constructor']) counts[word] = (counts[word] || 0) + 1;
console.log(counts.constructor); // a broken count: the inherited function plus 1
The last line is a real bug in word counters: counts.constructor starts out as Object (inherited), so
counts['constructor'] + 1 concatenates a function's source text with 1. A Map has no such keys.
If you must use an object as a dictionary, create it with Object.create(null) so it has no prototype.
Key equality
Map (and Set) compare keys with SameValueZero: like ===, except NaN equals NaN (and 0 and
-0 are the same key). Objects are compared by reference, so a lookup with an equal-looking new
object misses:
const seats = new Map();
seats.set({ row: 1, col: 2 }, 'Ana');
console.log(seats.get({ row: 1, col: 2 })); // undefined: a different object
const seatsByKey = new Map();
const key = (row, col) => `${row}:${col}`; // build a primitive key instead
seatsByKey.set(key(1, 2), 'Ana');
console.log(seatsByKey.get(key(1, 2)));
Converting and grouping
const settings = new Map([['theme', 'dark'], ['lang', 'en']]);
console.log(JSON.stringify(settings)); // {} : Map entries aren't own properties
const plain = Object.fromEntries(settings); // Map -> object
console.log(JSON.stringify(plain));
const back = new Map(Object.entries(plain)); // object -> Map
console.log(back.get('theme'));
const orders = [
{ id: 1, status: 'paid' },
{ id: 2, status: 'open' },
{ id: 3, status: 'paid' },
];
const byStatus = Map.groupBy(orders, (o) => o.status); // Node 21+, all current browsers
console.log(byStatus.get('paid').map((o) => o.id));
Use an object for records with known field names ({ id, name, email }) and for data that goes to JSON.
Use a Map for lookups by a key that comes from data: ids, words, objects, anything a user can type.
Set: uniqueness and fast membership
A Set holds each value once (by the same SameValueZero rule) and remembers insertion order.
const tags = ['js', 'ts', 'js', 'react', 'ts'];
const unique = [...new Set(tags)]; // the classic de-duplication one-liner
console.log(unique);
const allowed = new Set(['admin', 'editor']);
console.log(allowed.has('editor'), allowed.has('viewer')); // O(1) lookup
set.has(x) is a hash lookup. array.includes(x) scans the whole array. Inside a loop over another
big array, that's the difference between O(n) and O(n²): checking 50,000 ids against 50,000 ids is
2.5 billion comparisons with includes and 50,000 lookups with a Set.
Set operations
New Set methods do the math for you: union, intersection, difference, symmetricDifference,
isSubsetOf, isSupersetOf and isDisjointFrom. They return new Sets. union, difference and
symmetricDifference keep the order of the set you call them on; intersection follows the order of the
smaller set. They run in Node 22+, Chrome 122+, Firefox 127+ and Safari 17+. For older
targets, the filter versions in the comments do the same thing:
const before = new Set(['ana', 'ben', 'cy']);
const after = new Set(['ben', 'cy', 'dee']);
console.log([...after.difference(before)]); // added: after.filter(x => !before.has(x))
console.log([...before.difference(after)]); // removed: before.filter(x => !after.has(x))
console.log([...before.intersection(after)]); // kept: before.filter(x => after.has(x))
console.log([...before.union(after)]); // all: new Set([...before, ...after])
console.log(new Set(['ben']).isSubsetOf(before));
A Set has no index and no map or filter of its own. Spread it into an array ([...set]) or use the
iterator helpers (set.values().filter(...)) when you need them.
WeakMap and WeakSet
A WeakMap is a Map whose keys must be objects (or non-registered symbols), and which doesn't
keep its keys alive. When nothing else references a key object, the garbage collector can free it,
and its entry disappears with it. The price: you can't iterate a WeakMap, and it has no size, because
its contents depend on when the collector runs. It only has get, set, has and delete.
WeakSet is the same idea for a set of objects.
Use them to attach data to objects without owning their lifetime:
- Per-object caches. Cache a computed value for an object. When the object goes away, so does the cache entry. A normal Map would keep every object it ever saw alive: a memory leak.
- Metadata on objects you don't own. DOM nodes, objects from a library, request objects. You can't (or shouldn't) add properties to them, but you can key a WeakMap by them.
- "Have I seen this object?" A WeakSet of visited objects detects cycles in a graph, or marks objects you've already processed.
const sizeCache = new WeakMap();
let computations = 0;
function expensiveSize(doc) {
if (!sizeCache.has(doc)) {
computations++;
sizeCache.set(doc, JSON.stringify(doc).length);
}
return sizeCache.get(doc);
}
const doc = { title: 'Report', body: 'x'.repeat(1000) };
expensiveSize(doc);
expensiveSize(doc);
console.log(expensiveSize(doc), 'computed', computations, 'time(s)');
try {
sizeCache.set('a string', 1);
} catch (e) {
console.log(e.name); // keys must be objects
}
Before #private class fields existed, a module-level WeakMap keyed by this was the way to keep
data truly private. You'll still see it in older libraries. In new classes, use #fields. Keep
WeakMap for data about objects that some other code owns.
Async iterators: for await...of
Some sequences arrive over time: pages of an API, lines of a file, messages from a socket. An async
iterator is the same protocol with promises: its method is [Symbol.asyncIterator](), and next()
returns a promise of { value, done }. An async generator (async function*) can both await and
yield. You consume it with for await (const x of source) inside an async function.
// A fake API: 5 users, 2 per page.
const USERS = ['ana', 'ben', 'cy', 'dee', 'eve'];
async function fetchPage(cursor = 0) {
await new Promise((r) => setTimeout(r, 5));
console.log(' fetched page at', cursor);
const next = cursor + 2;
return { items: USERS.slice(cursor, next), nextCursor: next < USERS.length ? next : null };
}
async function* allUsers() {
let cursor = 0;
while (cursor !== null) {
const page = await fetchPage(cursor);
yield* page.items;
cursor = page.nextCursor;
}
}
async function main() {
for await (const user of allUsers()) {
console.log(user);
if (user === 'cy') break; // the third page is never fetched
}
}
main();
The caller writes a plain loop and never sees a cursor. Pages are fetched only when needed, and
stopping early stops fetching. Array.fromAsync(source) collects an async iterable into an array
(Node 22+, all current browsers). for await also accepts ordinary iterables of promises. The Promises
and async/await topic covers the promise side in depth.
Coming from C#, F# or TypeScript
Side note
- C#:
IterableandIteratorareIEnumerable<T>andIEnumerator<T>. A generator withyieldis a method withyield return, and the laziness is LINQ's deferred execution.MapisDictionary<TKey, TValue>(but ordered),SetisHashSet<T>(also ordered),WeakMapisConditionalWeakTable, and an async generator withfor awaitisIAsyncEnumerable<T>withawait foreach. One difference bites: C#DictionaryusesEquals/GetHashCode, so value-equal records can be keys. JavaScript has no hash protocol, so object keys are always by reference. - F#:
seq { yield ... }is lazy like a generator, andSeq.take,Seq.mapandSeq.filterare the iterator helpers. F#MapandSetare immutable trees; the JavaScript ones are mutable hash tables. - TypeScript: the types are
Iterable<T>,Iterator<T>,IterableIterator<T>,Generator<T, TReturn, TNext>,AsyncIterable<T>andAsyncGenerator<T>.Map<K, V>andSet<T>are generic. Spreading a Set or Map needstargetES2015 or later (ordownlevelIteration).
In real codebases
Side note
- Map for lookups by id. Turn an array into
new Map(items.map((i) => [i.id, i]))once, then look up in O(1) instead of callingfindin a loop. Normalised state in Redux or NgRx does the same thing with plain objects, because the store must stay serialisable: Redux Toolkit warns when state holds a Map or Set. - Set for selections and de-duplication. In React state, never mutate a Set in place. Create a new
one so React sees a new reference:
setSelected((prev) => new Set(prev).add(id)). - Async iteration for paged APIs and streams. Cloud SDKs (AWS, Azure, Google Cloud) expose paged list
calls as async iterables, so one
for awaitwalks every page. Node streams are async iterable:for await (const chunk of stream). - Generators show up in tree walkers, parsers, test data builders and redux-saga. Most app code only
consumes iterables. Knowing the protocol is what lets you make your own types work with spread,
for...ofandArray.from. - WeakMap shows up in framework internals: Vue's reactivity tracks dependencies per object in a
WeakMap, and libraries cache per-object results (
reselect-style memoisation, per-node layout data) the same way.
The exercises
- A lazy range (easy): a reusable iterable object with
[Symbol.iterator]. - Word frequency with Map (easy): counting without the
constructorbug, then top-N. - Permissions with Set operations (easy): union, difference and membership checks for roles.
- Lazy take, map, filter and chunk (medium): generator helpers that pull no more than they must.
- An iterable linked list (medium): a class that works with
for...of, spread andArray.from. - Paginated API as an async generator (medium):
for awaitover every item of every page. - Deep clone with cycles (hard): Map, Set, Date and circular references, with a WeakMap.
- A sorted set you can iterate (hard): a binary search tree with in-order traversal on an explicit stack, and lazy, pruned range queries.
Practise this lesson
In the app: a short video, 8 exercises checked by real tests and a 12-question concept check. Free with a GitHub account.
Open in the app