Spec-Zone.ru › Node.js 24 LTS

API веб-потоков

История
Версия Изменения
v21.0.0

Больше не является экспериментальным.
v18.0.0

Использование этого API больше не приводит к предупреждению во время выполнения.
v16.5.0

Добавлено в: v16.5.0
Стабильность: 2 — Стабильный

Реализация стандарта WHATWG Streams.

Обзор

Стандарт WHATWG Streams (или «веб-потоки») определяет API для обработки потоковых данных. Он похож на API потоков Node.js, но появился позже и стал «стандартным» API для потоковой передачи данных в различных средах JavaScript.

Существует три основных типа объектов:

  • ReadableStream — представляет источник потоковых данных.
  • WritableStream — представляет назначение потоковых данных.
  • TransformStream — представляет алгоритм преобразования потоковых данных.

Пример ReadableStream

В этом примере создаётся простой ReadableStream, который бесконечно отправляет текущую временную метку performance.now() раз в секунду. Для чтения данных из потока используется асинхронный итерируемый объект.

Модули JavaScript
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);
CommonJS
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);
})();

Взаимодействие с потоками Node.js

Потоки Node.js можно преобразовать в веб-потоки и наоборот с помощью методов toWeb и fromWeb, доступных у объектов stream.Readable, stream.Writable и stream.Duplex.

Дополнительные сведения см. в соответствующей документации:

  • stream.Readable.toWeb
  • stream.Readable.fromWeb
  • stream.Writable.toWeb
  • stream.Writable.fromWeb
  • stream.Duplex.toWeb
  • stream.Duplex.fromWeb

API

Класс: ReadableStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0
new ReadableStream([underlyingSource [, strategy]])
Добавлено в: v16.5.0
  • underlyingSource <Object>
    • start <Function> Пользовательская функция, которая вызывается сразу после создания ReadableStream.
      • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
      • Возвращает: undefined или промис, выполненный с undefined.
    • pull <Function> Пользовательская функция, которая вызывается повторно, пока внутренняя очередь ReadableStream не заполнена. Операция может быть синхронной или асинхронной. Если она асинхронная, функция не будет вызвана повторно, пока не будет выполнен ранее возвращённый промис.
      • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
      • Возвращает: промис, выполненный с undefined.
    • cancel <Function> Пользовательская функция, которая вызывается при отмене ReadableStream.
      • reason <any>
      • Возвращает: промис, выполненный с undefined.
    • type <string> Должно быть 'bytes' или undefined.
    • autoAllocateChunkSize <number> Используется только, если type равно 'bytes'. Если задано ненулевое значение, буфер представления автоматически выделяется для ReadableByteStreamController.byobRequest. Если значение не задано, для передачи данных через считыватель по умолчанию ReadableStreamDefaultReader необходимо использовать внутренние очереди потока.
  • strategy <Object>
    • highWaterMark <number> Максимальный размер внутренней очереди, до которого не применяется обратное давление.
    • size <Function> Пользовательская функция, используемая для определения размера каждого фрагмента данных.
      • chunk <any>
      • Возвращает: <number>
readableStream.locked
Добавлено в: v16.5.0
  • Тип: <boolean> Устанавливается в true, если у этого <ReadableStream> есть активный считыватель.

По умолчанию свойство readableStream.locked имеет значение false; при наличии активного считывателя, потребляющего данные потока, оно переключается на true.

readableStream.cancel([reason])
Добавлено в: v16.5.0
  • reason <any>
  • Возвращает: промис, выполненный с undefined после завершения отмены.
readableStream.getReader([options])
Добавлено в: v16.5.0
  • options <Object>
    • mode <string> 'byob' или undefined
  • Возвращает: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>
Модули JavaScript
import { ReadableStream } from 'node:stream/web';

const stream = new ReadableStream();

const reader = stream.getReader();

