Generators in JavaScript

This chapter follows Iterators in JavaScript.

A generator is a function that can pause and resume, passing values in both directions at each pause. Generators are iterators: calling a generator function returns an iterator object with next(), return(), and throw().

Define generators with function* (or method/generator shorthand in objects and classes):

1
function* myGen(start, end) {
2
  for (let n = start; n < end; n++) {
3
    yield n;
4
  }
5
}

1
const genIterator = myGen(0, 3);
2
console.log(genIterator.next()); // { value: 0, done: false }
3
console.log(genIterator.next()); // { value: 1, done: false }
4
console.log(genIterator.next()); // { value: 2, done: false }
5
console.log(genIterator.next()); // { value: undefined, done: true }

Invoking myGen(0, 3) does not run the loop body yet—it returns an iterator. As in the iterators chapter, execution advances only when you call next() (or use for..of).

Each call to a generator function creates a new iterator; a single iterator is consumed once.

Sending values to and from yield

When you call it.next(arg):

The generator runs until the next yield.
yield expr evaluates to { value: expr, done: false } for the caller.
The argument to the following next() becomes the result of that yield expression inside the generator.

1
function* myGenerator() {
2
  const inp = yield "Hi";
3
  console.log(inp);
4
  const name = yield;
5
  yield "My name is " + name;
6
}
7

8
const it = myGenerator();
9
console.log(it.next("A")); // { value: "Hi", done: false }
10
console.log(it.next("B")); // logs "B", then { value: undefined, done: false }
11
console.log(it.next("C")); // { value: "My name is C", done: false }
12
console.log(it.next("D")); // { value: undefined, done: true }

Using return(value) inside a generator completes the iterator (done: true) and sets the final value. That is the normal way to finish early with a result.

for..of over a generator

Because a generator return value is an iterable iterator, for..of works directly:

1
function* myGen() {
2
  let x = 0;
3
  while (x < 4) {
4
    yield x;
5
    x++;
6
  }
7
}
8

9
for (const val of myGen()) {
10
  console.log(val);
11
}
12
// 0, 1, 2, 3

Yield delegation

yield* delegates iteration to another iterable or generator, forwarding yields until that inner sequence completes. The return value of the inner generator becomes the value of the yield* expression.

1
function* firstGen() {
2
  yield 1;
3
  yield 2;
4
  return 4;
5
}
6

7
function* secondGen() {
8
  const firstGenReturnVal = yield* firstGen();
9
  yield 3;
10
  yield firstGenReturnVal;
11
}
12

13
const it = secondGen();
14
console.log(it.next()); // { value: 1, done: false }
15
console.log(it.next()); // { value: 2, done: false }
16
console.log(it.next()); // { value: 3, done: false }
17
console.log(it.next()); // { value: 4, done: false }
18
console.log(it.next()); // { value: undefined, done: true }

yield* also flattens any iterable, including arrays returned from ordinary functions:

1
function normalFunction() {
2
  return ["one", "two", "three"];
3
}
4

5
function* gen() {
6
  yield* normalFunction();
7
}
8

9
for (const v of gen()) {
10
  console.log(v);
11
}

Early generator completion

Without editing the generator body, the consumer can stop iteration:

iterator.return(value) — finishes the generator at the current suspension point
iterator.throw(error) — injects an error at the suspension point (must be caught inside the generator or the iterator completes)

1
function* myGen() {
2
  let x = 0;
3
  while (x < 10) {
4
    yield x;
5
    x++;
6
  }
7
}
8

9
const it = myGen();
10
console.log(it.next()); // { value: 0, done: false }
11
console.log(it.return()); // { value: undefined, done: true }
12
console.log(it.next()); // { value: undefined, done: true }

1
function* myGen() {
2
  let x = 0;
3
  try {
4
    while (x < 10) {
5
      yield x;
6
      x++;
7
    }
8
  } catch (error) {
9
    console.error(error);
10
  }
11
}
12

13
const it = myGen();
14
console.log(it.next()); // { value: 0, done: false }
15
console.log(it.throw("Oh oh")); // logs error, { value: undefined, done: true }

Continue with Async iterators and for await..of.