A palavra-chaveyield é usada para pausar e resumir uma generator function (function* orgenerator function legada).

Sintaxe

[rv] = yield [expressão];

expressão

Define o valor que retorna de uma generator function viao protocolo iterator. Se omitido, será retornadoundefined.

rv

Retorna o valor opcional passado para o metódonext() do generator e resume sua execução.

Descrição

A palavra-chaveyield pausa a execução de uma generator function e o valor da expressão em frente a palavra-chaveyield é retornado para a chamada do generator. Ele pode ser considerado uma versão da palavra-chavereturn para o generator.

A palavra-chaveyield atualmente retorna um objeto do tipoIteratorResult com duas propriedades,value edone. A propriedadevalue é o resultado da avaliação da expressãoyield, edone éfalse, indicando que a generator function não foi totalmente completada.

Uma vez pausado em uma expressãoyield, a execução do código do generator permanece pausado até a próxima chamada do métodnext(). Cada vez que o métodonext() do generator é chamado, o generator resume a execução e roda até atingir um dos seguintes estados:

• Umyield, que causa a pausa do generator novamente e retorna seu novo valor. Na próxima vez quenext() for chamado, a execução resumirá com a declaração imediamente apósyield.
• throw é usado para invocar uma exception à partir do generator. Isso irá parar completamente a execução do generator, e a execução resume para onde foi chamado o generator normalmente no caso que uma exception é invocada.
• O final de uma generator function é atingido; nesse caso, a execução do generator termina e umIteratorResult é retornado para onde o generator foi chamado no qual ovalue éundefined edone étrue.
• Uma declaraçãoreturn é atingida. Nesse caso, a execução do generator termina e umIteratorResult é retornado para onde o generator foi chamado no qual ovalue é o valor especificado pela declaraçãoreturn statement edone étrue.

Se um valor opcional é passado para o métodonext() do generator, esse valor se torna o valor retornado pela operaçãoyield atual do generator.

Entre o caminho de código do generator, os seus operadoresyield, e a habilidade de especificar um novo valor inicial passando isso para oGenerator.prototype.next(), generators oferecem um poder e controle enormes

Exemplos

O código seguinte é a declaração de um exemplo de uma generator function.

function* foo() {  var index = 0;  while (index <= 2) yield index++;}

Uma vez que a generator function é definida, isso pode ser usada para construir um iterator como mostrado a seguir:

var iterator = foo();console.log(iterator.next()); // { value: 0, done: false }console.log(iterator.next()); // { value: 1, done: false }console.log(iterator.next()); // { value: 2, done: false }console.log(iterator.next()); // { value: undefined, done: true }

Especificações

Compatibilidade com navegadores

Notas específicas do Firefox

• A partir do Gecko 29, uma generator function completada não invoca mais umTypeError "generator has already finished". Ao invés, isso retorna um objetoIteratorResult como{ value: undefined, done: true } (Erro do Firefox 958951).
• A partir do Gecko 33, a análise (parsing) de uma expressãoyield foi atualizada para se conformar com a especificação do ES2015 (Erro do Firefox 981599):
  • A expressão após a palavra-chaveyield é opcional e omitir isso não invoca mais umSyntaxError:function* foo() { yield; }

Veja também

• O protocolo Iterator
• function*
• function* expression
• yield*