console.log(await reader.read());
CommonJS
const { ReadableStream } = require('node:stream/web');

const stream = new ReadableStream();

const reader = stream.getReader();

reader.read().then(console.log);

Переводит readableStream.locked в состояние true.

readableStream.pipeThrough(transform[, options])
Добавлено в: v16.5.0
  • transform <Object>
    • readable <ReadableStream> Поток ReadableStream, в который transform.writable будет передавать потенциально изменённые данные, полученные из этого ReadableStream.
    • writable <WritableStream> Поток WritableStream, в который будут записываться данные этого ReadableStream.
  • options <Object>
    • preventAbort <boolean> Если true, ошибки в этом ReadableStream не приведут к прерыванию transform.writable.
    • preventCancel <boolean> Если true, ошибки в целевом transform.writable не приведут к отмене этого ReadableStream.
    • preventClose <boolean> Если true, закрытие этого ReadableStream не приведёт к закрытию transform.writable.
    • signal <AbortSignal> Позволяет отменить передачу данных с помощью <AbortController>.
  • Возвращает: <ReadableStream> Из transform.readable.

Подключает этот <ReadableStream> к паре <ReadableStream> и <WritableStream>, переданной в аргументе transform, так что данные из этого <ReadableStream> записываются в transform.writable, могут быть преобразованы, а затем передаются в transform.readable. После настройки конвейера возвращается transform.readable.

Переводит readableStream.locked в состояние true на время выполнения операции передачи.

Модули JavaScript
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
CommonJS
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])
Добавлено в: v16.5.0
  • destination <WritableStream> <WritableStream>, в который будут записываться данные этого ReadableStream.
  • options <Object>
    • preventAbort <boolean> Если true, ошибки в этом ReadableStream не приведут к прерыванию destination.
    • preventCancel <boolean> Если true, ошибки в destination не приведут к отмене этого ReadableStream.
    • preventClose <boolean> Если true, закрытие этого ReadableStream не приведёт к закрытию destination.
    • signal <AbortSignal> Позволяет отменить передачу данных с помощью <AbortController>.
  • Возвращает: промис, выполненный с undefined

Переводит readableStream.locked в состояние true на время выполнения операции передачи.

readableStream.tee()
История
Версия Изменения
v18.10.0, v16.18.0

Добавлена поддержка разделения потока байтов для чтения.
v16.5.0

Добавлено в: v16.5.0
  • Возвращает: <ReadableStream[]>

Возвращает пару новых экземпляров <ReadableStream>, которым будут передаваться данные этого ReadableStream. Каждый из них получит одинаковые данные.

Переводит readableStream.locked в состояние true.

readableStream.values([options])
Добавлено в: v16.5.0
  • options <Object>
    • preventCancel <boolean> Если true, <ReadableStream> не закрывается при досрочном завершении асинхронного итератора. По умолчанию: false.

Создаёт и возвращает асинхронный итератор, который можно использовать для чтения данных этого ReadableStream.

Переводит readableStream.locked в состояние true, пока активен асинхронный итератор.

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()); copy
Асинхронная итерация

Объект <ReadableStream> поддерживает протокол асинхронного итератора с использованием синтаксиса for await.

import { Buffer } from 'node:buffer';

const stream = new ReadableStream(getSomeSource());

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

Асинхронный итератор будет читать данные из <ReadableStream>, пока поток не завершится.

По умолчанию, если асинхронный итератор завершает работу досрочно (например, с помощью break, return или throw), <ReadableStream> будет закрыт. Чтобы предотвратить автоматическое закрытие <ReadableStream>, используйте метод readableStream.values() для получения асинхронного итератора и установите для параметра preventCancel значение true.

<ReadableStream> не должен быть заблокирован (то есть у него не должно быть уже существующего активного считывателя). Во время асинхронной итерации <ReadableStream> будет заблокирован.

Передача с помощью postMessage()

Экземпляр <ReadableStream> можно передать с помощью <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]); copy

