Web Streams API

[履歴]

バージョン	変更点
v21.0.0	実験的ではなくなりました。
v18.0.0	このAPIの使用は、ランタイム警告を発しなくなりました。
v16.5.0	v16.5.0で追加されました。

[安定版: 2 - 安定]

安定版: 2 安定度: 2 - 安定

WHATWG Streams Standardの実装。

概要

WHATWG Streams Standard（または「web streams」）は、ストリーミングデータを処理するためのAPIを定義します。これはNode.jsのStreams APIに似ていますが、後発であり、多くのJavaScript環境でストリーミングデータを扱うための「標準」APIとなっています。

主なオブジェクトのタイプは3つあります。

ReadableStream - ストリーミングデータのソースを表します。
WritableStream - ストリーミングデータの宛先を表します。
TransformStream - ストリーミングデータを変換するためのアルゴリズムを表します。

`ReadableStream`の例

この例では、現在の performance.now() タイムスタンプを毎秒ずっとプッシュする単純な ReadableStream を作成します。非同期イテラブルは、ストリームからデータを読み取るために使用されます。

ESMCJS

import {
  ReadableStream,
} from 'node:stream/web';

import {
  setInterval as every,
} from 'node:timers/promises';

import {
  performance,
} from 'node:perf_hooks';

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

for await (const value of stream)
  console.log(value);

const {
  ReadableStream,
} = require('node:stream/web');

const {
  setInterval: every,
} = require('node:timers/promises');

const {
  performance,
} = require('node:perf_hooks');

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

(async () => {
  for await (const value of stream)
    console.log(value);
})();

API

クラス: `ReadableStream`

[履歴]

バージョン	変更点
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	追加: v16.5.0

`new ReadableStream([underlyingSource [, strategy]])`

追加: v16.5.0

underlyingSource <Object>
- start <Function> ReadableStreamの作成直後に呼び出されるユーザー定義関数。
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- 戻り値: undefinedまたはundefinedで解決されるpromise。
- pull <Function> ReadableStreamの内部キューが満杯でない場合に繰り返し呼び出されるユーザー定義関数。操作は同期または非同期にできます。非同期の場合、以前に返されたpromiseが解決されるまで、関数は再度呼び出されません。
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- 戻り値: undefinedで解決されるpromise。
- cancel <Function> ReadableStreamがキャンセルされたときに呼び出されるユーザー定義関数。
- reason <any>
- 戻り値: undefinedで解決されるpromise。
- type <string> 'bytes'またはundefinedである必要があります。
- autoAllocateChunkSize <number> typeが'bytes'に等しい場合にのみ使用されます。ゼロ以外の値に設定すると、ビューバッファはReadableByteStreamController.byobRequestに自動的に割り当てられます。設定されていない場合は、ストリームの内部キューを使用して、デフォルトのリーダーReadableStreamDefaultReaderを介してデータを転送する必要があります。
strategy <Object>
- highWaterMark <number> 背圧が適用される前の最大の内部キューサイズ。
- size <Function> 各データチャンクのサイズを識別するために使用されるユーザー定義関数。
- chunk <any>
- 戻り値: <number>

`readableStream.locked`

Added in: v16.5.0

Type: <boolean> この<ReadableStream>にアクティブなリーダーが存在する場合、trueに設定されます。

readableStream.lockedプロパティは、デフォルトではfalseであり、ストリームのデータを消費するアクティブなリーダーが存在する場合はtrueに切り替わります。

`readableStream.cancel([reason])`

Added in: v16.5.0

reason <any>
Returns: キャンセルが完了するとundefinedで履行されるPromise。

`readableStream.getReader([options])`

Added in: v16.5.0

options <Object>
- mode <string> 'byob' または undefined
Returns: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

ESMCJS

import { ReadableStream } from 'node:stream/web';

const stream = new ReadableStream();

const reader = stream.getReader();

console.log(await reader.read());

const { ReadableStream } = require('node:stream/web');

const stream = new ReadableStream();

const reader = stream.getReader();

reader.read().then(console.log);

readableStream.lockedをtrueにします。

`readableStream.pipeThrough(transform[, options])`

Added in: v16.5.0

transform <Object>
- readable <ReadableStream> transform.writableがこのReadableStreamから受信した、潜在的に変更されたデータをプッシュするReadableStream。
- writable <WritableStream> このReadableStreamのデータが書き込まれるWritableStream。
options <Object>
- preventAbort <boolean> trueの場合、このReadableStreamのエラーはtransform.writableが中断される原因になりません。
- preventCancel <boolean> trueの場合、宛先transform.writableのエラーは、このReadableStreamがキャンセルされる原因になりません。
- preventClose <boolean> trueの場合、このReadableStreamを閉じてもtransform.writableが閉じられることはありません。
- signal <AbortSignal> <AbortController>を使用してデータ転送をキャンセルできます。
Returns: <ReadableStream> transform.readableから。

この<ReadableStream>を、transform引数で提供される<ReadableStream>と<WritableStream>のペアに接続し、この<ReadableStream>からのデータがtransform.writableに書き込まれ、場合によっては変換され、transform.readableにプッシュされるようにします。パイプラインが構成されると、transform.readableが返されます。

