Symbol.asyncDispose

値

ウェルノウンシンボル Symbol.asyncDispose です。

解説

非同期に破棄可能な (async disposable) オブジェクトとは、 [Symbol.asyncDispose]() メソッドを備えたオブジェクトです。このメソッドは、以下のようなセマンティクスを持つことが期待されます。

• このメソッドを呼び出すことで、呼び出し元がこのオブジェクトの使用を継続する意図がないことを、非同期に破棄可能なオブジェクトに伝えます。このメソッドは、ファイルシステムハンドル、ストリーム、ホストオブジェクトなど、リソースを明示的にクリーンアップするために必要なロジックを実行する必要があります。
• このメソッドはプロミスを返すことがあり、そのプロミスを待ってから処理を続行します。
• このメソッドで例外が発生した場合、通常はリソースを解放できなかったことを意味します。非同期に破棄可能なオブジェクトは、返される Promise が履行されるまで「破棄された」とはみなされません。
• 同じオブジェクトにおいて 2 回以上呼び出された場合に、メソッドは例外を発生させるべきではありません。ただし、この要件は強制ではありません。

例

ユーザー定義の非同期に破棄可能なオブジェクト

[Symbol.dispose] により、独自の非同期に破棄可能なオブジェクトが作成できます。詳細については、await using を参照してください。

class Disposable {
  #fileHandle;
  #disposed;

  constructor(handle) {
    this.#disposed = false;
    this.#fileHandle = handle;
  }

  async [Symbol.asyncDispose]() {
    await this.#fileHandle.close();
    this.disposed = true;
  }

  get isDisposed() {
    return this.disposed;
  }
}

const resource = new Disposable(await fs.open("my-file.txt", "r"));
{
  await using resourceUsed = resource;
  console.log(resource.isDisposed); // false
}
console.log(resource.isDisposed); // true

仕様書

ブラウザーの互換性

関連情報

• Symbol.asyncDispose のポリフィル (core-js)
• JavaScript のリソース管理
• Symbol.dispose
• await using
• AsyncDisposableStack.prototype[Symbol.asyncDispose]()
• AsyncIterator.prototype[Symbol.asyncDispose]()