API потоков

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

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

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

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

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

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

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

Вы также можете записывать данные в потоки с помощью WritableStream.

ReadableStream

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

ReadableStreamDefaultReader

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

ReadableStreamDefaultController

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

WritableStream

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

WritableStreamDefaultWriter

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

WritableStreamDefaultController

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

TransformStream

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

TransformStreamDefaultController

Предоставляет методы для управления ReadableStream и WritableStream, связанными с потоком преобразования.

ByteLengthQueuingStrategy

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

CountQueuingStrategy

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

Request

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

Response.body

Тело ответа, возвращённое успешным запросом fetch, по умолчанию представлено как ReadableStream и к нему можно подключить читатель и т. д.

ReadableStreamBYOBReader

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

ReadableByteStreamController

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

ReadableStreamBYOBRequest

Представляет запрос подтягивания в ReadableByteStreamController.

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

• Простой насос для потоков: Этот пример показывает, как потреблять ReadableStream и передавать его данные другому.
• Преобразование PNG в оттенки серого: Этот пример показывает, как ReadableStream PNG можно преобразовать в оттенки серого.
• Простой случайный поток: Этот пример показывает, как использовать пользовательский поток для генерации случайных строк, их вставки в очередь как фрагменты и их последующее считывание.
• Простой пример tee: Этот пример расширяет пример Простого случайного потока, демонстрируя, как поток можно разделить и прочитать оба результирующих потока независимо.
• Простой записывающий объект: Этот пример показывает, как записывать в поток для записи, затем декодировать поток и записывать содержимое на пользовательский интерфейс.
• Распаковка фрагментов PNG: Этот пример показывает, как pipeThrough() может использоваться для преобразования ReadableStream в поток других типов данных путём преобразования данных файла PNG в поток фрагментов PNG.

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

• Индикаторы прогресса с потоками, service worker и Fetch.

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