Web Streams API

[Cronologia]

Versione	Modifiche
v21.0.0	Non più sperimentale.
v18.0.0	L'utilizzo di questa API non genera 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 Standard.

Panoramica

Lo standard WHATWG Streams Standard (o "web streams") definisce un'API per la gestione dei dati in streaming. È simile all'API Streams di Node.js, ma è emersa più tardi 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 l'timestamp corrente performance.now() una volta al secondo per sempre. Un iterabile asincrono viene utilizzato per leggere i dati dal flusso.

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 <Oggetto>

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

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Restituisce: undefined o una promise completata con undefined.

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

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Restituisce: Una promise completata con undefined.

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

  • reason <qualsiasi>

  • Restituisce: Una promise completata con undefined.

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

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

• strategy <Oggetto>

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

readableStream.locked

Aggiunto in: v16.5.0

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

La proprietà readableStream.locked è false per impostazione predefinita e viene impostata su true mentre è presente un lettore attivo che consuma i dati del flusso.

readableStream.cancel([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise completata 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 in cui transform.writable invierà i dati potenzialmente modificati che riceve da questo ReadableStream.
  • writable <WritableStream> Il WritableStream in 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 il trasferimento dei dati da annullare utilizzando un <AbortController>.

• Restituisce: <ReadableStream> Da transform.readable.

Collega questo <ReadableStream> alla coppia di <ReadableStream> e <WritableStream> forniti nell'argomento transform in modo che i dati da 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)
// Stampa: 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)
  // Stampa: A
})()

readableStream.pipeTo(destination[, options])

Aggiunto in: v16.5.0

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

• options <Object>

  • 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> Consente di annullare il trasferimento dei dati usando un <AbortController>.

• Restituisce: Una promise che si risolve con undefined

Causa 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 creazione di un ramo di un flusso di byte leggibile.
v16.5.0	Aggiunto in: v16.5.0

• Restituisce: <ReadableStream[]>

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

Causa che readableStream.locked sia true.

readableStream.values([options])

Aggiunto in: v16.5.0

• options <Object>
  • preventCancel <boolean> Quando true, impedisce che il <ReadableStream> venga chiuso quando l'iteratore asincrono termina bruscamente. Predefinito: false.

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

Causa 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 iteratore asincrono usando 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à il <ReadableStream> fino alla sua terminazione.

Per impostazione predefinita, se l'iteratore asincrono esce prematuramente (tramite break, return o throw), il <ReadableStream> verrà chiuso. Per evitare la chiusura automatica del <ReadableStream>, utilizzare il metodo readableStream.values() per acquisire l'iteratore asincrono e impostare l'opzione preventCancel su true.

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

Trasferimento con postMessage()

Un'istanza <ReadableStream> può essere trasferita usando 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 iterable.

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

Classe: ReadableStreamDefaultReader

[Cronologia]

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

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

new ReadableStreamDefaultReader(stream)

Aggiunto in: v16.5.0

• stream <ReadableStream>

Crea un nuovo <ReadableStreamDefaultReader> bloccato sul dato <ReadableStream>.

readableStreamDefaultReader.cancel([reason])

Aggiunto in: v16.5.0

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

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

readableStreamDefaultReader.closed

Aggiunto in: v16.5.0

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

readableStreamDefaultReader.read()

Aggiunto in: v16.5.0

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

Richiede il blocco di dati successivo dallo <ReadableStream> sottostante e restituisce una promessa che viene risolta con i dati una volta che sono disponibili.

readableStreamDefaultReader.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo lettore 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

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

BYOB è l'abbreviazione di "bring your own buffer". Questo è un pattern che consente una lettura più efficiente dei dati orientati ai byte, evitando copie superflue.

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 sul dato <ReadableStream>.

readableStreamBYOBReader.cancel([reason])

Aggiunto in: v16.5.0

• reason <any>
• Restituisce: Una promise che si risolve con undefined.

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

readableStreamBYOBReader.closed

Aggiunto in: v16.5.0

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

readableStreamBYOBReader.read(view[, options])

[Cronologia]

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

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

• options <Object>

  • min <number> Se impostato, la promise restituita si risolverà solo non appena saranno disponibili min elementi. Se 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 dallo stream sottostante <ReadableStream> e restituisce una promise che si risolve 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 varie callback del modulo node:fs. Questi tipi di Buffer usano un oggetto <ArrayBuffer> sottostante condiviso che contiene tutti i dati di tutte le istanze Buffer in pool. Quando un Buffer, <TypedArray>, o <DataView> viene passato a readableStreamBYOBReader.read(), l'ArrayBuffer sottostante della vista viene staccato, invalidando tutte le viste esistenti che potrebbero esistere su tale ArrayBuffer. Questo può avere conseguenze disastrose per la tua applicazione.

readableStreamBYOBReader.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo lettore sullo stream <ReadableStream> sottostante.

Classe: ReadableStreamDefaultController

Aggiunto in: v16.5.0

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

readableStreamDefaultController.close()

Aggiunto in: v16.5.0

Chiude lo stream <ReadableStream> a cui è associato questo controller.

readableStreamDefaultController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

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

readableStreamDefaultController.enqueue([chunk])

Aggiunto in: v16.5.0

• chunk <any>

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

readableStreamDefaultController.error([error])

Aggiunto in: v16.5.0

• error <any>

Segnala un errore che fa sì che lo stream <ReadableStream> generi un errore e si chiuda.

Classe: ReadableByteStreamController

[Cronologia]

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

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

readableByteStreamController.byobRequest

Aggiunto in: v16.5.0

• Tipo: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Aggiunto in: v16.5.0

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

readableByteStreamController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

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

