API de Web Streams

[Historial]

Versión	Cambios
v21.0.0	Ya no es experimental.
v18.0.0	El uso de esta API ya no emite una advertencia en tiempo de ejecución.
v16.5.0	Añadido en: v16.5.0

[Estable: 2 - Estable]

Estable: 2 Estabilidad: 2 - Estable

Una implementación del Estándar de Streams de WHATWG.

Resumen

El Estándar de Streams de WHATWG (o "web streams") define una API para manejar datos en streaming. Es similar a la API de Streams de Node.js, pero surgió más tarde y se ha convertido en la API "estándar" para transmitir datos en muchos entornos de JavaScript.

Hay tres tipos principales de objetos:

• ReadableStream - Representa una fuente de datos en streaming.
• WritableStream - Representa un destino para datos en streaming.
• TransformStream - Representa un algoritmo para transformar datos en streaming.

Ejemplo de ReadableStream

Este ejemplo crea un ReadableStream simple que inserta la marca de tiempo actual de performance.now() una vez por segundo para siempre. Se utiliza un iterable asíncrono para leer los datos del 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

Clase: ReadableStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Añadido en: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Añadido en: v16.5.0

• underlyingSource <Objeto>

  • start <Función> Una función definida por el usuario que se invoca inmediatamente cuando se crea el ReadableStream.

  • controlador <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Devuelve: undefined o una promesa cumplida con undefined.

  • pull <Función> Una función definida por el usuario que se llama repetidamente cuando la cola interna del ReadableStream no está llena. La operación puede ser síncrona o asíncrona. Si es asíncrona, la función no se volverá a llamar hasta que se cumpla la promesa devuelta previamente.

  • controlador <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Devuelve: Una promesa cumplida con undefined.

  • cancel <Función> Una función definida por el usuario que se llama cuando se cancela el ReadableStream.

  • motivo <any>

  • Devuelve: Una promesa cumplida con undefined.

  • type <cadena> Debe ser 'bytes' o undefined.

  • autoAllocateChunkSize <número> Se utiliza solo cuando type es igual a 'bytes'. Cuando se establece en un valor distinto de cero, se asigna automáticamente un búfer de vista a ReadableByteStreamController.byobRequest. Cuando no se establece, se deben usar las colas internas del flujo para transferir datos a través del lector predeterminado ReadableStreamDefaultReader.

• strategy <Objeto>

  • highWaterMark <número> El tamaño máximo de la cola interna antes de que se aplique la contrapresión.
  • size <Función> Una función definida por el usuario que se utiliza para identificar el tamaño de cada fragmento de datos.
  • fragmento <any>
  • Devuelve: <número>

readableStream.locked

Agregado en: v16.5.0

• Tipo: <boolean> Se establece en true si hay un lector activo para este <ReadableStream>.

La propiedad readableStream.locked es false de forma predeterminada, y se cambia a true mientras haya un lector activo consumiendo los datos del flujo.

readableStream.cancel([reason])

Agregado en: v16.5.0

• reason <any>
• Devuelve: Una promesa cumplida con undefined una vez que la cancelación se ha completado.

readableStream.getReader([options])

Agregado en: v16.5.0

• options <Object>

  • mode <string> 'byob' o undefined

• Devuelve: <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)

Causa que readableStream.locked sea true.

readableStream.pipeThrough(transform[, options])

Añadido en: v16.5.0

• transform <Objeto>

  • readable <ReadableStream> El ReadableStream al que transform.writable enviará los datos potencialmente modificados que recibe de este ReadableStream.
  • writable <WritableStream> El WritableStream al que se escribirán los datos de este ReadableStream.

• options <Objeto>

  • preventAbort <boolean> Cuando es true, los errores en este ReadableStream no causarán que transform.writable se aborte.
  • preventCancel <boolean> Cuando es true, los errores en el destino transform.writable no causan que este ReadableStream se cancele.
  • preventClose <boolean> Cuando es true, cerrar este ReadableStream no causa que transform.writable se cierre.
  • signal <AbortSignal> Permite que la transferencia de datos se cancele usando un <AbortController>.

• Devuelve: <ReadableStream> De transform.readable.

Conecta este <ReadableStream> al par de <ReadableStream> y <WritableStream> proporcionado en el argumento transform de manera que los datos de este <ReadableStream> se escriban en transform.writable, posiblemente transformados, luego se envían a transform.readable. Una vez que la tubería está configurada, se devuelve transform.readable.

