Web Streams API

[Verlauf]

Version	Änderungen
v21.0.0	Nicht mehr experimentell.
v18.0.0	Die Verwendung dieser API gibt keine Runtime-Warnung mehr aus.
v16.5.0	Hinzugefügt in: v16.5.0

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Eine Implementierung des WHATWG Streams Standard.

Überblick

Der WHATWG Streams Standard (oder "Web Streams") definiert eine API zur Behandlung von Streaming-Daten. Es ähnelt der Node.js Streams API, entstand aber später und ist zur "Standard"-API für das Streaming von Daten in vielen JavaScript-Umgebungen geworden.

Es gibt drei Haupttypen von Objekten:

• ReadableStream - Repräsentiert eine Quelle für Streaming-Daten.
• WritableStream - Repräsentiert ein Ziel für Streaming-Daten.
• TransformStream - Repräsentiert einen Algorithmus zur Transformation von Streaming-Daten.

Beispiel ReadableStream

Dieses Beispiel erstellt einen einfachen ReadableStream, der einmal pro Sekunde den aktuellen performance.now()-Zeitstempel für immer pusht. Ein Async-Iterator wird verwendet, um die Daten aus dem Stream zu lesen.

ESM

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)

CJS

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

Klasse: ReadableStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Hinzugefügt in: v16.5.0

• underlyingSource <Object>

  • start <Function> Eine benutzerdefinierte Funktion, die sofort aufgerufen wird, wenn der ReadableStream erstellt wird.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Gibt zurück: undefined oder ein Promise, das mit undefined erfüllt wurde.

  • pull <Function> Eine benutzerdefinierte Funktion, die wiederholt aufgerufen wird, wenn die interne Warteschlange von ReadableStream nicht voll ist. Die Operation kann synchron oder asynchron sein. Wenn asynchron, wird die Funktion erst dann wieder aufgerufen, wenn das zuvor zurückgegebene Promise erfüllt wurde.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wurde.

  • cancel <Function> Eine benutzerdefinierte Funktion, die aufgerufen wird, wenn der ReadableStream abgebrochen wird.

  • reason <any>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wurde.

  • type <string> Muss 'bytes' oder undefined sein.

  • autoAllocateChunkSize <number> Wird nur verwendet, wenn type gleich 'bytes' ist. Wenn auf einen Wert ungleich Null gesetzt, wird automatisch ein Ansichtspuffer für ReadableByteStreamController.byobRequest zugeteilt. Wenn nicht gesetzt, muss man die internen Warteschlangen des Streams verwenden, um Daten über den Standardleser ReadableStreamDefaultReader zu übertragen.

• strategy <Object>

  • highWaterMark <number> Die maximale interne Warteschlangengröße, bevor Gegendruck angewendet wird.
  • size <Function> Eine benutzerdefinierte Funktion, die verwendet wird, um die Größe jedes Datenchunks zu identifizieren.
  • chunk <any>
  • Gibt zurück: <number>

readableStream.locked

Hinzugefügt in: v16.5.0

• Typ: <boolean> Auf true gesetzt, wenn ein aktiver Leser für diesen <ReadableStream> vorhanden ist.

Die Eigenschaft readableStream.locked ist standardmäßig false und wird auf true gesetzt, während ein aktiver Leser die Daten des Streams konsumiert.

readableStream.cancel([reason])

Hinzugefügt in: v16.5.0

• reason <any>
• Gibt zurück: Ein Promise, das mit undefined erfüllt wird, sobald die Abbruchaktion abgeschlossen ist.

readableStream.getReader([options])

Hinzugefügt in: v16.5.0

• options <Object>

  • mode <string> 'byob' oder undefined

• Gibt zurück: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

ESM

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

const stream = new ReadableStream()

const reader = stream.getReader()

console.log(await reader.read())

CJS

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

const stream = new ReadableStream()

const reader = stream.getReader()

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

Bewirkt, dass readableStream.locked auf true gesetzt wird.

readableStream.pipeThrough(transform[, options])

Hinzugefügt in: v16.5.0

• transform <Object>

  • readable <ReadableStream> Der ReadableStream, an den transform.writable die möglicherweise modifizierten Daten weiterleitet, die er von diesem ReadableStream empfängt.
  • writable <WritableStream> Der WritableStream, in den die Daten dieses ReadableStream geschrieben werden.

