Suggest an edit

Improve this article

Refine the answer for “What is an iterator?”. Your changes go to moderation before they’re published.

Approval required

Content

What you’re changing

Title (EN)

Short answer (EN)

Shown above the full answer for quick recall.

Answer (EN)

## What an iterator is

An **iterator** is an object that **returns elements of a sequence one at a time** on each call to its `.next()` method.

Formal definition:

> An iterator is an object implementing a `next()` method that returns an object of the shape `{ value: any, done: boolean }`

---

## What an iterator looks like by hand

```javascript
function createIterator(arr) {
  let i = 0;

return {
    next() {
      if (i < arr.length) {
        return { value: arr[i++], done: false };
      } else {
        return { value: undefined, done: true };
      }
    }
  };
}

const iterator = createIterator(['a', 'b', 'c']);

console.log(iterator.next()); // { value: 'a', done: false }
console.log(iterator.next()); // { value: 'b', done: false }
console.log(iterator.next()); // { value: 'c', done: false }
console.log(iterator.next()); // { value: undefined, done: true }
```

When `done: true`, the iteration ends.

---

## What an iterator does inside for...of

When you write:

```javascript
for (const item of ['a', 'b', 'c']) {
  console.log(item);
}
```

Under the hood, JavaScript does roughly this:

```javascript
const iterable = ['a', 'b', 'c'];
const iterator = iterable[Symbol.iterator](); // creates an iterator

while (true) {
  const { value, done } = iterator.next();
  if (done) break;
  console.log(value);
}
```

---

## What an iterable object is

An object is **iterable** if it has a method:

```javascript
obj[Symbol.iterator]()
```

that returns an **iterator**.

Examples of built-in iterable structures:

- `Array`
- `String`
- `Map`
- `Set`
- `arguments`
- `NodeList` (in the browser)
- `TypedArray`

---

## Example: your own iterable object

```javascript
const range = {
  from: 1,
  to: 4,

[Symbol.iterator]() {
    let current = this.from;
    let last = this.to;

return {
      next() {
        if (current <= last) {
          return { value: current++, done: false };
        } else {
          return { done: true };
        }
      }
    };
  }
};

for (const num of range) {
  console.log(num); // 1, 2, 3, 4
}
```

When JS encounters `for...of`, it calls `range[Symbol.iterator]()` and uses the returned iterator.

---

## Example: a string is iterable too

```javascript
const str = "Hi";

const iterator = str[Symbol.iterator]();

console.log(iterator.next()); // { value: 'H', done: false }
console.log(iterator.next()); // { value: 'i', done: false }
console.log(iterator.next()); // { value: undefined, done: true }
```

---

## Iterators + Spread / Destructuring / Array.from

All of these constructs **use an iterator internally**:

```javascript
const set = new Set([1, 2, 3]);

console.log([...set]);          // [1, 2, 3]
console.log(Array.from(set));   // [1, 2, 3]

const [a, b] = set;
console.log(a, b);              // 1 2
```

---

## What Symbol.iterator does

`Symbol.iterator` is a **special symbol** that defines whether an object is "iterable". JS calls this method automatically whenever it needs to iterate the object (`for...of`, spread, and so on).

---

## Generators = automatic iterators

A generator (`function*`) is a **function that creates its own iterator**.

```javascript
function* numbers() {
  yield 1;
  yield 2;
  yield 3;
}

const iterator = numbers();

console.log(iterator.next()); // { value: 1, done: false }
console.log(iterator.next()); // { value: 2, done: false }
console.log(iterator.next()); // { value: 3, done: false }
console.log(iterator.next()); // { value: undefined, done: true }
```

And also:

```javascript
for (const n of numbers()) {
  console.log(n); // 1, 2, 3
}
```

Generators are convenient because you do not have to manually write `return { value, done }`.

---

## Iterability across modern structures

| Structure | Iterable? | Returns |
|---|---|---|
| `Array` | Yes | values |
| `String` | Yes | characters |
| `Map` | Yes | `[key, value]` pairs |
| `Set` | Yes | values |
| `Object` | No | - (can be made iterable manually via `Symbol.iterator`) |
| `arguments` | Yes | argument values |

---

## Summary

| Term | Description |
|---|---|
| **Iterator** | An object with a `next()` method that returns `{ value, done }` |
| **Iterable object** | An object that has a `[Symbol.iterator]()` method |
| `Symbol.iterator` | A symbol pointing to the method that creates an iterator |
| **Used in** | `for...of`, `spread`, `Array.from`, destructuring |
| **Generator (**`function*`**)** | A simplified way to create an iterator |

Markdown · drag & drop images · ⌘B / ⌘I shortcuts688 words

For the reviewer

Note to the moderator (optional)

Visible only to the moderator. Helps review go faster.