Causa que readableStream.locked sea true mientras la operación de tubería está activa.

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

readableStream.pipeTo(destination[, options])

Añadido en: v16.5.0

• destination <WritableStream> Un <WritableStream> al que se escribirán los datos de este ReadableStream.

• options <Object>

  • preventAbort <boolean> Cuando es true, los errores en este ReadableStream no harán que destination se aborte.
  • preventCancel <boolean> Cuando es true, los errores en el destination no harán que este ReadableStream se cancele.
  • preventClose <boolean> Cuando es true, cerrar este ReadableStream no hace que destination se cierre.
  • signal <AbortSignal> Permite cancelar la transferencia de datos utilizando un <AbortController>.

• Devuelve: Una promesa resuelta con undefined

Hace que readableStream.locked sea true mientras la operación de tubería está activa.

readableStream.tee()

[Historial]

Versión	Cambios
v18.10.0, v16.18.0	Soporte para bifurcar un flujo de bytes legible.
v16.5.0	Añadido en: v16.5.0

• Devuelve: <ReadableStream[]>

Devuelve un par de nuevas instancias de <ReadableStream> a las que se reenviarán los datos de este ReadableStream. Cada una recibirá los mismos datos.

Hace que readableStream.locked sea true.

readableStream.values([options])

Añadido en: v16.5.0

• options <Objeto>
  • preventCancel <booleano> Cuando es true, evita que el <ReadableStream> se cierre cuando el iterador asíncrono termina abruptamente. Predeterminado: false.

Crea y devuelve un iterador asíncrono utilizable para consumir los datos de este ReadableStream.

Hace que readableStream.locked sea true mientras el iterador asíncrono está activo.

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

Iteración Asíncrona

El objeto <ReadableStream> admite el protocolo de iterador asíncrono utilizando la sintaxis for await.

import { Buffer } from 'node:buffer'

const stream = new ReadableStream(getSomeSource())

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

El iterador asíncrono consumirá el <ReadableStream> hasta que termine.

De forma predeterminada, si el iterador asíncrono finaliza anticipadamente (ya sea mediante un break, return o un throw), el <ReadableStream> se cerrará. Para evitar el cierre automático del <ReadableStream>, utilice el método readableStream.values() para adquirir el iterador asíncrono y establezca la opción preventCancel en true.

El <ReadableStream> no debe estar bloqueado (es decir, no debe tener un lector activo existente). Durante la iteración asíncrona, el <ReadableStream> se bloqueará.

Transferencia con postMessage()

Una instancia de <ReadableStream> se puede transferir 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)

Añadido en: v20.6.0

• iterable <Iterable> Objeto que implementa el protocolo iterable Symbol.asyncIterator o Symbol.iterator.

Un método de utilidad que crea un nuevo <ReadableStream> a partir de 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) // Imprime: '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) // Imprime: 'a', 'b', 'c'
})()

Clase: ReadableStreamDefaultReader

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Añadido en: v16.5.0

De forma predeterminada, al llamar a readableStream.getReader() sin argumentos, se devuelve una instancia de ReadableStreamDefaultReader. El lector predeterminado trata los fragmentos de datos que se pasan a través del flujo como valores opacos, lo que permite que <ReadableStream> funcione generalmente con cualquier valor de JavaScript.

new ReadableStreamDefaultReader(stream)

Añadido en: v16.5.0

• stream <ReadableStream>

Crea un nuevo <ReadableStreamDefaultReader> que está bloqueado al <ReadableStream> dado.

readableStreamDefaultReader.cancel([reason])

Añadido en: v16.5.0

• reason <any>
• Devuelve: Una promesa cumplida con undefined.

Cancela el <ReadableStream> y devuelve una promesa que se cumple cuando el flujo subyacente se ha cancelado.

readableStreamDefaultReader.closed

Añadido en: v16.5.0

• Tipo: <Promise> Resuelta con undefined cuando el <ReadableStream> asociado se cierra o rechazada si el flujo tiene errores o el bloqueo del lector se libera antes de que el flujo termine de cerrarse.

readableStreamDefaultReader.read()

Añadido en: v16.5.0

• Devuelve: Una promesa resuelta con un objeto:
  • value <any>
  • done <boolean>