• options <Object>

  • preventAbort <boolean> Wenn true, führen Fehler in diesem ReadableStream nicht dazu, dass transform.writable abgebrochen wird.
  • preventCancel <boolean> Wenn true, führen Fehler im Ziel transform.writable nicht dazu, dass dieser ReadableStream abgebrochen wird.
  • preventClose <boolean> Wenn true, führt das Schließen dieses ReadableStream nicht dazu, dass transform.writable geschlossen wird.
  • signal <AbortSignal> Ermöglicht das Abbrechen der Datenübertragung mit einem <AbortController>.

• Gibt zurück: <ReadableStream> von transform.readable.

Verbindet diesen <ReadableStream> mit dem Paar <ReadableStream> und <WritableStream>, das im Argument transform bereitgestellt wird, sodass die Daten aus diesem <ReadableStream> in transform.writable geschrieben, möglicherweise transformiert und dann an transform.readable weitergeleitet werden. Sobald die Pipeline konfiguriert ist, wird transform.readable zurückgegeben.

Bewirkt, dass readableStream.locked auf true gesetzt wird, während der Pipe-Vorgang aktiv ist.

ESM

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)
// Gibt aus: A

CJS

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)
  // Gibt aus: A
})()

readableStream.pipeTo(destination[, options])

Hinzugefügt in: v16.5.0

• destination <WritableStream> Ein <WritableStream>, in den die Daten dieses ReadableStream geschrieben werden.

• options <Object>

  • preventAbort <boolean> Wenn true, führen Fehler in diesem ReadableStream nicht dazu, dass destination abgebrochen wird.
  • preventCancel <boolean> Wenn true, führen Fehler in destination nicht dazu, dass dieser ReadableStream abgebrochen wird.
  • preventClose <boolean> Wenn true, führt das Schließen dieses ReadableStream nicht dazu, dass destination geschlossen wird.
  • signal <AbortSignal> Ermöglicht das Abbrechen der Datenübertragung mit einem <AbortController>.

• Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

Bewirkt, dass readableStream.locked auf true gesetzt wird, während die Pipe-Operation aktiv ist.

readableStream.tee()

[Verlauf]

Version	Änderungen
v18.10.0, v16.18.0	Unterstützung für das Verzweigen eines lesbaren Byte-Streams.
v16.5.0	Hinzugefügt in: v16.5.0

• Gibt zurück: <ReadableStream[]>

Gibt ein Paar neuer <ReadableStream>-Instanzen zurück, an die die Daten dieses ReadableStream weitergeleitet werden. Jede erhält die gleichen Daten.

Bewirkt, dass readableStream.locked auf true gesetzt wird.

readableStream.values([options])

Hinzugefügt in: v16.5.0

• options <Object>
  • preventCancel <boolean> Wenn true, verhindert, dass der <ReadableStream> geschlossen wird, wenn der asynchrone Iterator abrupt beendet wird. Standard: false.

Erstellt und gibt einen asynchronen Iterator zurück, der zum Verbrauchen der Daten dieses ReadableStream verwendet werden kann.

Bewirkt, dass readableStream.locked auf true gesetzt wird, während der asynchrone Iterator aktiv ist.

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

Asynchrone Iteration

Das <ReadableStream>-Objekt unterstützt das asynchrone Iteratorprotokoll unter Verwendung der for await-Syntax.

import { Buffer } from 'node:buffer'

const stream = new ReadableStream(getSomeSource())

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

Der asynchrone Iterator verbraucht den <ReadableStream>, bis er beendet ist.

Standardmäßig wird der <ReadableStream> geschlossen, wenn der asynchrone Iterator frühzeitig beendet wird (entweder durch ein break, return oder ein throw). Um das automatische Schließen des <ReadableStream> zu verhindern, verwenden Sie die Methode readableStream.values(), um den asynchronen Iterator zu erhalten und die Option preventCancel auf true zu setzen.

Der <ReadableStream> darf nicht gesperrt sein (d. h., er darf keinen vorhandenen aktiven Leser haben). Während der asynchronen Iteration wird der <ReadableStream> gesperrt.

Übertragung mit postMessage()

