API Web Streams

[Historique]

Version	Modifications
v21.0.0	N'est plus expérimental.
v18.0.0	L'utilisation de cette API n'émet plus d'avertissement d'exécution.
v16.5.0	Ajouté dans : v16.5.0

[Stable : 2 - Stable]

Stable : 2 Stabilité : 2 - Stable

Une implémentation de la norme WHATWG Streams.

Vue d'ensemble

La norme WHATWG Streams (ou « web streams ») définit une API pour la gestion des données en streaming. Elle est similaire à l'API Streams de Node.js, mais elle est apparue plus tard et est devenue l'API « standard » pour le streaming de données dans de nombreux environnements JavaScript.

Il existe trois principaux types d'objets :

ReadableStream - Représente une source de données en streaming.
WritableStream - Représente une destination pour les données en streaming.
TransformStream - Représente un algorithme pour transformer les données en streaming.

Exemple `ReadableStream`

Cet exemple crée un ReadableStream simple qui pousse l'horodatage performance.now() actuel une fois par seconde pour toujours. Un itérable asynchrone est utilisé pour lire les données du flux.

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

Classe : `ReadableStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est désormais exposée sur l'objet global.
v16.5.0	Ajoutée dans : v16.5.0

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

Ajoutée dans : v16.5.0

underlyingSource <Objet>
- start <Fonction> Une fonction définie par l'utilisateur qui est invoquée immédiatement lorsque le ReadableStream est créé.
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- Retourne : undefined ou une promesse résolue avec undefined.
- pull <Fonction> Une fonction définie par l'utilisateur qui est appelée à plusieurs reprises lorsque la file d'attente interne de ReadableStream n'est pas pleine. L'opération peut être synchrone ou asynchrone. Si elle est asynchrone, la fonction ne sera pas appelée à nouveau tant que la promesse précédemment retournée ne sera pas résolue.
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- Retourne : Une promesse résolue avec undefined.
- cancel <Fonction> Une fonction définie par l'utilisateur qui est appelée lorsque le ReadableStream est annulé.
- reason <n'importe quoi>
- Retourne : Une promesse résolue avec undefined.
- type <chaîne de caractères> Doit être 'bytes' ou undefined.
- autoAllocateChunkSize <nombre> Utilisé uniquement lorsque type est égal à 'bytes'. Lorsqu'il est défini sur une valeur non nulle, une mémoire tampon de vue est automatiquement allouée à ReadableByteStreamController.byobRequest. Lorsqu'il n'est pas défini, il faut utiliser les files d'attente internes du flux pour transférer des données via le lecteur par défaut ReadableStreamDefaultReader.
strategy <Objet>
- highWaterMark <nombre> La taille maximale de la file d'attente interne avant que la contre-pression ne soit appliquée.
- size <Fonction> Une fonction définie par l'utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <n'importe quoi>
- Retourne : <nombre>

`readableStream.locked`

Ajouté dans : v16.5.0

Type : <boolean> Fixé à true s’il existe un lecteur actif pour ce <ReadableStream>.

La propriété readableStream.locked est false par défaut, et passe à true lorsqu’un lecteur actif consomme les données du flux.

`readableStream.cancel([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse résolue avec undefined une fois l’annulation terminée.

`readableStream.getReader([options])`

Ajouté dans : v16.5.0

options <Object>
- mode <string> 'byob' ou undefined
Retourne : <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)

Rend readableStream.locked égal à true.

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

Ajouté dans : v16.5.0

transform <Object>
- readable <ReadableStream> Le ReadableStream dans lequel transform.writable enverra les données potentiellement modifiées qu’il reçoit de ce ReadableStream.
- writable <WritableStream> Le WritableStream dans lequel les données de ce ReadableStream seront écrites.
options <Object>
- preventAbort <boolean> Lorsque true, les erreurs dans ce ReadableStream n’entraîneront pas l’annulation de transform.writable.
- preventCancel <boolean> Lorsque true, les erreurs dans la destination transform.writable n’entraînent pas l’annulation de ce ReadableStream.
- preventClose <boolean> Lorsque true, la fermeture de ce ReadableStream n’entraîne pas la fermeture de transform.writable.
- signal <AbortSignal> Permet l’annulation du transfert de données à l’aide d’un <AbortController>.
Retourne : <ReadableStream> De transform.readable.

Connecte ce <ReadableStream> à la paire de <ReadableStream> et <WritableStream> fournie dans l’argument transform de sorte que les données de ce <ReadableStream> soient écrites dans transform.writable, éventuellement transformées, puis envoyées à transform.readable. Une fois le pipeline configuré, transform.readable est retourné.

Rend readableStream.locked égal à true pendant que l’opération pipe est active.

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

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

Ajouté dans : v16.5.0

destination <WritableStream> Un <WritableStream> vers lequel les données de ce ReadableStream seront écrites.
options <Object>
- preventAbort <boolean> Lorsque true, les erreurs dans ce ReadableStream n'entraîneront pas l'annulation de destination.
- preventCancel <boolean> Lorsque true, les erreurs dans destination n'entraîneront pas l'annulation de ce ReadableStream.
- preventClose <boolean> Lorsque true, la fermeture de ce ReadableStream n'entraînera pas la fermeture de destination.
- signal <AbortSignal> Permet d'annuler le transfert de données à l'aide d'un <AbortController>.
Retourne : Une promesse résolue avec undefined

Rend readableStream.locked égal à true pendant que l'opération de pipe est active.

`readableStream.tee()`

[Historique]

Version	Modifications
v18.10.0, v16.18.0	Prise en charge du branchement d'un flux d'octets lisible.
v16.5.0	Ajouté dans : v16.5.0

Retourne : <ReadableStream[]>

Retourne une paire de nouvelles instances <ReadableStream> vers lesquelles les données de ce ReadableStream seront transférées. Chacune recevra les mêmes données.

Rend readableStream.locked égal à true.

`readableStream.values([options])`

Ajouté dans : v16.5.0

options <Object>
- preventCancel <boolean> Lorsque true, empêche la fermeture du <ReadableStream> lorsque l'itérateur asynchrone se termine brutalement. Par défaut : false.

Crée et retourne un itérateur asynchrone utilisable pour consommer les données de ce ReadableStream.

Rend readableStream.locked égal à true pendant que l'itérateur asynchrone est actif.

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

Itération asynchrone

L'objet <ReadableStream> prend en charge le protocole d'itérateur asynchrone en utilisant la syntaxe for await.

import { Buffer } from 'node:buffer'

const stream = new ReadableStream(getSomeSource())

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

L'itérateur asynchrone consommera le <ReadableStream> jusqu'à ce qu'il se termine.

Par défaut, si l'itérateur asynchrone se termine prématurément (via un break, un return ou un throw), le <ReadableStream> sera fermé. Pour empêcher la fermeture automatique du <ReadableStream>, utilisez la méthode readableStream.values() pour acquérir l'itérateur asynchrone et définissez l'option preventCancel sur true.

Le <ReadableStream> ne doit pas être verrouillé (c'est-à-dire qu'il ne doit pas avoir de lecteur actif existant). Pendant l'itération asynchrone, le <ReadableStream> sera verrouillé.

Transfert avec `postMessage()`

Une instance <ReadableStream> peut être transférée à l'aide d'un <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)`

Ajouté dans : v20.6.0

iterable <Iterable> Objet implémentant le protocole itérable Symbol.asyncIterator ou Symbol.iterator.

Une méthode utilitaire qui crée un nouveau <ReadableStream> à partir d'un itérable.

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

Classe : `ReadableStreamDefaultReader`

[Historique]

Version	Modifications
v18.0.0	Cette classe est désormais exposée sur l'objet global.
v16.5.0	Ajoutée dans : v16.5.0

Par défaut, appeler readableStream.getReader() sans arguments renvoie une instance de ReadableStreamDefaultReader. Le lecteur par défaut traite les blocs de données passant par le flux comme des valeurs opaques, ce qui permet à <ReadableStream> de fonctionner avec pratiquement n'importe quelle valeur JavaScript.

`new ReadableStreamDefaultReader(stream)`

Ajouté dans : v16.5.0

stream <ReadableStream>

Crée un nouveau <ReadableStreamDefaultReader> verrouillé sur le <ReadableStream> donné.

`readableStreamDefaultReader.cancel([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse résolue avec undefined.

Annule le <ReadableStream> et renvoie une promesse qui est résolue lorsque le flux sous-jacent a été annulé.

`readableStreamDefaultReader.closed`

Ajouté dans : v16.5.0

Type : <Promise> Résolue avec undefined lorsque le <ReadableStream> associé est fermé, ou rejetée si le flux rencontre une erreur ou si le verrou du lecteur est libéré avant que le flux ne finisse de se fermer.

`readableStreamDefaultReader.read()`

Ajouté dans : v16.5.0

Retourne : Une promesse résolue avec un objet :
- value <any>
- done <boolean>

Demande le bloc de données suivant au <ReadableStream> sous-jacent et renvoie une promesse qui est résolue avec les données une fois qu'elles sont disponibles.

`readableStreamDefaultReader.releaseLock()`

Ajouté dans : v16.5.0

Libère le verrou de ce lecteur sur le <ReadableStream> sous-jacent.

Classe : `ReadableStreamBYOBReader`

[Historique]

Version	Modifications
v18.0.0	Cette classe est désormais exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

ReadableStreamBYOBReader est un consommateur alternatif pour les <ReadableStream> orientés octets (ceux qui sont créés avec underlyingSource.type défini égal à 'bytes' lors de la création de ReadableStream).

BYOB est l'abréviation de « bring your own buffer » (apportez votre propre tampon). Il s'agit d'un modèle qui permet une lecture plus efficace des données orientées octets en évitant les copies superflues.

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

Ajouté dans : v16.5.0

stream <ReadableStream>

Crée un nouveau ReadableStreamBYOBReader verrouillé sur le <ReadableStream> donné.

`readableStreamBYOBReader.cancel([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse résolue avec undefined.

Annule le flux <ReadableStream> et retourne une promesse qui est résolue lorsque le flux sous-jacent a été annulé.

`readableStreamBYOBReader.closed`

Ajouté dans : v16.5.0

Type : <Promise> Résolue avec undefined lorsque le <ReadableStream> associé est fermé, ou rejetée si le flux rencontre une erreur ou si le verrou du lecteur est libéré avant que le flux ne finisse de se fermer.

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

[Historique]

Version	Modifications
v21.7.0, v20.17.0	Option `min` ajoutée.
v16.5.0	Ajouté dans : v16.5.0

view <Buffer> | <TypedArray> | <DataView>
options <Object>
- min <number> Lorsqu'il est défini, la promesse retournée ne sera résolue que dès que min éléments seront disponibles. Lorsqu'il n'est pas défini, la promesse est résolue lorsqu'au moins un élément est disponible.
Retourne : Une promesse résolue avec un objet :
- value <TypedArray> | <DataView>
- done <boolean>

Demande le prochain bloc de données du <ReadableStream> sous-jacent et retourne une promesse qui est résolue avec les données une fois qu'elles sont disponibles.

Ne passez pas une instance d'objet <Buffer> mis en pool à cette méthode. Les objets Buffer mis en pool sont créés à l'aide de Buffer.allocUnsafe(), ou Buffer.from(), ou sont souvent retournés par diverses fonctions de rappel du module node:fs. Ces types de Buffer utilisent un objet <ArrayBuffer> sous-jacent partagé qui contient toutes les données de toutes les instances de Buffer mises en pool. Lorsqu'un Buffer, <TypedArray>, ou <DataView> est passé à readableStreamBYOBReader.read(), le ArrayBuffer sous-jacent de la vue est détaché, invalidant toutes les vues existantes qui peuvent exister sur ce ArrayBuffer. Cela peut avoir des conséquences désastreuses pour votre application.

`readableStreamBYOBReader.releaseLock()`

Ajouté dans : v16.5.0

Libère le verrou de ce lecteur sur le <ReadableStream> sous-jacent.

Classe : `ReadableStreamDefaultController`

Ajouté dans : v16.5.0

Chaque <ReadableStream> possède un contrôleur responsable de l'état interne et de la gestion de la file d'attente du flux. ReadableStreamDefaultController est l'implémentation du contrôleur par défaut pour les ReadableStream qui ne sont pas orientés octets.

`readableStreamDefaultController.close()`

Ajouté dans : v16.5.0

Ferme le <ReadableStream> auquel ce contrôleur est associé.

`readableStreamDefaultController.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

Retourne la quantité de données restantes pour remplir la file d'attente du <ReadableStream>.

`readableStreamDefaultController.enqueue([chunk])`

Ajouté dans : v16.5.0

chunk <any>

Ajoute un nouveau fragment de données à la file d'attente du <ReadableStream>.

`readableStreamDefaultController.error([error])`

Ajouté dans : v16.5.0

error <any>

Signale une erreur qui provoque une erreur et la fermeture du <ReadableStream>.

Classe : `ReadableByteStreamController`

[Historique]

Version	Modifications
v18.10.0	Prise en charge de la gestion d'une requête d'extraction BYOB d'un lecteur libéré.
v16.5.0	Ajouté dans : v16.5.0

Chaque <ReadableStream> possède un contrôleur responsable de l'état interne et de la gestion de la file d'attente du flux. ReadableByteStreamController est destiné aux ReadableStream orientés octets.

`readableByteStreamController.byobRequest`

Ajouté dans : v16.5.0

Type : <ReadableStreamBYOBRequest>

`readableByteStreamController.close()`

Ajouté dans : v16.5.0

Ferme le <ReadableStream> auquel ce contrôleur est associé.

`readableByteStreamController.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

Retourne la quantité de données restantes pour remplir la file d'attente du <ReadableStream>.

`readableByteStreamController.enqueue(chunk)`

Ajouté dans : v16.5.0

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

Ajoute un nouveau fragment de données à la file d'attente du <ReadableStream>.

`readableByteStreamController.error([error])`

Ajouté dans : v16.5.0

error <any>

Signale une erreur qui provoque une erreur et la fermeture du <ReadableStream>.

Classe : `ReadableStreamBYOBRequest`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

Lors de l'utilisation de ReadableByteStreamController dans les flux orientés octets, et lors de l'utilisation de ReadableStreamBYOBReader, la propriété readableByteStreamController.byobRequest fournit l'accès à une instance ReadableStreamBYOBRequest qui représente la requête de lecture actuelle. L'objet est utilisé pour accéder à ArrayBuffer/TypedArray qui a été fourni pour la requête de lecture à remplir, et fournit des méthodes pour signaler que les données ont été fournies.

`readableStreamBYOBRequest.respond(bytesWritten)`

Ajouté dans : v16.5.0

bytesWritten <nombre>

Signale que bytesWritten octets ont été écrits dans readableStreamBYOBRequest.view.

`readableStreamBYOBRequest.respondWithNewView(view)`

Ajouté dans : v16.5.0

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

Signale que la requête a été satisfaite avec des octets écrits dans un nouveau Buffer, TypedArray ou DataView.

`readableStreamBYOBRequest.view`

Ajouté dans : v16.5.0

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

Classe : `WritableStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

WritableStream est une destination vers laquelle les données du flux sont envoyées.

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

Ajouté dans : v16.5.0

underlyingSink <Objet>
- start <Fonction> Une fonction définie par l'utilisateur qui est appelée immédiatement lorsque WritableStream est créé.
- controller <WritableStreamDefaultController>
- Retourne : undefined ou une promesse résolue avec undefined.
- write <Fonction> Une fonction définie par l'utilisateur qui est appelée lorsqu'un bloc de données a été écrit dans WritableStream.
- chunk <quelconque>
- controller <WritableStreamDefaultController>
- Retourne : Une promesse résolue avec undefined.
- close <Fonction> Une fonction définie par l'utilisateur qui est appelée lorsque WritableStream est fermé.
- Retourne : Une promesse résolue avec undefined.
- abort <Fonction> Une fonction définie par l'utilisateur qui est appelée pour fermer brutalement WritableStream.
- reason <quelconque>
- Retourne : Une promesse résolue avec undefined.
- type <quelconque> L'option type est réservée à une utilisation future et doit être indéfinie.
strategy <Objet>
- highWaterMark <nombre> La taille maximale de la file d'attente interne avant que la contre-pression ne soit appliquée.
- size <Fonction> Une fonction définie par l'utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <quelconque>
- Retourne : <nombre>

`writableStream.abort([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse résolue avec undefined.

Met fin brutalement au WritableStream. Toutes les écritures en file d'attente seront annulées et leurs promesses associées rejetées.

`writableStream.close()`

Ajouté dans : v16.5.0

Retourne : Une promesse résolue avec undefined.

Ferme le WritableStream lorsqu'aucune écriture supplémentaire n'est attendue.

`writableStream.getWriter()`

Ajouté dans : v16.5.0

Retourne : <WritableStreamDefaultWriter>

Crée et retourne une nouvelle instance d'écrivain qui peut être utilisée pour écrire des données dans le WritableStream.

`writableStream.locked`

Ajouté dans : v16.5.0

Type : <boolean>

La propriété writableStream.locked est false par défaut, et passe à true lorsqu'un écrivain actif est attaché à ce WritableStream.

Transfert avec postMessage()

Une instance <WritableStream> peut être transférée à l'aide d'un <MessagePort>.

const stream = new WritableStream(getWritableSinkSomehow())

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Classe : `WritableStreamDefaultWriter`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

`new WritableStreamDefaultWriter(stream)`

Ajouté dans : v16.5.0

stream <WritableStream>

Crée un nouveau WritableStreamDefaultWriter verrouillé sur le WritableStream donné.

`writableStreamDefaultWriter.abort([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse résolue avec undefined.

Met fin brutalement au WritableStream. Toutes les écritures en file d'attente seront annulées et leurs promesses associées rejetées.

`writableStreamDefaultWriter.close()`

Ajouté dans : v16.5.0

Retourne : Une promesse résolue avec undefined.

Ferme le WritableStream lorsqu'aucune écriture supplémentaire n'est attendue.

`writableStreamDefaultWriter.closed`

Ajouté dans : v16.5.0

Type : <Promise> Résolue avec undefined lorsque le <WritableStream> associé est fermé, ou rejetée si le flux rencontre une erreur ou si le verrou du writer est libéré avant la fin de la fermeture du flux.

`writableStreamDefaultWriter.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

La quantité de données nécessaires pour remplir la file d'attente du <WritableStream>.

`writableStreamDefaultWriter.ready`

Ajouté dans : v16.5.0

Type : <Promise> Résolue avec undefined lorsque le writer est prêt à être utilisé.

`writableStreamDefaultWriter.releaseLock()`

Ajouté dans : v16.5.0

Libère le verrou de ce writer sur le <ReadableStream> sous-jacent.

`writableStreamDefaultWriter.write([chunk])`

Ajouté dans : v16.5.0

chunk : <any>
Retourne : Une promesse résolue avec undefined.

Ajoute un nouveau fragment de données à la file d'attente du <WritableStream>.

Classe : `WritableStreamDefaultController`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

Le WritableStreamDefaultController gère l'état interne du <WritableStream>.

`writableStreamDefaultController.error([error])`

Ajouté dans : v16.5.0

error <any>

Appelée par le code utilisateur pour signaler qu'une erreur s'est produite lors du traitement des données WritableStream. Lorsqu'elle est appelée, le <WritableStream> sera interrompu, les écritures en attente étant annulées.

`writableStreamDefaultController.signal`

Type : <AbortSignal> Un AbortSignal pouvant être utilisé pour annuler les opérations d'écriture ou de fermeture en attente lorsqu'un <WritableStream> est interrompu.

Classe : `TransformStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

Un TransformStream est composé d'un <ReadableStream> et d'un <WritableStream> qui sont connectés de telle sorte que les données écrites dans le WritableStream sont reçues, et potentiellement transformées, avant d'être poussées dans la file d'attente du 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]]])`

Ajouté dans : v16.5.0

transformer <Object>
- start <Function> Une fonction définie par l'utilisateur qui est appelée immédiatement lorsque le TransformStream est créé.
- controller <TransformStreamDefaultController>
- Retourne : undefined ou une promesse remplie avec undefined
- transform <Function> Une fonction définie par l'utilisateur qui reçoit, et potentiellement modifie, un bloc de données écrites dans transformStream.writable, avant de les transmettre à transformStream.readable.
- chunk <any>
- controller <TransformStreamDefaultController>
- Retourne : Une promesse remplie avec undefined.
- flush <Function> Une fonction définie par l'utilisateur qui est appelée immédiatement avant que le côté inscriptible du TransformStream ne soit fermé, signalant la fin du processus de transformation.
- controller <TransformStreamDefaultController>
- Retourne : Une promesse remplie avec undefined.
- readableType <any> l'option readableType est réservée à une utilisation future et doit être undefined.
- writableType <any> l'option writableType est réservée à une utilisation future et doit être undefined.
writableStrategy <Object>
- highWaterMark <number> La taille maximale de la file d'attente interne avant que la contre-pression ne soit appliquée.
- size <Function> Une fonction définie par l'utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <any>
- Retourne : <number>
readableStrategy <Object>
- highWaterMark <number> La taille maximale de la file d'attente interne avant que la contre-pression ne soit appliquée.
- size <Function> Une fonction définie par l'utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <any>
- Retourne : <number>

`transformStream.readable`

Ajouté dans : v16.5.0

Type : <ReadableStream>

`transformStream.writable`

Ajouté dans : v16.5.0

Type : <WritableStream>

Transfert avec postMessage()

Une instance de <TransformStream> peut être transférée à l'aide d'un <MessagePort>.

const stream = new TransformStream()

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Classe : `TransformStreamDefaultController`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

TransformStreamDefaultController gère l'état interne de TransformStream.

`transformStreamDefaultController.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