Solicita el siguiente fragmento de datos del <ReadableStream> subyacente y devuelve una promesa que se cumple con los datos una vez que están disponibles.

readableStreamDefaultReader.releaseLock()

Añadido en: v16.5.0

Libera el bloqueo de este lector en el <ReadableStream> subyacente.

Clase: ReadableStreamBYOBReader

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Añadido en: v16.5.0

El ReadableStreamBYOBReader es un consumidor alternativo para <ReadableStream>s orientados a bytes (aquellos que se crean con underlyingSource.type establecido en 'bytes' cuando se creó el ReadableStream).

BYOB es la abreviatura de "trae tu propio búfer" (bring your own buffer). Este es un patrón que permite una lectura más eficiente de los datos orientados a bytes que evita copias innecesarias.

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)

Agregado en: v16.5.0

• stream <ReadableStream>

Crea un nuevo ReadableStreamBYOBReader que está bloqueado al <ReadableStream> dado.

readableStreamBYOBReader.cancel([reason])

Agregado en: v16.5.0

• reason <any>
• Devuelve: Una promesa cumplida con undefined.

Cancela el <ReadableStream> y devuelve una promesa que se cumple cuando el flujo subyacente se ha cancelado.

readableStreamBYOBReader.closed

Agregado en: v16.5.0

• Tipo: <Promise> Cumplida con undefined cuando el <ReadableStream> asociado está cerrado o rechazada si el flujo produce errores o el bloqueo del lector se libera antes de que el flujo termine de cerrarse.

readableStreamBYOBReader.read(view[, options])

[Historial]

Versión	Cambios
v21.7.0, v20.17.0	Se añadió la opción min.
v16.5.0	Añadido en: v16.5.0

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

• options <Object>

  • min <number> Cuando se establece, la promesa devuelta solo se cumplirá tan pronto como haya un número min de elementos disponibles. Cuando no se establece, la promesa se cumple cuando hay al menos un elemento disponible.

• Devuelve: Una promesa cumplida con un objeto:

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

Solicita el siguiente fragmento de datos del <ReadableStream> subyacente y devuelve una promesa que se cumple con los datos una vez que están disponibles.

No pase una instancia de objeto <Buffer> agrupada en este método. Los objetos Buffer agrupados se crean usando Buffer.allocUnsafe(), o Buffer.from(), o a menudo son devueltos por varias devoluciones de llamada del módulo node:fs. Estos tipos de Buffer utilizan un objeto <ArrayBuffer> subyacente compartido que contiene todos los datos de todas las instancias de Buffer agrupadas. Cuando un Buffer, <TypedArray> o <DataView> se pasa a readableStreamBYOBReader.read(), el ArrayBuffer subyacente de la vista se desconecta, invalidando todas las vistas existentes que puedan existir en ese ArrayBuffer. Esto puede tener consecuencias desastrosas para su aplicación.

readableStreamBYOBReader.releaseLock()

Añadido en: v16.5.0

Libera el bloqueo de este lector en el <ReadableStream> subyacente.

Clase: ReadableStreamDefaultController

Añadido en: v16.5.0

Cada <ReadableStream> tiene un controlador que es responsable del estado interno y la gestión de la cola del flujo. El ReadableStreamDefaultController es la implementación del controlador predeterminado para los ReadableStream que no están orientados a bytes.

readableStreamDefaultController.close()

Añadido en: v16.5.0

Cierra el <ReadableStream> al que está asociado este controlador.

readableStreamDefaultController.desiredSize

Añadido en: v16.5.0

• Tipo: <number>

Devuelve la cantidad de datos restantes para llenar la cola del <ReadableStream>.

readableStreamDefaultController.enqueue([chunk])

Añadido en: v16.5.0

• chunk <any>

Agrega un nuevo fragmento de datos a la cola del <ReadableStream>.

readableStreamDefaultController.error([error])

Añadido en: v16.5.0

• error <any>

Señala un error que causa que el <ReadableStream> produzca un error y se cierre.

Clase: ReadableByteStreamController

[Historial]

Versión	Cambios
v18.10.0	Soporte para el manejo de una solicitud de extracción BYOB de un lector liberado.
v16.5.0	Añadido en: v16.5.0

