WritableStream

A interface WritableStream faz parte da Streams API do Azion Runtime. Ela grava um stream de dados em um destino, chamado sink, um chunk de cada vez. Ela enfileira os chunks e aplica backpressure, para que o sink receba os dados no ritmo que consegue processar. Para mais informações, consulte WritableStream na MDN Web Docs.

Em uma function, um WritableStream produz a saída chunk a chunk, então um corpo de resposta grande ou gerado nunca fica inteiro em memória. Ele é o lado writable de um TransformStream, que reescreve ou filtra um payload enquanto ele passa pela function. Ele também é o destino de pipeTo() em um ReadableStream: o backpressure desacelera o readable stream até o ritmo em que o sink consome os dados.

Construtor

O construtor WritableStream() cria e retorna um objeto writable stream a partir de um sink e de uma estratégia de enfileiramento opcional:

new WritableStream(sink, strategy)

O objeto sink aceita um método write(chunk), chamado para cada chunk gravado no stream, e um método close(), chamado quando o stream é fechado. O método abort(reason) do sink recebe o motivo passado para stream.abort(). O objeto strategy define o tamanho da fila, como new CountQueuingStrategy({ highWaterMark: 2 }), que conta chunks. A seção Exemplo mostra um stream construído dessa forma.

Propriedades

Propriedade	Tipo	Descrição
`locked`	Boolean	`true` enquanto um writer mantém o stream. É `true` depois de `getWriter()` e `false` depois que o writer chama `releaseLock()`.

Métodos

Método	Descrição
`stream.abort(reason)`	Aborta o stream. O produtor não consegue mais gravar nele, o stream passa imediatamente para um estado de erro e as gravações na fila são descartadas. O método `abort()` do sink recebe `reason`. Chame-o quando ocorrer um erro, para que a saída parcial ou inválida seja descartada.
`stream.close()`	Fecha o stream e executa o método `close()` do sink. Retorna uma promise.
`stream.getWriter()`	Retorna um WritableStreamDefaultWriter e bloqueia o stream para ele. Enquanto o stream está bloqueado, você não consegue obter outro writer até que o primeiro seja liberado.

Exemplo

Este handler constrói um stream cujo sink coleta cada chunk, grava dois chunks por meio de um writer e fecha o writer. Ele retorna o valor de locked, o nome da classe e o desiredSize do writer, e os chunks que o sink recebeu:

JavaScript

01export default {

02 async fetch(request, env, ctx) {

03 const got = [];

04 const stream = new WritableStream(

05 {

06 write(chunk) {

07 got.push(chunk);

08 },

09 },

10 new CountQueuingStrategy({ highWaterMark: 2 }),

11 );

12 const writer = stream.getWriter();

13 const info = {

14 locked: stream.locked,

15 ctor: writer.constructor.name,

16 desiredSize: writer.desiredSize,

17 };

18 await writer.ready;

19 await writer.write('one');

20 await writer.write('two');

21 await writer.close();

22 await writer.closed;

23 return Response.json({ ...info, got });

24 },

25};

A function retorna estes valores. O stream está bloqueado porque o writer o mantém, e desiredSize começa no highWaterMark da estratégia de enfileiramento:

JSON

01{

02 "locked": true,

03 "ctor": "WritableStreamDefaultWriter",

04 "desiredSize": 2,

05 "got": [

06 "one",

07 "two"

08 ]

09}