ReadableStream.from(iterable)

Добавлено в: v20.6.0
  • iterable <Iterable> Объект, реализующий протокол итерируемых объектов Symbol.asyncIterator или Symbol.iterator.

Вспомогательный метод, создающий новый <ReadableStream> из итерируемого объекта.

Модули JavaScript
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'
CommonJS
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'
})();

Чтобы передать полученный <ReadableStream> в <WritableStream>, итерируемый объект <Iterable> должен выдавать последовательность объектов <Buffer>, <TypedArray> или <DataView>.

Модули JavaScript
import { ReadableStream } from 'node:stream/web';
import { Buffer } from 'node:buffer';

async function* asyncIterableGenerator() {
  yield Buffer.from('a');
  yield Buffer.from('b');
  yield Buffer.from('c');
}

const stream = ReadableStream.from(asyncIterableGenerator());

await stream.pipeTo(createWritableStreamSomehow());
CommonJS
const { ReadableStream } = require('node:stream/web');
const { Buffer } = require('node:buffer');

async function* asyncIterableGenerator() {
  yield Buffer.from('a');
  yield Buffer.from('b');
  yield Buffer.from('c');
}

const stream = ReadableStream.from(asyncIterableGenerator());

(async () => {
  await stream.pipeTo(createWritableStreamSomehow());
})();

Класс: ReadableStreamDefaultReader

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

По умолчанию вызов readableStream.getReader() без аргументов возвращает экземпляр ReadableStreamDefaultReader. Считыватель по умолчанию рассматривает передаваемые через поток фрагменты данных как непрозрачные значения, благодаря чему <ReadableStream> может работать практически с любыми значениями JavaScript.

new ReadableStreamDefaultReader(stream)
Добавлено в: v16.5.0
  • stream <ReadableStream>

Создаёт новый <ReadableStreamDefaultReader>, блокирующий указанный <ReadableStream>.

readableStreamDefaultReader.cancel([reason])
Добавлено в: v16.5.0
  • reason <any>
  • Возвращает: промис, выполненный с undefined.

Отменяет <ReadableStream> и возвращает промис, который выполняется после отмены базового потока.

readableStreamDefaultReader.closed
Добавлено в: v16.5.0
  • Тип: <Promise> Выполняется с undefined, когда связанный <ReadableStream> закрывается, или отклоняется, если в потоке возникает ошибка либо блокировка считывателя снимается до завершения закрытия потока.
readableStreamDefaultReader.read()
Добавлено в: v16.5.0
  • Возвращает: промис, выполненный с объектом:
    • value <any>
    • done <boolean>

Запрашивает следующий фрагмент данных из базового <ReadableStream> и возвращает промис, который выполняется с этими данными, когда они становятся доступны.

readableStreamDefaultReader.releaseLock()
Добавлено в: v16.5.0

Снимает блокировку, установленную этим считывателем на базовый <ReadableStream>.

Класс: ReadableStreamBYOBReader

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

ReadableStreamBYOBReader — это альтернативный потребитель потоков <ReadableStream>, ориентированных на байты (созданных с underlyingSource.type, равным 'bytes', при создании ReadableStream).

Сокращение BYOB означает «используйте собственный буфер». Этот шаблон позволяет эффективнее считывать данные, ориентированные на байты, избегая лишнего копирования.

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()); copy
new ReadableStreamBYOBReader(stream)
Добавлено в: v16.5.0
  • stream <ReadableStream>

Создаёт новый ReadableStreamBYOBReader, блокирующий указанный <ReadableStream>.

readableStreamBYOBReader.cancel([reason])
Добавлено в: v16.5.0
  • reason <any>
  • Возвращает: промис, выполненный с undefined.

Отменяет <ReadableStream> и возвращает промис, который выполняется после отмены базового потока.