パイプ操作がアクティブな間、readableStream.lockedをtrueにします。

ESMCJS

import {
  ReadableStream,
  TransformStream,
} from 'node:stream/web';

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a');
  },
});

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const transformedStream = stream.pipeThrough(transform);

for await (const chunk of transformedStream)
  console.log(chunk);
  // Prints: A

const {
  ReadableStream,
  TransformStream,
} = require('node:stream/web');

const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('a');
  },
});

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const transformedStream = stream.pipeThrough(transform);

(async () => {
  for await (const chunk of transformedStream)
    console.log(chunk);
    // Prints: A
})();

`readableStream.pipeTo(destination[, options])`

Added in: v16.5.0

destination <WritableStream> このReadableStreamのデータが書き込まれる<WritableStream>。
options <Object>
- preventAbort <boolean> trueの場合、このReadableStreamのエラーはdestinationを中断させません。
- preventCancel <boolean> trueの場合、destinationのエラーは、このReadableStreamをキャンセルさせません。
- preventClose <boolean> trueの場合、このReadableStreamを閉じてもdestinationが閉じられることはありません。
- signal <AbortSignal> <AbortController>を使用して、データ転送をキャンセルできます。
戻り値: undefinedで解決されるPromise

パイプ操作がアクティブな間、readableStream.lockedをtrueにします。

`readableStream.tee()`

[履歴]

バージョン	変更点
v18.10.0, v16.18.0	可読バイトストリームのティーイングをサポートします。
v16.5.0	Added in: v16.5.0

戻り値: <ReadableStream[]>

このReadableStreamのデータが転送される、新しい<ReadableStream>インスタンスのペアを返します。それぞれが同じデータを受信します。

readableStream.lockedをtrueにします。

`readableStream.values([options])`

Added in: v16.5.0

options <Object>
- preventCancel <boolean> trueの場合、非同期イテレーターが突然終了したときに<ReadableStream>が閉じられるのを防ぎます。 デフォルト: false。

このReadableStreamのデータを使用するために使用できる非同期イテレーターを作成して返します。

非同期イテレーターがアクティブな間、readableStream.lockedをtrueにします。

import { Buffer } from 'node:buffer';

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream.values({ preventCancel: true }))
  console.log(Buffer.from(chunk).toString());

Async Iteration

<ReadableStream> オブジェクトは、for await 構文を使用した async iterator プロトコルをサポートします。

import { Buffer } from 'node:buffer';

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream)
  console.log(Buffer.from(chunk).toString());

async iterator は、<ReadableStream> が終了するまで消費します。

デフォルトでは、async iterator が（break、return、または throw によって）途中で終了した場合、<ReadableStream> は閉じられます。<ReadableStream> の自動クローズを防止するには、readableStream.values() メソッドを使用して async iterator を取得し、preventCancel オプションを true に設定します。

<ReadableStream> はロックされていてはなりません（つまり、アクティブな reader が存在してはなりません）。async iteration 中、<ReadableStream> はロックされます。

`postMessage()` での転送

<ReadableStream> インスタンスは、<MessagePort> を使用して転送できます。

const stream = new ReadableStream(getReadableSourceSomehow());

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  data.getReader().read().then((chunk) => {
    console.log(chunk);
  });
};

port2.postMessage(stream, [stream]);

`ReadableStream.from(iterable)`

Added in: v20.6.0

iterable <Iterable> Symbol.asyncIterator または Symbol.iterator iterable プロトコルを実装するオブジェクト。

iterable から新しい <ReadableStream> を作成するユーティリティメソッド。

ESMCJS

import { ReadableStream } from 'node:stream/web';

async function* asyncIterableGenerator() {
  yield 'a';
  yield 'b';
  yield 'c';
}

const stream = ReadableStream.from(asyncIterableGenerator());

for await (const chunk of stream)
  console.log(chunk); // Prints: 'a', 'b', 'c'

const { ReadableStream } = require('node:stream/web');

async function* asyncIterableGenerator() {
  yield 'a';
  yield 'b';
  yield 'c';
}

(async () => {
  const stream = ReadableStream.from(asyncIterableGenerator());

  for await (const chunk of stream)
    console.log(chunk); // Prints: 'a', 'b', 'c'
})();

クラス: `ReadableStreamDefaultReader`

[履歴]

バージョン	変更点
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	追加: v16.5.0

デフォルトでは、引数なしで readableStream.getReader() を呼び出すと、ReadableStreamDefaultReader のインスタンスが返されます。デフォルトのリーダーは、ストリームを通過するデータのチャンクを不透明な値として扱い、これにより、<ReadableStream> は一般的に任意の JavaScript 値で動作できます。

`new ReadableStreamDefaultReader(stream)`

追加: v16.5.0

stream <ReadableStream>

指定された<ReadableStream>にロックされた新しい<ReadableStreamDefaultReader>を作成します。

`readableStreamDefaultReader.cancel([reason])`

追加: v16.5.0

reason <any>
戻り値: undefined で解決される Promise。