Eine <ReadableStream>-Instanz kann mithilfe eines <MessagePort> übertragen werden.

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)

Hinzugefügt in: v20.6.0

• iterable <Iterable> Objekt, das das Symbol.asyncIterator oder Symbol.iterator Iterable-Protokoll implementiert.

Eine Hilfsmethode, die einen neuen <ReadableStream> aus einem Iterable erstellt.

ESM

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) // Gibt aus: 'a', 'b', 'c'

CJS

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) // Gibt aus: 'a', 'b', 'c'
})()

Klasse: ReadableStreamDefaultReader

[Historie]

Version	Änderungen
v18.0.0	Diese Klasse wird jetzt im globalen Objekt verfügbar gemacht.
v16.5.0	Hinzugefügt in: v16.5.0

Standardmäßig gibt der Aufruf von readableStream.getReader() ohne Argumente eine Instanz von ReadableStreamDefaultReader zurück. Der Standard-Reader behandelt die Datenchunks, die durch den Stream geleitet werden, als opake Werte, wodurch der <ReadableStream> generell mit jedem JavaScript-Wert arbeiten kann.

new ReadableStreamDefaultReader(stream)

Hinzugefügt in: v16.5.0

• stream <ReadableStream>

Erstellt einen neuen <ReadableStreamDefaultReader>, der an den angegebenen <ReadableStream> gebunden ist.

readableStreamDefaultReader.cancel([reason])

Hinzugefügt in: v16.5.0

• reason <any>
• Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

Bricht den <ReadableStream> ab und gibt ein Promise zurück, das erfüllt wird, wenn der zugrunde liegende Stream abgebrochen wurde.

readableStreamDefaultReader.closed

Hinzugefügt in: v16.5.0

• Typ: <Promise> Erfüllt mit undefined, wenn der zugehörige <ReadableStream> geschlossen wird, oder abgelehnt, wenn der Stream einen Fehler verursacht oder die Sperre des Readers aufgehoben wird, bevor der Stream den Abschluss beendet.

readableStreamDefaultReader.read()

Hinzugefügt in: v16.5.0

• Gibt zurück: Ein Promise, das mit einem Objekt erfüllt wird:
  • value <any>
  • done <boolean>

Fordert den nächsten Datenchunk vom zugrunde liegenden <ReadableStream> an und gibt ein Promise zurück, das mit den Daten erfüllt wird, sobald diese verfügbar sind.

readableStreamDefaultReader.releaseLock()

Hinzugefügt in: v16.5.0

Gibt die Sperre dieses Readers für den zugrunde liegenden <ReadableStream> frei.

Klasse: ReadableStreamBYOBReader

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse wird jetzt im globalen Objekt verfügbar gemacht.
v16.5.0	Hinzugefügt in: v16.5.0

Der ReadableStreamBYOBReader ist ein alternativer Konsument für byteorientierte <ReadableStream>s (solche, die mit underlyingSource.type gleich 'bytes' erstellt werden, als der ReadableStream erstellt wurde).

Das BYOB ist die Abkürzung für "bring your own buffer" (bringe deinen eigenen Puffer mit). Dies ist ein Muster, das ein effizienteres Lesen von byteorientierten Daten ermöglicht, das unnötiges Kopieren vermeidet.

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)

Hinzugefügt in: v16.5.0

• stream <ReadableStream>

Erstellt einen neuen ReadableStreamBYOBReader, der an den gegebenen <ReadableStream> gesperrt ist.

readableStreamBYOBReader.cancel([reason])

Hinzugefügt in: v16.5.0

• reason <beliebig>
• Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

Bricht den <ReadableStream> ab und gibt ein Promise zurück, das erfüllt wird, wenn der zugrunde liegende Stream abgebrochen wurde.

readableStreamBYOBReader.closed

Hinzugefügt in: v16.5.0

• Typ: <Promise> Wird mit undefined erfüllt, wenn der zugehörige <ReadableStream> geschlossen wird oder abgelehnt, wenn der Stream Fehler verursacht oder die Sperre des Readers aufgehoben wird, bevor der Stream den Schließvorgang beendet.

readableStreamBYOBReader.read(view[, options])

[Verlauf]

Version	Änderungen
v21.7.0, v20.17.0	Option min hinzugefügt.
v16.5.0	Hinzugefügt in: v16.5.0

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

