# compress

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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`

```ts
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.