La quantité de données requises pour remplir la file d'attente du côté lisible.

`transformStreamDefaultController.enqueue([chunk])`

Ajouté dans : v16.5.0

chunk <any>

Ajoute un bloc de données à la file d'attente du côté lisible.

`transformStreamDefaultController.error([reason])`

Ajouté dans : v16.5.0

reason <any>

Signale aux côtés lisible et inscriptible qu'une erreur s'est produite lors du traitement des données de transformation, entraînant la fermeture brutale des deux côtés.

`transformStreamDefaultController.terminate()`

Ajouté dans : v16.5.0

Ferme le côté lisible du transport et provoque la fermeture brutale du côté inscriptible avec une erreur.

Classe : `ByteLengthQueuingStrategy`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

`new ByteLengthQueuingStrategy(init)`

Ajouté dans : v16.5.0

init <Object>
- highWaterMark <number>

`byteLengthQueuingStrategy.highWaterMark`

Ajouté dans : v16.5.0

Type : <number>

`byteLengthQueuingStrategy.size`

Ajouté dans : v16.5.0

Type : <Function>
- chunk <any>
- Retourne : <number>

Class: `CountQueuingStrategy`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.5.0	Ajouté dans : v16.5.0

`new CountQueuingStrategy(init)`

Ajouté dans : v16.5.0

