Add a general purpose decode-as-a-stream method

Author: pimterry

README.md

@@ -63,6 +63,20 @@ Each method accepts a buffer and returns a promise for a buffer.
 
 This library also supports streaming encoding and decoding, returning web-standard `TransformStream` instances. This uses native `CompressionStream`/`DecompressionStream` where available (all modern browsers and Node 18+).
 
+### `createDecodeStream(encoding)`
+
+Takes an encoding (in the format of a standard HTTP [content-encoding header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding)) and returns a `TransformStream` that decodes data with the specified encoding(s), or `null` if no transformation is needed (identity encoding or undefined).
+
+The encoding can be a string (e.g. `'gzip'` or `'gzip, base64'`), an array of strings, or undefined.
+
+### `createEncodeStream(encoding)`
+
+Takes an encoding (a valid HTTP [content-encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding) name) and returns a `TransformStream` that encodes data with the specified encoding(s), or `null` if no transformation is needed (identity encoding or undefined).
+
+The encoding can be a string (e.g. `'gzip'` or `'gzip, base64'`), an array of strings, or undefined.
+
+### Per-codec streaming methods
+
 * `createGzipStream`
 * `createGunzipStream`
 * `createDeflateStream`
@@ -73,6 +87,8 @@ This library also supports streaming encoding and decoding, returning web-standa
 * `createBrotliDecompressStream`
 * `createZstdCompressStream`
 * `createZstdDecompressStream`
+* `createBase64EncodeStream`
+* `createBase64DecodeStream`
 
 ## Browser usage
 

src/index.ts

@@ -730,6 +730,127 @@ export function createBase64DecodeStream(): TransformStream<BufferSource, Uint8A
     });
 }
 