<ReadableStream>を取り消し、基になるストリームが取り消されたときに解決される Promise を返します。

`readableStreamDefaultReader.closed`

追加: v16.5.0

型: <Promise> 関連付けられた<ReadableStream>が閉じられたときに undefined で解決されるか、ストリームでエラーが発生した場合、またはストリームが閉じる前にリーダーのロックが解除された場合は拒否されます。

`readableStreamDefaultReader.read()`

追加: v16.5.0

戻り値: オブジェクトで解決される Promise:
- value <any>
- done <boolean>

基になる<ReadableStream>からデータの次のチャンクを要求し、データが利用可能になると、データで解決される Promise を返します。

`readableStreamDefaultReader.releaseLock()`

Added in: v16.5.0

基になる<ReadableStream>に対するこのリーダーのロックを解放します。

Class: `ReadableStreamBYOBReader`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

ReadableStreamBYOBReader は、バイト指向の<ReadableStream>の代替コンシューマーです (これは、ReadableStream の作成時に underlyingSource.type が 'bytes' と等しく設定されて作成されたものです)。

BYOB は "bring your own buffer" の略です。これは、余分なコピーを回避する、バイト指向のデータのより効率的な読み取りを可能にするパターンです。

import {
  open,
} from 'node:fs/promises';

import {
  ReadableStream,
} from 'node:stream/web';

import { Buffer } from 'node:buffer';

class Source {
  type = 'bytes';
  autoAllocateChunkSize = 1024;

  async start(controller) {
    this.file = await open(new URL(import.meta.url));
    this.controller = controller;
  }

  async pull(controller) {
    const view = controller.byobRequest?.view;
    const {
      bytesRead,
    } = await this.file.read({
      buffer: view,
      offset: view.byteOffset,
      length: view.byteLength,
    });

    if (bytesRead === 0) {
      await this.file.close();
      this.controller.close();
    }
    controller.byobRequest.respond(bytesRead);
  }
}

const stream = new ReadableStream(new Source());

async function read(stream) {
  const reader = stream.getReader({ mode: 'byob' });

  const chunks = [];
  let result;
  do {
    result = await reader.read(Buffer.alloc(100));
    if (result.value !== undefined)
      chunks.push(Buffer.from(result.value));
  } while (!result.done);

  return Buffer.concat(chunks);
}

const data = await read(stream);
console.log(Buffer.from(data).toString());

`new ReadableStreamBYOBReader(stream)`

Added in: v16.5.0

stream <ReadableStream>

指定された<ReadableStream>にロックされた新しいReadableStreamBYOBReaderを作成します。

`readableStreamBYOBReader.cancel([reason])`

Added in: v16.5.0

reason <any>
戻り値: undefined で解決される Promise。

<ReadableStream> をキャンセルし、基になるストリームがキャンセルされたときに解決される Promise を返します。

`readableStreamBYOBReader.closed`

Added in: v16.5.0

型: <Promise> 関連付けられた<ReadableStream>が閉じられたときにundefinedで解決されるか、ストリームのエラーが発生した場合、またはストリームが閉じる前にリーダーのロックが解除された場合に拒否されます。

`readableStreamBYOBReader.read(view[, options])`

[履歴]

バージョン	変更点
v21.7.0, v20.17.0	`min` オプションが追加されました。
v16.5.0	Added in: v16.5.0

view <Buffer> | <TypedArray> | <DataView>
options <Object>
- min <number> 設定すると、min 個の要素が利用可能になるとすぐに、返される Promise が解決されます。設定しない場合、少なくとも 1 つの要素が利用可能になると Promise は解決されます。
戻り値: オブジェクトで解決される Promise:
- value <TypedArray> | <DataView>
- done <boolean>

基になる<ReadableStream>から次のデータのチャンクをリクエストし、データが利用可能になるとデータで解決される Promise を返します。

このメソッドにプールされた<Buffer>オブジェクトのインスタンスを渡さないでください。プールされたBufferオブジェクトは、Buffer.allocUnsafe()またはBuffer.from()を使用して作成されるか、さまざまなnode:fsモジュールのコールバックによって返されることがよくあります。これらのタイプのBufferは、すべてのプールされたBufferインスタンスからのすべてのデータを含む共有の基になる<ArrayBuffer>オブジェクトを使用します。Buffer、<TypedArray>、または<DataView>がreadableStreamBYOBReader.read()に渡されると、ビューの基になるArrayBufferはデタッチされ、そのArrayBufferに存在する可能性のある既存のすべてのビューが無効になります。これは、アプリケーションに悲惨な結果をもたらす可能性があります。

`readableStreamBYOBReader.releaseLock()`

Added in: v16.5.0

基になる<ReadableStream>に対するこのリーダーのロックを解除します。

クラス: `ReadableStreamDefaultController`

Added in: v16.5.0

すべての<ReadableStream>には、ストリームのキューの内部状態と管理を担当するコントローラーがあります。ReadableStreamDefaultControllerは、バイト指向でないReadableStreamのデフォルトのコントローラー実装です。

`readableStreamDefaultController.close()`

Added in: v16.5.0