Cada <ReadableStream> tiene un controlador que es responsable del estado interno y la gestión de la cola de la secuencia. El ReadableByteStreamController es para ReadableStreams orientados a bytes.

readableByteStreamController.byobRequest

Agregado en: v16.5.0

• Tipo: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Agregado en: v16.5.0

Cierra el <ReadableStream> al que está asociado este controlador.

readableByteStreamController.desiredSize

Agregado en: v16.5.0

• Tipo: <number>

Devuelve la cantidad de datos restantes para llenar la cola del <ReadableStream>.

readableByteStreamController.enqueue(chunk)

Agregado en: v16.5.0

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

Agrega un nuevo fragmento de datos a la cola del <ReadableStream>.

readableByteStreamController.error([error])

Agregado en: v16.5.0

• error <any>

Señala un error que hace que el <ReadableStream> genere un error y se cierre.

Clase: ReadableStreamBYOBRequest

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Agregado en: v16.5.0

Cuando se utiliza ReadableByteStreamController en flujos orientados a bytes, y cuando se utiliza ReadableStreamBYOBReader, la propiedad readableByteStreamController.byobRequest proporciona acceso a una instancia ReadableStreamBYOBRequest que representa la solicitud de lectura actual. El objeto se utiliza para obtener acceso al ArrayBuffer/TypedArray que se ha proporcionado para que la solicitud de lectura se complete, y proporciona métodos para señalar que los datos se han proporcionado.

readableStreamBYOBRequest.respond(bytesWritten)

Agregado en: v16.5.0

• bytesWritten <number>

Señala que se ha escrito un número bytesWritten de bytes en readableStreamBYOBRequest.view.

readableStreamBYOBRequest.respondWithNewView(view)

Añadido en: v16.5.0

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

Indica que la solicitud se ha cumplido con bytes escritos en un nuevo Buffer, TypedArray o DataView.

readableStreamBYOBRequest.view

Añadido en: v16.5.0

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

Clase: WritableStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Añadido en: v16.5.0

WritableStream es un destino al cual se envían los datos de flujo.

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

const stream = new WritableStream({
  write(chunk) {
    console.log(chunk)
  },
})

await stream.getWriter().write('Hola Mundo')

new WritableStream([underlyingSink[, strategy]])

Añadido en: v16.5.0

• underlyingSink <Object>

  • start <Function> Una función definida por el usuario que se invoca inmediatamente cuando se crea el WritableStream.

  • controller <WritableStreamDefaultController>

  • Devuelve: undefined o una promesa resuelta con undefined.

  • write <Function> Una función definida por el usuario que se invoca cuando se ha escrito un fragmento de datos en el WritableStream.

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Devuelve: Una promesa resuelta con undefined.

  • close <Function> Una función definida por el usuario que se llama cuando se cierra el WritableStream.

  • Devuelve: Una promesa resuelta con undefined.

  • abort <Function> Una función definida por el usuario que se llama para cerrar abruptamente el WritableStream.

  • reason <any>

  • Devuelve: Una promesa resuelta con undefined.

  • type <any> La opción type está reservada para uso futuro y debe ser indefinida.

• strategy <Object>

  • highWaterMark <number> El tamaño máximo de la cola interna antes de que se aplique la contrapresión.
  • size <Function> Una función definida por el usuario que se utiliza para identificar el tamaño de cada fragmento de datos.
  • chunk <any>
  • Devuelve: <number>

writableStream.abort([reason])

Agregado en: v16.5.0

• reason <any>
• Devuelve: Una promesa cumplida con undefined.

Termina abruptamente el WritableStream. Todas las escrituras en cola se cancelarán y sus promesas asociadas serán rechazadas.

writableStream.close()

Agregado en: v16.5.0

• Devuelve: Una promesa cumplida con undefined.

Cierra el WritableStream cuando no se esperan más escrituras.

writableStream.getWriter()

Agregado en: v16.5.0

• Devuelve: <WritableStreamDefaultWriter>

Crea y devuelve una nueva instancia de escritor que se puede utilizar para escribir datos en el WritableStream.

writableStream.locked

Agregado en: v16.5.0

• Tipo: <boolean>

La propiedad writableStream.locked es false por defecto y cambia a true mientras haya un escritor activo adjunto a este WritableStream.

Transferencia con postMessage()

Una instancia de <WritableStream> puede ser transferida usando un <MessagePort>.