init <Object>
- highWaterMark <number>

`countQueuingStrategy.highWaterMark`

Ajouté dans : v16.5.0

Type : <number>

`countQueuingStrategy.size`

Ajouté dans : v16.5.0

Type : <Function>
- chunk <any>
- Retourne : <number>

Class: `TextEncoderStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.6.0	Ajouté dans : v16.6.0

`new TextEncoderStream()`

Ajouté dans : v16.6.0

Crée une nouvelle instance TextEncoderStream.

`textEncoderStream.encoding`

Ajouté dans : v16.6.0

Type : <string>

L'encodage supporté par l'instance TextEncoderStream.

`textEncoderStream.readable`

Ajouté dans : v16.6.0

Type : <ReadableStream>

`textEncoderStream.writable`

Ajouté dans : v16.6.0

Type : <WritableStream>

Classe : `TextDecoderStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v16.6.0	Ajouté dans : v16.6.0

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

Ajouté dans : v16.6.0

encoding <string> Identifie l'encodage supporté par cette instance TextDecoder. Valeur par défaut : 'utf-8'.
options <Object>
- fatal <boolean> true si les échecs de décodage sont fatals.
- ignoreBOM <boolean> Lorsque true, le TextDecoderStream inclura la marque d'ordre des octets dans le résultat décodé. Lorsque false, la marque d'ordre des octets sera supprimée de la sortie. Cette option est uniquement utilisée lorsque encoding est 'utf-8', 'utf-16be', ou 'utf-16le'. Valeur par défaut : false.