このコントローラーが関連付けられている<ReadableStream>を閉じます。

`readableStreamDefaultController.desiredSize`

Added in: v16.5.0

型: <number>

<ReadableStream>のキューを満たすために残っているデータの量を返します。

`readableStreamDefaultController.enqueue([chunk])`

Added in: v16.5.0

chunk <any>

<ReadableStream>のキューに新しいデータのチャンクを追加します。

`readableStreamDefaultController.error([error])`

Added in: v16.5.0

error <any>

<ReadableStream>をエラーにして閉じるエラーを通知します。

クラス: `ReadableByteStreamController`

[履歴]

バージョン	変更
v18.10.0	リリースされたリーダーからの BYOB プルリクエストの処理のサポート。
v16.5.0	Added in: v16.5.0

すべての<ReadableStream>には、ストリームのキューの内部状態と管理を担当するコントローラーがあります。ReadableByteStreamControllerは、バイト指向のReadableStream用です。

`readableByteStreamController.byobRequest`

Added in: v16.5.0

タイプ: <ReadableStreamBYOBRequest>

`readableByteStreamController.close()`

Added in: v16.5.0

このコントローラーが関連付けられている<ReadableStream>を閉じます。

`readableByteStreamController.desiredSize`

Added in: v16.5.0

タイプ: <number>

<ReadableStream>のキューを満たすために残っているデータ量を返します。

`readableByteStreamController.enqueue(chunk)`

Added in: v16.5.0

chunk: <Buffer> | <TypedArray> | <DataView>

<ReadableStream>のキューに新しいデータのチャンクを追加します。

`readableByteStreamController.error([error])`

Added in: v16.5.0

error <any>

<ReadableStream>をエラーにして閉じるエラーを通知します。

クラス: `ReadableStreamBYOBRequest`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

バイト指向のストリームで ReadableByteStreamController を使用する場合、および ReadableStreamBYOBReader を使用する場合、readableByteStreamController.byobRequest プロパティは、現在の読み取りリクエストを表す ReadableStreamBYOBRequest インスタンスへのアクセスを提供します。このオブジェクトは、読み取りリクエストを満たすために提供された ArrayBuffer/TypedArray へのアクセスを取得するために使用され、データが提供されたことを通知するためのメソッドを提供します。

`readableStreamBYOBRequest.respond(bytesWritten)`

Added in: v16.5.0

bytesWritten <number>

readableStreamBYOBRequest.view に bytesWritten バイト数が書き込まれたことを通知します。

`readableStreamBYOBRequest.respondWithNewView(view)`

Added in: v16.5.0

view <Buffer> | <TypedArray> | <DataView>

リクエストが新しい Buffer、TypedArray、または DataView に書き込まれたバイトで完了したことを通知します。

`readableStreamBYOBRequest.view`

Added in: v16.5.0

Type: <Buffer> | <TypedArray> | <DataView>

Class: `WritableStream`

[History]

Version	Changes
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

WritableStream は、ストリームデータが送信される宛先です。

import {
  WritableStream,
} from 'node:stream/web';

const stream = new WritableStream({
  write(chunk) {
    console.log(chunk);
  },
});

await stream.getWriter().write('Hello World');

`new WritableStream([underlyingSink[, strategy]])`

Added in: v16.5.0

underlyingSink <Object>
- start <Function> WritableStream が作成された直後に呼び出されるユーザー定義関数。
- controller <WritableStreamDefaultController>
- 戻り値: undefined または undefined で fulfilled される Promise。
- write <Function> データチャンクが WritableStream に書き込まれたときに呼び出されるユーザー定義関数。
- chunk <any>
- controller <WritableStreamDefaultController>
- 戻り値: undefined で fulfilled される Promise。
- close <Function> WritableStream が閉じられたときに呼び出されるユーザー定義関数。
- 戻り値: undefined で fulfilled される Promise。
- abort <Function> WritableStream を急に閉じるために呼び出されるユーザー定義関数。
- reason <any>
- 戻り値: undefined で fulfilled される Promise。
- type <any> type オプションは将来の使用のために予約されており、必ず undefined にする必要があります。
strategy <Object>
- highWaterMark <number> 背圧が適用される前の内部キューの最大サイズ。
- size <Function> 各データチャンクのサイズを識別するために使用されるユーザー定義関数。
- chunk <any>
- 戻り値: <number>

`writableStream.abort([reason])`

Added in: v16.5.0

reason <any>
戻り値: undefined で解決される Promise。

WritableStream を中断します。キューに登録された書き込みはすべてキャンセルされ、関連する Promise は拒否されます。

`writableStream.close()`

Added in: v16.5.0

戻り値: undefined で解決される Promise。

追加の書き込みが予想されない場合に WritableStream を閉じます。

`writableStream.getWriter()`

Added in: v16.5.0

戻り値: <WritableStreamDefaultWriter>

WritableStream にデータを書き込むために使用できる新しいライターインスタンスを作成して返します。

`writableStream.locked`

Added in: v16.5.0

型: <boolean>

writableStream.locked プロパティは、デフォルトでは false であり、この WritableStream にアクティブなライターがアタッチされている間は true に切り替わります。