• options <Object>

  • min <number> Wenn festgelegt, wird das zurückgegebene Promise erst erfüllt, sobald min-Anzahl von Elementen verfügbar sind. Wenn nicht festgelegt, wird das Promise erfüllt, wenn mindestens ein Element verfügbar ist.

• Gibt zurück: Ein Promise, das mit einem Objekt erfüllt wird:

  • value <TypedArray> | <DataView>
  • done <boolean>

Fordert den nächsten Datenblock vom zugrunde liegenden <ReadableStream> an und gibt ein Promise zurück, das mit den Daten erfüllt wird, sobald diese verfügbar sind.

Übergeben Sie keine gepoolte <Buffer>-Objektinstanz an diese Methode. Gepoolte Buffer-Objekte werden mit Buffer.allocUnsafe() oder Buffer.from() erstellt oder werden oft von verschiedenen Rückrufen des node:fs-Moduls zurückgegeben. Diese Arten von Buffer verwenden ein gemeinsames zugrunde liegendes <ArrayBuffer>-Objekt, das alle Daten aller gepoolten Buffer-Instanzen enthält. Wenn ein Buffer, <TypedArray> oder <DataView> an readableStreamBYOBReader.read() übergeben wird, wird das zugrunde liegende ArrayBuffer der View abgetrennt, wodurch alle vorhandenen Views ungültig werden, die möglicherweise auf diesem ArrayBuffer existieren. Dies kann katastrophale Folgen für Ihre Anwendung haben.

readableStreamBYOBReader.releaseLock()

Hinzugefügt in: v16.5.0

Gibt die Sperre dieses Readers für den zugrunde liegenden <ReadableStream> frei.

Klasse: ReadableStreamDefaultController

Hinzugefügt in: v16.5.0

Jeder <ReadableStream> hat einen Controller, der für den internen Zustand und die Verwaltung der Warteschlange des Streams verantwortlich ist. Der ReadableStreamDefaultController ist die Standard-Controller-Implementierung für ReadableStreams, die nicht byteorientiert sind.

readableStreamDefaultController.close()

Hinzugefügt in: v16.5.0

Schließt den <ReadableStream>, dem dieser Controller zugeordnet ist.

readableStreamDefaultController.desiredSize

Hinzugefügt in: v16.5.0

• Typ: <number>

Gibt die Datenmenge zurück, die noch aussteht, um die Warteschlange des <ReadableStream> zu füllen.

readableStreamDefaultController.enqueue([chunk])

Hinzugefügt in: v16.5.0

• chunk <any>

Hängt einen neuen Datenblock an die Warteschlange des <ReadableStream> an.

readableStreamDefaultController.error([error])

Hinzugefügt in: v16.5.0

• error <any>

Signalisiert einen Fehler, der dazu führt, dass der <ReadableStream> einen Fehler verursacht und sich schließt.

Klasse: ReadableByteStreamController

[Verlauf]

Version	Änderungen
v18.10.0	Unterstützung für die Handhabung einer BYOB-Pull-Anfrage von einem freigegebenen Reader.
v16.5.0	Hinzugefügt in: v16.5.0

Jeder <ReadableStream> hat einen Controller, der für den internen Zustand und die Verwaltung der Warteschlange des Streams verantwortlich ist. Der ReadableByteStreamController ist für byteorientierte ReadableStreams.

readableByteStreamController.byobRequest

Hinzugefügt in: v16.5.0

• Typ: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Hinzugefügt in: v16.5.0

Schließt den <ReadableStream>, dem dieser Controller zugeordnet ist.

readableByteStreamController.desiredSize

Hinzugefügt in: v16.5.0

• Typ: <number>

Gibt die Datenmenge zurück, die noch zum Füllen der Warteschlange des <ReadableStream> verbleibt.

readableByteStreamController.enqueue(chunk)

Hinzugefügt in: v16.5.0

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

Hängt einen neuen Datenchunk an die Warteschlange des <ReadableStream> an.

readableByteStreamController.error([error])

Hinzugefügt in: v16.5.0

• error <any>

Signalisiert einen Fehler, der dazu führt, dass der <ReadableStream> einen Fehler verursacht und geschlossen wird.

