The iteration protocols

One agreement behind many tools

In the for…of & for…in lesson, you used for...of to get the values out of arrays and strings. This lesson shows how for...of gets those values. It works with two kinds of objects:

• An iterable is a value that can make an iterator. Arrays and strings are iterables.
• An iterator is an object that gives out values one at a time. It remembers which value comes next.

The rules for these two objects are called the iteration protocols. A protocol is an agreement: if an object has the right methods, JavaScript knows how to use it.

Many tools follow this one agreement. Each of these can take values from any iterable:

• for...of loops
• spread, like [...values]
• Array.from(values)
• array destructuring, like const [a, b] = values
• Promise.all(values)
• new Map(values)

The table below compares the two kinds of objects. Read each row as: "this kind of object has this method, and the method gives back this."

The two words sound almost the same, so read them carefully. An array is an iterable. It is not an iterator. The object that array[Symbol.iterator]() gives back is the iterator.

An iterable must have one method. The method's name is not a normal string. It is the built-in symbol Symbol.iterator. A symbol is a special value that can be used as a property name. It never clashes with a normal name like "iterator". You met symbols in the Symbols lesson.

To use a symbol as a method name, put it in square brackets: [Symbol.iterator]() { ... }. Here are the smallest iterable and iterator:

1const iterable = {2  [Symbol.iterator]() {3    return iterator;4  },5};6 7const iterator = {8  next() {9    return { done: true };10  },11};

• Lines 2–3: the iterable's [Symbol.iterator]() method gives back the iterator.
• Lines 8–9: the iterator's next() method gives back a result. This one says done: true right away, so it gives no values at all.

Here is the same shape doing useful work. range(2, 4) gives the numbers 2, 3, and 4.

function range(start, end) {
  return {
    [Symbol.iterator]() {
      let current = start;
      return {
        next() {
          return current <= end
            ? { value: current++, done: false }
            : { done: true };
        },
      };
    },
  };
}

console.log([...range(2, 4)].join(","));

Line 4 makes a variable, current, inside the [Symbol.iterator]() method. The next() method can still use current after that method has finished. (A function that keeps using a variable from around it is called a closure.) So the iterator remembers its place between calls. Each next() call on lines 7–9 does one of two things:

• If current is not past end, it gives back { value: current, done: false }. Then current++ adds 1 to current.
• Otherwise, it gives back { done: true }.

On the last line, spread (...) asks the range for an iterator. It calls next() until it sees done: true. The output is 2,3,4.

You can spread the same range again and get the same three numbers. Each call to [Symbol.iterator]() makes a new current that starts at start. This matters when two loops need to start from the beginning.

Most iterables work this way: they make a new iterator each time you ask. The iterable can be used many times. Each iterator it makes goes through the values only once.

JavaScript checks two things when a loop or spread starts:

• [Symbol.iterator]() must give back an object.
• That object must have a next() method.

If either check fails, JavaScript throws a TypeError. Below, the method gives back the number 1 instead of an iterator.

const broken = {
  [Symbol.iterator]() {
    return 1;
  },
};

console.log([...broken]);

Spread calls the method on line 2 and gets 1. A number is not an object, so spread throws a TypeError before it reads any value.

Every next() call gives back a small object called a result. A result has two properties:

• value: the value being handed out.
• done: false while there are values, and true when there are no more.

Code that reads the values stops as soon as it sees done: true. Step through the code below. Line 1 makes a range from 1 to 5. Line 2 asks it for an iterator. Lines 4–7 call next() four times.

1const numbers = range(1, 5, 1);Run2const iterator = numbers[Symbol.iterator]();3 4console.log(iterator.next());5console.log(iterator.next());6console.log(iterator.next());7console.log(iterator.next());8 9function range(start, end, step = 1) {10  return {11    [Symbol.iterator]() {12      let current = start;13      return {14        next() {15          if (current > end) return { done: true };16          const value = current;17          current = current + step;18          return { value, done: false };19        },20      };21    },22  };23}

