Lançando @hsblabs/web-stream-extras

Publiquei @hsblabs/web-stream-extras.

Ele começou como um conjunto de implementações internas que eu seguia copiando entre projetos. Com o tempo, juntou utilitários suficientes em torno de ReadableStream<Uint8Array> para justificar um pacote de verdade.

npm install @hsblabs/web-stream-extras

Funciona em Node.js ≥22 e navegadores modernos. Sem dependências de runtime.

O que existe no pacote raiz

O export raiz cobre as operações do dia a dia com byte streams.

import {
  readableFromChunks,
  readAllBytes,
  stringToBinary,
  binaryToString,
} from "@hsblabs/web-stream-extras";

const stream = readableFromChunks([
  stringToBinary("hello"),
  stringToBinary(" world"),
]);

const result = await readAllBytes(stream);
console.log(binaryToString(result)); // "hello world"

readableFromChunks envolve um array de chunks Uint8Array em um ReadableStream. readAllBytes coleta todo o fluxo em um único Uint8Array. Os helpers de conversão — stringToBinary, binaryToString, toU8Array, toArrayBuffer, concatU8Arrays — existem porque converter entre string, Uint8Array e ArrayBuffer é repetitivo e fácil de errar em detalhes sutis.

ByteTransformStream é uma classe base abstrata para montar pipelines tipados de transformação binária. ByteQueue cuida do buffering interno quando você precisa ler bytes parcialmente atravessando limites de chunks.

O pacote também inclui codificação Base64url. encodeBase64Url e decodeBase64Url funcionam sem padding.

Criptografia de streams

O subcaminho encryption adiciona criptografia com base na Web Crypto API.

import {
  encryptStream,
  decryptStream,
} from "@hsblabs/web-stream-extras/encryption";

const key = crypto.getRandomValues(new Uint8Array(32));
const encrypted = encryptStream(key, plaintext);
const decrypted = decryptStream(key, encrypted);

encryptStream e decryptStream recebem um ReadableStream e devolvem outro ReadableStream. Os componentes internos EncryptionStream e DecryptionStream também são expostos como wrappers TransformStream, caso você precise compô-los de outra forma.

Quando há necessidade de gestão de chaves, webCryptoStream(masterKey) cuida da derivação e da criptografia de chaves por stream com uma chave mestre AES-GCM.

Por que Web Streams

A API WHATWG Streams está disponível nativamente no Node.js ≥18 e nos navegadores modernos. Usá-la diretamente evita abstrações específicas do Node.js e mantém o código portável. Se navegador e servidor precisam lidar com o mesmo pipeline de bytes, a API WHATWG é a base mais adequada.

npm · GitHub

Feedback e issues são sempre bem-vindos.