Klasse: ReadableStreamBYOBRequest

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

Bei Verwendung von ReadableByteStreamController in byteorientierten Streams und bei Verwendung des ReadableStreamBYOBReader bietet die Eigenschaft readableByteStreamController.byobRequest Zugriff auf eine ReadableStreamBYOBRequest-Instanz, die die aktuelle Leseanforderung darstellt. Das Objekt wird verwendet, um Zugriff auf den ArrayBuffer/TypedArray zu erhalten, der für die Leseanforderung zum Ausfüllen bereitgestellt wurde, und bietet Methoden zum Signalisieren, dass die Daten bereitgestellt wurden.

readableStreamBYOBRequest.respond(bytesWritten)

Hinzugefügt in: v16.5.0

• bytesWritten <number>

Signalisiert, dass eine Anzahl von bytesWritten Bytes in readableStreamBYOBRequest.view geschrieben wurde.

readableStreamBYOBRequest.respondWithNewView(view)

Hinzugefügt in: v16.5.0

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

Signalisiert, dass die Anfrage mit Bytes erfüllt wurde, die in einen neuen Buffer, TypedArray oder DataView geschrieben wurden.

readableStreamBYOBRequest.view

Hinzugefügt in: v16.5.0

• Typ: <Buffer> | <TypedArray> | <DataView>

Klasse: WritableStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist nun im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

Der WritableStream ist ein Ziel, an das Streamdaten gesendet werden.

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]])

Hinzugefügt in: v16.5.0

• underlyingSink <Object>

  • start <Function> Eine benutzerdefinierte Funktion, die sofort aufgerufen wird, wenn der WritableStream erstellt wird.

  • controller <WritableStreamDefaultController>

  • Gibt zurück: undefined oder ein Promise, das mit undefined erfüllt wird.

  • write <Function> Eine benutzerdefinierte Funktion, die aufgerufen wird, wenn ein Datenblock in den WritableStream geschrieben wurde.

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

  • close <Function> Eine benutzerdefinierte Funktion, die aufgerufen wird, wenn der WritableStream geschlossen wird.

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

  • abort <Function> Eine benutzerdefinierte Funktion, die aufgerufen wird, um den WritableStream abrupt zu schließen.

  • reason <any>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

  • type <any> Die type-Option ist für die zukünftige Verwendung reserviert und muss undefiniert sein.

• strategy <Object>

  • highWaterMark <number> Die maximale interne Warteschlangengröße, bevor Gegendruck angewendet wird.
  • size <Function> Eine benutzerdefinierte Funktion, die verwendet wird, um die Größe jedes Datenblocks zu identifizieren.
  • chunk <any>
  • Gibt zurück: <number>

writableStream.abort([reason])

Hinzugefügt in: v16.5.0

• reason <any>
• Gibt zurück: Eine mit undefined erfüllte Promise.

Beendet abrupt den WritableStream. Alle in der Warteschlange befindlichen Schreibvorgänge werden abgebrochen und ihre zugehörigen Promises werden abgelehnt.

writableStream.close()

Hinzugefügt in: v16.5.0

• Gibt zurück: Eine mit undefined erfüllte Promise.

Schließt den WritableStream, wenn keine zusätzlichen Schreibvorgänge erwartet werden.

writableStream.getWriter()

Hinzugefügt in: v16.5.0

• Gibt zurück: <WritableStreamDefaultWriter>

Erstellt und gibt eine neue Writer-Instanz zurück, die zum Schreiben von Daten in den WritableStream verwendet werden kann.

writableStream.locked

Hinzugefügt in: v16.5.0

• Typ: <boolean>

Die Eigenschaft writableStream.locked ist standardmäßig false und wird auf true gesetzt, solange ein aktiver Writer an diesen WritableStream angehängt ist.

Übertragung mit postMessage()

Eine <WritableStream>-Instanz kann mit einem <MessagePort> übertragen werden.

const stream = new WritableStream(getWritableSinkSomehow())

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Klasse: WritableStreamDefaultWriter

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

new WritableStreamDefaultWriter(stream)

Hinzugefügt in: v16.5.0

• stream <WritableStream>

Erstellt einen neuen WritableStreamDefaultWriter, der an den gegebenen WritableStream gebunden ist.

