yield
The yield
operator is used to pause and resume a generator function.
Try it
Syntax
js
yield
yield expression
Parameters
expression
Optional-
The value to yield from the generator function via the iterator protocol. If omitted,
undefined
is yielded.
Return value
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
.
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 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:
- A
yield
expression. In this case, the generator pauses, and thenext()
method return an iterator result object with two properties:value
anddone
. Thevalue
property is the value of the expression after theyield
operator, anddone
isfalse
, indicating that the generator function has not fully completed. - The end of the generator function. In this case, execution of the generator ends, and the
next()
method returns an iterator result object where thevalue
isundefined
anddone
istrue
. - A
return
statement. In this case, execution of the generator ends, and thenext()
method returns an iterator result object where thevalue
is the specified return value anddone
istrue
. - A
throw
statement. In this case, execution of the generator halts entirely, and thenext()
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.
Examples
Using yield
The following code is the declaration of an example generator function.
js
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.
js
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.
js
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
Specifications
Specification |
---|
ECMAScript Language Specification # prod-YieldExpression |
Browser compatibility
BCD tables only load in the browser