The yield
operator is used to pause and resume a generator function.
The yield
operator is used to pause and resume a generator function.
yield yield expression
expression
Optional
The value to yield from the generator function via the iterator protocol. If omitted, undefined
is yielded.
Returns the optional value passed to the generator's next()
method to resume its execution.
Note: This means next()
is asymmetric: it always sends a value to the currently suspended yield
, but returns the operand of the next yield
. The argument passed to the first next()
call cannot be retrieved because there's no currently suspended yield
.
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 used directly within the generator function that contains it. It cannot be used within nested functions.
Calling a generator function constructs a Generator
object. Each time the generator's next()
method is called, the generator resumes execution, and runs until it reaches one of the following:
yield
expression. In this case, the generator pauses, and the next()
method return an iterator result object with two properties: value
and done
. The value
property is the value of the expression after the yield
operator, and done
is false
, indicating that the generator function has not fully completed.next()
method returns an iterator result object where the value
is undefined
and done
is true
.return
statement. In this case, execution of the generator ends, and the next()
method returns an iterator result object where the value
is the specified return value and done
is true
.throw
statement. In this case, execution of the generator halts entirely, and the next()
method throws the specified exception.Once paused on a yield
expression, the generator's code execution remains paused until the generator's next()
method is called again. 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. The first next()
call does not have a corresponding suspended yield
operation, so there's no way to get the argument passed to the first next()
call.
If the generator's return()
or throw()
method is called, it acts as if a return
or throw
statement was executed at the paused yield
expression. You can use try...catch...finally
within the generator function body to handle these early completions. If the return()
or throw()
method is called but there's no suspended yield
expression (because next()
has not been called yet, or because the generator has already completed), then the early completions cannot be handled and always terminate the generator.
The following code is the declaration of an example generator function.
function* countAppleSales() { const 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.
const 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 }
You can also send a value with next(value)
into the generator. step
evaluates as a return value of the yield
expression — although the value passed to the generator's next()
method the first time next()
is called is ignored.
function* counter(value) { while (true) { const step = yield value++; if (step) { value += step; } } } const generatorFunc = counter(0); console.log(generatorFunc.next().value); // 0 console.log(generatorFunc.next().value); // 1 console.log(generatorFunc.next().value); // 2 console.log(generatorFunc.next().value); // 3 console.log(generatorFunc.next(10).value); // 14 console.log(generatorFunc.next().value); // 15 console.log(generatorFunc.next(10).value); // 26
Specification |
---|
ECMAScript Language Specification # prod-YieldExpression |
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android | Deno | Node.js | ||
yield |
39 | 12 | 26["Starting with Firefox 33, the parsing of theyield expression has been updated to conform with the ES2015 specification.", "Starting with Firefox 29, an IteratorResult object returned for completed generator function."] |
26 | 10 | 39 | 26["Starting with Firefox 33, the parsing of theyield expression has been updated to conform with the ES2015 specification.", "Starting with Firefox 29, an IteratorResult object returned for completed generator function."] |
26 | 10 | 4.0 | 39 | 1.0 | 4.0.0 |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/yield