The function*
declaration (function
keyword followed by an asterisk) defines a generator function, which returns a Generator
object.
You can also define generator functions using the GeneratorFunction
constructor.
Syntax
function* name([param[, param[, ... param]]]) { statements }
name
- The function name.
param
- The name of an argument to be passed to the function. A function can have up to 255 arguments.
statements
- The statements comprising the body of the function.
Description
Generators are functions which can be exited and later re-entered. Their context (variable bindings) will be saved across re-entrances.
Calling a generator function does not execute its body immediately; an iterator object for the function is returned instead. When the iterator's next()
method is called, the generator function's body is executed until the first yield
expression, which specifies the value to be returned from the iterator or, with yield*
, delegates to another generator function. The next()
method returns an object with a value
property containing the yielded value and a done
property which indicates whether the generator has yielded its last value as a boolean. Calling the next()
method with an argument will resume the generator function execution, replacing the yield
expression where execution was paused with the argument from next()
.
A return
statement in a generator, when executed, will make the generator done
. If a value is return
ed, it will be passed back as the value
. A generator which has returned will not yield any more values.
Examples
Simple example
function* idMaker() { var index = 0; while (index < 3) yield index++; } var 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); // undefined // ...
Example with yield*
function* anotherGenerator(i) { yield i + 1; yield i + 2; yield i + 3; } function* generator(i) { yield i; yield* anotherGenerator(i); yield i + 10; } var 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
function* logGenerator() { console.log(0); console.log(1, yield); console.log(2, yield); console.log(3, yield); } var 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
function* yieldAndReturn() { yield "Y"; return "R"; yield "unreachable"; } var 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 }
Generators are not constructable
function* f() {} var obj = new f; // throws "TypeError: f is not a constructor"
Specifications
Specification | Status | Comment |
---|---|---|
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'function*' in that specification. |
Standard | Initial definition. |
ECMAScript 2016 (ECMA-262) The definition of 'function*' in that specification. |
Standard | Changed that generators should not have [[Construct]] trap and will throw when used with new . |
ECMAScript Latest Draft (ECMA-262) The definition of 'function*' in that specification. |
Living Standard |
Browser compatibility
Feature | Chrome | Edge | Firefox | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 39 | 13 | 26 | No | 26 | 10 |
IteratorResult object instead of throwing | 49 | 13 | 29 | No | Yes | Yes |
Not constructable with new (ES2016) | Yes | ? | 43 | No | Yes | 10 |
Trailing comma in parameters | ? | ? | 52 | ? | Yes | ? |
Feature | Android webview | Chrome for Android | Edge mobile | Firefox for Android | IE mobile | Opera Android | iOS Safari |
---|---|---|---|---|---|---|---|
Basic support | Yes | 39 | Yes | 26 | No | Yes | 10 |
IteratorResult object instead of throwing | Yes | Yes | Yes | 29 | No | Yes | Yes |
Not constructable with new (ES2016) | Yes | Yes | ? | 43 | No | Yes | 10 |
Trailing comma in parameters | ? | ? | ? | ? | ? | ? | ? |
Firefox-specific notes
Generators and iterators in Firefox versions before 26
Older Firefox versions implement an older version of the generators proposal. In the older version, generators were defined using a regular function
keyword (without an asterisk) among other differences. See Legacy generator function for further information.
IteratorResult
object returned instead of throwing
Starting with Gecko 29 (Firefox 29 / Thunderbird 29 / SeaMonkey 2.26), the completed generator function no longer throws a TypeError
"generator has already finished". Instead, it returns an IteratorResult
object like { value: undefined, done: true }
(bug 958951).
See also
function* expression
GeneratorFunction
object- The Iterator protocol
yield
yield*
Function
objectfunction declaration
function expression
Functions and function scope
- Other web resources:
- Regenerator an ES2015 generator compiler to ES5
- Forbes Lindesay: Promises and Generators: control flow utopia -- JSConf EU 2013
- Hemanth.HM: The New gen of *gen(){}
- Task.js