ReadableStream

Интерфейс ReadableStream из API потоков Streams API представляет собой поток для чтения байтовых данных. API Fetch API предоставляет конкретный экземпляр ReadableStream через свойство body объекта Response.

ReadableStream — это передаваемый объект.

ReadableStream()

Создаёт и возвращает объект потока для чтения из предоставленных обработчиков.

ReadableStream.locked Только для чтения

Возвращает булевое значение, указывающее, заблокирован ли поток для чтения.

ReadableStream.from() Экспериментальная

Возвращает ReadableStream из предоставленного итерируемого или асинхронного итерируемого объекта, например, массива, множества, асинхронного генератора и так далее.

ReadableStream.cancel()

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

ReadableStream.getReader()

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

ReadableStream.pipeThrough()

Предоставляет цепкий способ передачи текущего потока через поток преобразования или любую другую пару потоков для записи/чтения.

ReadableStream.pipeTo()

Передает текущий поток ReadableStream заданному WritableStream и возвращает Promise, который выполняется при успешном завершении процесса передачи, или отклоняется, если возникли какие-либо ошибки.

ReadableStream.tee()

Метод tee разветвляет этот поток для чтения, возвращая массив из двух элементов, содержащий две полученные ветви как новые экземпляры ReadableStream. Каждый из этих потоков получает те же входные данные.

ReadableStream реализует протокол асинхронной итерируемости. Это позволяет выполнить асинхронную итерацию по частям в потоке с помощью синтаксиса for await...of:

const stream = new ReadableStream(getSomeSource());

for await (const chunk of stream) {
  // Do something with each 'chunk'
}

Асинхронный итератор потребляет поток, пока не закончится данные или не произойдёт другое завершение. Цикл также может завершиться досрочно из-за break, throw, или return инструкции.

Во время итерации поток блокируется, чтобы предотвратить получение читателя другими потребителями (попытка итерации по уже заблокированному потоку вызовет TypeError). Эта блокировка снимается при выходе из цикла.

По умолчанию выход из цикла также отменяет поток, так что он больше не может использоваться. Чтобы продолжить использование потока после выхода из цикла, передайте { preventCancel: true } в метод values() потока:

for await (const chunk of stream.values({ preventCancel: true })) {
  // Do something with 'chunk'
  break;
}
// Acquire a reader for the stream and continue reading ...

В следующем примере создаётся искусственный Response для потоковой передачи фрагментов HTML, полученных из другого ресурса в браузер.

Он демонстрирует использование ReadableStream в сочетании с Uint8Array.

fetch("https://www.example.org")
  .then((response) => response.body)
  .then((rb) => {
    const reader = rb.getReader();

    return new ReadableStream({
      start(controller) {
        // The following function handles each data chunk
        function push() {
          // "done" is a Boolean and value a "Uint8Array"
          reader.read().then(({ done, value }) => {
            // If there is no more data to read
            if (done) {
              console.log("done", done);
              controller.close();
              return;
            }
            // Get the data and send it to the browser via the controller
            controller.enqueue(value);
            // Check chunks by logging to the console
            console.log(done, value);
            push();
          });
        }

        push();
      },
    });
  })
  .then((stream) =>
    // Respond with our stream
    new Response(stream, { headers: { "Content-Type": "text/html" } }).text(),
  )
  .then((result) => {
    // Do things with result
    console.log(result);
  });

Статический метод from() может преобразовать итератор, например, Array или Map, или (асинхронный) итератор в поток для чтения:

const myReadableStream = ReadableStream.from(iteratorOrAsyncIterator);

В браузерах, не поддерживающих метод from(), можно вместо этого создать собственный настраиваемый поток для чтения для достижения того же результата:

function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();

      if (value) {
        controller.enqueue(value);
      }
      if (done) {
        controller.close();
      }
    },
  });
}

В этом примере показано, как обработать ответ fetch() с помощью цикла for await...of для итерации по поступающим частям.

const response = await fetch("https://www.example.org");
let total = 0;

// Iterate response.body (a ReadableStream) asynchronously
for await (const chunk of response.body) {
  // Do something with each chunk
  // Here we just accumulate the size of the response.
  total += chunk.length;
}

// Do something with the total
console.log(total);

• Концепции API потоков
• Использование потоков для чтения
• Использование потоков для чтения байтов
• Визуализатор потоков WHATWG, для базовой визуализации потоков для чтения, записи и преобразования.
• Web-streams-polyfill или sd-streams - полифилы