postMessage() での転送

<WritableStream> インスタンスは、<MessagePort> を使用して転送できます。

const stream = new WritableStream(getWritableSinkSomehow());

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  data.getWriter().write('hello');
};

port2.postMessage(stream, [stream]);

Class: `WritableStreamDefaultWriter`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

`new WritableStreamDefaultWriter(stream)`

Added in: v16.5.0

stream <WritableStream>

指定された WritableStream にロックされた新しい WritableStreamDefaultWriter を作成します。

`writableStreamDefaultWriter.abort([reason])`

Added in: v16.5.0

reason <any>
戻り値: undefined で解決される Promise。

WritableStream を中断します。キューに登録された書き込みはすべてキャンセルされ、関連する Promise は拒否されます。

`writableStreamDefaultWriter.close()`

Added in: v16.5.0

戻り値: undefined で履行される Promise。

追加の書き込みが予期されない場合に WritableStream を閉じます。

`writableStreamDefaultWriter.closed`

Added in: v16.5.0

型: <Promise> 関連付けられた<WritableStream>が閉じられたときに undefined で履行されるか、ストリームでエラーが発生した場合、またはストリームが閉じる前にライターのロックが解除された場合に拒否されます。

`writableStreamDefaultWriter.desiredSize`

Added in: v16.5.0

型: <number>

<WritableStream>のキューを埋めるために必要なデータ量。

`writableStreamDefaultWriter.ready`

Added in: v16.5.0

型: <Promise> ライターが使用できる状態になったときに undefined で履行されます。

`writableStreamDefaultWriter.releaseLock()`

Added in: v16.5.0

基になる<ReadableStream>に対するこのライターのロックを解除します。

`writableStreamDefaultWriter.write([chunk])`

Added in: v16.5.0

chunk: <any>
戻り値: undefined で履行される Promise。

<WritableStream>のキューに新しいデータのチャンクを追加します。

Class: `WritableStreamDefaultController`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

WritableStreamDefaultController は、<WritableStream>の内部状態を管理します。

`writableStreamDefaultController.error([error])`

Added in: v16.5.0

error <any>

ユーザーコードによって呼び出され、WritableStream データの処理中にエラーが発生したことを通知します。呼び出されると、<WritableStream>が中止され、現在保留中の書き込みがキャンセルされます。

`writableStreamDefaultController.signal`

型: <AbortSignal> <WritableStream> が中断されたときに、保留中の書き込みまたはクローズ操作をキャンセルするために使用できる AbortSignal。

クラス: `TransformStream`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	追加: v16.5.0

TransformStream は、<ReadableStream> と<WritableStream> で構成され、WritableStream に書き込まれたデータが受信され、変換されてから ReadableStream のキューにプッシュされるように接続されています。

import {
  TransformStream,
} from 'node:stream/web';

const transform = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

await Promise.all([
  transform.writable.getWriter().write('A'),
  transform.readable.getReader().read(),
]);

`new TransformStream([transformer[, writableStrategy[, readableStrategy]]])`

追加: v16.5.0

transformer <Object>
- start <Function> TransformStream が作成された直後に呼び出されるユーザー定義の関数。
- controller <TransformStreamDefaultController>
- 戻り値: undefined または undefined で解決されるPromise
- transform <Function> transformStream.writable に書き込まれたデータのチャンクを受信し、場合によっては変更してから、transformStream.readable に転送するユーザー定義の関数。
- chunk <any>
- controller <TransformStreamDefaultController>
- 戻り値: undefined で解決されるPromise。
- flush <Function> TransformStream の書き込み側が閉じられる直前に呼び出され、変換プロセスの終了を示すユーザー定義の関数。
- controller <TransformStreamDefaultController>
- 戻り値: undefined で解決されるPromise。
- readableType <any> readableType オプションは将来の使用のために予約されており、必ず undefined でなければなりません。
- writableType <any> writableType オプションは将来の使用のために予約されており、必ず undefined でなければなりません。
writableStrategy <Object>
- highWaterMark <number> バックプレッシャーが適用される前の最大内部キューサイズ。
- size <Function> 各データのチャンクのサイズを識別するために使用されるユーザー定義関数。
- chunk <any>
- 戻り値: <number>
readableStrategy <Object>
- highWaterMark <number> バックプレッシャーが適用される前の最大内部キューサイズ。
- size <Function> 各データのチャンクのサイズを識別するために使用されるユーザー定義関数。
- chunk <any>
- 戻り値: <number>

`transformStream.readable`

Added in: v16.5.0

Type: <ReadableStream>

`transformStream.writable`

Added in: v16.5.0

Type: <WritableStream>

postMessage() での転送

<TransformStream> インスタンスは、<MessagePort> を使用して転送できます。

const stream = new TransformStream();

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => {
  const { writable, readable } = data;
  // ...
};

port2.postMessage(stream, [stream]);

クラス: `TransformStreamDefaultController`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

TransformStreamDefaultController は、TransformStream の内部状態を管理します。

`transformStreamDefaultController.desiredSize`

Added in: v16.5.0