Crée une nouvelle instance TextDecoderStream.

`textDecoderStream.encoding`

Ajouté dans : v16.6.0

Type : <string>

L'encodage supporté par l'instance TextDecoderStream.

`textDecoderStream.fatal`

Ajouté dans : v16.6.0

Type : <boolean>

La valeur sera true si les erreurs de décodage entraînent le lancement d'une erreur TypeError.

`textDecoderStream.ignoreBOM`

Ajouté dans : v16.6.0

Type : <boolean>

La valeur sera true si le résultat du décodage inclut la marque d'ordre des octets.

`textDecoderStream.readable`

Ajouté dans : v16.6.0

Type : <ReadableStream>

`textDecoderStream.writable`

Ajouté dans : v16.6.0

Type : <WritableStream>

Classe : `CompressionStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v17.0.0	Ajouté dans : v17.0.0

`new CompressionStream(format)`

[Historique]

Version	Modifications
v21.2.0, v20.12.0	format accepte maintenant la valeur `deflate-raw`.
v17.0.0	Ajouté dans : v17.0.0

format <string> L'une des valeurs 'deflate', 'deflate-raw' ou 'gzip'.

`compressionStream.readable`

Ajouté dans : v17.0.0

Type : <ReadableStream>

`compressionStream.writable`

Ajouté dans : v17.0.0

Type : <WritableStream>

Classe : `DecompressionStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est maintenant exposée sur l'objet global.
v17.0.0	Ajouté dans : v17.0.0