+// --- Generic Streaming API ---
+
+// Chain multiple TransformStreams into one composite stream
+function chainStreams(streams: TransformStream<BufferSource, Uint8Array>[]): TransformStream<BufferSource, Uint8Array> {
+    if (streams.length === 1) {
+        return streams[0];
+    }
+
+    // Connect streams: readable of each flows into writable of next
+    const first = streams[0];
+    const last = streams[streams.length - 1];
+
+    for (let i = 0; i < streams.length - 1; i++) {
+        streams[i].readable.pipeTo(streams[i + 1].writable);
+    }
+
+    return { writable: first.writable, readable: last.readable } as TransformStream<BufferSource, Uint8Array>;
+}
+
+// Get decoder stream for a single encoding (identity already filtered out)
+function getDecoderStream(encoding: string): TransformStream<BufferSource, Uint8Array> {
+    switch (encoding.toLowerCase()) {
+        case 'gzip':
+        case 'x-gzip':
+            return createGunzipStream();
+        case 'deflate':
+        case 'x-deflate':
+            return createInflateStream();
+        case 'br':
+            return createBrotliDecompressStream();
+        case 'zstd':
+            return createZstdDecompressStream();
+        case 'base64':
+            return createBase64DecodeStream();
+        default:
+            throw new Error(`Unsupported encoding: ${encoding}`);
+    }
+}
+
+// Get encoder stream for a single encoding (identity already filtered out)
+function getEncoderStream(encoding: string): TransformStream<BufferSource, Uint8Array> {
+    switch (encoding.toLowerCase()) {
+        case 'gzip':
+        case 'x-gzip':
+            return createGzipStream();
+        case 'deflate':
+        case 'x-deflate':
+            return createDeflateStream();
+        case 'br':
+            return createBrotliCompressStream();
+        case 'zstd':
+            return createZstdCompressStream();
+        case 'base64':
+            return createBase64EncodeStream();
+        default:
+            throw new Error(`Unsupported encoding: ${encoding}`);
+    }
+}
+
+// Parse encoding header into array of non-identity encodings
+function parseEncodings(encoding: string | string[] | undefined): string[] {
+    if (!encoding) return [];
+
+    const encodings = Array.isArray(encoding)
+        ? encoding
+        : encoding.includes(', ')
+            ? encoding.split(', ')
+            : [encoding];
+
+    return encodings.filter(e => !IDENTITY_ENCODINGS.includes(e.toLowerCase()));
+}
+
+/**
+ * Creates a decode stream for the given content-encoding header value.
+ * Supports multiple encodings (comma-separated or array), applied in reverse order.
+ * Returns null if no decoding is needed (identity or no encoding).
+ *
+ * @example
+ * const decoder = createDecodeStream('gzip');
+ * const output = decoder ? stream.pipeThrough(decoder) : stream;
+ *
+ * @example
+ * // Multiple encodings (decodes in reverse order)
+ * const decoder = createDecodeStream('gzip, br');
+ */
+export function createDecodeStream(encoding: string | string[] | undefined): TransformStream<BufferSource, Uint8Array> | null {
+    const encodings = parseEncodings(encoding);
+    if (encodings.length === 0) return null;
+
+    // Reverse order for decoding (last applied encoding = first to decode)
+    encodings.reverse();
+
+    if (encodings.length === 1) {
+        return getDecoderStream(encodings[0]);
+    }
+    return chainStreams(encodings.map(e => getDecoderStream(e)));
+}
+
+/**
+ * Creates an encode stream for the given content-encoding header value.
+ * Supports multiple encodings (comma-separated or array), applied in order.
+ * Returns null if no encoding is needed (identity or no encoding).
+ *
+ * @example
+ * const encoder = createEncodeStream('gzip');
+ * const output = encoder ? stream.pipeThrough(encoder) : stream;
+ *
+ * @example
+ * // Multiple encodings (applies gzip first, then base64)
+ * const encoder = createEncodeStream('gzip, base64');
+ */
+export function createEncodeStream(encoding: string | string[] | undefined): TransformStream<BufferSource, Uint8Array> | null {
+    const encodings = parseEncodings(encoding);
+    if (encodings.length === 0) return null;
+
+    if (encodings.length === 1) {
+        return getEncoderStream(encodings[0]);
+    }
+    return chainStreams(encodings.map(e => getEncoderStream(e)));
+}
+
 // --- Buffer helpers ---
 
 const asBuffer = (input: Buffer | Uint8Array | ArrayBuffer): Buffer => {

test/stream.spec.ts

@@ -21,7 +21,9 @@ import {
     createBase64EncodeStream,
     createBase64DecodeStream,
     encodeBase64,
-    decodeBase64
+    decodeBase64,
+    createDecodeStream,
+    createEncodeStream
 } from '../src/index';
 
 describe("Streaming", () => {
@@ -677,6 +679,134 @@ describe("Streaming", () => {
             }
         });
     });