Type: <number>

読み取り側のキューを埋めるために必要なデータ量。

`transformStreamDefaultController.enqueue([chunk])`

Added in: v16.5.0

chunk <any>

データを読み取り側のキューに追加します。

`transformStreamDefaultController.error([reason])`

Added in: v16.5.0

reason <any>

変換データの処理中にエラーが発生したことを読み取り側と書き込み側の両方に通知し、両側が突然閉じられるようにします。

`transformStreamDefaultController.terminate()`

Added in: v16.5.0

トランスポートの読み取り側を閉じ、書き込み側がエラーで突然閉じられるようにします。

クラス: `ByteLengthQueuingStrategy`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

`new ByteLengthQueuingStrategy(init)`

Added in: v16.5.0

init <Object>
- highWaterMark <number>

`byteLengthQueuingStrategy.highWaterMark`

Added in: v16.5.0

型: <number>

`byteLengthQueuingStrategy.size`

Added in: v16.5.0

型: <Function>
- chunk <any>
- 戻り値: <number>

クラス: `CountQueuingStrategy`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.5.0	Added in: v16.5.0

`new CountQueuingStrategy(init)`

Added in: v16.5.0

init <Object>
- highWaterMark <number>

`countQueuingStrategy.highWaterMark`

Added in: v16.5.0

型: <number>

`countQueuingStrategy.size`

Added in: v16.5.0

型: <Function>
- chunk <any>
- 戻り値: <number>

クラス: `TextEncoderStream`

[履歴]

バージョン	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.6.0	Added in: v16.6.0

`new TextEncoderStream()`

Added in: v16.6.0

新しい TextEncoderStream インスタンスを作成します。

`textEncoderStream.encoding`

Added in: v16.6.0

Type: <string>

TextEncoderStream インスタンスでサポートされているエンコーディング。

`textEncoderStream.readable`

Added in: v16.6.0

Type: <ReadableStream>

`textEncoderStream.writable`

Added in: v16.6.0

Type: <WritableStream>

Class: `TextDecoderStream`

[履歴]

Version	Changes
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v16.6.0	Added in: v16.6.0

`new TextDecoderStream([encoding[, options]])`

Added in: v16.6.0

encoding <string> この TextDecoder インスタンスがサポートする encoding を識別します。 デフォルト: 'utf-8'。
options <Object>
- fatal <boolean> デコードの失敗が致命的な場合は true。
- ignoreBOM <boolean> true の場合、TextDecoderStream はデコードされた結果にバイトオーダーマークを含めます。false の場合、バイトオーダーマークは出力から削除されます。このオプションは、encoding が 'utf-8'、'utf-16be'、または 'utf-16le' の場合にのみ使用されます。 デフォルト: false。

新しい TextDecoderStream インスタンスを作成します。

`textDecoderStream.encoding`

Added in: v16.6.0

Type: <string>

TextDecoderStream インスタンスでサポートされているエンコーディング。

`textDecoderStream.fatal`

Added in: v16.6.0

Type: <boolean>

デコードエラーが発生した場合に TypeError がスローされる場合、値は true になります。

`textDecoderStream.ignoreBOM`

Added in: v16.6.0

Type: <boolean>

デコード結果にバイトオーダーマークが含まれる場合、値は true になります。

`textDecoderStream.readable`

Added in: v16.6.0

Type: <ReadableStream>

`textDecoderStream.writable`

Added in: v16.6.0

Type: <WritableStream>

Class: `CompressionStream`

[履歴]

Version	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v17.0.0	Added in: v17.0.0

`new CompressionStream(format)`

[履歴]

Version	変更
v21.2.0, v20.12.0	format で `deflate-raw` 値を受け入れるようになりました。
v17.0.0	Added in: v17.0.0

format <string> 'deflate', 'deflate-raw', または 'gzip' のいずれか。

`compressionStream.readable`

Added in: v17.0.0

Type: <ReadableStream>

`compressionStream.writable`

Added in: v17.0.0

Type: <WritableStream>

Class: `DecompressionStream`

[履歴]

Version	変更
v18.0.0	このクラスはグローバルオブジェクトで公開されるようになりました。
v17.0.0	Added in: v17.0.0

`new DecompressionStream(format)`

[履歴]

Version	変更
v21.2.0, v20.12.0	format で `deflate-raw` 値を受け入れるようになりました。
v17.0.0	Added in: v17.0.0

format <string> 'deflate', 'deflate-raw', または 'gzip' のいずれか。

`decompressionStream.readable`

Added in: v17.0.0

Type: <ReadableStream>

`decompressionStream.writable`

Added in: v17.0.0

Type: <WritableStream>

ユーティリティコンシューマー

追加: v16.7.0

ユーティリティコンシューマー関数は、ストリームを消費するための共通オプションを提供します。

これらは以下を使用してアクセスできます。

ESMCJS

import {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} from 'node:stream/consumers';

const {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} = require('node:stream/consumers');

`streamConsumers.arrayBuffer(stream)`

追加: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
戻り値: <Promise> ストリームのすべてのコンテンツを含む ArrayBuffer で履行します。

