API de Web Streams

[Historia]

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	Agregado 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 de 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 la transmisión de datos en muchos entornos de JavaScript.

Hay tres tipos principales de objetos:

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

Ejemplo ReadableStream

Este ejemplo crea un ReadableStream simple que envía la marca de tiempo performance.now() actual una vez por segundo para siempre. Un iterable asíncrono se utiliza 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 está expuesta en el objeto global.
v16.5.0	Agregado en: v16.5.0

new ReadableStream([underlyingSource [, strategy]])

Agregado 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.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Regresa: undefined o una promesa resuelta con undefined.

  • pull <Función> Una función definida por el usuario que se llama repetidamente cuando la cola interna de 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 previamente devuelta.

  • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>

  • Regresa: Una promesa resuelta con undefined.

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

  • reason <any>

  • Regresa: Una promesa resuelta con undefined.

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

  • autoAllocateChunkSize <number> 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 <number> 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.
  • chunk <any>
  • Regresa: <number>

readableStream.locked

Añadido en: v16.5.0

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

La propiedad readableStream.locked es false por defecto, y se cambia a true mientras haya un lector activo consumiendo los datos del stream.

readableStream.cancel([reason])

Añadido en: v16.5.0

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

readableStream.getReader([options])

Añadido 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 <Object>

  • 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 <Object>

  • 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> Desde transform.readable.

Conecta este <ReadableStream> al par de <ReadableStream> y <WritableStream> proporcionado en el argumento transform de tal manera que los datos de este <ReadableStream> se escriben en transform.writable, posiblemente transformados, y 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);
  // 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])

Agregado 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 causarán que destination sea abortado.
  • preventCancel <boolean> Cuando es true, los errores en el destination no causarán que este ReadableStream sea cancelado.
  • preventClose <boolean> Cuando es true, cerrar este ReadableStream no causa que destination sea cerrado.
  • signal <AbortSignal> Permite que la transferencia de datos se cancele utilizando un <AbortController>.

• Devuelve: Una promesa cumplida con undefined

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

readableStream.tee()

[Historial]

Versión	Cambios
v18.10.0, v16.18.0	Soporte para dividir un flujo de bytes legibles.
v16.5.0	Agregado en: v16.5.0

• Devuelve: <ReadableStream[]>

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

Causa que readableStream.locked sea true.

readableStream.values([options])

Agregado en: v16.5.0

• options <Object>
  • preventCancel <boolean> 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.

Causa 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 sale prematuramente (ya sea a través de 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 utilizando 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)

Agregado 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); // 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'
})();

Clase: ReadableStreamDefaultReader

[Historial]

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

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

new ReadableStreamDefaultReader(stream)

Agregado en: v16.5.0

• stream <ReadableStream>

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

readableStreamDefaultReader.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 stream subyacente ha sido cancelado.

readableStreamDefaultReader.closed

Agregado en: v16.5.0

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

readableStreamDefaultReader.read()

Agregado en: v16.5.0

• Devuelve: Una promesa cumplida 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()

Agregado 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 está expuesta en el objeto global.
v16.5.0	Agregado en: v16.5.0

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

BYOB es la abreviatura de "bring your own buffer" ("trae tu propio búfer"). Este es un patrón que permite una lectura más eficiente de 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])

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.

readableStreamBYOBReader.closed

Añadido en: v16.5.0

• Tipo: <Promise> Cumplida con undefined cuando el <ReadableStream> asociado se cierra o se rechaza si el flujo genera 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 sólo se cumplirá tan pronto como haya disponible un número min de elementos. Cuando no se establece, la promesa se cumple cuando al menos un elemento está 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 utilizando Buffer.allocUnsafe() o Buffer.from(), o a menudo son devueltos por varias retrollamadas 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 se pasa un Buffer, <TypedArray>, o <DataView> a readableStreamBYOBReader.read(), el ArrayBuffer subyacente de la vista se separa, invalidando todas las vistas existentes que puedan existir en ese ArrayBuffer. Esto puede tener consecuencias desastrosas para su aplicación.

readableStreamBYOBReader.releaseLock()

Agregado en: v16.5.0

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

Clase: ReadableStreamDefaultController

Agregado 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 ReadableStreamDefaultController es la implementación del controlador predeterminado para ReadableStreams que no están orientados a bytes.

readableStreamDefaultController.close()

Agregado en: v16.5.0

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

readableStreamDefaultController.desiredSize

Agregado en: v16.5.0

• Tipo: <number>

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

readableStreamDefaultController.enqueue([chunk])

Agregado en: v16.5.0

• chunk <any>

Añade un nuevo fragmento de datos a la cola del <ReadableStream>.

readableStreamDefaultController.error([error])

Agregado en: v16.5.0

• error <any>

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

Clase: ReadableByteStreamController

[Historial]

Versión	Cambios
v18.10.0	Soporte para manejar una solicitud BYOB pull de un lector liberado.
v16.5.0	Agregado 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

Añadido en: v16.5.0

• Tipo: <ReadableStreamBYOBRequest>

readableByteStreamController.close()

Añadido en: v16.5.0

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

readableByteStreamController.desiredSize

Añadido en: v16.5.0

• Tipo: <number>

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

readableByteStreamController.enqueue(chunk)

Añadido en: v16.5.0

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

Añade un nuevo fragmento de datos a la cola del <ReadableStream>.

readableByteStreamController.error([error])

Añadido en: v16.5.0

• error <any>

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

Clase: ReadableStreamBYOBRequest

