async function*

BaselineWidely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.

Theasync function* declaration creates abinding of a new async generator function to a given name.

You can also define async generator functions using theasync function* expression.

Try it

async function* foo() {  yield await Promise.resolve("a");  yield await Promise.resolve("b");  yield await Promise.resolve("c");}let str = "";async function generate() {  for await (const val of foo()) {    str += val;  }  console.log(str);}generate();// Expected output: "abc"

Syntax

async function* name(param0) {  statements}async function* name(param0, param1) {  statements}async function* name(param0, param1, /* …, */ paramN) {  statements}

Note:Async generator functions do not have arrow function counterparts.

Note:function and* are separate tokens, so they can be separated bywhitespace or line terminators. However, there cannot be a line terminator betweenasync andfunction, otherwise a semicolon isautomatically inserted, causingasync to become an identifier and the rest to become afunction* declaration.

Parameters

name: The function name.
paramOptional: The name of a formal parameter for the function. For the parameters' syntax, see theFunctions reference.
statementsOptional: The statements comprising the body of the function.

Description

Anasync function* declaration creates anAsyncGeneratorFunction object. Each time when an async generator function is called, it returns a newAsyncGenerator object, which conforms to theasync iterator protocol. Every call tonext() returns aPromise that resolves to the iterator result object.

An async generator function combines the features ofasync functions andgenerator functions. You can use both theawait andyield keywords within the function body. This empowers you to handle asynchronous tasks ergonomically withawait, while leveraging the lazy nature of generator functions.

When a promise is yielded from an async generator, the iterator result promise's eventual state will match that of the yielded promise. For example:

async function* foo() {  yield Promise.reject(new Error("failed"));}foo()  .next()  .catch((e) => console.error(e));

Error: failed will be logged, because if the yielded promise rejects, the iterator result will reject as well. Thevalue property of an async generator's resolved result will not be another promise.

async function* declarations behave similar tofunction declarations — they arehoisted to the top of their scope and can be called anywhere in their scope, and they can be redeclared only in certain contexts.

Examples

Declaring an async generator function

Async generator functions always produce promises of results — even when eachyield step is synchronous.

async function* myGenerator(step) {  await new Promise((resolve) => setTimeout(resolve, 10));  yield 0;  yield step;  yield step * 2;}const gen = myGenerator(2);gen  .next()  .then((res) => {    console.log(res); // { value: 0, done: false }    return gen.next();  })  .then((res) => {    console.log(res); // { value: 2, done: false }    return gen.next();  })  .then((res) => {    console.log(res); // { value: 4, done: false }    return gen.next();  })  .then((res) => {    console.log(res); // { value: undefined, done: true }    return gen.next();  });

Using an async generator function to read a series of files

In this example, we read a series of files and only access its content when requested, using Node'sfs/promises module.

async function* readFiles(directory) {  const files = await fs.readdir(directory);  for (const file of files) {    const stats = await fs.stat(file);    if (stats.isFile()) {      yield {        name: file,        content: await fs.readFile(file, "utf8"),      };    }  }}const files = readFiles(".");console.log((await files.next()).value);// Possible output: { name: 'file1.txt', content: '...' }console.log((await files.next()).value);// Possible output: { name: 'file2.txt', content: '...' }