Publication de @hsblabs/web-stream-extras

J’ai publié @hsblabs/web-stream-extras.

À l’origine, c’était juste de la plomberie interne que je recopiais d’un projet à l’autre. J’avais accumulé assez d’utilitaires autour de ReadableStream<Uint8Array> pour que cela mérite enfin un vrai package.

npm install @hsblabs/web-stream-extras

Le package fonctionne sur Node.js ≥22 et sur les navigateurs modernes. Aucune dépendance runtime.

Ce que contient le package racine

L’export racine couvre les opérations quotidiennes sur des flux d’octets.

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 transforme un tableau de chunks Uint8Array en ReadableStream. readAllBytes collecte tout le flux dans un seul Uint8Array. Les helpers de conversion — stringToBinary, binaryToString, toU8Array, toArrayBuffer, concatU8Arrays — existent parce que les conversions entre string, Uint8Array et ArrayBuffer reviennent sans cesse et sont faciles à rater subtilement.

ByteTransformStream est une classe de base abstraite pour construire des pipelines typés de transformation binaire. ByteQueue gère le buffering interne quand il faut lire partiellement des octets à travers plusieurs chunks.

L’encodage Base64url est également inclus. encodeBase64Url et decodeBase64Url fonctionnent sans padding.

Chiffrement de flux

Le sous-chemin encryption ajoute du chiffrement basé sur 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 et decryptStream prennent un ReadableStream et renvoient un ReadableStream. Les EncryptionStream et DecryptionStream internes sont aussi exposés comme wrappers TransformStream, ce qui permet de les recomposer autrement si nécessaire.

Quand il faut gérer les clés, webCryptoStream(masterKey) prend en charge la dérivation et le chiffrement d’une clé par flux à partir d’une clé maître AES-GCM.

Pourquoi Web Streams

L’API WHATWG Streams est disponible nativement dans Node.js ≥18 et dans les navigateurs modernes. L’utiliser directement évite les abstractions spécifiques à Node.js et rend le code plus portable. Si le navigateur et le serveur doivent manipuler le même pipeline d’octets, l’API WHATWG est la bonne couche de base.

npm · GitHub

Les retours et issues sont toujours bienvenus.