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.

Aperçu

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

Il existe trois principaux types d'objets :

ReadableStream - Représente une source de données de flux.
WritableStream - Représente une destination pour les données de flux.
TransformStream - Représente un algorithme de transformation des données de flux.

Exemple `ReadableStream`

Cet exemple crée un ReadableStream simple qui envoie l'horodatage performance.now() actuel une fois par seconde indéfiniment. 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 maintenant 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 <Object>
- start <Function> 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 <Function> Une fonction définie par l'utilisateur qui est appelée à plusieurs reprises lorsque la file d'attente interne 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 n'est pas résolue.
- controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
- Retourne : Une promesse résolue avec undefined.
- cancel <Function> Une fonction définie par l'utilisateur qui est appelée lorsque le ReadableStream est annulé.
- reason <any>
- Retourne : Une promesse résolue avec undefined.
- type <string> Doit être 'bytes' ou undefined.
- autoAllocateChunkSize <number> Utilisé uniquement lorsque type est égal à 'bytes'. Lorsqu'il est défini sur une valeur différente de zéro, un tampon de vue est automatiquement alloué à 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 <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>

`readableStream.locked`

Ajouté dans : v16.5.0

Type : <boolean> Défini sur true s'il existe un lecteur actif pour ce <ReadableStream>.

La propriété readableStream.locked est false par défaut et passe à true lorsqu'il existe un lecteur actif consommant 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);

Fait passer readableStream.locked à true.

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

Ajouté dans : v16.5.0

transform <Object>
- readable <ReadableStream> Le ReadableStream vers 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'abandon 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 d'annuler le transfert de données à l'aide d'un <AbortController>.
Retourne : <ReadableStream> Depuis 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 renvoyé.

Fait passer readableStream.locked à true pendant que l'opération de 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);
  // 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])`

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'abandon de destination.
- preventCancel <boolean> Lorsque true, les erreurs dans la destination n'entraîneront pas l'annulation de ce ReadableStream.
- preventClose <boolean> Lorsque true, la fermeture de ce ReadableStream n'entraîne 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

Fait en sorte que readableStream.locked soit true pendant que l'opération de tube est active.

`readableStream.tee()`

[Historique]

Version	Modifications
v18.10.0, v16.18.0	Prise en charge du partage 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 transmises. Chacune recevra les mêmes données.

Fait en sorte que readableStream.locked soit true.

`readableStream.values([options])`

Ajouté dans : v16.5.0

options <Object>
- preventCancel <boolean> Lorsque true, empêche le <ReadableStream> d'être fermé lorsque l'itérateur asynchrone se termine brusquement. Par défaut : false.

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

Fait en sorte que readableStream.locked soit 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 de <ReadableStream> peut être transférée en utilisant 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); // 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'
})();

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 renverra une instance de ReadableStreamDefaultReader. Le lecteur par défaut traite les morceaux de données transmis via le flux comme des valeurs opaques, ce qui permet à <ReadableStream> de fonctionner généralement avec n’importe quelle valeur JavaScript.

`new ReadableStreamDefaultReader(stream)`

Ajoutée dans : v16.5.0

stream <ReadableStream>

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

`readableStreamDefaultReader.cancel([reason])`

Ajoutée dans : v16.5.0

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

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

`readableStreamDefaultReader.closed`

Ajoutée dans : v16.5.0

Type : <Promise> Résolue avec undefined lorsque le <ReadableStream> associé est fermé ou rejetée si le flux présente des erreurs ou si le verrou du lecteur est libéré avant que le flux ne termine sa fermeture.

`readableStreamDefaultReader.read()`

Ajoutée dans : v16.5.0

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

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

`readableStreamDefaultReader.releaseLock()`

Ajouté dans : v16.5.0

Libère le verrouillage 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 sur 'bytes' lorsque le ReadableStream a été créé).

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 qui évite 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 qui est verrouillé sur le <ReadableStream> donné.

`readableStreamBYOBReader.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é.

`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	Ajout de l'option `min`.
v16.5.0	Ajouté dans : v16.5.0

view <Buffer> | <TypedArray> | <DataView>
options <Object>
- min <number> Lorsqu'elle est définie, la promesse renvoyée ne sera résolue que lorsque le nombre min d'éléments sera disponible. Lorsqu'elle n'est pas définie, la promesse se résout lorsqu'au moins un élément est disponible.
Retourne : Une promesse résolue avec un objet :
- value <TypedArray> | <DataView>
- done <boolean>

