W3cubDocs

function*

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 returned, 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 < index+1)
    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); // 3
// ...

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.	Draft

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	Opera Android	iOS Safari	Samsung Internet
Basic support	Yes	39	Yes	26	Yes	10	?
`IteratorResult` object instead of throwing	Yes	Yes	Yes	29	Yes	Yes	?
Not constructable with `new` (ES2016)	Yes	Yes	?	43	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).