Look at the last result. for...of checks done first. If done is true, the loop body does not run. Even if that last result has a value, for...of ignores it.

1const source = "A😀B";2const iterator = source[Symbol.iterator]();3 4iterator.next(); // { value: "A", done: false }5iterator.next(); // { value: "😀", done: false }6iterator.next(); // { value: "B", done: false }7iterator.next(); // { value: undefined, done: true }

A countdown shows the difference between the last value and the final result. The first three calls give 3, 2, and 1. The fourth call gives { value: "go", done: true }. Lines 9–11 give the countdown a [Symbol.iterator]() method that gives back the countdown itself, so spread can use it.

function countdown(start) {
  let current = start;
  return {
    next() {
      return current > 0
        ? { value: current--, done: false }
        : { value: "go", done: true };
    },
    [Symbol.iterator]() {
      return this;
    },
  };
}

console.log([...countdown(3)].join(","));

The output is 3,2,1. A result with done: true may carry a value, but spread, for...of, and the other tools in this lesson ignore it.

A consumer is any tool that takes an iterable and reads values from it. Consumers look different in code, but they all follow the same steps:

1. Call [Symbol.iterator]() to get an iterator.
2. Call next() again and again.
3. Stop when they have enough values, or when a result says done: true.

The lab below gives each consumer the values 1, 2, and 3. new Map gets two pairs instead, ["a", 1] and ["b", 2]. The lab counts how many times each consumer calls next() and return().

1function counting(limit) {2  let nextCalls = 0;3  let returnCalls = 0;4  return {5    stats: () => ({ nextCalls, returnCalls }),6    [Symbol.iterator]() {7      let value = 1;8      return {9        next() {10          nextCalls = nextCalls + 1;11          return value <= limit12            ? { value: value++, done: false }13            : { done: true };14        },15        return() {16          returnCalls = returnCalls + 1;17          return { done: true };18        },19      };20    },21  };22}

An iterator may also have a return() method. JavaScript calls it when a consumer stops early, so the iterator can clean up. For example, it could close a file it was reading. Below, the loop stops after the first value with break.

const stream = {
  [Symbol.iterator]() {
    let value = 1;
    return {
      next() {
        return value <= 3 ? { value: value++, done: false } : { done: true };
      },
      return() {
        console.log("cleaned up");
        return { done: true };
      },
    };
  },
};

for (const value of stream) {
  console.log(value);
  break;
}

The output is 1, then cleaned up. The break leaves the loop while values are still left, so JavaScript calls return().

Destructuring is the most surprising consumer. const [a, b] = iterable needs only two values. After the second value, the iterator is not done yet. If it has a return() method, JavaScript calls it. A break or a thrown error inside for...of also calls return().

The lab below calls next() four times on one array iterator. The array has only two items, so the last two calls give done: true. Then line 9 asks the array for a new iterator.

1const iterable = ["tea", "cake"];2const iterator = iterable[Symbol.iterator]();3 4console.log(iterator.next());5console.log(iterator.next());6console.log(iterator.next());7console.log(iterator.next());8 9const fresh = iterable[Symbol.iterator]();10console.log(fresh.next());11console.log(iterator[Symbol.iterator]() === iterator);

A consumer can also start in the middle of an iterator. Line 4 takes the first color. Line 5 spreads the same iterator, so it gets only the colors that are left.

const colors = ["red", "green", "blue"];
const iterator = colors[Symbol.iterator]();

console.log(iterator.next().value);
console.log([...iterator].join(","));

The output is red, then green,blue. Spread does not go back to the array. It reads from the iterator it was given, starting where that iterator is.

This works because the iterators JavaScript makes are iterables too. Their [Symbol.iterator]() method gives back the iterator itself, so iterator[Symbol.iterator]() === iterator is true. You can pass such an iterator to any consumer. The consumer starts from the iterator's current place, not from the beginning.

Built-in iterables you already use