readableStreamBYOBReader.closed
Добавлено в: v16.5.0
  • Тип: <Promise> Выполняется с undefined, когда связанный <ReadableStream> закрывается, или отклоняется, если в потоке возникает ошибка либо блокировка считывателя снимается до завершения закрытия потока.
readableStreamBYOBReader.read(view[, options])
История
Версия Изменения
v21.7.0, v20.17.0

Добавлен параметр min.
v16.5.0

Добавлено в: v16.5.0
  • view <Buffer> | <TypedArray> | <DataView>
  • options <Object>
    • min <number> Если задано, возвращённый промис будет выполнен, только когда станет доступно указанное количество элементов min. Если значение не задано, промис выполняется, когда доступен хотя бы один элемент.
  • Возвращает: промис, выполненный с объектом:
    • value <TypedArray> | <DataView>
    • done <boolean>

Запрашивает следующий фрагмент данных из базового <ReadableStream> и возвращает промис, который выполняется с этими данными, когда они становятся доступны.

Не передавайте в этот метод экземпляр объекта <Buffer> из пула. Буферизованные объекты Buffer создаются с помощью Buffer.allocUnsafe() или Buffer.from() либо часто возвращаются различными обратными вызовами модуля node:fs. В таких объектах Buffer используется общий базовый объект <ArrayBuffer>, содержащий данные всех буферизованных экземпляров Buffer. Когда в readableStreamBYOBReader.read() передаётся Buffer, <TypedArray> или <DataView>, базовый буфер представления ArrayBuffer отсоединяется, что делает недействительными все существующие представления этого буфера ArrayBuffer. Это может иметь катастрофические последствия для приложения.

readableStreamBYOBReader.releaseLock()
Добавлено в: v16.5.0

Снимает блокировку, установленную этим считывателем на базовый <ReadableStream>.

Класс: ReadableStreamDefaultController

Добавлено в: v16.5.0

У каждого <ReadableStream> есть контроллер, отвечающий за внутреннее состояние и управление очередью потока. ReadableStreamDefaultController — это реализация контроллера по умолчанию для ReadableStream, не ориентированных на байты.

readableStreamDefaultController.close()
Добавлено в: v16.5.0

Закрывает <ReadableStream>, с которым связан этот контроллер.

readableStreamDefaultController.desiredSize
Добавлено в: v16.5.0
  • Тип: <number>

Возвращает количество данных, необходимое для заполнения очереди <ReadableStream>.

readableStreamDefaultController.enqueue([chunk])
Добавлено в: v16.5.0
  • chunk <any>

Добавляет новый фрагмент данных в очередь <ReadableStream>.

readableStreamDefaultController.error([error])
Добавлено в: v16.5.0
  • error <any>

Сигнализирует об ошибке, из-за которой в <ReadableStream> возникает ошибка и поток закрывается.

Класс: ReadableByteStreamController

История
Версия Изменения
v18.10.0

Добавлена поддержка обработки запроса BYOB pull от разблокированного считывателя.
v16.5.0

Добавлено в: v16.5.0

У каждого <ReadableStream> есть контроллер, отвечающий за внутреннее состояние и управление очередью потока. ReadableByteStreamController предназначен для потоков ReadableStream, ориентированных на байты.

readableByteStreamController.byobRequest
Добавлено в: v16.5.0
  • Тип: <ReadableStreamBYOBRequest>
readableByteStreamController.close()
Добавлено в: v16.5.0

Закрывает <ReadableStream>, с которым связан этот контроллер.

readableByteStreamController.desiredSize
Добавлено в: v16.5.0
  • Тип: <number>

Возвращает количество данных, необходимое для заполнения очереди <ReadableStream>.

readableByteStreamController.enqueue(chunk)
Добавлено в: v16.5.0
  • chunk <Buffer> | <TypedArray> | <DataView>

Добавляет новый фрагмент данных в очередь <ReadableStream>.