ESMCJS

import { arrayBuffer } from 'node:stream/consumers';
import { Readable } from 'node:stream';
import { TextEncoder } from 'node:util';

const encoder = new TextEncoder();
const dataArray = encoder.encode('hello world from consumers!');

const readable = Readable.from(dataArray);
const data = await arrayBuffer(readable);
console.log(`from readable: ${data.byteLength}`);
// Prints: from readable: 76

const { arrayBuffer } = require('node:stream/consumers');
const { Readable } = require('node:stream');
const { TextEncoder } = require('node:util');

const encoder = new TextEncoder();
const dataArray = encoder.encode('hello world from consumers!');
const readable = Readable.from(dataArray);
arrayBuffer(readable).then((data) => {
  console.log(`from readable: ${data.byteLength}`);
  // Prints: from readable: 76
});

`streamConsumers.blob(stream)`

追加: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
戻り値: <Promise> ストリームのすべてのコンテンツを含む <Blob> で履行します。

ESMCJS

import { blob } from 'node:stream/consumers';

const dataBlob = new Blob(['hello world from consumers!']);

const readable = dataBlob.stream();
const data = await blob(readable);
console.log(`from readable: ${data.size}`);
// Prints: from readable: 27

const { blob } = require('node:stream/consumers');

const dataBlob = new Blob(['hello world from consumers!']);

const readable = dataBlob.stream();
blob(readable).then((data) => {
  console.log(`from readable: ${data.size}`);
  // Prints: from readable: 27
});

`streamConsumers.buffer(stream)`

Added in: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
戻り値: <Promise> ストリームのすべてのコンテンツを含む<Buffer>で履行される。

ESMCJS

import { buffer } from 'node:stream/consumers';
import { Readable } from 'node:stream';
import { Buffer } from 'node:buffer';

const dataBuffer = Buffer.from('hello world from consumers!');

const readable = Readable.from(dataBuffer);
const data = await buffer(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27

const { buffer } = require('node:stream/consumers');
const { Readable } = require('node:stream');
const { Buffer } = require('node:buffer');

const dataBuffer = Buffer.from('hello world from consumers!');

const readable = Readable.from(dataBuffer);
buffer(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});

`streamConsumers.json(stream)`

Added in: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
戻り値: <Promise> JSON.parse() を通過する UTF-8 エンコード文字列として解析されたストリームのコンテンツで履行される。

ESMCJS

import { json } from 'node:stream/consumers';
import { Readable } from 'node:stream';

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  }),
);

const readable = Readable.from(JSON.stringify(items));
const data = await json(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 100

const { json } = require('node:stream/consumers');
const { Readable } = require('node:stream');

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: 'hello world from consumers!',
  }),
);

const readable = Readable.from(JSON.stringify(items));
json(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 100
});

`streamConsumers.text(stream)`

追加: v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
戻り値: <Promise> ストリームの内容をUTF-8エンコードされた文字列として解析し、履行します。

ESMCJS

import { text } from 'node:stream/consumers';
import { Readable } from 'node:stream';

const readable = Readable.from('Hello world from consumers!');
const data = await text(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27

const { text } = require('node:stream/consumers');
const { Readable } = require('node:stream');

const readable = Readable.from('Hello world from consumers!');
text(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});

Web Streams API ​

概要 ​

ReadableStreamの例 ​

API ​

クラス: ReadableStream ​

new ReadableStream([underlyingSource [, strategy]]) ​

readableStream.locked ​

readableStream.cancel([reason]) ​

readableStream.getReader([options]) ​

readableStream.pipeThrough(transform[, options]) ​

readableStream.pipeTo(destination[, options]) ​

readableStream.tee() ​

readableStream.values([options]) ​

Async Iteration ​

postMessage() での転送 ​

ReadableStream.from(iterable) ​

クラス: ReadableStreamDefaultReader ​

new ReadableStreamDefaultReader(stream) ​

readableStreamDefaultReader.cancel([reason]) ​

readableStreamDefaultReader.closed ​

readableStreamDefaultReader.read() ​

readableStreamDefaultReader.releaseLock() ​

Class: ReadableStreamBYOBReader ​

new ReadableStreamBYOBReader(stream) ​

readableStreamBYOBReader.cancel([reason]) ​

readableStreamBYOBReader.closed ​

readableStreamBYOBReader.read(view[, options]) ​

readableStreamBYOBReader.releaseLock() ​

クラス: ReadableStreamDefaultController ​

readableStreamDefaultController.close() ​

readableStreamDefaultController.desiredSize ​

readableStreamDefaultController.enqueue([chunk]) ​

readableStreamDefaultController.error([error]) ​

クラス: ReadableByteStreamController ​

readableByteStreamController.byobRequest ​

readableByteStreamController.close() ​

readableByteStreamController.desiredSize ​

readableByteStreamController.enqueue(chunk) ​

readableByteStreamController.error([error]) ​

クラス: ReadableStreamBYOBRequest ​

readableStreamBYOBRequest.respond(bytesWritten) ​

readableStreamBYOBRequest.respondWithNewView(view) ​