`new DecompressionStream(format)`

[Historique]

Version	Modifications
v21.2.0, v20.12.0	format accepte maintenant la valeur `deflate-raw`.
v17.0.0	Ajouté dans : v17.0.0

format <string> L'une des valeurs 'deflate', 'deflate-raw' ou 'gzip'.

`decompressionStream.readable`

Ajouté dans : v17.0.0

Type : <ReadableStream>

`decompressionStream.writable`

Ajouté dans : v17.0.0

Type : <WritableStream>

Consommateurs d'utilitaires

Ajouté dans : v16.7.0

Les fonctions de consommation d'utilitaires fournissent des options courantes pour consommer des flux.

Elles sont accessibles à l'aide de :

ESMCJS

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

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

`streamConsumers.arrayBuffer(stream)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Rempli avec un ArrayBuffer contenant le contenu complet du flux.

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

`streamConsumers.blob(stream)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Rempli avec un <Blob> contenant le contenu complet du flux.

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

`streamConsumers.buffer(stream)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Restitue un <Buffer> contenant le contenu complet du flux.

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

`streamConsumers.json(stream)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Restitue le contenu du flux analysé en tant que chaîne codée en UTF-8, puis passée via JSON.parse().

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

`streamConsumers.text(stream)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Resolu avec le contenu du flux analysé en tant que chaîne codée en 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}`)
// Affiche : 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}`)
  // Affiche : from readable: 27
})

