[codex] Add base64 stream helpers

.changeset/base64-streams.md

@@ -0,0 +1,5 @@
+---
+"@hsblabs/web-stream-extras": minor
+---
+
+Add a `base64` subpath with streaming base64 and base64url encode/decode helpers.

README.md

@@ -11,6 +11,7 @@ Use this package when you need to:
 - build or consume `ReadableStream<Uint8Array>` pipelines
 - collect byte streams into a single `Uint8Array`
 - convert between strings and `Uint8Array`
+- encode and decode base64 or base64url streams
 - decode, encode, split, and join text streams
 - encrypt or decrypt byte streams with the Web Streams API
 
@@ -155,6 +156,27 @@ const lines = await readAllChunks(
 );
 ```
 
+### `@hsblabs/web-stream-extras/base64`
+
+The `base64` subpath provides streaming base64 and base64url codecs:
+
+- `Base64EncodeStream`
+- `Base64DecodeStream`
+- `encodeBase64Stream`
+- `decodeBase64Stream`
+- `encodeBase64UrlStream`
+- `decodeBase64UrlStream`
+
+The encoder preserves chunk boundaries where it can while carrying incomplete 3-byte groups to the next chunk. `encodeBase64UrlStream()` omits padding by default.
+
+```ts
+import { readAllChunks } from "@hsblabs/web-stream-extras";
+import { encodeBase64UrlStream } from "@hsblabs/web-stream-extras/base64";
+
+const encoded = await readAllChunks(encodeBase64UrlStream(file.stream()));
+const token = encoded.join("");
+```
+
 ### `webCryptoStream` example
 
 ```ts

package.json

@@ -25,6 +25,7 @@
   ],
   "exports": {
     ".": "./dist/index.js",
+    "./base64": "./dist/base64.js",
     "./encryption": "./dist/encryption.js",
     "./jsonl": "./dist/jsonl.js",
     "./text": "./dist/text.js",

src/base64.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import {
+	Base64DecodeStream,
+	Base64EncodeStream,
+	decodeBase64Stream,
+	decodeBase64UrlStream,
+	encodeBase64Stream,
+	encodeBase64UrlStream,
+} from "./base64";
+import {
+	binaryToString,
+	readAllBytes,
+	readAllChunks,
+	readableFromChunks,
+	stringToBinary,
+} from "./index";
+
+describe("base64", () => {
+	it("encodes byte chunks across 3-byte boundaries", async () => {
+		const encoded = await readAllChunks(
+			readableFromChunks([
+				stringToBinary("he"),
+				stringToBinary("llo "),
+				stringToBinary("world"),
+			]).pipeThrough(new Base64EncodeStream()),
+		);
+
+		expect(encoded.join("")).toBe("aGVsbG8gd29ybGQ=");
+	});
+
+	it("encodes base64url without padding by default", async () => {
+		const encoded = await readAllChunks(
+			encodeBase64UrlStream(
+				readableFromChunks(new Uint8Array([251, 255, 255])),
+			),
+		);
+
+		expect(encoded.join("")).toBe("-___");
+	});
+
+	it("can keep base64url padding when requested", async () => {
+		const encoded = await readAllChunks(
+			readableFromChunks(stringToBinary("hi")).pipeThrough(
+				new Base64EncodeStream({ variant: "base64url", padding: true }),
+			),
+		);
+
+		expect(encoded.join("")).toBe("aGk=");
+	});
+
+	it("decodes base64 chunks across 4-character boundaries", async () => {
+		const decoded = await readAllBytes(
+			readableFromChunks(["aG", "Vsb", "G8gd29ybGQ="]).pipeThrough(
+				new Base64DecodeStream(),
+			),
+		);
+
+		expect(binaryToString(decoded)).toBe("hello world");
+	});
+
+	it("decodes base64url without padding", async () => {
+		const decoded = await readAllBytes(
+			decodeBase64UrlStream(readableFromChunks(["-_", "__"])),
+		);
+
+		expect(decoded).toEqual(new Uint8Array([251, 255, 255]));
+	});
+
+	it("ignores ASCII whitespace while decoding", async () => {
+		const decoded = await readAllBytes(
+			decodeBase64Stream(readableFromChunks(["aGVs\n", "bG8gd29y\r\nbGQ="])),
+		);
+
+		expect(binaryToString(decoded)).toBe("hello world");
+	});
+
+	it("rejects malformed base64 input", async () => {
+		await expect(
+			readAllBytes(decodeBase64Stream(readableFromChunks("%%%"))),
+		).rejects.toThrow(SyntaxError);
+	});
+
+	it("creates encoded streams from iterables", async () => {
+		const encoded = await readAllChunks(
+			encodeBase64Stream([stringToBinary("hello"), stringToBinary(" world")]),
+		);
+
+		expect(encoded.join("")).toBe("aGVsbG8gd29ybGQ=");
+	});
+});

src/base64.ts

@@ -0,0 +1,15 @@
+export type {
+	Base64DecodeStreamOptions,
+	Base64EncodeStreamOptions,
+	Base64InputChunk,
+	Base64Variant,
+} from "./base64/public";
+
+export {
+	Base64DecodeStream,
+	Base64EncodeStream,
+	decodeBase64Stream,
+	decodeBase64UrlStream,
+	encodeBase64Stream,
+	encodeBase64UrlStream,
+} from "./base64/public";

src/base64/public.ts

@@ -0,0 +1,14 @@
+export type {
+	Base64DecodeStreamOptions,
+	Base64EncodeStreamOptions,
+	Base64InputChunk,
+	Base64Variant,
+} from "./stream";
+export {
+	Base64DecodeStream,
+	Base64EncodeStream,
+	decodeBase64Stream,
+	decodeBase64UrlStream,
+	encodeBase64Stream,
+	encodeBase64UrlStream,
+} from "./stream";