const stream = new WritableStream(getWritableSinkSomehow())

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Clase: WritableStreamDefaultWriter

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Añadido en: v16.5.0

new WritableStreamDefaultWriter(stream)

Añadido en: v16.5.0

• stream <WritableStream>

Crea un nuevo WritableStreamDefaultWriter que está bloqueado al WritableStream dado.

writableStreamDefaultWriter.abort([reason])

Añadido en: v16.5.0

• reason <any>
• Devuelve: Una promesa cumplida con undefined.

Termina abruptamente el WritableStream. Todas las escrituras en cola serán canceladas con sus promesas asociadas rechazadas.

writableStreamDefaultWriter.close()

Añadido en: v16.5.0

• Devuelve: Una promesa resuelta con undefined.

Cierra el WritableStream cuando no se esperan más escrituras.

writableStreamDefaultWriter.closed

Añadido en: v16.5.0

• Tipo: <Promise> Resuelta con undefined cuando el <WritableStream> asociado está cerrado o rechazada si el flujo produce errores o se libera el bloqueo del escritor antes de que el flujo termine de cerrarse.

writableStreamDefaultWriter.desiredSize

Añadido en: v16.5.0

• Tipo: <number>

La cantidad de datos necesarios para llenar la cola del <WritableStream>.

writableStreamDefaultWriter.ready

Añadido en: v16.5.0

• Tipo: <Promise> Resuelta con undefined cuando el escritor está listo para ser utilizado.

writableStreamDefaultWriter.releaseLock()

Agregado en: v16.5.0

Libera el bloqueo de este escritor en el <ReadableStream> subyacente.

writableStreamDefaultWriter.write([chunk])

Agregado en: v16.5.0

• chunk: <any>
• Devuelve: Una promesa resuelta con undefined.

Agrega un nuevo fragmento de datos a la cola del <WritableStream>.

Clase: WritableStreamDefaultController

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Agregado en: v16.5.0

El WritableStreamDefaultController gestiona el estado interno del <WritableStream>.

writableStreamDefaultController.error([error])

Agregado en: v16.5.0

• error <any>

Llamado por el código de usuario para señalar que ha ocurrido un error mientras se procesaban los datos de WritableStream. Cuando se llama, el <WritableStream> se abortará y se cancelarán las escrituras pendientes.

writableStreamDefaultController.signal

• Tipo: <AbortSignal> Un AbortSignal que puede usarse para cancelar operaciones de escritura o cierre pendientes cuando un <WritableStream> se anula.

Clase: TransformStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Añadido en: v16.5.0

Un TransformStream consiste en un <ReadableStream> y un <WritableStream> que están conectados de tal manera que los datos escritos en el WritableStream se reciben y, potencialmente, se transforman, antes de ser empujados a la cola 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]]])

Agregado en: v16.5.0

• transformer <Object>

  • start <Function> Una función definida por el usuario que se invoca inmediatamente cuando se crea el TransformStream.

  • controller <TransformStreamDefaultController>

  • Devuelve: undefined o una promesa cumplida con undefined

  • transform <Function> Una función definida por el usuario que recibe y, potencialmente, modifica un fragmento de datos escrito en transformStream.writable, antes de enviarlo a transformStream.readable.

  • chunk <any>

  • controller <TransformStreamDefaultController>

  • Devuelve: Una promesa cumplida con undefined.

  • flush <Function> Una función definida por el usuario que se llama inmediatamente antes de que se cierre el lado grabable de TransformStream, señalando el final del proceso de transformación.

  • controller <TransformStreamDefaultController>

  • Devuelve: Una promesa cumplida con undefined.

  • readableType <any> La opción readableType está reservada para uso futuro y debe ser undefined.

  • writableType <any> La opción writableType está reservada para uso futuro y debe ser undefined.

• writableStrategy <Object>

  • highWaterMark <number> El tamaño máximo de la cola interna antes de aplicar contrapresión.
  • size <Function> Una función definida por el usuario que se utiliza para identificar el tamaño de cada fragmento de datos.
  • chunk <any>
  • Devuelve: <number>

• readableStrategy <Object>

  • highWaterMark <number> El tamaño máximo de la cola interna antes de aplicar contrapresión.
  • size <Function> Una función definida por el usuario que se utiliza para identificar el tamaño de cada fragmento de datos.
  • chunk <any>
  • Devuelve: <number>