readableByteStreamController.enqueue(chunk)

Aggiunto in: v16.5.0

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

Aggiunge un nuovo chunk di dati alla coda di <ReadableStream>.

readableByteStreamController.error([error])

Aggiunto in: v16.5.0

• error <any>

Segnala un errore che causa l'errore e la chiusura di <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 nei flussi orientati ai byte e quando si utilizza ReadableStreamBYOBReader, la proprietà readableByteStreamController.byobRequest fornisce accesso a un'istanza ReadableStreamBYOBRequest che rappresenta la richiesta di lettura corrente. L'oggetto viene utilizzato per ottenere l'accesso all'ArrayBuffer/TypedArray che è stato 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 di byte bytesWritten è 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

• Tipo: <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 del 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 WritableStream.

  • controller <WritableStreamDefaultController>

  • Restituisce: undefined o una promise che si risolve con undefined.

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

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Restituisce: Una promise che si risolve con undefined.

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

  • Restituisce: Una promise che si risolve con undefined.

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

  • reason <any>

  • Restituisce: Una promise che si risolve con undefined.

  • type <any> L'opzione type è riservata per usi futuri 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>
  • Restituisce: <number>

writableStream.abort([reason])

Aggiunto in: v16.5.0

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

Termina bruscamente il WritableStream. Tutte le scritture in coda verranno annullate e le promise associate rifiutate.

writableStream.close()

Aggiunto in: v16.5.0

• Restituisce: Una promise completata 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 di 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 passa a true mentre è presente uno scrittore attivo associato 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 dato.

writableStreamDefaultWriter.abort([reason])

Aggiunto in: v16.5.0

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

Termina bruscamente il WritableStream. Tutte le scritture in coda verranno annullate e le promise associate rifiutate.

writableStreamDefaultWriter.close()

Aggiunto in: v16.5.0

• Restituisce: Una promise che si risolve con undefined.

Chiude lo WritableStream quando non sono previsti ulteriori scritture.

writableStreamDefaultWriter.closed

Aggiunto in: v16.5.0

• Tipo: <Promise> Risolta con undefined quando lo <WritableStream> associato è chiuso, oppure rifiutata se lo stream genera errori o il blocco dello scrittore viene rilasciato prima che lo stream finisca di chiudersi.

writableStreamDefaultWriter.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

La quantità di dati necessaria per riempire la coda dello <WritableStream>.

writableStreamDefaultWriter.ready

Aggiunto in: v16.5.0

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

writableStreamDefaultWriter.releaseLock()

Aggiunto in: v16.5.0

Rilascia il blocco di questo scrittore sullo <ReadableStream> sottostante.

writableStreamDefaultWriter.write([chunk])

Aggiunto in: v16.5.0

• chunk: <any>
• Restituisce: Una promise che si risolve con undefined.

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

Classe: WritableStreamDefaultController

[Cronologia]

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

Lo WritableStreamDefaultController gestisce lo stato interno dello <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, lo <WritableStream> verrà interrotto e le scritture attualmente in sospeso verranno annullate.

writableStreamDefaultController.signal

• Tipo: <AbortSignal> Un AbortSignal che può essere utilizzato per annullare le 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	Aggiunta in: v16.5.0

Un TransformStream consiste in un <ReadableStream> e un <WritableStream> che sono connessi 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 completata 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 completata 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 completata con undefined.

  • readableType <any> l'opzione readableType è riservata per usi futuri e deve essere undefined.

  • writableType <any> l'opzione writableType è riservata per usi futuri 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

TransformStreamDefaultController gestisce lo stato interno di TransformStream.

transformStreamDefaultController.desiredSize

Aggiunto in: v16.5.0

• Tipo: <number>

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

transformStreamDefaultController.enqueue([chunk])

Aggiunto in: v16.5.0

• chunk <any>

Aggiunge un blocco di dati alla coda del lato leggibile.

transformStreamDefaultController.error([reason])

Aggiunto in: v16.5.0

• reason <any>

Segnala sia al lato leggibile che a quello 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 bruscamente 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 TextEncoderStream.

textEncoderStream.encoding

Aggiunto in: v16.6.0

• Tipo: <string>

La codifica supportata dall'istanza 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 codifica supportata da questa istanza TextDecoder. Default: 'utf-8'.
• options <Object>
  • fatal <boolean> true se gli errori 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'. Default: false.

Crea una nuova istanza TextDecoderStream.

textDecoderStream.encoding

Aggiunto in: v16.6.0

• Tipo: <string>

La codifica supportata dall'istanza TextDecoderStream.

textDecoderStream.fatal

Aggiunto in: v16.6.0

• Tipo: <boolean>

Il valore sarà true se gli errori di decodifica provocano 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>

Consumatori di Utilità

Aggiunto in: v16.7.0

Le funzioni di consumo di utilità forniscono opzioni comuni per consumare stream.

Sono accessibili 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> Risolve con un ArrayBuffer contenente il contenuto completo dello stream.

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

streamConsumers.blob(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Risolve con un <Blob> contenente il contenuto completo dello stream.

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

streamConsumers.buffer(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Risolta con un <Buffer> contenente il contenuto completo 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}`)
// Stampa: 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}`)
  // Stampa: from readable: 27
})

streamConsumers.json(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Risolta con il contenuto dello stream analizzato come stringa codificata UTF-8 che viene quindi 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}`)
// Stampa: 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}`)
  // Stampa: from readable: 100
})

streamConsumers.text(stream)

Aggiunto in: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Restituisce: <Promise> Soddisfa con il contenuto dello stream analizzato come stringa codificata 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}`)
// Stampa: 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}`)
  // Stampa: from readable: 27
})