# 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.