API Web Streams ​

Vue d'ensemble ​

Exemple ReadableStream ​

API ​

Classe : 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]) ​

Itération asynchrone ​

Transfert avec postMessage() ​

ReadableStream.from(iterable) ​

Classe : ReadableStreamDefaultReader ​

new ReadableStreamDefaultReader(stream) ​

readableStreamDefaultReader.cancel([reason]) ​

readableStreamDefaultReader.closed ​

readableStreamDefaultReader.read() ​

readableStreamDefaultReader.releaseLock() ​

Classe : ReadableStreamBYOBReader ​

new ReadableStreamBYOBReader(stream) ​

readableStreamBYOBReader.cancel([reason]) ​

readableStreamBYOBReader.closed ​

readableStreamBYOBReader.read(view[, options]) ​

readableStreamBYOBReader.releaseLock() ​

Classe : ReadableStreamDefaultController ​

readableStreamDefaultController.close() ​

readableStreamDefaultController.desiredSize ​

readableStreamDefaultController.enqueue([chunk]) ​

readableStreamDefaultController.error([error]) ​

Classe : ReadableByteStreamController ​

readableByteStreamController.byobRequest ​

readableByteStreamController.close() ​

readableByteStreamController.desiredSize ​

readableByteStreamController.enqueue(chunk) ​

