Streams API
===========

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

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

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

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

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

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

![](/ru/docs/Web/API/Streams_API/concept.png)

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

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

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

Вы также можете записывать данные в потоки используя `WritableStream` (en-US).

**Примечание:** вы можете найти больше информации о теории и практике использования потоков в следующих статьях — Концепты API потоков (en-US) , Использование потоков на чтение (en-US), и Использование потоков на запись (en-US).

Интерфейсы
----------

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

`ReadableStream` (en-US)

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

`ReadableStreamDefaultReader` (en-US)

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

`ReadableStreamDefaultController` (en-US)

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

### Writable streams

`WritableStream` (en-US)

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

`WritableStreamDefaultWriter` (en-US)

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

`WritableStreamDefaultController` (en-US)

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

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

`ByteLengthQueuingStrategy` (en-US)

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

`CountQueuingStrategy` (en-US)

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

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

`Request`

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

`Body`

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

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

**Предупреждение:** **Важно**: данные интерфейсы пока не реализованы, и были подняты вопросы о том, находятся ли детали спецификации в достаточно законченном состоянии для их реализации. Со временем это может измениться

`ReadableStreamBYOBReader` (en-US)

Represents a BYOB ("bring your own buffer") reader that can be used to read stream data supplied by the developer (e.g. a custom `ReadableStream()` (en-US) constructor).

`ReadableByteStreamController` (en-US)

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

`ReadableStreamBYOBRequest` (en-US)

Represents a pull into request in a `ReadableByteStreamController` (en-US).

Примеры
-------

Мы создали папку с примерами, которые идут вместе с документацией к 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 how `pipeThrough()` (en-US) 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.
Спецификации
------------

| Specification |
| --- |
| Streams Living Standard |

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

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

### api.ReadableStream

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.WritableStream

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

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

* Streams API концепт (en-US)
* Использование потоков чтения (en-US)
* Использование потоков записи (en-US)