Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Iterators, Generators and Symbols

Generator objects

Reference for JavaScript generator objects: next(value), return() and throw() methods, how yield pauses a generator, finally blocks, and one-shot behavior.

Calling a generator function (function*) does not run its body. It returns a generator object, which is an iterator you drive by hand or with for...of. The body runs only when you call next(), and it pauses at each yield.

A generator object has three methods, next(), return() and throw(), and it is its own iterable, so [Symbol.iterator]() returns itself. See function* for how to declare one and yield for the operator.

JavaScript
function* numbers() {
  yield 1;
  yield 2;
}
const generator = numbers();
generator.next(); // { value: 1, done: false }

Try it

JS next(), two-way values and return()

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS throw() into a generator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Methods

Method Description
next(value) Resumes the generator. The value becomes the result of the yield expression it was paused on (ignored on the first call). Returns { value, done }.
return(value) Finishes the generator early at the paused yield, running any finally blocks. Returns { value, done: true }.
throw(error) Throws error at the paused yield. If the generator catches it, it continues and returns the next yielded result; otherwise the error propagates to the caller and the generator finishes.

States

A generator is suspended-start, suspended-yield, executing or completed.

  • The first next() starts the body and runs to the first yield; the argument to that first call has nowhere to go and is dropped.
  • After completion (by return statement, falling off the end, return() or an uncaught error), every next() returns { value: undefined, done: true }.
  • A return statement inside the generator produces a final result with done: true. for...of and spread ignore that final value.
  • Calling next() while the generator is already running (re-entrance) throws a TypeError.

Usage notes

  • Lazy evaluation. Nothing runs until requested, so generators can model infinite sequences. Always limit them with break, take() or a counter.
  • One-shot. A generator object cannot be restarted. Call the generator function again for a fresh one.
  • finally blocks run on return() and on break out of a for...of loop (which calls return() for you), but not if the generator is simply abandoned.
  • yield* delegates to another iterable or generator, forwarding next(), return() and throw() to it.
  • return() can be overridden by a yield inside finally; the generator then stays alive.
  • Generators cannot be arrow functions, and new cannot be used with them.
  • Methods: *name() {} in objects and classes, and static *name() {}.

Browser support

Generators have been available since ES2015 in all current browsers and Node.js.