readableByteStreamController.error([error])
Добавлено в: v16.5.0
  • error <any>

Сигнализирует об ошибке, из-за которой в <ReadableStream> возникает ошибка и поток закрывается.

Класс: ReadableStreamBYOBRequest

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

При использовании ReadableByteStreamController в потоках, ориентированных на байты, и при использовании ReadableStreamBYOBReader свойство readableByteStreamController.byobRequest предоставляет доступ к экземпляру ReadableStreamBYOBRequest, представляющему текущий запрос на чтение. Этот объект используется для доступа к ArrayBuffer/TypedArray, предоставленному для заполнения запроса на чтение, и содержит методы для уведомления о предоставлении данных.

readableStreamBYOBRequest.respond(bytesWritten)
Добавлено в: v16.5.0
  • bytesWritten <number>

Указывает, что в readableStreamBYOBRequest.view записано bytesWritten байтов.

readableStreamBYOBRequest.respondWithNewView(view)
Добавлено в: v16.5.0
  • view <Buffer> | <TypedArray> | <DataView>

Указывает, что запрос выполнен: байты записаны в новое представление Buffer, TypedArray или DataView.

readableStreamBYOBRequest.view
Добавлено в: v16.5.0
  • Тип: <Buffer> | <TypedArray> | <DataView>

Класс: WritableStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

WritableStream — это приемник, в который передаются данные потока.

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

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

await stream.getWriter().write('Hello World'); copy
new WritableStream([underlyingSink[, strategy]])
Добавлено в: v16.5.0
  • underlyingSink <Object>
    • start <Function> Пользовательская функция, вызываемая сразу после создания WritableStream.
      • controller <WritableStreamDefaultController>
      • Возвращает: undefined или промис, выполненный с undefined.
    • write <Function> Пользовательская функция, вызываемая при записи фрагмента данных в WritableStream.
      • chunk <any>
      • controller <WritableStreamDefaultController>
      • Возвращает: промис, выполненный с undefined.
    • close <Function> Пользовательская функция, вызываемая при закрытии WritableStream.
      • Возвращает: промис, выполненный с undefined.
    • abort <Function> Пользовательская функция, вызываемая для аварийного закрытия WritableStream.
      • reason <any>
      • Возвращает: промис, выполненный с undefined.
    • type <any> Параметр type зарезервирован для будущего использования и должен иметь значение undefined.
  • strategy <Object>
    • highWaterMark <number> Максимальный размер внутренней очереди до применения обратного давления.
    • size <Function> Пользовательская функция для определения размера каждого фрагмента данных.
      • chunk <any>
      • Возвращает: <number>
writableStream.abort([reason])
Добавлено в: v16.5.0
  • reason <any>
  • Возвращает: промис, выполненный с undefined.

Аварийно завершает WritableStream. Все записи в очереди будут отменены, а связанные с ними промисы — отклонены.

writableStream.close()
Добавлено в: v16.5.0
  • Возвращает: промис, выполненный с undefined.

Закрывает WritableStream, когда больше не ожидается новых записей.

writableStream.getWriter()
Добавлено в: v16.5.0
  • Возвращает: <WritableStreamDefaultWriter>

Создает и возвращает новый экземпляр средства записи, который можно использовать для записи данных в WritableStream.

writableStream.locked
Добавлено в: v16.5.0
  • Тип: <boolean>

По умолчанию свойство writableStream.locked имеет значение false. Оно переключается на true, пока с этим WritableStream связан активный объект средства записи.

Передача с помощью postMessage()

Экземпляр <WritableStream> можно передать с помощью <MessagePort>.

const stream = new WritableStream(getWritableSinkSomehow());

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

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

port2.postMessage(stream, [stream]); copy

Класс: WritableStreamDefaultWriter

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0
new WritableStreamDefaultWriter(stream)
Добавлено в: v16.5.0
  • stream <WritableStream>