writableStreamDefaultWriter.abort([reason])

Hinzugefügt in: v16.5.0

• reason <any>
• Gibt zurück: Eine mit undefined erfüllte Promise.

Beendet abrupt den WritableStream. Alle in der Warteschlange befindlichen Schreibvorgänge werden abgebrochen und ihre zugehörigen Promises werden abgelehnt.

writableStreamDefaultWriter.close()

Hinzugefügt in: v16.5.0

• Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

Schließt den WritableStream, wenn keine weiteren Schreibvorgänge erwartet werden.

writableStreamDefaultWriter.closed

Hinzugefügt in: v16.5.0

• Typ: <Promise> Erfüllt mit undefined, wenn der zugehörige <WritableStream> geschlossen wird oder abgelehnt, wenn der Stream Fehler aufweist oder die Sperre des Writers freigegeben wird, bevor der Stream mit dem Schließen fertig ist.

writableStreamDefaultWriter.desiredSize

Hinzugefügt in: v16.5.0

• Typ: <number>

Die Datenmenge, die erforderlich ist, um die Warteschlange des <WritableStream> zu füllen.

writableStreamDefaultWriter.ready

Hinzugefügt in: v16.5.0

• Typ: <Promise> Erfüllt mit undefined, wenn der Writer bereit zur Verwendung ist.

writableStreamDefaultWriter.releaseLock()

Hinzugefügt in: v16.5.0

Gibt die Sperre dieses Writers auf den zugrunde liegenden <ReadableStream> frei.

writableStreamDefaultWriter.write([chunk])

Hinzugefügt in: v16.5.0

• chunk: <any>
• Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

Hängt einen neuen Datenblock an die Warteschlange des <WritableStream> an.

Klasse: WritableStreamDefaultController

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse wird jetzt im globalen Objekt bereitgestellt.
v16.5.0	Hinzugefügt in: v16.5.0

Der WritableStreamDefaultController verwaltet den internen Zustand des <WritableStream>.

writableStreamDefaultController.error([error])

Hinzugefügt in: v16.5.0

• error <any>

Wird vom Benutzercode aufgerufen, um zu signalisieren, dass beim Verarbeiten der WritableStream-Daten ein Fehler aufgetreten ist. Wenn sie aufgerufen wird, wird der <WritableStream> abgebrochen, wobei derzeit ausstehende Schreibvorgänge abgebrochen werden.

writableStreamDefaultController.signal

• Typ: <AbortSignal> Ein AbortSignal, das verwendet werden kann, um ausstehende Schreib- oder Schließoperationen abzubrechen, wenn ein <WritableStream> abgebrochen wird.

Klasse: TransformStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist nun im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

Ein TransformStream besteht aus einem <ReadableStream> und einem <WritableStream>, die so verbunden sind, dass die in den WritableStream geschriebenen Daten empfangen und potenziell transformiert werden, bevor sie in die Warteschlange des ReadableStream eingereiht werden.

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]]])

Hinzugefügt in: v16.5.0

• transformer <Object>

  • start <Function> Eine benutzerdefinierte Funktion, die sofort aufgerufen wird, wenn der TransformStream erstellt wird.

  • controller <TransformStreamDefaultController>

  • Gibt zurück: undefined oder ein Promise, das mit undefined erfüllt wird

  • transform <Function> Eine benutzerdefinierte Funktion, die einen Datenblock empfängt und potenziell modifiziert, der in transformStream.writable geschrieben wurde, bevor er an transformStream.readable weitergeleitet wird.

  • chunk <any>

  • controller <TransformStreamDefaultController>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

  • flush <Function> Eine benutzerdefinierte Funktion, die unmittelbar vor dem Schließen der schreibbaren Seite des TransformStream aufgerufen wird und das Ende des Transformationsprozesses signalisiert.

  • controller <TransformStreamDefaultController>

  • Gibt zurück: Ein Promise, das mit undefined erfüllt wird.

  • readableType <any> Die Option readableType ist für die zukünftige Verwendung reserviert und muss undefined sein.

  • writableType <any> Die Option writableType ist für die zukünftige Verwendung reserviert und muss undefined sein.