Many values in JavaScript are already iterables:

• arrays
• strings
• Maps and Sets
• typed arrays, which are arrays of raw numbers, like Uint8Array
• arguments, the list of arguments inside a normal (non-arrow) function
• in browsers, lists of page elements, like a NodeList

The table below shows what each one gives you, one value for each next() call.

A Map gives one pair for each entry: a two-item array, [key, value]. So you can split each pair right in the loop with destructuring: for (const [key, value] of map). You met Map and Set in the Map & Set lesson. This agreement is what lets them work with for...of and spread.

const settings = new Map([
  ["theme", "dark"],
  ["font", "mono"],
]);

for (const [key, value] of settings) {
  console.log(key + "=" + value);
}

The output is theme=dark, then font=mono. The Map keeps the order the entries were added. Each entry comes out as a two-item array, so line 6 can split it into key and value.

A plain object, like { a: 1, b: 2 }, has no [Symbol.iterator]() method. JavaScript can't guess which values you want: the keys, the values, or both. So for...of on a plain object throws a TypeError. You can fix it in two ways:

• Turn the object into an array first, for example with Object.entries.
• Give the object its own [Symbol.iterator]() method, when its values have a clear order.

1const plain = { a: 1, b: 2 };2 3for (const item of plain) {4  console.log(item);5}6 7for (const entry of Object.entries(plain)) {8  console.log(entry);9}

Press Try plain object to run the failing loop in your browser.

Most of the time, Object.entries(object) is the simple fix. It gives back an array of [key, value] pairs, and arrays are iterable. You saw it in the Object.keys, values & entries and Destructuring lessons.

const user = { name: "Asha", role: "editor" };

for (const [key, value] of Object.entries(user)) {
  console.log(key + "=" + value);
}

The output is name=Asha, then role=editor. Pick the method that gives you what you need:

• Object.keys for the keys.
• Object.values for the values.
• Object.entries for both, as pairs.

Where you’ll use this

Knowing the agreement helps you write helpers that accept more kinds of input. A helper that only asks for an iterable works with an array, a Set, a Map's keys, or a custom range.

It also helps you read errors. When spread, destructuring, Promise.all, or new Map says a value "is not iterable", it means it could not find a [Symbol.iterator]() method on that value.

The helper below takes the first two values from any iterable. Line 2 asks for an iterator. Lines 3–4 call next() twice. Line 8 passes it a Set, and it gives back draft and review.

1function firstTwoLabels(items) {2  const iterator = items[Symbol.iterator]();3  const first = iterator.next();4  const second = iterator.next();5  return [first.value, second.value];6}7 8console.log(firstTwoLabels(new Set(["draft", "review", "done"])));

A class can follow the agreement too. Below, the constructor saves an array in this.items. The [Symbol.iterator]() method passes the job to that array: it gives back the array's own iterator. So the class needs no next() method of its own.

class ShoppingList {
  constructor(items) {
    this.items = items;
  }

  [Symbol.iterator]() {
    return this.items[Symbol.iterator]();
  }
}

const groceries = new ShoppingList(["tea", "rice"]);
console.log([...groceries].join(","));

The output is tea,rice. You can spread groceries again, because every call to [Symbol.iterator]() makes a new array iterator. Use this for a collection whose items have a clear order. Don't make a plain object iterable just to avoid choosing between its keys and its values.

Common misconceptions

Predict each answer first. Every answer says why it is right or wrong.

Key takeaways

• An iterable has a [Symbol.iterator]() method. That method gives back an iterator.
• An iterator has a next() method. Each call gives back a result, { value, done }.
• for...of, spread, Array.from, destructuring, Promise.all, and new Map read values from iterables. They are consumers.
• When a consumer stops early, JavaScript calls the iterator's return() method, if it has one.
• Plain objects are not iterable. Use Object.entries, or give the object its own [Symbol.iterator]() method.

Up next: Generators, functions that make iterators for you with yield.