Demande le bloc de données suivant depuis le <ReadableStream> sous-jacent et renvoie 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 renvoyés par divers rappels 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 Buffer mises en pool. Lorsqu'un Buffer, <TypedArray> ou <DataView> est passé à readableStreamBYOBReader.read(), l'ArrayBuffer sous-jacent de la vue est détaché, invalidant toutes les vues existantes qui peuvent exister sur cet 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> a un contrôleur responsable de l'état interne et de la gestion de la file d'attente du stream. Le ReadableStreamDefaultController est l'implémentation de contrôleur par défaut pour les ReadableStreams 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>

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

`readableStreamDefaultController.enqueue([chunk])`

Ajouté dans : v16.5.0

chunk <any>

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

`readableStreamDefaultController.error([error])`

Ajouté dans : v16.5.0

error <any>

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

Classe : `ReadableByteStreamController`

[Historique]

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

Chaque <ReadableStream> a un contrôleur responsable de l'état interne et de la gestion de la file d'attente du stream. Le ReadableByteStreamController est destiné aux ReadableStreams 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>

Renvoie la quantité de données restant à remplir dans la file d'attente du <ReadableStream>.

`readableByteStreamController.enqueue(chunk)`

Ajouté dans : v16.5.0

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

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

`readableByteStreamController.error([error])`

Ajouté dans : v16.5.0

error <any>

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

Classe : `ReadableStreamBYOBRequest`