transformStream.readable

Agregado en: v16.5.0

• Tipo: <ReadableStream>

transformStream.writable

Agregado en: v16.5.0

• Tipo: <WritableStream>

Transferir con postMessage()

Una instancia de <TransformStream> se puede transferir utilizando un <MessagePort>.

const stream = new TransformStream()

const { port1, port2 } = new MessageChannel()

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

port2.postMessage(stream, [stream])

Clase: TransformStreamDefaultController

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Agregado en: v16.5.0

TransformStreamDefaultController gestiona el estado interno de TransformStream.

transformStreamDefaultController.desiredSize

Agregado en: v16.5.0

• Tipo: <number>

La cantidad de datos necesarios para llenar la cola del lado legible.

transformStreamDefaultController.enqueue([chunk])

Agregado en: v16.5.0

• chunk <any>

Añade un fragmento de datos a la cola del lado legible.

transformStreamDefaultController.error([reason])

Agregado en: v16.5.0

• reason <any>

Indica tanto al lado legible como al grabable que ha ocurrido un error mientras se procesaban los datos de transformación, lo que provoca que ambos lados se cierren abruptamente.

transformStreamDefaultController.terminate()

Agregado en: v16.5.0

Cierra el lado legible del transporte y hace que el lado grabable se cierre abruptamente con un error.

Clase: ByteLengthQueuingStrategy

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Agregado en: v16.5.0

new ByteLengthQueuingStrategy(init)

Agregado en: v16.5.0

• init <Object>
  • highWaterMark <number>

byteLengthQueuingStrategy.highWaterMark

Agregado en: v16.5.0

• Tipo: <number>

byteLengthQueuingStrategy.size

Agregado en: v16.5.0

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

Clase: CountQueuingStrategy

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.5.0	Agregado en: v16.5.0

new CountQueuingStrategy(init)

Agregado en: v16.5.0

• init <Object>
  • highWaterMark <number>

countQueuingStrategy.highWaterMark

Agregado en: v16.5.0

• Tipo: <number>

countQueuingStrategy.size

Agregado en: v16.5.0

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

Clase: TextEncoderStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.6.0	Agregado en: v16.6.0

new TextEncoderStream()

Agregado en: v16.6.0

Crea una nueva instancia de TextEncoderStream.

textEncoderStream.encoding

Agregado en: v16.6.0

• Tipo: <string>

La codificación soportada por la instancia de TextEncoderStream.

textEncoderStream.readable

Agregado en: v16.6.0

• Tipo: <ReadableStream>

textEncoderStream.writable

Agregado en: v16.6.0

• Tipo: <WritableStream>

Clase: TextDecoderStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.6.0	Agregado en: v16.6.0

new TextDecoderStream([encoding[, options]])

Agregado en: v16.6.0

• encoding <string> Identifica la encoding que esta instancia de TextDecoder soporta. Predeterminado: 'utf-8'.
• options <Objeto>
  • fatal <boolean> true si los fallos de decodificación son fatales.
  • ignoreBOM <boolean> Cuando es true, el TextDecoderStream incluirá la marca de orden de bytes en el resultado decodificado. Cuando es false, la marca de orden de bytes se eliminará de la salida. Esta opción solo se utiliza cuando encoding es 'utf-8', 'utf-16be' o 'utf-16le'. Predeterminado: false.

Crea una nueva instancia de TextDecoderStream.

textDecoderStream.encoding

Añadido en: v16.6.0

• Tipo: <string>

La codificación compatible con la instancia TextDecoderStream.

textDecoderStream.fatal

Añadido en: v16.6.0

• Tipo: <boolean>

El valor será true si los errores de decodificación resultan en el lanzamiento de un TypeError.

textDecoderStream.ignoreBOM

Añadido en: v16.6.0

• Tipo: <boolean>

El valor será true si el resultado de la decodificación incluirá la marca de orden de bytes.

textDecoderStream.readable

Añadido en: v16.6.0

• Tipo: <ReadableStream>

textDecoderStream.writable

Añadido en: v16.6.0

• Tipo: <WritableStream>

Clase: CompressionStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v17.0.0	Añadido en: v17.0.0

new CompressionStream(format)

[Historial]

Versión	Cambios
v21.2.0, v20.12.0	format ahora acepta el valor deflate-raw.
v17.0.0	Añadido en: v17.0.0

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

