ReadableStreamBYOBReader

Интерфейс ReadableStreamBYOBReader из API потоков определяет читатель для ReadableStream, который поддерживает чтение без копирования из базового источника байтов. Он используется для эффективного копирования из базовых источников, где данные представляются как последовательность байтов, например, файлы.

Экземпляр этого типа читателя обычно получается путём вызова ReadableStream.getReader() потока, указав mode: "byob" в параметре options. Поток чтения должен иметь базовый источник байтов. Другими словами, он должен быть создан, указав базовый источник с type: "bytes".

Использование такого читателя, запрос read(), когда внутренние очереди потока чтения пустые, приведёт к передаче без копирования из базового источника (обойдя внутренние очереди потока). Если внутренние очереди не пустые, запрос будет удовлетворён из буферизованных данных.

Обратите внимание, что методы и свойства аналогичны методам и свойствам стандартного читателя (ReadableStreamDefaultReader). Метод read() отличается тем, что предоставляет представление, в которое необходимо записать данные.

ReadableStreamBYOBReader()

Создаёт и возвращает экземпляр объекта ReadableStreamBYOBReader.

ReadableStreamBYOBReader.closed Только для чтения

Возвращает Promise, который выполняется при закрытии потока или отклоняется, если поток выбросил ошибку или блокировка читателя была освобождена. Это свойство позволяет писать код, реагирующий на завершение процесса потоковой передачи.

ReadableStreamBYOBReader.cancel()

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

ReadableStreamBYOBReader.read()

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

ReadableStreamBYOBReader.releaseLock()

Освобождает блокировку читателя в потоке.

Пример ниже взят из живых примеров в Использование потоков чтения байтов.

Сначала создайте читатель, вызвав ReadableStream.getReader() на потоке, указав mode: "byob" в параметре options. Поскольку это читатель "Bring Your Own Buffer", нам также нужно создать ArrayBuffer для чтения.

const reader = stream.getReader({ mode: "byob" });
let buffer = new ArrayBuffer(200);

Функция, использующая читателя, показана ниже. Она рекурсивно вызывает метод read() для чтения данных в буфер. Метод принимает Uint8Array массив типа данных, который представляет представление части исходного буфера, которая ещё не была записана. Параметры представления рассчитываются на основе данных, полученных в предыдущих вызовах, которые определяют смещение в исходном буфере.

readStream(reader);

function readStream(reader) {
  let bytesReceived = 0;
  let offset = 0;

  // read() returns a promise that resolves when a value has been received
  reader
    .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
    .then(function processText({ done, value }) {
      // Result objects contain two properties:
      // done  - true if the stream has already given all its data.
      // value - some data. Always undefined when done is true.

      if (done) {
        logConsumer(`readStream() complete. Total bytes: ${bytesReceived}`);
        return;
      }

      buffer = value.buffer;
      offset += value.byteLength;
      bytesReceived += value.byteLength;

      logConsumer(
        `Read ${value.byteLength} (${bytesReceived}) bytes: ${value}`,
      );
      result += value;

      // Read some more, and call this function again
      return reader
        .read(new Uint8Array(buffer, offset, buffer.byteLength - offset))
        .then(processText);
    });
}

Когда больше данных в потоке нет, метод read() разрешается с объектом, в котором свойство done установлено в значение true, и функция возвращается.

Свойство ReadableStreamBYOBReader.closed возвращает промис, который можно использовать для отслеживания закрытия или возникновения ошибки в потоке, или освобождения блокировки читателя.

reader.closed
  .then(() => {
    // Resolved - code to handle stream closing
  })
  .catch(() => {
    // Rejected - code to handle error
  });

Для отмены потока вызовите ReadableStreamBYOBReader.cancel(), необязательно указав причину. Это возвращает промис, который разрешится, когда поток будет отменён. При отмене потока контроллер, в свою очередь, вызовет cancel() на базовом источнике, передав необязательную причину.

Пример кода в Использование потоков чтения байтов вызывает метод cancel при нажатии кнопки, как показано:

button.addEventListener("click", () => {
  reader.cancel("user choice").then(() => console.log("cancel complete"));
});

Потребитель также может вызвать releaseLock() для освобождения блокировки читателя на потоке, но только когда ни один процесс чтения не ожидается:

reader.releaseLock();

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