first commit

docs/foundation/flow/streams/src/transforms/compress/compress.md

@@ -0,0 +1,78 @@
+# 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.