API Web Streams

[Cronologia]

Versione	Modifiche
v21.0.0	Non è più sperimentale.
v18.0.0	L'uso di questa API non emette più un avviso di runtime.
v16.5.0	Aggiunto in: v16.5.0

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Un'implementazione dello Standard WHATWG Streams.

Panoramica

Lo Standard WHATWG Streams (o "web streams") definisce un'API per la gestione dei dati in streaming. È simile all'API Streams di Node.js ma è emersa in seguito ed è diventata l'API "standard" per lo streaming di dati in molti ambienti JavaScript.

Ci sono tre tipi principali di oggetti:

• ReadableStream - Rappresenta una sorgente di dati in streaming.
• WritableStream - Rappresenta una destinazione per i dati in streaming.
• TransformStream - Rappresenta un algoritmo per la trasformazione dei dati in streaming.

Esempio ReadableStream

Questo esempio crea un semplice ReadableStream che invia il timestamp corrente di performance.now() una volta al secondo per sempre. Un iterable asincrono viene utilizzato per leggere i dati dallo stream.

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

Classe: ReadableStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunta in: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Aggiunta in: v16.5.0

• underlyingSource <Object>

  • start <Function> Una funzione definita dall'utente che viene invocata immediatamente quando viene creato il ReadableStream.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Restituisce: undefined o una promise risolta con undefined.

  • pull <Function> Una funzione definita dall'utente che viene chiamata ripetutamente quando la coda interna ReadableStream non è piena. L'operazione può essere sincrona o asincrona. Se asincrona, la funzione non verrà chiamata di nuovo finché la promise restituita in precedenza non sarà stata risolta.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Restituisce: Una promise risolta con undefined.

  • cancel <Function> Una funzione definita dall'utente che viene chiamata quando il ReadableStream viene annullato.

  • reason <any>

  • Restituisce: Una promise risolta con undefined.

  • type <string> Deve essere 'bytes' o undefined.

  • autoAllocateChunkSize <number> Utilizzato solo quando type è uguale a 'bytes'. Quando è impostato su un valore diverso da zero, viene allocato automaticamente un buffer di visualizzazione a ReadableByteStreamController.byobRequest. Quando non è impostato, è necessario utilizzare le code interne dello stream per trasferire i dati tramite il lettore predefinito ReadableStreamDefaultReader.

• strategy <Object>

  • highWaterMark <number> La dimensione massima della coda interna prima che venga applicata la contropressione.
  • size <Function> Una funzione definita dall'utente utilizzata per identificare la dimensione di ogni blocco di dati.
  • chunk <any>
  • Restituisce: <number>

readableStream.locked

Aggiunto in: v16.5.0

• Tipo: <boolean> Impostato su true se c'è un lettore attivo per questo <ReadableStream>.

La proprietà readableStream.locked è false per impostazione predefinita e viene impostata su true quando c'è un lettore attivo che consuma i dati dello stream.

