AbstractPacker

(no submodules)

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

import { Packer } from "@suaveplan/packer";

class MyPacker extends Packer {
    // override hooks if needed
}

Usage: Advanced Example

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.

2.8 KiB Raw Blame History