Создает новый WritableStreamDefaultWriter, заблокированный для указанного WritableStream.

writableStreamDefaultWriter.abort([reason])
Добавлено в: v16.5.0
  • reason <any>
  • Возвращает: промис, выполненный с undefined.

Аварийно завершает WritableStream. Все записи в очереди будут отменены, а связанные с ними промисы — отклонены.

writableStreamDefaultWriter.close()
Добавлено в: v16.5.0
  • Возвращает: промис, выполненный с undefined.

Закрывает WritableStream, когда больше не ожидается новых записей.

writableStreamDefaultWriter.closed
Добавлено в: v16.5.0
  • Тип: <Promise> Выполняется с undefined, когда связанный <WritableStream> закрыт; отклоняется, если в потоке возникает ошибка или блокировка средства записи снята до завершения закрытия потока.
writableStreamDefaultWriter.desiredSize
Добавлено в: v16.5.0
  • Тип: <number>

Объем данных, необходимый для заполнения очереди <WritableStream>.

writableStreamDefaultWriter.ready
Добавлено в: v16.5.0
  • Тип: <Promise> Выполняется с undefined, когда средство записи готово к использованию.
writableStreamDefaultWriter.releaseLock()
Добавлено в: v16.5.0

Снимает блокировку этого средства записи с базового <ReadableStream>.

writableStreamDefaultWriter.write([chunk])
Добавлено в: v16.5.0
  • chunk <any>
  • Возвращает: промис, выполненный с undefined.

Добавляет новый фрагмент данных в очередь <WritableStream>.

Класс: WritableStreamDefaultController

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

WritableStreamDefaultController управляет внутренним состоянием <WritableStream>.

writableStreamDefaultController.error([error])
Добавлено в: v16.5.0
  • error <any>

Вызывается пользовательским кодом для оповещения об ошибке при обработке данных WritableStream. При вызове <WritableStream> прерывается, а ожидающие записи отменяются.

writableStreamDefaultController.signal
  • Тип: <AbortSignal> AbortSignal, который можно использовать для отмены ожидающих операций записи или закрытия при прерывании <WritableStream>.

Класс: TransformStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

TransformStream состоит из <ReadableStream> и <WritableStream>, соединенных таким образом, что данные, записанные в WritableStream, принимаются и, возможно, преобразуются, прежде чем попасть в очередь 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(),
]); copy
new TransformStream([transformer[, writableStrategy[, readableStrategy]]])
Добавлено в: v16.5.0
  • transformer <Object>
    • start <Function> Пользовательская функция, вызываемая сразу после создания TransformStream.
      • controller <TransformStreamDefaultController>
      • Возвращает: undefined или промис, выполненный с undefined
    • transform <Function> Пользовательская функция, которая получает и, возможно, изменяет фрагмент данных, записанный в transformStream.writable, прежде чем передать его в transformStream.readable.
      • chunk <any>
      • controller <TransformStreamDefaultController>
      • Возвращает: промис, выполненный с undefined.
    • flush <Function> Пользовательская функция, вызываемая непосредственно перед закрытием записываемой стороны TransformStream, чтобы обозначить конец процесса преобразования.
      • controller <TransformStreamDefaultController>
      • Возвращает: промис, выполненный с undefined.
    • readableType <any> Параметр readableType зарезервирован для будущего использования и должен иметь значение undefined.
    • writableType <any> Параметр writableType зарезервирован для будущего использования и должен иметь значение undefined.
  • writableStrategy <Object>
    • highWaterMark <number> Максимальный размер внутренней очереди до применения обратного давления.
    • size <Function> Пользовательская функция для определения размера каждого фрагмента данных.
      • chunk <any>
      • Возвращает: <number>
  • readableStrategy <Object>
    • highWaterMark <number> Максимальный размер внутренней очереди до применения обратного давления.
    • size <Function> Пользовательская функция для определения размера каждого фрагмента данных.
      • chunk <any>
      • Возвращает: <number>
