function* generator(i) { yield i; yield i + 10; } const gen = generator(10); console.log(gen.next().value); // Expected output: 10 console.log(gen.next().value); // Expected output: 20
js
function* name(param0) { statements } function* name(param0, param1) { statements } function* name(param0, param1, /* …, */ paramN) { statements } Note: Generator functions do not have arrow function counterparts.
The function name.
The name of a formal parameter for the function. For the parameters' syntax, see the
.
The statements comprising the body of the function.
A function* declaration creates a
object. Each time a generator function is called, it returns a new
object, which conforms to the
. The generator function's execution is suspended at some place, which is initially at the very beginning of the function body. The generator function can be called multiple times to create multiple generators simultaneously; every generator maintains its own
of the generator function and can be stepped independently.
The generator allows bidirectional control flow: control flow can transfer between the generator function (callee) and its caller as many times as both parties wish to. Control flow can go from the caller to the callee by calling the generator's methods:
,
, and
. Control flow can go from the callee to the caller by exiting the function as normal using return or throw or execution all statements, or by using the yield and yield* expressions.
When the generator's
method is called, the generator function's body is executed until one of the following:
A
expression. In this case, the next() method returns an object with a value property containing the yielded value and a done property that is always false. The next time next() is called, the yield expression evaluates to the value passed to next().
A
, delegating to another iterator. In this case, this call and any future calls to next() on the generator is the same as calling next() on the delegated iterator, until the delegated iterator is finished.
A
statement (that is not intercepted by a
), or the end of the control flow which implicitly means return undefined. In this case, the generator is finished, and the next() method returns an object with a value property containing the returned value and a done property that is always true. Any further next() calls have no effect and always return { value: undefined, done: true }.
An error thrown inside the function, either via a
statement or an unhandled exception. The next() method throws that error, and the generator is finished. Any further next() calls have no effect and always return { value: undefined, done: true }.
When the generator's
method is called, it acts as if a throw statement is inserted in the generator's body at the current suspended position. Similarly, when the generator's
method is called, it acts as if a return statement is inserted in the generator's body at the current suspended position. Both methods usually finish the generator, unless the generator function catches the completion via
.
Generators used to be a paradigm for asynchronous programming, avoiding
by achieving
. Nowadays, this use case is solved with the simpler
model and the
object. However, generators are still useful for many other tasks, such as defining
in a straightforward way.
function* declarations behave similar to
declarations — they are
to the top of their scope and can be called anywhere in their scope, and they can be redeclared only in certain contexts.
js
function* idMaker() { let index = 0; while (true) { yield index++; } } const gen = idMaker(); console.log(gen.next().value); // 0 console.log(gen.next().value); // 1 console.log(gen.next().value); // 2 console.log(gen.next().value); // 3 // …
js
function* anotherGenerator(i) { yield i + 1; yield i + 2; yield i + 3; } function* generator(i) { yield i; yield* anotherGenerator(i); yield i + 10; } const gen = generator(10); console.log(gen.next().value); // 10 console.log(gen.next().value); // 11 console.log(gen.next().value); // 12 console.log(gen.next().value); // 13 console.log(gen.next().value); // 20
Passing arguments into Generators
js
function* logGenerator() { console.log(0); console.log(1, yield); console.log(2, yield); console.log(3, yield); } const gen = logGenerator(); // the first call of next executes from the start of the function // until the first yield statement gen.next(); // 0 gen.next("pretzel"); // 1 pretzel gen.next("california"); // 2 california gen.next("mayonnaise"); // 3 mayonnaise
Return statement in a generator
js
function* yieldAndReturn() { yield "Y"; return "R"; yield "unreachable"; } const gen = yieldAndReturn(); console.log(gen.next()); // { value: "Y", done: false } console.log(gen.next()); // { value: "R", done: true } console.log(gen.next()); // { value: undefined, done: true }
Generator as an object property
js
const someObj = { *generator() { yield "a"; yield "b"; }, }; const gen = someObj.generator(); console.log(gen.next()); // { value: 'a', done: false } console.log(gen.next()); // { value: 'b', done: false } console.log(gen.next()); // { value: undefined, done: true }
js
class Foo { *generator() { yield 1; yield 2; yield 3; } } const f = new Foo(); const gen = f.generator(); console.log(gen.next()); // { value: 1, done: false } console.log(gen.next()); // { value: 2, done: false } console.log(gen.next()); // { value: 3, done: false } console.log(gen.next()); // { value: undefined, done: true }
Generator as a computed property
js
class Foo { *[Symbol.iterator]() { yield 1; yield 2; } } const SomeObj = { *[Symbol.iterator]() { yield "a"; yield "b"; }, }; console.log(Array.from(new Foo())); // [ 1, 2 ] console.log(Array.from(SomeObj)); // [ 'a', 'b' ]
Generators are not constructable
js
function* f() {} const obj = new f(); // throws "TypeError: f is not a constructor
js
function* powers(n) { // Endless loop to generate for (let current = n; ; current *= n) { yield current; } } for (const power of powers(2)) { // Controlling generator if (power > 32) { break; } console.log(power); // 2 // 4 // 8 // 16 // 32 }
Specification
ECMAScript® 2027 Language Specification# sec-generator-function-definitions
guide
guide
on GitHub
Promises and Generators: control flow utopia
presentation by Forbes Lindesay at JSConf (2013)
on GitHub
You Don't Know JS: Async & Performance, Ch.4: Generators
by Kyle Simpson