WritableStream

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

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

WritableStream()

Создаёт новый объект WritableStream.

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

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

WritableStream.abort()

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

WritableStream.close()

Закрывает поток.

WritableStream.getWriter()

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

Следующий пример иллюстрирует несколько особенностей данного интерфейса. Он демонстрирует создание WritableStream с пользовательским стоком и стратегией очереди, предоставляемой API. Затем он вызывает функцию, называемую sendMessage(), передавая ей недавно созданный поток и строку. Внутри этой функции он вызывает метод потока getWriter(), который возвращает экземпляр WritableStreamDefaultWriter. Вызов forEach() используется для записи каждого фрагмента строки в поток. Наконец, write() и close() возвращают обещания, которые обрабатываются для обработки успешного или неудачного выполнения фрагментов и потоков.

const list = document.querySelector("ul");

function sendMessage(message, writableStream) {
  // defaultWriter is of type WritableStreamDefaultWriter
  const defaultWriter = writableStream.getWriter();
  const encoder = new TextEncoder();
  const encoded = encoder.encode(message);
  encoded.forEach((chunk) => {
    defaultWriter.ready
      .then(() => defaultWriter.write(chunk))
      .then(() => {
        console.log("Chunk written to sink.");
      })
      .catch((err) => {
        console.log("Chunk error:", err);
      });
  });
  // Call ready again to ensure that all chunks are written
  //   before closing the writer.
  defaultWriter.ready
    .then(() => {
      defaultWriter.close();
    })
    .then(() => {
      console.log("All chunks written");
    })
    .catch((err) => {
      console.log("Stream error:", err);
    });
}

const decoder = new TextDecoder("utf-8");
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });
let result = "";
const writableStream = new WritableStream(
  {
    // Implement the sink
    write(chunk) {
      return new Promise((resolve, reject) => {
        const buffer = new ArrayBuffer(1);
        const view = new Uint8Array(buffer);
        view[0] = chunk;
        const decoded = decoder.decode(view, { stream: true });
        const listItem = document.createElement("li");
        listItem.textContent = `Chunk decoded: ${decoded}`;
        list.appendChild(listItem);
        result += decoded;
        resolve();
      });
    },
    close() {
      const listItem = document.createElement("li");
      listItem.textContent = `[MESSAGE RECEIVED] ${result}`;
      list.appendChild(listItem);
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);

sendMessage("Hello, world.", writableStream);

Полный код можно найти в нашем примере с простым писателем.

Из-за того, как обратная связь поддерживается в API, её реализация в коде может быть не очевидна. Чтобы увидеть, как реализована обратная связь, обратите внимание на три вещи:

• Свойство highWaterMark, которое устанавливается при создании стратегии подсчёта с использованием new CountQueuingStrategy, задаёт максимальный объём данных, который экземпляр WritableStream будет обрабатывать в одной операции write(). В данном примере это максимальный объём данных, который может быть отправлен в defaultWriter.write(), в функции sendMessage.
• Свойство defaultWriter.ready возвращает обещание, которое разрешается, когда сток (первое свойство конструктора WritableStream ) завершает запись данных. Источник данных может либо записать больше данных с помощью defaultWriter.write(), либо вызвать defaultWriter.close(), как показано в примере выше. Вызов close() слишком рано может помешать записи данных. Именно поэтому в примере вызов defaultWriter.ready осуществляется дважды.
• Promise, возвращаемый методом write() стока, сообщает WritableStream и его писателю, когда разрешить defaultWriter.ready.

• Визуализатор потоков WHATWG, для базовой визуализации читаемых, записываемых и преобразующих потоков.