A declaraçãofunction* (palavra chavefunction seguida de um asterisco) define umafunção geradora (generator function), que retorna um objetoGenerator.

Experimente

function* generator(i) {  yield i;  yield i + 10;}const gen = generator(10);console.log(gen.next().value);// Expected output: 10console.log(gen.next().value);// Expected output: 20

Você também pode definir funções geradoras usando o construtorGeneratorFunction ou a sintaxe da expressão de uma função.

Sintaxe

function* name([param[, param[, ... param]]]) {   statements}

name

O nome da função.

param

O nome do argumento que será passado á função. Uma função pode ter até 255 argumentos.

statements

As instruções que formam o corpo da função.

Descrição

Geradores são funções cuja execução pode ser interrompida e posteriormente reconduzida. Seus contextos (de associações de variáveis) ficarão salvos entre cada recondução.

Geradores em JavaScript — especialmente quando combinados comPromises — são uma ferramenta muito poderosa para programação assíncrona, por mitigarem — se não eliminarem — problemas com callbacks, como oCallback Hell eInversão de Controle. Funçõesasync são fundamentadas nisso.

Chamar uma função geradora não executa seu conteúdo imediatamente; ao invés disso um objetoiterator é retornado. Quando o métodonext() do objetoiterator é chamado, o conteúdo da função do gerador é executado até a primeira expressãoyield, que especifica o valor a ser devolvido doiterator ou comyield* que delega para outra função geradora. O métodonext() retorna um objeto com uma propriedadevalue contendo o valor retornado e a propriedadeboolean:done indicando se o gerador produziu seu último valor. Chamar o métodonext() com um argumento resumirá a execução da função geradora, substituindo a expressãoyield onde a execução foi pausada com o argumento denext().

Uma expressãoreturn em um gerador, quando executada, fará com que o gerador termine (isto é, a propriedadedone do objeto retornado será atribuído com o valortrue). Se um valor foi retornado, este será usado como propriedadevalue do objeto retornado pelo gerador. Semelhantemente a uma expressãoreturn, um erro lançado dentro do gerador o terminará — a não ser que tratado no corpo do gerador. Quando um gerador estiver terminado, chamadasnext subsequentes não executarão nenhum código do gerador, retornarão simplesmente um objeto da seguinte forma:{value: undefined, done: true}.

Exemplos

Exemplo simples

function* idMaker() {  var index = 0;  while (true) yield index++;}var gen = idMaker();console.log(gen.next().value); // 0console.log(gen.next().value); // 1console.log(gen.next().value); // 2console.log(gen.next().value); // 3// ...

Exemplo com yield*

function* outroGerador(i) {  yield i + 1;  yield i + 2;  yield i + 3;}function* gerador(i) {  yield i;  yield* outroGerador(i);  yield i + 10;}var gen = gerador(10);console.log(gen.next().value); // 10console.log(gen.next().value); // 11console.log(gen.next().value); // 12console.log(gen.next().value); // 13console.log(gen.next().value); // 20

Passando argumentos em geradores

function* logGenerator() {  console.log(0);  console.log(1, yield);  console.log(2, yield);  console.log(3, yield);}var gen = logGenerator();// a primeira chamada next é executada desde o início da função// até a primeira declaração yieldgen.next();             // 0gen.next('pretzel');    // 1 pretzelgen.next('california'); // 2 californiagen.next('mayonnaise'); // 3 mayonnaise

Declaração de retono em um gerador

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 }

Geradores não possuem construtor

function* f() {}var obj = new f; // lança o TypeError: f não é construtor

Gerador definido em uma expressão

const foo = function* () {  yield 10;  yield 20;};const bar = foo();console.log(bar.next()); // {value: 10, done: false}

Especificações

Compatibilidade com navegadores

Observações específicas Firefox

Generators e iterators no Firefox em versões anteriores a 26

Versões mais antigas do Firefox implementam uma versão antiga da proposta degenerators. Na versão mais antiga,generators foram intruídos a usarem a palavra chavefunction(sem um asterísco) dentre outras diferenças.

O retorno do objetoIteratorResult ao invés de um throw

Iniciando com Gecko 29, ogenerator finalizado não lança mais umTypeError "generator has already finished". Ao invés disso, ele retorna um objetoIteratorResult, como por exemplo{ value: undefined, done: true } (Erro do Firefox 958951).

Veja também

• function* expression
• GeneratorFunction object
• The Iterator protocol
• yield
• yield*
• Function object
• function declaration
• function expression
• Functions and function scope
• Outras fontes na web:
  • Regenerator um ES6 generator que compila para ES5
  • Forbes Lindesay: Promises and Generators: control flow utopia — JSConf EU 2013
  • Hemanth.HM: The New gen of *gen(){}
  • Task.js