[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

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 un accès à une instance ReadableStreamBYOBRequest qui représente la requête de lecture en cours. L'objet est utilisé pour accéder à l'ArrayBuffer/TypedArray qui a été fourni pour que la requête de lecture soit remplie, et fournit des méthodes pour signaler que les données ont été fournies.

`readableStreamBYOBRequest.respond(bytesWritten)`

Ajouté dans : v16.5.0

bytesWritten <number>

Signale qu'un nombre bytesWritten d'octets a été écrit 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

Le WritableStream est une destination vers laquelle les données de 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 <Object>
- start <Function> Une fonction définie par l'utilisateur qui est invoquée immédiatement lorsque le WritableStream est créé.
- controller <WritableStreamDefaultController>
- Retourne : undefined ou une promesse remplie avec undefined.
- write <Function> Une fonction définie par l'utilisateur qui est invoquée lorsqu'un bloc de données a été écrit dans le WritableStream.
- chunk <any>
- controller <WritableStreamDefaultController>
- Retourne : Une promesse remplie avec undefined.
- close <Function> Une fonction définie par l'utilisateur qui est appelée lorsque le WritableStream est fermé.
- Retourne : Une promesse remplie avec undefined.
- abort <Function> Une fonction définie par l'utilisateur qui est appelée pour fermer brusquement le WritableStream.
- reason <any>
- Retourne : Une promesse remplie avec undefined.
- type <any> L'option type est réservée pour une utilisation future et doit être indéfinie.
strategy <Object>
- highWaterMark <number> La taille maximale de la file d'attente interne avant l'application de la contre-pression.
- 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>

`writableStream.abort([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse remplie avec undefined.

Interrompt brusquement le WritableStream. Toutes les écritures en file d’attente seront annulées avec leurs promesses associées rejetées.

`writableStream.close()`

Ajouté dans : v16.5.0

Retourne : Une promesse remplie 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’écriture 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’il y a un writer actif attaché à ce WritableStream.

Transfert avec postMessage()

Une instance <WritableStream> peut être transférée en utilisant 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 qui est verrouillé au WritableStream donné.

`writableStreamDefaultWriter.abort([reason])`

Ajouté dans : v16.5.0

reason <any>
Retourne : Une promesse remplie avec undefined.

Interrompt brusquement le WritableStream. Toutes les écritures en file d’attente seront annulées avec 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 des erreurs ou si le verrou du writer est relâché avant que le flux ne termine sa fermeture.

`writableStreamDefaultWriter.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

La quantité de données requise 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 bloc 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é par le code utilisateur pour signaler qu'une erreur s'est produite lors du traitement des données du WritableStream. Une fois appelé, le <WritableStream> sera abandonné, avec les écritures en attente actuellement annulées.

`writableStreamDefaultController.signal`

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

Class : `TransformStream`

[Historique]

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

Un TransformStream se compose d’un <ReadableStream> et d’un <WritableStream> qui sont connectés de telle sorte que les données écrites dans le WritableStream soient 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ée 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>
- Renvoie : 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 écrit dans transformStream.writable, avant de le transférer vers transformStream.readable.
- chunk <any>
- controller <TransformStreamDefaultController>
- Renvoie : 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é accessible en écriture du TransformStream ne soit fermé, signalant la fin du processus de transformation.
- controller <TransformStreamDefaultController>
- Renvoie : une promesse remplie avec undefined.
- readableType <any> l’option readableType est réservée pour une utilisation future et doit être undefined.
- writableType <any> l’option writableType est réservée pour une utilisation future et doit être undefined.
writableStrategy <Object>
- highWaterMark <number> La taille maximale de la file d’attente interne avant l’application de la contre-pression.
- size <Function> Une fonction définie par l’utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <any>
- Renvoie : <number>
readableStrategy <Object>
- highWaterMark <number> La taille maximale de la file d’attente interne avant l’application de la contre-pression.
- size <Function> Une fonction définie par l’utilisateur utilisée pour identifier la taille de chaque bloc de données.
- chunk <any>
- Renvoie : <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 en utilisant 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

Le TransformStreamDefaultController gère l'état interne du TransformStream.

`transformStreamDefaultController.desiredSize`

Ajouté dans : v16.5.0

Type : <number>

La quantité de données nécessaire pour remplir la queue côté lisible.

`transformStreamDefaultController.enqueue([chunk])`

Ajouté dans : v16.5.0

chunk <any>

Ajoute un morceau de données à la queue 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, ce qui entraîne la fermeture abrupte des deux côtés.

`transformStreamDefaultController.terminate()`

Ajouté dans : v16.5.0

Ferme le côté lisible du transport et entraîne la fermeture abrupte 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 de TextEncoderStream.

`textEncoderStream.encoding`

Ajouté dans : v16.6.0

Type : <string>

L’encodage pris en charge par l’instance de TextEncoderStream.

`textEncoderStream.readable`

Ajouté dans : v16.6.0

Type : <ReadableStream>

`textEncoderStream.writable`

Ajouté dans : v16.6.0

Type : <WritableStream>

Class: `TextDecoderStream`

[Historique]

Version	Modifications
v18.0.0	Cette classe est désormais 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’encoding que cette instance de TextDecoder prend en charge. 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 n’est utilisée que lorsque encoding est 'utf-8', 'utf-16be' ou 'utf-16le'. Par défaut : false.

Crée une nouvelle instance de TextDecoderStream.

`textDecoderStream.encoding`

Ajouté dans : v16.6.0

Type : <string>

L’encodage pris en charge par l’instance de TextDecoderStream.

`textDecoderStream.fatal`

Ajouté dans : v16.6.0

Type : <boolean>

La valeur sera true si les erreurs de décodage entraînent la levée d’une 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>

Class: `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	Le format accepte désormais la valeur `deflate-raw`.
v17.0.0	Ajouté dans: v17.0.0

format <string> Un parmi 'deflate', 'deflate-raw', ou 'gzip'.

`compressionStream.readable`

Ajouté dans: v17.0.0

Type: <ReadableStream>

`compressionStream.writable`

Ajouté dans: v17.0.0

Type: <WritableStream>

Class: `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	Le format accepte désormais la valeur `deflate-raw`.
v17.0.0	Ajouté dans: v17.0.0

format <string> Un parmi '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 consommateur d'utilitaires fournissent des options courantes pour consommer des flux.

Elles sont accessibles en utilisant :

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> Se réalise 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}`);
// 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)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Se réalise 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}`);
// 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)`

Ajouté dans : v16.7.0

stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
Retourne : <Promise> Se réalise avec un <Buffer> contenant l’intégralité du contenu 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> Se réalise avec le contenu du flux analysé en tant que chaîne encodée en UTF-8 qui est ensuite 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> Réussit avec le contenu du flux analysé en tant que chaîne encodé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}`);
// 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
});

API Web Streams ​

Aperçu ​

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 ​

Class : 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

Aperçu

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`

Class : `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`