readableByteStreamController.error([error]) ​

Classe : ReadableStreamBYOBRequest ​

readableStreamBYOBRequest.respond(bytesWritten) ​

readableStreamBYOBRequest.respondWithNewView(view) ​

readableStreamBYOBRequest.view ​

Classe : WritableStream ​

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

writableStream.abort([reason]) ​

writableStream.close() ​

writableStream.getWriter() ​

writableStream.locked ​

Transfert avec postMessage() ​

Classe : WritableStreamDefaultWriter ​

new WritableStreamDefaultWriter(stream) ​

writableStreamDefaultWriter.abort([reason]) ​

writableStreamDefaultWriter.close() ​

writableStreamDefaultWriter.closed ​

writableStreamDefaultWriter.desiredSize ​

writableStreamDefaultWriter.ready ​

writableStreamDefaultWriter.releaseLock() ​

writableStreamDefaultWriter.write([chunk]) ​

Classe : WritableStreamDefaultController ​

writableStreamDefaultController.error([error]) ​

writableStreamDefaultController.signal ​

Classe : TransformStream ​

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

transformStream.readable ​

transformStream.writable ​

Transfert avec postMessage() ​

Classe : TransformStreamDefaultController ​

transformStreamDefaultController.desiredSize ​

transformStreamDefaultController.enqueue([chunk]) ​

