yield

The yield keyword is used to pause and resume a generator function (function* or legacy generator function).

Syntax

[rv] = yield [expression]
expression Optional
Defines the value to return from the generator function via the iterator protocol. If omitted, undefined is returned instead.
rv Optional

Retrieves the optional value passed to the generator's next() method to resume its execution.

Description

The yield keyword pauses generator function execution and the value of the expression following the yield keyword is returned to the generator's caller. It can be thought of as a generator-based version of the return keyword.

yield can only be called directly from the generator function that contains it. It cannot be called from nested functions or from callbacks.

The yield keyword causes the call to the generator's next() method to return an IteratorResult object with two properties: value and done. The value property is the result of evaluating the yield expression, and done is false, indicating that the generator function has not fully completed.

Once paused on a yield expression, the generator's code execution remains paused until the generator's next() method is called. Each time the generator's next() method is called, the generator resumes execution, and runs until it reaches one of the following:

  • A yield, which causes the generator to once again pause and return the generator's new value. The next time next() is called, execution resumes with the statement immediately after the yield.
  • throw is used to throw an exception from the generator. This halts execution of the generator entirely, and execution resumes in the caller (as is normally the case when an exception is thrown).
  • The end of the generator function is reached. In this case, execution of the generator ends and an IteratorResult is returned to the caller in which the value is undefined and done is true.
  • A return statement is reached. In this case, execution of the generator ends and an IteratorResult is returned to the caller in which the value is the value specified by the return statement and done is true.

If an optional value is passed to the generator's next() method, that value becomes the value returned by the generator's current yield operation.

Between the generator's code path, its yield operators, and the ability to specify a new starting value by passing it to Generator.prototype.next(), generators offer enormous power and control.

Unfortunately, next() is asymmetric, but that can’t be helped: It always sends a value to the currently suspended yield, but returns the operand of the following yield.

Examples

The following code is the declaration of an example generator function.

function* countAppleSales () {
  let saleList = [3, 7, 5]
  for (let i = 0; i < saleList.length; i++) {
    yield saleList[i]
  }
}

Once a generator function is defined, it can be used by constructing an iterator as shown.

let appleStore = countAppleSales()  // Generator { }
console.log(appleStore.next())      // { value: 3, done: false }
console.log(appleStore.next())      // { value: 7, done: false }
console.log(appleStore.next())      // { value: 5, done: false }
console.log(appleStore.next())      // { value: undefined, done: true }

Specifications

Specification
ECMAScript (ECMA-262)
The definition of 'Yield' in that specification.

Browser compatibility

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
yieldChrome Full support 39Edge Full support 12Firefox Full support 26
Notes
Full support 26
Notes
Notes Starting with Firefox 33, the parsing of the yield expression has been updated to conform with the ES2015 specification.
Notes Starting with Firefox 29, an IteratorResult object returned for completed generator function.
IE No support NoOpera Full support 26Safari Full support 10WebView Android Full support 39Chrome Android Full support 39Firefox Android Full support 26
Notes
Full support 26
Notes
Notes Starting with Firefox 33, the parsing of the yield expression has been updated to conform with the ES2015 specification.
Notes Starting with Firefox 29, an IteratorResult object returned for completed generator function.
Opera Android Full support 26Safari iOS Full support 10Samsung Internet Android Full support 4.0nodejs Full support 4.0.0
Full support 4.0.0
Full support 0.12
Disabled
Disabled From version 0.12: this feature is behind the --harmony runtime flag.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.
User must explicitly enable this feature.
User must explicitly enable this feature.

See also