compress

(no submodules)

Purpose

Provides compressStream and decompressStream — thin wrappers over the WHATWG CompressionStream and DecompressionStream platform APIs — for gzip, deflate, and raw deflate compression of binary streams. The wrappers add a consistent error wrapping contract: if the underlying platform constructor throws (e.g. for an unsupported format), the error is caught and re-thrown as StreamPipeFailedError with the original cause.

These transforms are designed for large-scale binary data movement: compressing database dumps, network payloads, or log files before writing to storage, and decompressing them on read.

Features

compressStream: wraps CompressionStream (gzip / deflate / deflate-raw)
decompressStream: wraps DecompressionStream (gzip / deflate / deflate-raw)
Constructor errors wrapped as StreamPipeFailedError
Composable with fromBytes, toBytes, encodeTextStream

Usage: Basic Example

import { compressStream, decompressStream } from "@suaveplan/streams/transforms/compress/compress";
import { fromBytes } from "@suaveplan/streams/readable/from-bytes/from-bytes";
import { toArray } from "@suaveplan/streams/sinks/to-array/to-array";

const data = new TextEncoder().encode("hello world");
const compressed = fromBytes(data).pipeThrough(compressStream("gzip"));
const decompressed = compressed.pipeThrough(decompressStream("gzip"));
const chunks = await toArray(decompressed);
const text = new TextDecoder().decode(chunks[0]);
console.log(text); // "hello world"

Usage: Advanced Example

import { compressStream, decompressStream } from "@suaveplan/streams/transforms/compress/compress";
import { fromBytes } from "@suaveplan/streams/readable/from-bytes/from-bytes";
import { encodeTextStream } from "@suaveplan/streams/transforms/text-codec/text-codec";
import { fromArray } from "@suaveplan/streams/readable/from-array/from-array";

// Compress a text stream to gzip
const textStream = fromArray(["line1\n", "line2\n"])
  .pipeThrough(encodeTextStream())
  .pipeThrough(compressStream("gzip"));

// Accumulate compressed bytes
const reader = textStream.getReader();
const parts: Uint8Array[] = [];
let r = await reader.read();
while (!r.done) { parts.push(r.value); r = await reader.read(); }
const totalBytes = parts.reduce((s, c) => s + c.byteLength, 0);
console.log("compressed size:", totalBytes);

API Reference

`compressStream(format?: CompressionFormat): TransformStream<Uint8Array, Uint8Array>`

format — "gzip" | "deflate" | "deflate-raw" (default "gzip").

Throws (immediate): StreamPipeFailedError if the platform CompressionStream constructor rejects the format.

`decompressStream(format?: CompressionFormat): TransformStream<Uint8Array, Uint8Array>`

format — "gzip" | "deflate" | "deflate-raw" (default "gzip").

Throws (immediate): StreamPipeFailedError if the platform DecompressionStream constructor rejects the format.

`CompressionFormat`

type CompressionFormat = "gzip" | "deflate" | "deflate-raw";

Implementation Notes

Both functions are synchronous constructors that create and return the built-in stream objects. No additional buffering or chunk manipulation is performed — the platform implementation handles all compression logic. The wrapping try/catch is there purely for the error code contract; it should almost never trigger on modern runtimes that support all three formats.

3.5 KiB Raw Blame History