+
+    describe("Generic Streaming API", () => {
+        it('should decode with createDecodeStream for single encoding', async () => {
+            const original = 'Hello generic decode stream!';
+            const compressed = zlib.gzipSync(original);
+            const inputStream = createReadableStream(compressed);
+
+            const decodedStream = inputStream.pipeThrough(createDecodeStream('gzip')!);
+            const decoded = await collectStream(decodedStream);
+
+            expect(Buffer.from(decoded).toString()).to.equal(original);
+        });
+
+        it('should encode with createEncodeStream for single encoding', async () => {
+            const original = Buffer.from('Hello generic encode stream!');
+            const inputStream = createReadableStream(original);
+
+            const encodedStream = inputStream.pipeThrough(createEncodeStream('gzip')!);
+            const encoded = await collectStream(encodedStream);
+
+            const decoded = zlib.gunzipSync(Buffer.from(encoded));
+            expect(decoded.toString()).to.equal(original.toString());
+        });
+
+        it('should handle multiple encodings in decode (comma-separated)', async () => {
+            const original = 'Multiple encodings test!';
+            // Encode: first gzip, then base64
+            const gzipped = zlib.gzipSync(original);
+            const encoded = await encodeBase64(gzipped);
+
+            const inputStream = createReadableStream(encoded);
+            // Decode: "gzip, base64" means gzip was applied first, base64 second
+            // So we decode base64 first, then gzip
+            const decodedStream = inputStream.pipeThrough(createDecodeStream('gzip, base64')!);
+            const decoded = await collectStream(decodedStream);
+
+            expect(Buffer.from(decoded).toString()).to.equal(original);
+        });
+
+        it('should handle multiple encodings in decode (array)', async () => {
+            const original = 'Array encodings test!';
+            const gzipped = zlib.gzipSync(original);
+            const encoded = await encodeBase64(gzipped);
+
+            const inputStream = createReadableStream(encoded);
+            const decodedStream = inputStream.pipeThrough(createDecodeStream(['gzip', 'base64'])!);
+            const decoded = await collectStream(decodedStream);
+
+            expect(Buffer.from(decoded).toString()).to.equal(original);
+        });
+
+        it('should handle multiple encodings in encode', async () => {
+            const original = Buffer.from('Encode multiple test!');
+            const inputStream = createReadableStream(original);
+
+            // Encode with gzip then base64
+            const encodedStream = inputStream.pipeThrough(createEncodeStream('gzip, base64')!);
+            const encoded = await collectStream(encodedStream);
+
+            // Decode manually in reverse order
+            const decoded64 = await decodeBase64(encoded);
+            const decoded = zlib.gunzipSync(Buffer.from(decoded64));
+            expect(decoded.toString()).to.equal(original.toString());
+        });
+
+        it('should round-trip with encode and decode streams', async () => {
+            const original = Buffer.from('Round trip with generic streams!');
+            const encoding = 'gzip, base64';
+
+            const inputStream = createReadableStream(original);
+            const encodedStream = inputStream.pipeThrough(createEncodeStream(encoding)!);
+            const decodedStream = encodedStream.pipeThrough(createDecodeStream(encoding)!);
+            const result = await collectStream(decodedStream);
+
+            expect(Buffer.from(result).toString()).to.equal(original.toString());
+        });
+
+        it('should return null for identity/undefined encoding', async () => {
+            // Test undefined
+            expect(createDecodeStream(undefined)).to.equal(null);
+            expect(createEncodeStream(undefined)).to.equal(null);
+
+            // Test 'identity'
+            expect(createDecodeStream('identity')).to.equal(null);
+            expect(createEncodeStream('identity')).to.equal(null);
+
+            // Test empty string equivalent
+            expect(createDecodeStream('')).to.equal(null);
+        });
+
+        it('should throw for unsupported encoding', () => {
+            expect(() => createDecodeStream('unsupported-encoding')).to.throw('Unsupported encoding');
+            expect(() => createEncodeStream('unsupported-encoding')).to.throw('Unsupported encoding');
+        });
+
+        it('should handle case-insensitive encodings', async () => {
+            const original = 'Case insensitive test!';
+            const compressed = zlib.gzipSync(original);
+            const inputStream = createReadableStream(compressed);
+
+            const decodedStream = inputStream.pipeThrough(createDecodeStream('GZIP')!);
+            const decoded = await collectStream(decodedStream);
+
+            expect(Buffer.from(decoded).toString()).to.equal(original);
+        });
+
+        it('should handle brotli encoding', async () => {
+            const original = Buffer.from('Brotli generic test!');
+            const inputStream = createReadableStream(original);
+
+            const encodedStream = inputStream.pipeThrough(createEncodeStream('br')!);
+            const decodedStream = encodedStream.pipeThrough(createDecodeStream('br')!);
+            const result = await collectStream(decodedStream);
+
+            expect(Buffer.from(result).toString()).to.equal(original.toString());
+        });
+
+        it('should handle zstd encoding', async () => {
+            const original = Buffer.from('Zstd generic test!');
+            const inputStream = createReadableStream(original);
+
+            const encodedStream = inputStream.pipeThrough(createEncodeStream('zstd')!);
+            const decodedStream = encodedStream.pipeThrough(createDecodeStream('zstd')!);
+            const result = await collectStream(decodedStream);
+
+            expect(Buffer.from(result).toString()).to.equal(original.toString());
+        });
+    });
 });
 
 // Helper to collect all chunks from a ReadableStream into a single Uint8Array