Iterators in JavaScript

An iterator is any object with a next() method that returns { value, done }. An iterable is anything that can produce such an iterator—usually via [Symbol.iterator](). Built-in loops and spread syntax depend on that contract.

What is an iterator?

From Latin iterare (“to repeat”), an iterator lets you visit each item in a sequence without loading the whole collection into memory at once.

Common ways to walk data in JavaScript:

• for loops over indices or keys
• Array methods such as map and filter (they still materialize or scan collections)
• Iterators and for..of, which consume values lazily through a shared protocol

Why iterators?

You already know loops and array methods. Iterators still matter because:

• for..of and for await..of call into the iterator protocol under the hood.
• An iterator can pause between values; the consumer decides when to call next() again.
• Sequences can be unbounded or expensive to copy into an array; iterators produce values on demand.

Iterator protocol

Technically, an iterator is any object whose next() method returns a result object with:

• value — the current item (often undefined when done is true)
• done — true when the sequence is finished

Calling next() is often called consuming the iterator; many iterators are single-pass (you cannot rewind without creating a new iterator).

What is an iterable?

An iterable is a value you can iterate over with for..of or spread. It must provide a [Symbol.iterator]() method that returns a fresh iterator.

Built-in iterables include Array, String, Map, Set, TypedArray, and arguments (in non-arrow functions).

Create a custom iterable

1
const myIterable = {
2
  *[Symbol.iterator]() {
3
    yield 1;
4
    yield 2;
5
    yield 3;
6
  },
7
};
8

9
for (const value of myIterable) {
10
  console.log(value);
11
}
12
// 1, 2, 3
13

14
console.log([...myIterable]); // [1, 2, 3]

for..of walks values on iterables. for..in walks enumerable string keys on objects—a different loop for a different job.

Iterating over an array

With for..of:

1
const arr = [1, 2, 3, 4];
2

3
for (const value of arr) {
4
  console.log(value);
5
}

Or via the array’s iterator:

1
const arr = [1, 2, 3, 4];
2
const it = arr[Symbol.iterator]();
3

4
console.log(it.next()); // { value: 1, done: false }
5
console.log(it.next()); // { value: 2, done: false }
6
console.log(it.next()); // { value: 3, done: false }
7
console.log(it.next()); // { value: 4, done: false }
8
console.log(it.next()); // { value: undefined, done: true }

Iterating over a Map

With for..of (default entries are [key, value] pairs):

1
const map = new Map([
2
  ["key1", "value 1"],
3
  ["key2", "value 2"],
4
]);
5

6
for (const [key, value] of map) {
7
  console.log(`${key} and ${value}`);
8
}

Using the map iterator directly:

1
const mapIterator = map[Symbol.iterator]();
2

3
console.log(mapIterator.next()); // { value: ["key1", "value 1"], done: false }
4
console.log(mapIterator.next()); // { value: ["key2", "value 2"], done: false }
5
console.log(mapIterator.next()); // { value: undefined, done: true }

Iterating over a Set

1
const set = new Set(["Apples", "Bananas"]);
2

3
for (const value of set) {
4
  console.log(value);
5
}

1
const setIterator = set[Symbol.iterator]();
2

3
console.log(setIterator.next()); // { value: "Apples", done: false }
4
console.log(setIterator.next()); // { value: "Bananas", done: false }
5
console.log(setIterator.next()); // { value: undefined, done: true }

Create a custom iterator

Manual next()

You can implement next() by hand. It works, but callers cannot tell from the type alone that your object is an iterator—prefer exposing iterables (with [Symbol.iterator]) or generator functions.

1
function myIterator(start, finish) {
2
  let index = start;
3

4
  return {
5
    next() {
6
      if (index < finish) {
7
        return { value: index++, done: false };
8
      }
9
      return { value: undefined, done: true };
10
    },
11
  };
12
}
13

14
const it = myIterator(0, 8);
15
let res = it.next();
16
while (!res.done) {
17
  console.log(res.value);
18
  res = it.next();
19
}
20
// 0 … 7

Relation to generators

Hand-rolled iterators must track state yourself. Generator functions (function*) are the usual way to build iterators: they return an iterator object and use yield for each step. That is the focus of the next chapter.

Continue with Generators in JavaScript.