• writableStrategy <Object>

  • highWaterMark <number> Die maximale Größe der internen Warteschlange, bevor Gegendruck ausgeübt wird.
  • size <Function> Eine benutzerdefinierte Funktion, die verwendet wird, um die Größe jedes Datenblocks zu identifizieren.
  • chunk <any>
  • Gibt zurück: <number>

• readableStrategy <Object>

  • highWaterMark <number> Die maximale Größe der internen Warteschlange, bevor Gegendruck ausgeübt wird.
  • size <Function> Eine benutzerdefinierte Funktion, die verwendet wird, um die Größe jedes Datenblocks zu identifizieren.
  • chunk <any>
  • Gibt zurück: <number>

transformStream.readable

Hinzugefügt in: v16.5.0

• Typ: <ReadableStream>

transformStream.writable

Hinzugefügt in: v16.5.0

• Typ: <WritableStream>

Übertragen mit postMessage()

Eine <TransformStream>-Instanz kann mit einem <MessagePort> übertragen werden.

const stream = new TransformStream()

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Klasse: TransformStreamDefaultController

[Historie]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

Der TransformStreamDefaultController verwaltet den internen Zustand des TransformStream.

transformStreamDefaultController.desiredSize

Hinzugefügt in: v16.5.0

• Typ: <number>

Die Datenmenge, die benötigt wird, um die Warteschlange der lesbaren Seite zu füllen.

transformStreamDefaultController.enqueue([chunk])

Hinzugefügt in: v16.5.0

• chunk <beliebig>

Hängt einen Datenblock an die Warteschlange der lesbaren Seite an.

transformStreamDefaultController.error([reason])

Hinzugefügt in: v16.5.0

• reason <beliebig>

Signalisiert sowohl der lesbaren als auch der schreibbaren Seite, dass ein Fehler bei der Verarbeitung der Transformationsdaten aufgetreten ist, wodurch beide Seiten abrupt geschlossen werden.

transformStreamDefaultController.terminate()

Hinzugefügt in: v16.5.0

Schließt die lesbare Seite des Transports und bewirkt, dass die schreibbare Seite abrupt mit einem Fehler geschlossen wird.

Klasse: ByteLengthQueuingStrategy

[Historie]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

new ByteLengthQueuingStrategy(init)

Hinzugefügt in: v16.5.0

• init <Object>
  • highWaterMark <number>

byteLengthQueuingStrategy.highWaterMark

Hinzugefügt in: v16.5.0

• Typ: <number>

byteLengthQueuingStrategy.size

Hinzugefügt in: v16.5.0

• Typ: <Function>
  • chunk <any>
  • Gibt zurück: <number>

Klasse: CountQueuingStrategy

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist nun im globalen Objekt verfügbar.
v16.5.0	Hinzugefügt in: v16.5.0

new CountQueuingStrategy(init)

Hinzugefügt in: v16.5.0

• init <Object>
  • highWaterMark <number>

countQueuingStrategy.highWaterMark

Hinzugefügt in: v16.5.0

• Typ: <number>

countQueuingStrategy.size

Hinzugefügt in: v16.5.0

• Typ: <Function>
  • chunk <any>
  • Gibt zurück: <number>

Klasse: TextEncoderStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist nun im globalen Objekt verfügbar.
v16.6.0	Hinzugefügt in: v16.6.0

new TextEncoderStream()

Hinzugefügt in: v16.6.0

Erstellt eine neue TextEncoderStream-Instanz.

textEncoderStream.encoding

Hinzugefügt in: v16.6.0

• Typ: <string>

Die von der TextEncoderStream-Instanz unterstützte Kodierung.

textEncoderStream.readable

Hinzugefügt in: v16.6.0

• Typ: <ReadableStream>

textEncoderStream.writable

Hinzugefügt in: v16.6.0

• Typ: <WritableStream>

Klasse: TextDecoderStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v16.6.0	Hinzugefügt in: v16.6.0

new TextDecoderStream([encoding[, options]])

Hinzugefügt in: v16.6.0

• encoding <string> Identifiziert die encoding, die diese TextDecoder-Instanz unterstützt. Standard: 'utf-8'.
• options <Object>
  • fatal <boolean> true, wenn Dekodierungsfehler schwerwiegend sind.
  • ignoreBOM <boolean> Wenn true, schließt der TextDecoderStream die Byte Order Mark in das dekodierte Ergebnis ein. Wenn false, wird die Byte Order Mark aus der Ausgabe entfernt. Diese Option wird nur verwendet, wenn encoding 'utf-8', 'utf-16be' oder 'utf-16le' ist. Standard: false.