transformStream.readable
Добавлено в: v16.5.0
  • Тип: <ReadableStream>
transformStream.writable
Добавлено в: v16.5.0
  • Тип: <WritableStream>
Передача с помощью postMessage()

Экземпляр <TransformStream> можно передать с помощью <MessagePort>.

const stream = new TransformStream();

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

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

port2.postMessage(stream, [stream]); copy

Класс: TransformStreamDefaultController

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0

TransformStreamDefaultController управляет внутренним состоянием TransformStream.

transformStreamDefaultController.desiredSize
Добавлено в: v16.5.0
  • Тип: <number>

Объем данных, необходимый для заполнения очереди читаемой стороны.

transformStreamDefaultController.enqueue([chunk])
Добавлено в: v16.5.0
  • chunk <any>

Добавляет фрагмент данных в очередь читаемой стороны.

transformStreamDefaultController.error([reason])
Добавлено в: v16.5.0
  • reason <any>

Оповещает читаемую и записываемую стороны об ошибке при обработке преобразуемых данных, в результате чего обе стороны аварийно закрываются.

transformStreamDefaultController.terminate()
Добавлено в: v16.5.0

Закрывает читаемую сторону потока и вызывает аварийное закрытие записываемой стороны с ошибкой.

Класс: ByteLengthQueuingStrategy

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0
new ByteLengthQueuingStrategy(init)
Добавлено в: v16.5.0
  • init <Object>
    • highWaterMark <number>
byteLengthQueuingStrategy.highWaterMark
Добавлено в: v16.5.0
  • Тип: <number>
byteLengthQueuingStrategy.size
Добавлено в: v16.5.0
  • Тип: <Function>
    • chunk <any>
    • Возвращает: <number>

Класс: CountQueuingStrategy

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.5.0

Добавлено в: v16.5.0
new CountQueuingStrategy(init)
Добавлено в: v16.5.0
  • init <Object>
    • highWaterMark <number>
countQueuingStrategy.highWaterMark
Добавлено в: v16.5.0
  • Тип: <number>
countQueuingStrategy.size
Добавлено в: v16.5.0
  • Тип: <Function>
    • chunk <any>
    • Возвращает: <number>

Класс: TextEncoderStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.6.0

Добавлено в: v16.6.0
new TextEncoderStream()
Добавлено в: v16.6.0

Создает новый экземпляр TextEncoderStream.

textEncoderStream.encoding
Добавлено в: v16.6.0
  • Тип: <string>

Кодировка, поддерживаемая экземпляром TextEncoderStream.

textEncoderStream.readable
Добавлено в: v16.6.0
  • Тип: <ReadableStream>
textEncoderStream.writable
Добавлено в: v16.6.0
  • Тип: <WritableStream>

Класс: TextDecoderStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v16.6.0

Добавлено в: v16.6.0
new TextDecoderStream([encoding[, options]])
Добавлено в: v16.6.0
  • encoding <string> Определяет encoding, поддерживаемую этим экземпляром TextDecoder. По умолчанию: 'utf-8'.
  • options <Object>
    • fatal <boolean> true, если ошибки декодирования считаются фатальными.
    • ignoreBOM <boolean> Если задано значение true, TextDecoderStream включит метку порядка байтов в результат декодирования. Если задано значение false, метка порядка байтов будет удалена из выходных данных. Этот параметр используется только если encoding имеет значение 'utf-8', 'utf-16be' или 'utf-16le'. По умолчанию: false.

Создает новый экземпляр TextDecoderStream.

textDecoderStream.encoding
Добавлено в: v16.6.0
  • Тип: <string>

Кодировка, поддерживаемая экземпляром TextDecoderStream.

textDecoderStream.fatal
Добавлено в: v16.6.0
  • Тип: <boolean>

