async function*
The async function*
declaration defines an async generator function, which returns an AsyncGenerator
object.
You can also define async generator functions using the AsyncGeneratorFunction
constructor or the async function*
expression syntax.
Try it
Syntax
js
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.
Parameters
name
-
The function name.
param
Optional-
The name of a formal parameter for the function.
statements
Optional-
The statements comprising the body of the function.
Description
An async generator function combines the features of async functions and generator functions. You can use both the await
and yield
keywords within the function body. This empowers you to handle asynchronous tasks ergonomically with await
, while leveraging the lazy nature of generator functions.
Unlike normal generator functions declared with function*
, an async generator function return an AsyncGenerator
object, which conforms to the async iterable protocol. Every call to next()
returns a Promise
that resolves to the iterator result object.
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:
js
async function* foo() {
yield Promise.reject(1);
}
foo()
.next()
.catch((e) => console.error(e));
1
will be logged, because if the yielded promise rejects, the iterator result will reject as well. The value
property of an async generator's resolved result will not be another promise.
async function*
declarations are hoisted to the top of their scope and can be called anywhere in their scope.
Examples
Declaring an async generator function
Async generator functions always produce promises of results — even when each yield
step is synchronous.
js
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's fs/promises
module.
js
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: '...' }
Specifications
Specification |
---|
ECMAScript Language Specification # sec-async-generator-function-definitions |
Browser compatibility
BCD tables only load in the browser
See also
async function*
expressionAsyncGeneratorFunction
object- The Iterator protocol
GeneratorFunction
objectyield
yield*
Function
object- Functions