Erstellt eine neue TextDecoderStream-Instanz.

textDecoderStream.encoding

Hinzugefügt in: v16.6.0

• Typ: <string>

Die von der TextDecoderStream-Instanz unterstützte Kodierung.

textDecoderStream.fatal

Hinzugefügt in: v16.6.0

• Typ: <boolean>

Der Wert ist true, wenn Dekodierungsfehler dazu führen, dass ein TypeError ausgelöst wird.

textDecoderStream.ignoreBOM

Hinzugefügt in: v16.6.0

• Typ: <boolean>

Der Wert ist true, wenn das Dekodierungsergebnis die Byte Order Mark enthält.

textDecoderStream.readable

Hinzugefügt in: v16.6.0

• Typ: <ReadableStream>

textDecoderStream.writable

Hinzugefügt in: v16.6.0

• Typ: <WritableStream>

Klasse: CompressionStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v17.0.0	Hinzugefügt in: v17.0.0

new CompressionStream(format)

[Verlauf]

Version	Änderungen
v21.2.0, v20.12.0	format akzeptiert jetzt den Wert deflate-raw.
v17.0.0	Hinzugefügt in: v17.0.0

• format <string> Eines von 'deflate', 'deflate-raw' oder 'gzip'.

compressionStream.readable

Hinzugefügt in: v17.0.0

• Typ: <ReadableStream>

compressionStream.writable

Hinzugefügt in: v17.0.0

• Typ: <WritableStream>

Klasse: DecompressionStream

[Verlauf]

Version	Änderungen
v18.0.0	Diese Klasse ist jetzt im globalen Objekt verfügbar.
v17.0.0	Hinzugefügt in: v17.0.0

new DecompressionStream(format)

[Verlauf]

Version	Änderungen
v21.2.0, v20.12.0	format akzeptiert jetzt den Wert deflate-raw.
v17.0.0	Hinzugefügt in: v17.0.0

• format <string> Eines von 'deflate', 'deflate-raw' oder 'gzip'.

decompressionStream.readable

Hinzugefügt in: v17.0.0

• Typ: <ReadableStream>

decompressionStream.writable

Hinzugefügt in: v17.0.0

• Typ: <WritableStream>

Utility-Konsumenten

Hinzugefügt in: v16.7.0

Die Utility-Konsumentenfunktionen bieten allgemeine Optionen für das Konsumieren von Streams.

Der Zugriff erfolgt über:

ESM

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

CJS

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

streamConsumers.arrayBuffer(stream)

Hinzugefügt in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Gibt zurück: <Promise> Wird mit einem ArrayBuffer erfüllt, das den gesamten Inhalt des Streams enthält.

ESM

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}`)
// Gibt aus: from readable: 76

CJS

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}`)
  // Gibt aus: from readable: 76
})

streamConsumers.blob(stream)

Hinzugefügt in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Gibt zurück: <Promise> Wird mit einem <Blob> erfüllt, das den gesamten Inhalt des Streams enthält.

ESM

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}`)
// Gibt aus: from readable: 27

CJS

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}`)
  // Gibt aus: from readable: 27
})

streamConsumers.buffer(stream)

Hinzugefügt in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Gibt zurück: <Promise> Wird mit einem <Buffer> erfüllt, der den gesamten Inhalt des Streams enthält.

ESM

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}`)
// Gibt aus: from readable: 27

CJS

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}`)
  // Gibt aus: from readable: 27
})

streamConsumers.json(stream)

Hinzugefügt in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Gibt zurück: <Promise> Wird mit dem Inhalt des Streams als UTF-8-kodierter String erfüllt, der dann durch JSON.parse() geleitet wird.

ESM

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}`)
// Gibt aus: from readable: 100

CJS

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}`)
  // Gibt aus: from readable: 100
})

streamConsumers.text(stream)

Hinzugefügt in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Gibt zurück: <Promise> Wird mit dem Inhalt des Streams erfüllt, der als UTF-8-kodierter String geparst wurde.

ESM

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

CJS

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