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.

16 min read

In short

  • Iterable: [Symbol.iterator]() returns an iterator with next()
  • 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 await for 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 }. When done is true, the sequence is over.

Here's the protocol written by hand, with no special syntax:

▶ Try
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:

  1. Calls countdown[Symbol.iterator]() once to get an iterator.
  2. Calls iterator.next() and runs the loop body with value, until a result has done: true.
  3. If you leave the loop early (break, return, or an exception), it calls iterator.return() if the iterator has one. That's the hook for cleanup, and generators use it for finally blocks.

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 iterablesConsumers of iterables
Arrays, strings, Maps, Sets, arguments, typed arraysfor...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 objectsPromise.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:

▶ Try
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:

▶ Try
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...of walks the values of an iterable.
  • for...in walks the enumerable string keys of any object, including inherited ones. On an array, those keys are the indexes, as strings.
▶ Try
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.

▶ Try
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 return value is not part of the sequence. It arrives with done: true, and for...of, spread and Array.from ignore 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:

▶ Try
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.

▶ Try
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).

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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:

▶ Try
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 typesstrings and symbols (numbers become strings)anything: objects, numbers, NaN, functions
Orderinteger-like keys first (ascending), then insertion orderinsertion order, always
SizeObject.keys(o).length (O(n))map.size
Inherited keysconstructor, toString, __proto__ lurk on the prototypenone
Iterableno (use Object.entries)yes, as [key, value] pairs
JSONJSON.stringify worksbecomes {} unless you convert it
Frequent add and deleteslower in V8designed for it
▶ Try
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:

▶ Try
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

▶ Try
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.

▶ Try
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:

▶ Try
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.
▶ Try
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.

▶ Try
// 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#: Iterable and Iterator are IEnumerable<T> and IEnumerator<T>. A generator with yield is a method with yield return, and the laziness is LINQ's deferred execution. Map is Dictionary<TKey, TValue> (but ordered), Set is HashSet<T> (also ordered), WeakMap is ConditionalWeakTable, and an async generator with for await is IAsyncEnumerable<T> with await foreach. One difference bites: C# Dictionary uses Equals/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, and Seq.take, Seq.map and Seq.filter are the iterator helpers. F# Map and Set are 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> and AsyncGenerator<T>. Map<K, V> and Set<T> are generic. Spreading a Set or Map needs target ES2015 or later (or downlevelIteration).

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 calling find in 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 await walks 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...of and Array.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

  1. A lazy range (easy): a reusable iterable object with [Symbol.iterator].
  2. Word frequency with Map (easy): counting without the constructor bug, then top-N.
  3. Permissions with Set operations (easy): union, difference and membership checks for roles.
  4. Lazy take, map, filter and chunk (medium): generator helpers that pull no more than they must.
  5. An iterable linked list (medium): a class that works with for...of, spread and Array.from.
  6. Paginated API as an async generator (medium): for await over every item of every page.
  7. Deep clone with cycles (hard): Map, Set, Date and circular references, with a WeakMap.
  8. 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