first commit

docs/foundation/data/packer/src/abstract/abstract.md

@@ -0,0 +1,56 @@
+# AbstractPacker
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Base class for whole-file packer implementations (`Packer`, `Unpacker`). Holds resolved options (with sensible defaults applied), a typed `EventBus<PackerEventMap>` for observability, and shared helpers for SHA-256 checksum, MIME detection, and metadata assembly. Subclasses implement the `pack` pipeline; `packStream` is provided for free by collecting the source into a buffer first (whole-file mode is not streaming-native — use `@suaveplan/packer/chunked` for true streaming).
+
+## Features
+
+- `EventBus<PackerEventMap>` typed events: `pack:start`, `pack:compressed`, `pack:encrypted`, `pack:signed`, `pack:complete`, plus matching `unpack:*`.
+- `protected checksum(data)` — SHA-256 hex.
+- `protected mimeFor(filename?)` — MIME detection via `@suaveplan/mime`.
+- `protected buildMetadata(...)` — assembles the metadata object with timestamp, checksum, optional MIME, optional `signed`, and any caller-supplied `custom` fields.
+- `packStream(source, filename?)` — buffers any `PackSource` and delegates to `pack`.
+
+## Usage: Basic Example
+
+```ts
+import { Packer } from "@suaveplan/packer";
+
+class MyPacker extends Packer {
+    // override hooks if needed
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { Packer } from "@suaveplan/packer";
+
+const packer = new Packer({
+    compressionLevel: 9,
+    encryption: { algorithm: "xchacha20-poly1305", key: fileKey },
+    signing: { key: serverSignKey },
+    metadata: { author: "alice" },
+});
+packer.on("pack:compressed", (env) => console.log("size", env.payload.compressedSize));
+const result = await packer.pack(bytes, "report.pdf");
+```
+
+## API Reference
+
+- **`abstract class AbstractPacker extends EventBus<PackerEventMap>`**
+  - `constructor(options?: PackerOptions)` — applies defaults: `compressionLevel: 6`, empty `metadata`.
+  - `abstract pack(data: Uint8Array, filename?: string): Promise<PackedData>`.
+  - `packStream(source: PackSource, filename?: string): Promise<PackedData>` — buffers source and delegates.
+  - `protected checksum(data: Uint8Array): string` — SHA-256 hex.
+  - `protected mimeFor(filename?: string): string | undefined`.
+  - `protected buildMetadata(input): PackedDataMetadata`.
+- **`interface ResolvedPackerOptions`** — internal shape of `this.options`.
+
+## Implementation Notes
+
+`packStream`'s buffering is intentional — whole-file mode produces a single envelope with one checksum and one optional signature, which requires the full byte stream to be in hand before the pipeline can complete. The streaming-native pipeline lives in `@suaveplan/packer/chunked`. The collector handles all four `PackSource` shapes (`Uint8Array`, `Blob`, `ReadableStream`, `AsyncIterable`) and falls back from async-iteration to `getReader` for `ReadableStream` instances that lack the iterator protocol.