Initial Commit

packages/foundation/bitpacker/bitpacker-compressed/src/api/api.md

@@ -0,0 +1,62 @@
+# compression API (`compressData` / `decompressData`)
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`compressData` and `decompressData` are the primary public surface of `@suaveplan/bitpacker-compressed`. They are algorithm-by-name helpers that route through a `CompressionRegistry` (defaulting to the process-wide singleton) so callers can switch between `"gzip"`, `"deflate"`, `"none"`, and any custom registered adapter without touching adapter classes directly. They are the layer that hot-path consumers like `CompressedBitPacker` use; it is also the layer that wraps codec failures in `BitpackerError` codes so application code never has to handle a raw `DOMException` or platform-specific stream error.
+
+## Features
+
+- Algorithm-by-name routing through a pluggable `CompressionRegistry`.
+- Coded errors: unknown algorithm → `UNKNOWN_COMPRESSION_ALGORITHM`, codec failure → `COMPRESSION_FAILED` / `DECOMPRESSION_FAILED` with the underlying error chained.
+- Optional registry parameter — pass a custom `CompressionRegistry` for isolation in tests.
+- Symmetric: `compressData(data, "gzip")` round-trips through `decompressData(bytes, "gzip")`.
+
+## Usage: Basic Example
+
+```ts
+import { compressData, decompressData } from "@suaveplan/bitpacker-compressed";
+
+const data = new TextEncoder().encode("hello world".repeat(100));
+const compressed = await compressData(data, "gzip");
+const restored = await decompressData(compressed, "gzip");
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  compressData,
+  createCompressionRegistry,
+} from "@suaveplan/bitpacker-compressed";
+
+// Test isolation: create a fresh registry that ONLY has the "none" adapter
+// registered, then prove the unknown-algorithm path throws coded errors.
+const registry = createCompressionRegistry({ withDefaults: false });
+try {
+  await compressData(data, "gzip", { registry });
+} catch (err) {
+  // BitpackerError with code BITPACKER.UNKNOWN_COMPRESSION_ALGORITHM
+}
+```
+
+## API Reference
+
+### `compressData(data, algorithm, options?): Promise<Uint8Array>`
+
+- `data: Uint8Array` — bytes to compress.
+- `algorithm: string` — registry key (e.g. `"gzip"`, `"deflate"`, `"none"`).
+- `options?: { registry?, level? }` — `registry` overrides the default singleton; `level` is forwarded to the adapter.
+- **Throws:** `BitpackerError(UNKNOWN_COMPRESSION_ALGORITHM)` or `BitpackerError(COMPRESSION_FAILED, { cause })`.
+
+### `decompressData(data, algorithm, options?): Promise<Uint8Array>`
+
+- Inverse of `compressData`. Throws `BitpackerError(DECOMPRESSION_FAILED, { cause })` on codec failure.
+
+## Implementation Notes
+
+- The default singleton is initialized lazily; it registers `"none"`, `"gzip"`, `"deflate"` only if the host supports `CompressionStream`.
+- Adapters are async because `CompressionStream` is async; `NoCompressionAdapter` returns immediately.
+- Hot-path callers should resolve the adapter once and call it directly to avoid the per-call registry lookup.