A declaração function* (palavra chave function seguida de um asterisco) define um função geradora (generator function), que retorna um objeto Generator.

Você também pode definir funções geradoras usando o construtor GeneratorFunction 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 com Promises -- são uma ferramenta muito poderosa para programação assíncrona, por mitigarem -- se não eliminarem -- problemas com callbacks, como o Callback Hell e Inversão de Controle. Funções async são fundamentadas nisso.

Chamar uma função geradora não executa seu conteúdo imediatamente; ao invés disso um objeto iterator é retornado. Quando o método next() do objeto iterator é chamado, o conteúdo da função do gerador é executado até a primeira expressão yield, que especifica o valor a ser devolvido do iterator ou com yield* que delega para outra função geradora. O método next() retorna um objeto com uma propriedade value contendo o valor retornado e a propriedade booleandone indicando se o gerador produziu seu último valor. Chamar o método next() com um argumento resumirá a execução da função geradora, substituindo a expressão yield onde a execução foi pausada com o argumento de next().

Uma expressão return em um gerador, quando executada, fará com que o gerador termine (isto é, a propriedade done do objeto retornado será atribuído com o valor true). Se um valor foi retornado, este será usado como propriedade value do objeto retornado pelo gerador. Semelhantemente a uma expressão return, um erro lançado dentro do gerador o terminará -- a não ser que tratado no corpo do gerador. Quando um gerador estiver terminado, chamadas next 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); // 0
console.log(gen.next().value); // 1
console.log(gen.next().value); // 2
console.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); // 10
console.log(gen.next().value); // 11
console.log(gen.next().value); // 12
console.log(gen.next().value); // 13
console.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 yield
gen.next();             // 0
gen.next('pretzel');    // 1 pretzel
gen.next('california'); // 2 california
gen.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

Especificação Status Comentário
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'function*' in that specification.
Padrão Definição inicial.
ECMAScript 2016 (ECMA-262)
The definition of 'function*' in that specification.
Padrão Mudou para que generators não tenham a armadilha de [[Construct]] e irão lançar um erro, quando usados com new.
ECMAScript Latest Draft (ECMA-262)
The definition of 'function*' in that specification.
Rascunho  

Compatibilidade entre Navegadores

 
Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
function*Chrome Full support 39Edge Full support 13Firefox Full support 26IE No support NoOpera Full support 26Safari Full support 10WebView Android Full support YesChrome Android Full support 39Edge Mobile Full support YesFirefox Android Full support 26Opera Android Full support YesSafari 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.
IteratorResult object instead of throwingChrome Full support 49Edge Full support 13Firefox Full support 29IE No support NoOpera Full support YesSafari Full support YesWebView Android Full support YesChrome Android Full support YesEdge Mobile Full support YesFirefox Android Full support 29Opera Android Full support YesSafari iOS Full support YesSamsung Internet Android Full support Yesnodejs Full support Yes
Not constructable with new (ES2016)Chrome Full support YesEdge ? Firefox Full support 43IE No support NoOpera Full support YesSafari Full support 10WebView Android Full support YesChrome Android Full support YesEdge Mobile ? Firefox Android Full support 43Opera Android Full support YesSafari iOS Full support 10Samsung Internet Android Full support Yesnodejs Full support Yes
Trailing comma in parametersChrome ? Edge ? Firefox Full support 52IE No support NoOpera Full support YesSafari ? WebView Android ? Chrome Android ? Edge Mobile ? Firefox Android Full support 52Opera Android ? Safari iOS ? Samsung Internet Android ? nodejs Full support 8.0.0

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
User must explicitly enable this feature.
User must explicitly enable this feature.

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 de generators. Na versão mais antiga, generators foram intruídos a usarem a palavra chave function(sem um asterísco) dentre outras diferenças.

O retorno do objeto IteratorResult ao invés de um throw

Iniciando com Gecko 29 (Firefox 29 / Thunderbird 29 / SeaMonkey 2.26), o generator finalizado não lança mais um TypeError "generator has already finished". Ao invés disso, ele retorna um objeto IteratorResult, como por exemplo { value: undefined, done: true } (bug 958951).

Veja também

Etiquetas do documento e colaboradores

Última atualização por: mdnwebdocs-bot,