readableStreamBYOBRequest.view ​

Class: WritableStream ​

new WritableStream([underlyingSink[, strategy]]) ​

writableStream.abort([reason]) ​

writableStream.close() ​

writableStream.getWriter() ​

writableStream.locked ​

postMessage() での転送 ​

Class: WritableStreamDefaultWriter ​

new WritableStreamDefaultWriter(stream) ​

writableStreamDefaultWriter.abort([reason]) ​

writableStreamDefaultWriter.close() ​

writableStreamDefaultWriter.closed ​

writableStreamDefaultWriter.desiredSize ​

writableStreamDefaultWriter.ready ​

writableStreamDefaultWriter.releaseLock() ​

writableStreamDefaultWriter.write([chunk]) ​

Class: WritableStreamDefaultController ​

writableStreamDefaultController.error([error]) ​

writableStreamDefaultController.signal ​

クラス: TransformStream ​

new TransformStream([transformer[, writableStrategy[, readableStrategy]]]) ​

transformStream.readable ​

transformStream.writable ​

postMessage() での転送 ​

クラス: TransformStreamDefaultController ​

transformStreamDefaultController.desiredSize ​

transformStreamDefaultController.enqueue([chunk]) ​

transformStreamDefaultController.error([reason]) ​

transformStreamDefaultController.terminate() ​

クラス: ByteLengthQueuingStrategy ​

new ByteLengthQueuingStrategy(init) ​

byteLengthQueuingStrategy.highWaterMark ​

byteLengthQueuingStrategy.size ​

クラス: CountQueuingStrategy ​

new CountQueuingStrategy(init) ​

countQueuingStrategy.highWaterMark ​

countQueuingStrategy.size ​

Web Streams API

概要

`ReadableStream`の例

API

クラス: `ReadableStream`

`new ReadableStream([underlyingSource [, strategy]])`

`readableStream.locked`

`readableStream.cancel([reason])`

`readableStream.getReader([options])`

`readableStream.pipeThrough(transform[, options])`

`readableStream.pipeTo(destination[, options])`

`readableStream.tee()`

`readableStream.values([options])`

Async Iteration

`postMessage()` での転送

`ReadableStream.from(iterable)`

クラス: `ReadableStreamDefaultReader`

`new ReadableStreamDefaultReader(stream)`

`readableStreamDefaultReader.cancel([reason])`

`readableStreamDefaultReader.closed`

`readableStreamDefaultReader.read()`

`readableStreamDefaultReader.releaseLock()`

Class: `ReadableStreamBYOBReader`

`new ReadableStreamBYOBReader(stream)`

`readableStreamBYOBReader.cancel([reason])`

`readableStreamBYOBReader.closed`

`readableStreamBYOBReader.read(view[, options])`

`readableStreamBYOBReader.releaseLock()`

クラス: `ReadableStreamDefaultController`

`readableStreamDefaultController.close()`

`readableStreamDefaultController.desiredSize`

`readableStreamDefaultController.enqueue([chunk])`

`readableStreamDefaultController.error([error])`

クラス: `ReadableByteStreamController`

`readableByteStreamController.byobRequest`

`readableByteStreamController.close()`

`readableByteStreamController.desiredSize`

`readableByteStreamController.enqueue(chunk)`

`readableByteStreamController.error([error])`

クラス: `ReadableStreamBYOBRequest`

`readableStreamBYOBRequest.respond(bytesWritten)`

`readableStreamBYOBRequest.respondWithNewView(view)`

`readableStreamBYOBRequest.view`

Class: `WritableStream`

`new WritableStream([underlyingSink[, strategy]])`

`writableStream.abort([reason])`

`writableStream.close()`

`writableStream.getWriter()`

`writableStream.locked`

postMessage() での転送

Class: `WritableStreamDefaultWriter`

`new WritableStreamDefaultWriter(stream)`

`writableStreamDefaultWriter.abort([reason])`

`writableStreamDefaultWriter.close()`

`writableStreamDefaultWriter.closed`

`writableStreamDefaultWriter.desiredSize`

`writableStreamDefaultWriter.ready`

`writableStreamDefaultWriter.releaseLock()`

`writableStreamDefaultWriter.write([chunk])`

Class: `WritableStreamDefaultController`

`writableStreamDefaultController.error([error])`

`writableStreamDefaultController.signal`

クラス: `TransformStream`

`new TransformStream([transformer[, writableStrategy[, readableStrategy]]])`

`transformStream.readable`

`transformStream.writable`

postMessage() での転送

クラス: `TransformStreamDefaultController`

`transformStreamDefaultController.desiredSize`

`transformStreamDefaultController.enqueue([chunk])`

`transformStreamDefaultController.error([reason])`

`transformStreamDefaultController.terminate()`

クラス: `ByteLengthQueuingStrategy`

`new ByteLengthQueuingStrategy(init)`

`byteLengthQueuingStrategy.highWaterMark`

`byteLengthQueuingStrategy.size`

クラス: `CountQueuingStrategy`

`new CountQueuingStrategy(init)`

`countQueuingStrategy.highWaterMark`

`countQueuingStrategy.size`