@hsblabs/web-stream-extras를 출시했다

@hsblabs/web-stream-extras를 공개했다.

여러 프로젝트에서 계속 복붙하던 내부 구현에서 시작했다. ReadableStream<Uint8Array> 주변 유틸리티가 충분히 쌓였고, 이제는 패키지로 정리할 가치가 있다고 판단했다.

npm install @hsblabs/web-stream-extras

Node.js ≥22와 최신 브라우저에서 동작한다. 런타임 의존성은 없다.

루트 패키지에 들어 있는 것

루트 export는 일상적인 바이트 스트림 작업을 담당한다.

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는 Uint8Array 청크 배열을 ReadableStream으로 감싼다. readAllBytes는 스트림 전체를 하나의 Uint8Array로 모은다. stringToBinary, binaryToString, toU8Array, toArrayBuffer, concatU8Arrays 같은 변환 헬퍼는 string, Uint8Array, ArrayBuffer 사이 변환이 반복적이고 미묘하게 틀리기 쉬워서 준비해 둔 것이다.

ByteTransformStream은 타입이 있는 바이너리 변환 파이프라인을 만들기 위한 추상 기반 클래스다. ByteQueue는 청크 경계를 넘는 부분 읽기가 필요할 때 내부 버퍼링을 맡는다.

Base64url 인코딩도 포함되어 있다. encodeBase64Url과 decodeBase64Url은 패딩 없이 동작한다.

스트림 암호화

encryption 서브패스는 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과 decryptStream은 ReadableStream을 받아 ReadableStream을 반환한다. 내부의 EncryptionStream과 DecryptionStream도 TransformStream 래퍼 형태로 공개되어 있어서 다른 방식으로 조합할 수도 있다.

키 관리가 필요한 경우에는 webCryptoStream(masterKey)가 AES-GCM 마스터 키를 사용해 스트림별 키를 파생하고 암호화하는 흐름을 담당한다.

왜 Web Streams인가

WHATWG Streams API는 Node.js ≥18과 최신 브라우저에서 기본 제공된다. Node.js 전용 스트림 추상을 피하면 코드 이식성이 좋아진다. 브라우저와 서버 양쪽에서 같은 바이트 파이프라인을 다뤄야 한다면, WHATWG API가 가장 자연스러운 기반이다.

npm · GitHub

피드백과 이슈는 언제든 환영한다.