# 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](https://developer.mozilla.org/en-US/docs/Web/API/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](/pt-br/documentacao/devtools/runtime/api-reference/transform-stream/), que reescreve ou filtra um payload enquanto ele passa pela function. Ele também é o destino de `pipeTo()` em um [ReadableStream](/pt-br/documentacao/devtools/runtime/api-reference/readable-stream/): o backpressure desacelera o readable stream até o ritmo em que o sink consome os dados.

---

## Construtor

O construtor [`WritableStream()`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/WritableStream) cria e retorna um objeto writable stream a partir de um sink e de uma estratégia de enfileiramento opcional:

```javascript
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](#exemplo) mostra um stream construído dessa forma.

---

## Propriedades

| Propriedade                                                                        | Tipo    | Descrição                                                                                                                        |
| ---------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`locked`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/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)`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/abort)   | 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()`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/close)         | Fecha o stream e executa o método `close()` do sink. Retorna uma promise.                                                                                                                                                                                                                |
| [`stream.getWriter()`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream/getWriter) | Retorna um [WritableStreamDefaultWriter](/pt-br/documentacao/devtools/runtime/api-reference/stream-default-writer/) 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
export default {
  async fetch(request, env, ctx) {
    const got = [];
    const stream = new WritableStream(
      {
        write(chunk) {
          got.push(chunk);
        },
      },
      new CountQueuingStrategy({ highWaterMark: 2 }),
    );
    const writer = stream.getWriter();
    const info = {
      locked: stream.locked,
      ctor: writer.constructor.name,
      desiredSize: writer.desiredSize,
    };
    await writer.ready;
    await writer.write('one');
    await writer.write('two');
    await writer.close();
    await writer.closed;
    return Response.json({ ...info, got });
  },
};
```

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
{
 "locked": true,
 "ctor": "WritableStreamDefaultWriter",
 "desiredSize": 2,
 "got": [
  "one",
  "two"
 ]
}
```

---

## Recursos relacionados

- [WritableStreamDefaultWriter](/pt-br/documentacao/devtools/runtime/api-reference/stream-default-writer.md): O writer que `getWriter()` bloqueia para um stream, e os métodos dele.
- [ReadableStream](/pt-br/documentacao/devtools/runtime/api-reference/readable-stream.md): Como canalizar um readable stream para um `WritableStream` com `pipeTo()`.
- [TransformStream](/pt-br/documentacao/devtools/runtime/api-reference/transform-stream.md): O par de streams cujo lado writable é um `WritableStream`.
- [Web APIs](/pt-br/documentacao/devtools/runtime/api-reference/javascript.md): As outras Web APIs que o Azion Runtime suporta.