Значение будет true, если ошибки декодирования приводят к выбрасыванию TypeError.

textDecoderStream.ignoreBOM
Добавлено в: v16.6.0
  • Тип: <boolean>

Значение будет true, если результат декодирования будет содержать метку порядка байтов.

textDecoderStream.readable
Добавлено в: v16.6.0
  • Тип: <ReadableStream>
textDecoderStream.writable
Добавлено в: v16.6.0
  • Тип: <WritableStream>

Class: CompressionStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v17.0.0

Добавлено в: v17.0.0
new CompressionStream(format)
История
Версия Изменения
v24.7.0

Теперь format принимает значение brotli.
v21.2.0, v20.12.0

Теперь format принимает значение deflate-raw.
v17.0.0

Добавлено в: v17.0.0
  • format <string> Одно из значений: 'deflate', 'deflate-raw', 'gzip' или 'brotli'.
compressionStream.readable
Добавлено в: v17.0.0
  • Тип: <ReadableStream>
compressionStream.writable
Добавлено в: v17.0.0
  • Тип: <WritableStream>

Class: DecompressionStream

История
Версия Изменения
v18.0.0

Теперь этот класс доступен в глобальном объекте.
v17.0.0

Добавлено в: v17.0.0
new DecompressionStream(format)
История
Версия Изменения
v24.7.0

Теперь format принимает значение brotli.
v21.2.0, v20.12.0

Теперь format принимает значение deflate-raw.
v17.0.0

Добавлено в: v17.0.0
  • format <string> Одно из значений: 'deflate', 'deflate-raw', 'gzip' или 'brotli'.
decompressionStream.readable
Добавлено в: v17.0.0
  • Тип: <ReadableStream>
decompressionStream.writable
Добавлено в: v17.0.0
  • Тип: <WritableStream>

Вспомогательные функции для чтения потоков

Добавлено в: v16.7.0

Вспомогательные функции для чтения потоков предоставляют стандартные способы чтения потоков.

Они доступны с помощью:

Модули JavaScript
import {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} from 'node:stream/consumers';
CommonJS
const {
  arrayBuffer,
  blob,
  buffer,
  json,
  text,
} = require('node:stream/consumers');
streamConsumers.arrayBuffer(stream)
Добавлено в: v16.7.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с ArrayBuffer, содержащим всё содержимое потока.
Модули JavaScript
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
CommonJS
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)
Добавлено в: v16.7.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с объектом <Blob>, содержащим всё содержимое потока.
Модули JavaScript
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
CommonJS
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)
Добавлено в: v16.7.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с объектом <Buffer>, содержащим всё содержимое потока.
Модули JavaScript
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
CommonJS
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.bytes(stream)
Добавлено в: v24.14.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с объектом <Uint8Array>, содержащим всё содержимое потока.
Модули JavaScript
import { bytes } 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 bytes(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27
CommonJS
const { bytes } = 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);
bytes(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});
streamConsumers.json(stream)
Добавлено в: v16.7.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с содержимым потока, разобранным как строка в кодировке UTF-8, которая затем передаётся в JSON.parse().
Модули JavaScript
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
CommonJS
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)
Добавлено в: v16.7.0
  • stream <ReadableStream> | <stream.Readable> | <AsyncIterator>
  • Возвращает: <Promise> Выполняется с содержимым потока, разобранным как строка в кодировке UTF-8.
Модули JavaScript
import { text } from 'node:stream/consumers';
import { Readable } from 'node:stream';

const readable = Readable.from('Hello world from consumers!');
const data = await text(readable);
console.log(`from readable: ${data.length}`);
// Prints: from readable: 27
CommonJS
const { text } = require('node:stream/consumers');
const { Readable } = require('node:stream');

const readable = Readable.from('Hello world from consumers!');
text(readable).then((data) => {
  console.log(`from readable: ${data.length}`);
  // Prints: from readable: 27
});

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/webstreams.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API