Spec-Zone.ru › Node.js 22 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 означает «предоставьте собственный буфер» (bring your own buffer). Этот шаблон позволяет эффективнее считывать данные, ориентированные на байты, избегая лишнего копирования.

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

Добавлен параметр 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 от считывателя, блокировка которого снята.
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>

Класс: CompressionStream

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

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

Добавлено в: v17.0.0
new CompressionStream(format)
История
Версия Изменения
v22.20.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>

Класс: DecompressionStream

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

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

Добавлено в: v17.0.0
new DecompressionStream(format)
История
Версия Изменения
v22.20.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.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-v22.x/docs/api/webstreams.html

Spec-Zone.ru

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