skills/docs/foundation/bitpacker/bitpacker-compressed/src/adapters/gzip/gzip.md

GzipCompressionAdapter

(no submodules)

Purpose

GzipCompressionAdapter is the WHATWG Streams-backed gzip codec. It uses globalThis.CompressionStream("gzip") and DecompressionStream("gzip") — available in modern browsers, Bun, Deno, and Node 18+. The adapter exists so callers don't have to reach into Web Streams APIs directly: the pipeline framing, error coding, and chunk-concatenation loop are all handled here so compressData(data, "gzip") is a one-liner. If the host environment lacks CompressionStream, the registry's defaultCompressionRegistry() skips registering this adapter; constructing one directly and calling compress in such a host throws BitpackerError(COMPRESSION_FAILED) with a descriptive cause chain.

Features

• Drop-in CompressionAdapter implementation registered as "gzip" in the default registry.
• Streaming pump under the hood — large payloads are chunked through CompressionStream rather than buffered whole.
• Coded errors (COMPRESSION_FAILED / DECOMPRESSION_FAILED) wrap any underlying stream exception with cause.
• Re-exported _runStreamForTests helper used by DeflateCompressionAdapter to share the chunk-concatenation loop.

Usage: Basic Example

import { GzipCompressionAdapter } from "@suaveplan/bitpacker-compressed";

const gzip = new GzipCompressionAdapter();
const compressed = await gzip.compress(myBytes);
const restored = await gzip.decompress(compressed);

Usage: Advanced Example

import { defaultCompressionRegistry } from "@suaveplan/bitpacker-compressed";

// Production code typically goes through the registry.
const registry = defaultCompressionRegistry();
const adapter = registry.resolve("gzip");
const out = await adapter.compress(payload, { level: 9 });

API Reference

class GzipCompressionAdapter implements CompressionAdapter

• readonly name: "gzip"
• async compress(data: Uint8Array, options?: { level?: number }): Promise<Uint8Array>
• async decompress(data: Uint8Array, options?: { level?: number }): Promise<Uint8Array>

Throws: BitpackerError(COMPRESSION_FAILED, { cause }) / BitpackerError(DECOMPRESSION_FAILED, { cause }) if the underlying CompressionStream rejects, including environments without globalThis.CompressionStream.

_runStreamForTests(stream, data): Promise<Uint8Array> (internal)

Exposed for the deflate adapter to re-use the pump loop. Not part of the public API.

Implementation Notes

• WHATWG CompressionStream does not honour the level option — gzip level is fixed at the platform default. The option is accepted for API symmetry with adapters that DO honour it (e.g. a future BrotliAdapter).
• The pump loop uses ReadableStream.prototype.getReader() and concatenates chunks into a single Uint8Array at the end. For very large payloads, callers should consider invoking CompressionStream directly to get backpressure-aware streaming output.
• Every async method awaits inside a try/catch and re-throws as a coded BitpackerError. There is no silent fallback — if gzip fails, the caller sees a fully-typed coded error.