async function*

Baseline Widely available

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

async function* 宣言は非同期ジェネレーター関数を定義し、これは AsyncGenerator オブジェクトを返します。

非同期ジェネレーター関数は、AsyncGeneratorFunction コンストラクターや async function* 式の構文を使用して定義することもできます。

試してみましょう

構文

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

メモ: 非同期ジェネレーター関数には、対応するアロー関数はありません。

引数

name

関数名です。

param 省略可

関数の構文上の引数名です。

statements 省略可

関数の本体を構成する文です。

解説

非同期ジェネレーター関数は、非同期関数とジェネレーター関数の機能を組み合わせたものです。関数の内部で await と yield のキーワードの両方を使うことができます。これにより、ジェネレーター関数の遅延の性質を利用しながら、await で人間工学的に非同期タスクを処理することができるようになります。

function* で宣言された通常のジェネレーター関数とは異なり、非同期ジェネレーター関数は AsyncGenerator オブジェクトを返します。非同期反復可能プロトコルに準拠しています。next() を呼び出すたびに、イテレーターの結果オブジェクトに解決する Promise を返します。

非同期ジェネレーターからプロミスが生成されると、イテレーターの結果のプロミスの最終的な状態は、生成されたプロミスの状態と一致します。例えば次のようになります。

js
async function* foo() {
  yield Promise.reject(1);
}

foo()
  .next()
  .catch((e) => console.error(e));

生成されたプロミスが拒否された場合、イテレーターの結果も拒否されるため、1 がログ出力されます。非同期ジェネレーターの解決結果の value プロパティは、別のプロミスにはなりません。

async function* 宣言は、そのスコープの先頭に巻き上げされ、そのスコープ内のどこでも呼び出すことができます。

例

非同期ジェネレーター関数の宣言

非同期ジェネレーター関数は、常に結果のプロミスを生成します。それぞれの yield 手順が同期的であってもです。

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();
  });

非同期ジェネレーター関数を用いて一連のファイルを読み込む

この例では、Node の fs/promises モジュールを使用して、一連のファイルを読み、リクエストされたときだけそのコンテンツにアクセスするようにしています。

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: '...' }

仕様書

Specification
ECMAScript Language Specification
# sec-async-generator-function-definitions

ブラウザーの互換性

BCD tables only load in the browser

関連情報