compressionStream.readable

Añadido en: v17.0.0

• Tipo: <ReadableStream>

compressionStream.writable

Añadido en: v17.0.0

• Tipo: <WritableStream>

Clase: DecompressionStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v17.0.0	Añadido en: v17.0.0

new DecompressionStream(format)

[Historial]

Versión	Cambios
v21.2.0, v20.12.0	format ahora acepta el valor deflate-raw.
v17.0.0	Añadido en: v17.0.0

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

decompressionStream.readable

Agregado en: v17.0.0

• Tipo: <ReadableStream>

decompressionStream.writable

Agregado en: v17.0.0

• Tipo: <WritableStream>

Consumidores de Utilidad

Agregado en: v16.7.0

Las funciones de consumidor de utilidad proporcionan opciones comunes para consumir streams.

Se accede a ellas 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)

Agregado en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Devuelve: <Promise> Se cumple con un ArrayBuffer que contiene el contenido completo del 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}`)
// Imprime: 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}`)
  // Imprime: from readable: 76
})

streamConsumers.blob(stream)

Agregado en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Devuelve: <Promise> Se cumple con un <Blob> que contiene el contenido completo del flujo.

ESM

import { blob } from 'node:stream/consumers'

const dataBlob = new Blob(['¡hola mundo desde consumidores!'])

const readable = dataBlob.stream()
const data = await blob(readable)
console.log(`desde readable: ${data.size}`)
// Imprime: desde readable: 27

CJS

const { blob } = require('node:stream/consumers')

const dataBlob = new Blob(['¡hola mundo desde consumidores!'])

const readable = dataBlob.stream()
blob(readable).then(data => {
  console.log(`desde readable: ${data.size}`)
  // Imprime: desde readable: 27
})

streamConsumers.buffer(stream)

Agregado en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Devuelve: <Promise> Se cumple con un <Buffer> que contiene todo el contenido del flujo.

ESM

import { buffer } from 'node:stream/consumers'
import { Readable } from 'node:stream'
import { Buffer } from 'node:buffer'

const dataBuffer = Buffer.from('¡hola mundo desde consumers!')

const readable = Readable.from(dataBuffer)
const data = await buffer(readable)
console.log(`desde readable: ${data.length}`)
// Imprime: desde readable: 27

CJS

const { buffer } = require('node:stream/consumers')
const { Readable } = require('node:stream')
const { Buffer } = require('node:buffer')

const dataBuffer = Buffer.from('¡hola mundo desde consumers!')

const readable = Readable.from(dataBuffer)
buffer(readable).then(data => {
  console.log(`desde readable: ${data.length}`)
  // Imprime: desde readable: 27
})

streamConsumers.json(stream)

Añadido en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Devuelve: <Promise> Se cumple con el contenido del flujo analizado como una cadena codificada en UTF-8 que luego se pasa a través de JSON.parse().

ESM

import { json } from 'node:stream/consumers'
import { Readable } from 'node:stream'

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: '¡hola mundo desde consumers!',
  })
)

const readable = Readable.from(JSON.stringify(items))
const data = await json(readable)
console.log(`desde readable: ${data.length}`)
// Imprime: desde readable: 100

CJS

const { json } = require('node:stream/consumers')
const { Readable } = require('node:stream')

const items = Array.from(
  {
    length: 100,
  },
  () => ({
    message: '¡hola mundo desde consumers!',
  })
)

const readable = Readable.from(JSON.stringify(items))
json(readable).then(data => {
  console.log(`desde readable: ${data.length}`)
  // Imprime: desde readable: 100
})

streamConsumers.text(stream)

Añadido en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Devuelve: <Promise> Se cumple con el contenido del flujo analizado como una cadena codificada en UTF-8.

ESM

import { text } from 'node:stream/consumers'
import { Readable } from 'node:stream'

const readable = Readable.from('¡Hola mundo desde consumidores!')
const data = await text(readable)
console.log(`desde readable: ${data.length}`)
// Imprime: desde readable: 30

CJS

const { text } = require('node:stream/consumers')
const { Readable } = require('node:stream')

const readable = Readable.from('¡Hola mundo desde consumidores!')
text(readable).then(data => {
  console.log(`desde readable: ${data.length}`)
  // Imprime: desde readable: 30
})