Streams API (API обработки потоков) позволяет программно получить доступ с помощью JavaScript к полученным по сети потокам данных и обработать их по желанию разработчика.

Концепция и использование

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

Но методы работы с этим и данные никогда прежде не были доступны для JavaScript. Раньше, если мы хотели обработать часть ресурса, нам всё равно пришлось бы загрузить весь файл (будь то видео, текстовый файл и т.п.), мы были бы обязаны скачать файл целиком, дождаться пока он будет приведён к необходимому формату и только потом работать с файлом после его полной загрузки.

С помощью потоков доступных в JavaScript меняется все — вы можете начать обрабатывать данные бит за битом как только данные появляются на стороне клиента, без необходимости генерировать буфер, строку или какой либо объект из потока.

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

Основное использование потоков крутиться вокруг создания ответов доступными в виде потоков. Например, тело ответаBody возвращённого успешнымfetch запросом может быть представлено какReadableStream, и вы можете прочитать его используя ридер полученный методомReadableStream.getReader(), отменить его с помощьюReadableStream.cancel(), и тп.

Более сложные примеры задействуют создание ваших собственных потоков с помощью конструктораReadableStream(), например чтобы обработать данные внутриservice worker.

Вы также можете записывать данные в потоки используяWritableStream.

Интерфейсы

Потоки чтения данных

ReadableStream

Представляет собой считываемый поток данных. Он может быть использован чтобы обработать потоки ответов отFetch API, или созданный разработчиком поток (например произвольныйReadableStream()).

ReadableStreamDefaultReader

Представляет собой считывателя, который может быть использован чтобы считать данные поставляемые из сети (например fetch запрос).

ReadableStreamDefaultController

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

Writable streams

WritableStream

Предоставляет стандартную абстракцию, известную как раковина, для записи потоков по месту назначения. Этот объект идёт вместе со встроенными методами контроля обратного потока и созданием очередей.

WritableStreamDefaultWriter

Представляет запись потока по умолчанию, которая может использоваться для записи фрагментов данных в записываемый поток.

WritableStreamDefaultController

Представляет собой контроллер состоянияWritableStream. При созданииWritableStream, создаётся также соответствующий экземплярWritableStreamDefaultController.

Дополнительные API и операции по работе с потоками

ByteLengthQueuingStrategy

Предоставляет встроенную стратегию длины байт-очереди, которая может быть использована при построении потоков.

CountQueuingStrategy

Предоставляет встроенную стратегию организации очередей подсчёта чанков, которая может использоваться при построении потоков.

Дополнения к другим API

Request

При создании нового объекта типаRequest, вы можете добавитьReadableStream в свойствоbody его словаряRequestInit. Этот объект типаRequest может быть отправлен вfetch(), чтобы начать загрузку потока.

Body

ОтветBody возвращённый успешномуfetch запросу вывешивается по умолчанию какReadableStream, и может иметь получателя прикреплённого к нему и тп.

Интерфейсы в дополнение к ByteStream

ReadableStreamBYOBReader

Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g. a customReadableStream() constructor).

ReadableByteStreamController

Контроллер позволяющий обрабатывать состояниеReadableStream и внутреннюю очередь. Байтовые контроллеры для байтовых потоков.

ReadableStreamBYOBRequest

Represents a pull into request in aReadableByteStreamController.

Примеры

Мы создали папку с примерами, которые идут вместе с документацией к API потоков — смотритеmdn/dom-examples/streams. Можно найти такие примеры как:

• Simple stream pump: Этот пример показывает как использовать поток чтения данных и передавать его данные в другой поток.
• Сделать черно-белый PNG: Пример показывает конвертацию потока данных PNG изображения в черно-белый формат.
• Простой произвольный поток: В этом примере показано, как использовать пользовательский поток для создания случайных строк, помещать их в очередь как блоки, а затем считывать их обратно.
• Simple tee example: Этот пример расширяет первый пример, показывая как поток может быть связан, и оба результирующих потока будут прочитаны независимо.
• Simple writer: This example shows how to to write to a writable stream, then decode the stream and write the contents to the UI.
• Unpack chunks of a PNG: This example shows howpipeThrough() can be used to transform a ReadableStream into a stream of other data types by transforming a data of a PNG file into a stream of PNG chunks.

Примеры от других разработчиков:

• Progress Indicators with Streams, Service Workers, & Fetch.

Спецификации

Совместимость с браузерами

Поток записи данных

api.ReadableStream

api.WritableStream

Смотрите также

• Streams API концепт
• Использование потоков чтения
• Использование потоков записи