[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

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

readableStreamBYOBRequest.respond(bytesWritten)

Añadido en: v16.5.0

• bytesWritten <number>

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

readableStreamBYOBRequest.respondWithNewView(view)

Añadido en: v16.5.0

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

Señala 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

[Historia]

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

WritableStream es un destino al que se envían los datos del stream.

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

Añadido en: v16.5.0

• underlyingSink <Object>

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

  • controller <WritableStreamDefaultController>

  • Devuelve: undefined o una promesa cumplida con undefined.

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

  • chunk <any>

  • controller <WritableStreamDefaultController>

  • Devuelve: Una promesa cumplida con undefined.

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

  • Devuelve: Una promesa cumplida con undefined.

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

  • reason <any>

  • Devuelve: Una promesa cumplida 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])

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 y sus promesas asociadas rechazadas.

writableStream.close()

Añadido en: v16.5.0

• Devuelve: Una promesa cumplida con undefined.

Cierra el WritableStream cuando no se esperan escrituras adicionales.

writableStream.getWriter()

Añadido 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

Añadido en: v16.5.0

• Tipo: <boolean>

La propiedad writableStream.locked es false por defecto, y se 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 y sus promesas asociadas rechazadas.

writableStreamDefaultWriter.close()

Agregado en: v16.5.0

• Devuelve: Una promesa cumplida con undefined.

Cierra el WritableStream cuando no se esperan escrituras adicionales.

writableStreamDefaultWriter.closed

Agregado en: v16.5.0

• Tipo: <Promise> Cumplida con undefined cuando el <WritableStream> asociado se cierra o se rechaza si el flujo tiene errores o el bloqueo del escritor se libera antes de que el flujo termine de cerrarse.

writableStreamDefaultWriter.desiredSize

Agregado en: v16.5.0

• Tipo: <number>

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

writableStreamDefaultWriter.ready

Agregado en: v16.5.0

• Tipo: <Promise> Cumplida 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 cumplida con undefined.

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

Clase: WritableStreamDefaultController

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta 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 indicar que se ha producido un error al procesar los datos de WritableStream. Cuando se llama, el <WritableStream> se abortará, y las escrituras pendientes se cancelarán.

writableStreamDefaultController.signal

• Tipo: <AbortSignal> Un AbortSignal que puede ser usado para cancelar operaciones de escritura o cierre pendientes cuando un <WritableStream> es abortado.

Clase: TransformStream

[Historial]

Versión	Cambios
v18.0.0	Esta clase ahora está expuesta en el objeto global.
v16.5.0	Agregado 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 son recibidos, y potencialmente transformados, 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 reenviarlo 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 del TransformStream, lo que indica 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 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>

• readableStrategy <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>

transformStream.readable

Añadido en: v16.5.0

• Tipo: <ReadableStream>

transformStream.writable

Añadido en: v16.5.0

• Tipo: <WritableStream>

Transferencia con postMessage()

Se puede transferir una instancia de <TransformStream> usando 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	Añadido en: v16.5.0

TransformStreamDefaultController gestiona el estado interno de TransformStream.

transformStreamDefaultController.desiredSize

Añadido en: v16.5.0

• Tipo: <number>

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

transformStreamDefaultController.enqueue([chunk])

Añadido en: v16.5.0

• chunk <any>

Anexa un fragmento de datos a la cola del lado legible.

transformStreamDefaultController.error([reason])

Añadido en: v16.5.0

• reason <any>

Señala tanto al lado legible como al lado escribible que se ha producido un error al procesar los datos de transformación, lo que provoca que ambos lados se cierren abruptamente.

transformStreamDefaultController.terminate()

Añadido en: v16.5.0

Cierra el lado legible del transporte y hace que el lado escribible 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	Añadido en: v16.5.0

new ByteLengthQueuingStrategy(init)

Añadido en: v16.5.0

• init <Objeto>
  • highWaterMark <número>

byteLengthQueuingStrategy.highWaterMark

Añadido en: v16.5.0

• Tipo: <número>

byteLengthQueuingStrategy.size

Añadido en: v16.5.0

• Tipo: <Función>
  • chunk <any>
  • Devuelve: <número>

Clase: CountQueuingStrategy

[Historia]

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

Añadido en: v16.5.0

• init <Objeto>
  • highWaterMark <número>

countQueuingStrategy.highWaterMark

Añadido en: v16.5.0

• Tipo: <número>

countQueuingStrategy.size

Añadido en: v16.5.0

• Tipo: <Función>
  • chunk <any>
  • Devuelve: <número>

Clase: TextEncoderStream

[Historia]

Versión	Cambios
v18.0.0	Esta clase ahora se expone en el objeto global.
v16.6.0	Añadido 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 admitida 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 está expuesta 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 admite esta instancia de TextDecoder. Predeterminado: 'utf-8'.
• options <Object>
  • fatal <boolean> true si los errores 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 usa cuando encoding es 'utf-8', 'utf-16be' o 'utf-16le'. Predeterminado: false.

Crea una nueva instancia de TextDecoderStream.

textDecoderStream.encoding

Agregado en: v16.6.0

• Tipo: <string>

La codificación admitida por la instancia de TextDecoderStream.

textDecoderStream.fatal

Agregado en: v16.6.0

• Tipo: <boolean>

El valor será true si los errores de decodificación provocan que se lance 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 está expuesta 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

Añadido en: v17.0.0

• Tipo: <ReadableStream>

decompressionStream.writable

Añadido en: v17.0.0

• Tipo: <WritableStream>

Consumidores de utilidades

Agregado en: v16.7.0

Las funciones del consumidor de utilidades proporcionan opciones comunes para consumir flujos.

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 flujo.

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)

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

Añadido en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Regresa: <Promise> Cumple con un <Buffer> que contiene el contenido completo del 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)

Añadido en: v16.7.0

• stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
• Regresa: <Promise> Cumple con el contenido del stream 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: '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)

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 consumers!');
const data = await text(readable);
console.log(`from readable: ${data.length}`);
// Imprime: from readable: 27

CJS

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

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