readableStream.cancel([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise risolta con undefined una volta completata l'annullamento.

readableStream.getReader([options])

Aggiunto in: v16.5.0

• options <Object>

  • mode <string> 'byob' o undefined

• Restituisce: <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);

Fa sì che readableStream.locked sia true.

readableStream.pipeThrough(transform[, options])

Aggiunto in: v16.5.0

• transform <Object>

  • readable <ReadableStream> Il ReadableStream a cui transform.writable invierà i dati potenzialmente modificati che riceve da questo ReadableStream.
  • writable <WritableStream> Il WritableStream a cui verranno scritti i dati di questo ReadableStream.

• options <Object>

  • preventAbort <boolean> Quando true, gli errori in questo ReadableStream non causeranno l'interruzione di transform.writable.
  • preventCancel <boolean> Quando true, gli errori nella destinazione transform.writable non causano l'annullamento di questo ReadableStream.
  • preventClose <boolean> Quando true, la chiusura di questo ReadableStream non causa la chiusura di transform.writable.
  • signal <AbortSignal> Consente di annullare il trasferimento dei dati utilizzando un <AbortController>.

• Restituisce: <ReadableStream> Da transform.readable.

Collega questo <ReadableStream> alla coppia di <ReadableStream> e <WritableStream> fornita nell'argomento transform in modo tale che i dati di questo <ReadableStream> vengano scritti in transform.writable, possibilmente trasformati, quindi inviati a transform.readable. Una volta configurata la pipeline, viene restituito transform.readable.

Fa sì che readableStream.locked sia true mentre l'operazione di pipe è attiva.

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

readableStream.pipeTo(destination[, options])

Aggiunto in: v16.5.0

• destination <WritableStream> Uno <WritableStream> in cui verranno scritti i dati di questo ReadableStream.

• options <Oggetto>

  • preventAbort <boolean> Quando true, gli errori in questo ReadableStream non causeranno l'interruzione di destination.
  • preventCancel <boolean> Quando true, gli errori in destination non causeranno l'annullamento di questo ReadableStream.
  • preventClose <boolean> Quando true, la chiusura di questo ReadableStream non causa la chiusura di destination.
  • signal <AbortSignal> Permette di annullare il trasferimento di dati utilizzando un <AbortController>.

• Restituisce: Una promise risolta con undefined

Fa sì che readableStream.locked sia true mentre l'operazione di pipe è attiva.

readableStream.tee()

[Cronologia]

Versione	Modifiche
v18.10.0, v16.18.0	Supporto per la divisione di uno stream di byte leggibile.
v16.5.0	Aggiunto in: v16.5.0

• Restituisce: <ReadableStream[]>

Restituisce una coppia di nuove istanze di <ReadableStream> a cui verranno inoltrati i dati di questo ReadableStream. Ognuna riceverà gli stessi dati.

Fa sì che readableStream.locked sia true.

readableStream.values([options])

Aggiunto in: v16.5.0

• options <Oggetto>
  • preventCancel <boolean> Quando true, impedisce la chiusura del <ReadableStream> quando l'iteratore asincrono termina bruscamente. Predefinito: false.

Crea e restituisce un iteratore asincrono utilizzabile per consumare i dati di questo ReadableStream.

Fa sì che readableStream.locked sia true mentre l'iteratore asincrono è attivo.

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

Iterazione Asincrona

L'oggetto <ReadableStream> supporta il protocollo di iterazione asincrona utilizzando la sintassi 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'iteratore asincrono consumerà <ReadableStream> fino a quando non termina.

Per impostazione predefinita, se l'iteratore asincrono si chiude anticipatamente (tramite break, return o throw), il <ReadableStream> verrà chiuso. Per impedire la chiusura automatica di <ReadableStream>, usa il metodo readableStream.values() per acquisire l'iteratore asincrono e imposta l'opzione preventCancel su true.

Il <ReadableStream> non deve essere bloccato (ovvero, non deve avere un lettore attivo esistente). Durante l'iterazione asincrona, il <ReadableStream> verrà bloccato.

Trasferimento con postMessage()

Un'istanza <ReadableStream> può essere trasferita utilizzando 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)

Aggiunto in: v20.6.0

• iterable <Iterable> Oggetto che implementa il protocollo iterabile Symbol.asyncIterator o Symbol.iterator.

Un metodo di utilità che crea un nuovo <ReadableStream> da un iterabile.

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

Classe: ReadableStreamDefaultReader

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Per impostazione predefinita, la chiamata a readableStream.getReader() senza argomenti restituirà un'istanza di ReadableStreamDefaultReader. Il reader predefinito tratta i chunk di dati passati attraverso lo stream come valori opachi, il che consente a <ReadableStream> di funzionare generalmente con qualsiasi valore JavaScript.

new ReadableStreamDefaultReader(stream)

Aggiunto in: v16.5.0

• stream <ReadableStream>

Crea un nuovo <ReadableStreamDefaultReader> che è bloccato al dato <ReadableStream>.

readableStreamDefaultReader.cancel([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise risolta con undefined.

Annulla il <ReadableStream> e restituisce una promise che viene risolta quando lo stream sottostante è stato annullato.

readableStreamDefaultReader.closed

Aggiunto in: v16.5.0

• Tipo: <Promise> Risolta con undefined quando il <ReadableStream> associato è chiuso o rifiutata se lo stream genera errori o il blocco del reader viene rilasciato prima che lo stream finisca di chiudersi.

readableStreamDefaultReader.read()

Aggiunto in: v16.5.0

• Restituisce: Una promise risolta con un oggetto:
  • value <any>
  • done <boolean>

Richiede il prossimo chunk di dati dal sottostante <ReadableStream> e restituisce una promise che viene risolta con i dati una volta che sono disponibili.

readableStreamDefaultReader.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo reader sul sottostante <ReadableStream>.

Classe: ReadableStreamBYOBReader

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Il ReadableStreamBYOBReader è un consumatore alternativo per <ReadableStream> orientati ai byte (quelli creati con underlyingSource.type impostato su 'bytes' quando è stato creato il ReadableStream).

BYOB è l'abbreviazione di "bring your own buffer" (porta il tuo buffer). Questo è un modello che consente una lettura più efficiente dei dati orientati ai byte che evita copie estranee.

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)

Aggiunto in: v16.5.0

• stream <ReadableStream>

Crea un nuovo ReadableStreamBYOBReader bloccato al dato <ReadableStream>.

readableStreamBYOBReader.cancel([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise risolta con undefined.

Annulla il <ReadableStream> e restituisce una promise che viene risolta quando lo stream sottostante è stato annullato.

readableStreamBYOBReader.closed

Aggiunto in: v16.5.0

• Tipo: <Promise> Risolta con undefined quando il <ReadableStream> associato è chiuso o rifiutata se lo stream genera errori o il blocco del reader viene rilasciato prima che lo stream finisca di chiudersi.

readableStreamBYOBReader.read(view[, options])

[Cronologia]

Versione	Modifiche
v21.7.0, v20.17.0	Aggiunta l'opzione min.
v16.5.0	Aggiunto in: v16.5.0

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

• options <Object>

  • min <number> Quando impostato, la promise restituita verrà risolta solo quando sarà disponibile il numero min di elementi. Quando non impostato, la promise si risolve quando è disponibile almeno un elemento.

• Restituisce: Una promise risolta con un oggetto:

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

Richiede il prossimo blocco di dati dal <ReadableStream> sottostante e restituisce una promise che viene risolta con i dati una volta che sono disponibili.

Non passare un'istanza di oggetto <Buffer> in pool a questo metodo. Gli oggetti Buffer in pool vengono creati usando Buffer.allocUnsafe(), o Buffer.from(), o vengono spesso restituiti da vari callback del modulo node:fs. Questi tipi di Buffer utilizzano un oggetto sottostante condiviso <ArrayBuffer> che contiene tutti i dati da tutte le istanze Buffer in pool. Quando un Buffer, <TypedArray> o <DataView> viene passato a readableStreamBYOBReader.read(), l'ArrayBuffer sottostante della view viene scollegato, invalidando tutte le view esistenti che potrebbero esistere su quell'ArrayBuffer. Questo può avere conseguenze disastrose per la tua applicazione.

readableStreamBYOBReader.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo reader sul sottostante <ReadableStream>.

Classe: ReadableStreamDefaultController

Aggiunto in: v16.5.0

Ogni <ReadableStream> ha un controller che è responsabile dello stato interno e della gestione della coda dello stream. Il ReadableStreamDefaultController è l'implementazione del controller predefinita per i ReadableStream che non sono orientati ai byte.

readableStreamDefaultController.close()

Aggiunto in: v16.5.0

Chiude il <ReadableStream> a cui questo controller è associato.

readableStreamDefaultController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

Restituisce la quantità di dati rimanenti per riempire la coda del <ReadableStream>.

readableStreamDefaultController.enqueue([chunk])

Aggiunto in: v16.5.0

• chunk <any>

Aggiunge un nuovo blocco di dati alla coda del <ReadableStream>.

readableStreamDefaultController.error([error])

Aggiunto in: v16.5.0

• error <any>

Segnala un errore che causa l'errore e la chiusura del <ReadableStream>.

Classe: ReadableByteStreamController

[Cronologia]

Versione	Modifiche
v18.10.0	Supporta la gestione di una richiesta pull BYOB da un reader rilasciato.
v16.5.0	Aggiunto in: v16.5.0

Ogni <ReadableStream> ha un controller che è responsabile dello stato interno e della gestione della coda dello stream. Il ReadableByteStreamController è per i ReadableStream orientati ai byte.

readableByteStreamController.byobRequest

Aggiunto in: v16.5.0

• Tipo: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Aggiunto in: v16.5.0

Chiude il <ReadableStream> a cui questo controller è associato.

readableByteStreamController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

Restituisce la quantità di dati rimanenti per riempire la coda del <ReadableStream>.

readableByteStreamController.enqueue(chunk)

Aggiunto in: v16.5.0

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

Aggiunge un nuovo blocco di dati alla coda del <ReadableStream>.

readableByteStreamController.error([error])

Aggiunto in: v16.5.0

• error <any>

Segnala un errore che causa l'errore e la chiusura del <ReadableStream>.

Classe: ReadableStreamBYOBRequest

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Quando si utilizza ReadableByteStreamController in flussi orientati ai byte e quando si utilizza ReadableStreamBYOBReader, la proprietà readableByteStreamController.byobRequest fornisce l'accesso a un'istanza ReadableStreamBYOBRequest che rappresenta la richiesta di lettura corrente. L'oggetto viene utilizzato per ottenere l'accesso a ArrayBuffer/TypedArray fornito per la richiesta di lettura da riempire e fornisce metodi per segnalare che i dati sono stati forniti.

readableStreamBYOBRequest.respond(bytesWritten)

Aggiunto in: v16.5.0

• bytesWritten <number>

Segnala che un numero bytesWritten di byte è stato scritto in readableStreamBYOBRequest.view.

readableStreamBYOBRequest.respondWithNewView(view)

Aggiunto in: v16.5.0

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

Segnala che la richiesta è stata soddisfatta con byte scritti in un nuovo Buffer, TypedArray o DataView.

readableStreamBYOBRequest.view

Aggiunto in: v16.5.0

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

Classe: WritableStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

WritableStream è una destinazione a cui vengono inviati i dati di flusso.

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

Aggiunto in: v16.5.0

• underlyingSink <Object>

  • start <Function> Una funzione definita dall'utente che viene invocata immediatamente quando viene creato il WritableStream.

  • controller <WritableStreamDefaultController>

  • Returns: undefined o una promise risolta con undefined.

  • write <Function> Una funzione definita dall'utente che viene invocata quando un blocco di dati è stato scritto nel WritableStream.

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Returns: Una promise risolta con undefined.

  • close <Function> Una funzione definita dall'utente che viene chiamata quando il WritableStream viene chiuso.

  • Returns: Una promise risolta con undefined.

  • abort <Function> Una funzione definita dall'utente che viene chiamata per chiudere bruscamente il WritableStream.

  • reason <any>

  • Returns: Una promise risolta con undefined.

  • type <any> L'opzione type è riservata per un uso futuro e deve essere undefined.

• strategy <Object>

  • highWaterMark <number> La dimensione massima della coda interna prima che venga applicata la contropressione.
  • size <Function> Una funzione definita dall'utente utilizzata per identificare la dimensione di ciascun blocco di dati.
  • chunk <any>
  • Returns: <number>

writableStream.abort([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise risolta con undefined.

Termina bruscamente il WritableStream. Tutte le scritture in coda verranno annullate con le relative promise rifiutate.

writableStream.close()

Aggiunto in: v16.5.0

• Restituisce: Una promise risolta con undefined.

Chiude il WritableStream quando non sono previste ulteriori scritture.

writableStream.getWriter()

Aggiunto in: v16.5.0

• Restituisce: <WritableStreamDefaultWriter>

Crea e restituisce una nuova istanza writer che può essere utilizzata per scrivere dati nel WritableStream.

writableStream.locked

Aggiunto in: v16.5.0

• Tipo: <boolean>

La proprietà writableStream.locked è false per impostazione predefinita e viene impostata su true quando è presente un writer attivo collegato a questo WritableStream.

Trasferimento con postMessage()

Un'istanza <WritableStream> può essere trasferita utilizzando 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

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

new WritableStreamDefaultWriter(stream)

Aggiunto in: v16.5.0

• stream <WritableStream>

Crea un nuovo WritableStreamDefaultWriter bloccato sul WritableStream specificato.

writableStreamDefaultWriter.abort([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise risolta con undefined.

Termina bruscamente il WritableStream. Tutte le scritture in coda verranno annullate con le relative promise rifiutate.

writableStreamDefaultWriter.close()

Aggiunto in: v16.5.0

• Restituisce: Una promise risolta con undefined.

Chiude il WritableStream quando non sono previste ulteriori scritture.

writableStreamDefaultWriter.closed

Aggiunto in: v16.5.0

• Tipo: <Promise> Risolto con undefined quando l'associato <WritableStream> è chiuso o rifiutato se lo stream genera errori o il blocco dello writer viene rilasciato prima che lo stream termini la chiusura.

writableStreamDefaultWriter.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

La quantità di dati necessari per riempire la coda del <WritableStream>.

writableStreamDefaultWriter.ready

Aggiunto in: v16.5.0

• Tipo: <Promise> Risolto con undefined quando lo writer è pronto per essere utilizzato.

writableStreamDefaultWriter.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo writer sul sottostante <ReadableStream>.

writableStreamDefaultWriter.write([chunk])

Aggiunto in: v16.5.0

• chunk: <any>
• Restituisce: Una promise risolta con undefined.

Aggiunge un nuovo blocco di dati alla coda del <WritableStream>.

Classe: WritableStreamDefaultController

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Il WritableStreamDefaultController gestisce lo stato interno del <WritableStream>.

writableStreamDefaultController.error([error])

Aggiunto in: v16.5.0

• error <any>

Chiamato dal codice utente per segnalare che si è verificato un errore durante l'elaborazione dei dati WritableStream. Quando viene chiamato, il <WritableStream> verrà interrotto, con le scritture attualmente in sospeso annullate.

writableStreamDefaultController.signal

• Tipo: <AbortSignal> Un AbortSignal che può essere utilizzato per annullare operazioni di scrittura o chiusura in sospeso quando un <WritableStream> viene interrotto.

Classe: TransformStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Un TransformStream è costituito da un <ReadableStream> e un <WritableStream> che sono collegati in modo tale che i dati scritti nel WritableStream vengano ricevuti e potenzialmente trasformati, prima di essere inseriti nella coda del 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]]])

Aggiunto in: v16.5.0

• transformer <Object>

  • start <Function> Una funzione definita dall'utente che viene invocata immediatamente quando viene creato il TransformStream.

  • controller <TransformStreamDefaultController>

  • Restituisce: undefined o una promise risolta con undefined

  • transform <Function> Una funzione definita dall'utente che riceve e potenzialmente modifica un blocco di dati scritto in transformStream.writable, prima di inoltrarlo a transformStream.readable.

  • chunk <any>

  • controller <TransformStreamDefaultController>

  • Restituisce: Una promise risolta con undefined.

  • flush <Function> Una funzione definita dall'utente che viene chiamata immediatamente prima che il lato scrivibile del TransformStream venga chiuso, segnalando la fine del processo di trasformazione.

  • controller <TransformStreamDefaultController>

  • Restituisce: Una promise risolta con undefined.

  • readableType <any> l'opzione readableType è riservata per un uso futuro e deve essere undefined.

  • writableType <any> l'opzione writableType è riservata per un uso futuro e deve essere undefined.

• writableStrategy <Object>

  • highWaterMark <number> La dimensione massima della coda interna prima che venga applicata la contropressione.
  • size <Function> Una funzione definita dall'utente utilizzata per identificare la dimensione di ogni blocco di dati.
  • chunk <any>
  • Restituisce: <number>

• readableStrategy <Object>

  • highWaterMark <number> La dimensione massima della coda interna prima che venga applicata la contropressione.
  • size <Function> Una funzione definita dall'utente utilizzata per identificare la dimensione di ogni blocco di dati.
  • chunk <any>
  • Restituisce: <number>

transformStream.readable

Aggiunto in: v16.5.0

• Tipo: <ReadableStream>

transformStream.writable

Aggiunto in: v16.5.0

• Tipo: <WritableStream>

Trasferimento con postMessage()

Un'istanza di <TransformStream> può essere trasferita usando un <MessagePort>.

const stream = new TransformStream();

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

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

port2.postMessage(stream, [stream]);

Classe: TransformStreamDefaultController

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

Il TransformStreamDefaultController gestisce lo stato interno del TransformStream.

transformStreamDefaultController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

La quantità di dati richiesta per riempire la coda del lato leggibile.

transformStreamDefaultController.enqueue([chunk])

Aggiunto in: v16.5.0

• chunk <any>

Accoda un blocco di dati alla coda del lato leggibile.

transformStreamDefaultController.error([reason])

Aggiunto in: v16.5.0

• reason <any>

Segnala a entrambi i lati, leggibile e scrivibile, che si è verificato un errore durante l'elaborazione dei dati di trasformazione, causando la chiusura improvvisa di entrambi i lati.

transformStreamDefaultController.terminate()

Aggiunto in: v16.5.0

Chiude il lato leggibile del trasporto e fa sì che il lato scrivibile venga chiuso improvvisamente con un errore.

Classe: ByteLengthQueuingStrategy

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

new ByteLengthQueuingStrategy(init)

Aggiunto in: v16.5.0

• init <Object>
  • highWaterMark <number>

byteLengthQueuingStrategy.highWaterMark

Aggiunto in: v16.5.0

• Tipo: <number>

byteLengthQueuingStrategy.size

Aggiunto in: v16.5.0

• Tipo: <Function>
  • chunk <any>
  • Restituisce: <number>

Classe: CountQueuingStrategy

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.5.0	Aggiunto in: v16.5.0

new CountQueuingStrategy(init)

Aggiunto in: v16.5.0

• init <Object>
  • highWaterMark <number>

countQueuingStrategy.highWaterMark

Aggiunto in: v16.5.0

• Tipo: <number>

countQueuingStrategy.size

Aggiunto in: v16.5.0

• Tipo: <Function>
  • chunk <any>
  • Restituisce: <number>

Classe: TextEncoderStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.6.0	Aggiunto in: v16.6.0

new TextEncoderStream()

Aggiunto in: v16.6.0

Crea una nuova istanza di TextEncoderStream.

textEncoderStream.encoding

Aggiunto in: v16.6.0

• Tipo: <string>

La codifica supportata dall'istanza di TextEncoderStream.

textEncoderStream.readable

Aggiunto in: v16.6.0

• Tipo: <ReadableStream>

textEncoderStream.writable

Aggiunto in: v16.6.0

• Tipo: <WritableStream>

Classe: TextDecoderStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v16.6.0	Aggiunto in: v16.6.0

new TextDecoderStream([encoding[, options]])

Aggiunto in: v16.6.0

• encoding <string> Identifica la encoding supportata da questa istanza di TextDecoder. Predefinito: 'utf-8'.
• options <Object>
  • fatal <boolean> true se i fallimenti di decodifica sono fatali.
  • ignoreBOM <boolean> Quando true, TextDecoderStream includerà il byte order mark nel risultato decodificato. Quando false, il byte order mark verrà rimosso dall'output. Questa opzione viene utilizzata solo quando encoding è 'utf-8', 'utf-16be' o 'utf-16le'. Predefinito: false.

Crea una nuova istanza di TextDecoderStream.

textDecoderStream.encoding

Aggiunto in: v16.6.0

• Tipo: <string>

La codifica supportata dall'istanza di TextDecoderStream.

textDecoderStream.fatal

Aggiunto in: v16.6.0

• Tipo: <boolean>

Il valore sarà true se gli errori di decodifica comportano il lancio di un TypeError.

textDecoderStream.ignoreBOM

Aggiunto in: v16.6.0

• Tipo: <boolean>

Il valore sarà true se il risultato della decodifica includerà il byte order mark.

textDecoderStream.readable

Aggiunto in: v16.6.0

• Tipo: <ReadableStream>

textDecoderStream.writable

Aggiunto in: v16.6.0

• Tipo: <WritableStream>

Classe: CompressionStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v17.0.0	Aggiunto in: v17.0.0

new CompressionStream(format)

[Cronologia]

Versione	Modifiche
v21.2.0, v20.12.0	format ora accetta il valore deflate-raw.
v17.0.0	Aggiunto in: v17.0.0

• format <string> Uno tra 'deflate', 'deflate-raw' o 'gzip'.

compressionStream.readable

Aggiunto in: v17.0.0

• Tipo: <ReadableStream>

compressionStream.writable

Aggiunto in: v17.0.0

• Tipo: <WritableStream>

Classe: DecompressionStream

[Cronologia]

Versione	Modifiche
v18.0.0	Questa classe è ora esposta sull'oggetto globale.
v17.0.0	Aggiunto in: v17.0.0

new DecompressionStream(format)

[Cronologia]

Versione	Modifiche
v21.2.0, v20.12.0	format ora accetta il valore deflate-raw.
v17.0.0	Aggiunto in: v17.0.0

• format <string> Uno tra 'deflate', 'deflate-raw' o 'gzip'.

decompressionStream.readable

Aggiunto in: v17.0.0

• Tipo: <ReadableStream>

decompressionStream.writable

Aggiunto in: v17.0.0

• Tipo: <WritableStream>

Utilità Consumer

Aggiunto in: v16.7.0

Le funzioni consumer di utilità forniscono opzioni comuni per l'utilizzo di flussi.

Vi si accede usando:

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)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Si risolve con un ArrayBuffer contenente l'intero contenuto del flusso.

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

streamConsumers.blob(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Si risolve con un <Blob> contenente l'intero contenuto del flusso.

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

streamConsumers.buffer(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Si completa con un <Buffer> contenente l'intero contenuto dello stream.

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

streamConsumers.json(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Si completa con il contenuto dello stream analizzato come stringa codificata in UTF-8 che viene poi passata attraverso JSON.parse().

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

streamConsumers.text(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Si risolve con il contenuto dello stream analizzato come una stringa con codifica UTF-8.

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