transformStreamDefaultController.error([reason]) ​

transformStreamDefaultController.terminate() ​

Classe : ByteLengthQueuingStrategy ​

new ByteLengthQueuingStrategy(init) ​

byteLengthQueuingStrategy.highWaterMark ​

byteLengthQueuingStrategy.size ​

Class: CountQueuingStrategy ​

new CountQueuingStrategy(init) ​

countQueuingStrategy.highWaterMark ​

countQueuingStrategy.size ​

API Web Streams

Vue d'ensemble

Exemple `ReadableStream`

API

Classe : `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])`

Itération asynchrone

Transfert avec `postMessage()`

`ReadableStream.from(iterable)`

Classe : `ReadableStreamDefaultReader`

`new ReadableStreamDefaultReader(stream)`

`readableStreamDefaultReader.cancel([reason])`

`readableStreamDefaultReader.closed`

`readableStreamDefaultReader.read()`

`readableStreamDefaultReader.releaseLock()`

Classe : `ReadableStreamBYOBReader`

`new ReadableStreamBYOBReader(stream)`

`readableStreamBYOBReader.cancel([reason])`

`readableStreamBYOBReader.closed`

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

`readableStreamBYOBReader.releaseLock()`

Classe : `ReadableStreamDefaultController`

`readableStreamDefaultController.close()`

`readableStreamDefaultController.desiredSize`

`readableStreamDefaultController.enqueue([chunk])`

`readableStreamDefaultController.error([error])`

Classe : `ReadableByteStreamController`

`readableByteStreamController.byobRequest`

`readableByteStreamController.close()`

`readableByteStreamController.desiredSize`

`readableByteStreamController.enqueue(chunk)`

`readableByteStreamController.error([error])`

Classe : `ReadableStreamBYOBRequest`

`readableStreamBYOBRequest.respond(bytesWritten)`

`readableStreamBYOBRequest.respondWithNewView(view)`

`readableStreamBYOBRequest.view`

Classe : `WritableStream`

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

`writableStream.abort([reason])`

`writableStream.close()`

`writableStream.getWriter()`

`writableStream.locked`

Transfert avec postMessage()

Classe : `WritableStreamDefaultWriter`

`new WritableStreamDefaultWriter(stream)`

`writableStreamDefaultWriter.abort([reason])`

`writableStreamDefaultWriter.close()`

`writableStreamDefaultWriter.closed`

`writableStreamDefaultWriter.desiredSize`

`writableStreamDefaultWriter.ready`

`writableStreamDefaultWriter.releaseLock()`

`writableStreamDefaultWriter.write([chunk])`

Classe : `WritableStreamDefaultController`

`writableStreamDefaultController.error([error])`

`writableStreamDefaultController.signal`

Classe : `TransformStream`

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

`transformStream.readable`

`transformStream.writable`

Transfert avec postMessage()

Classe : `TransformStreamDefaultController`

`transformStreamDefaultController.desiredSize`

`transformStreamDefaultController.enqueue([chunk])`

`transformStreamDefaultController.error([reason])`

`transformStreamDefaultController.terminate()`

Classe : `ByteLengthQueuingStrategy`

`new ByteLengthQueuingStrategy(init)`

`byteLengthQueuingStrategy.highWaterMark`

`byteLengthQueuingStrategy.size`

Class: `CountQueuingStrategy`

`new CountQueuingStrategy(init)`

`countQueuingStrategy.highWaterMark`

`countQueuingStrategy.size`