@a0n/aeon 5.0.1

package/dist/compression/index.d.ts

@@ -0,0 +1,451 @@
+import { Operation } from '../core/index.js';
+
+/**
+ * Compression Engine (Phase 12)
+ *
+ * Provides compression for delta operations using native CompressionStream API.
+ * Falls back gracefully when native compression is unavailable.
+ */
+interface CompressedBatch {
+    id: string;
+    compressed: Uint8Array;
+    originalSize: number;
+    compressedSize: number;
+    compressionRatio: number;
+    algorithm: 'gzip' | 'deflate' | 'none';
+    timestamp: number;
+}
+interface CompressedChunk {
+    chunkId: string;
+    batchId: string;
+    data: Uint8Array;
+    index: number;
+    total: number;
+    checksum: string;
+}
+interface CompressionStats {
+    totalCompressed: number;
+    totalDecompressed: number;
+    totalOriginalBytes: number;
+    totalCompressedBytes: number;
+    averageCompressionRatio: number;
+    compressionTimeMs: number;
+    decompressionTimeMs: number;
+}
+declare class CompressionEngine {
+    private stats;
+    private preferredAlgorithm;
+    constructor(preferredAlgorithm?: 'gzip' | 'deflate');
+    /**
+     * Check if native compression is available
+     */
+    supportsNativeCompression(): boolean;
+    /**
+     * Compress data
+     */
+    compress(data: Uint8Array | string): Promise<CompressedBatch>;
+    /**
+     * Decompress data
+     */
+    decompress(batch: CompressedBatch): Promise<Uint8Array>;
+    /**
+     * Compress using native CompressionStream
+     */
+    private compressNative;
+    /**
+     * Decompress using native DecompressionStream
+     */
+    private decompressNative;
+    /**
+     * Split compressed batch into chunks for transmission
+     */
+    splitIntoChunks(batch: CompressedBatch, chunkSize?: number): CompressedChunk[];
+    /**
+     * Reassemble chunks into compressed batch
+     */
+    reassembleChunks(chunks: CompressedChunk[]): Uint8Array;
+    /**
+     * Simple checksum for chunk verification
+     */
+    private simpleChecksum;
+    /**
+     * Update average compression ratio
+     */
+    private updateAverageRatio;
+    /**
+     * Get statistics
+     */
+    getStats(): CompressionStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+}
+declare function getCompressionEngine(): CompressionEngine;
+declare function resetCompressionEngine(): void;
+
+/**
+ * Delta Sync Optimizer (Phase 12)
+ *
+ * Implements field-level change detection to reduce payload size.
+ * Computes delta between current and previous operation state.
+ *
+ * Performance Impact:
+ * - Delta sync alone: 70-80% payload reduction
+ * - Combined with compression: 80-90% total reduction
+ */
+
+/**
+ * Delta operation - represents only changed fields
+ */
+interface DeltaOperation {
+    id: string;
+    type: 'full' | 'delta';
+    operationId: string;
+    operationType: Operation['type'];
+    sessionId: string;
+    timestamp: number;
+    changes?: Record<string, unknown>;
+    changeMask?: string[];
+    fullData?: Record<string, unknown>;
+    priority?: 'high' | 'normal' | 'low';
+}
+/**
+ * Batch of delta operations
+ */
+interface DeltaBatch {
+    batchId: string;
+    operations: DeltaOperation[];
+    timestamp: number;
+    totalOriginalSize: number;
+    totalDeltaSize: number;
+    reductionPercent: number;
+}
+/**
+ * Statistics about delta sync performance
+ */
+interface DeltaStats {
+    totalOperations: number;
+    totalFull: number;
+    totalDelta: number;
+    totalOriginalSize: number;
+    totalDeltaSize: number;
+    averageReductionPercent: number;
+    lastSyncTime: number;
+    fullOperationThreshold: number;
+}
+declare class DeltaSyncOptimizer {
+    private static readonly MAX_HISTORY_SIZE;
+    private operationHistory;
+    private stats;
+    constructor(fullOperationThreshold?: number);
+    /**
+     * Compute delta for single operation
+     */
+    computeDelta(operation: Operation): DeltaOperation;
+    /**
+     * Compute deltas for batch of operations
+     */
+    computeBatchDeltas(operations: Operation[]): DeltaBatch;
+    /**
+     * Decompress delta operation back to full operation
+     */
+    decompressDelta(delta: DeltaOperation): Operation;
+    /**
+     * Update history after successful sync
+     */
+    updateHistory(operations: Operation[]): void;
+    /**
+     * Clear history for specific operations
+     */
+    clearHistory(operationIds: string[]): void;
+    /**
+     * Get current performance statistics
+     */
+    getStats(): DeltaStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Set the full operation threshold
+     */
+    setFullOperationThreshold(bytes: number): void;
+    /**
+     * Get history size for memory monitoring
+     */
+    getHistorySize(): number;
+    /**
+     * Get memory footprint estimate
+     */
+    getMemoryEstimate(): number;
+    /**
+     * Deep equality check for nested objects
+     */
+    private deepEqual;
+}
+declare function getDeltaSyncOptimizer(threshold?: number): DeltaSyncOptimizer;
+declare function resetDeltaSyncOptimizer(): void;
+
+/**
+ * Compression Codecs — Pluggable implementations for topological compression.
+ *
+ * Each codec implements the same interface. The TopologicalCompressor races
+ * them per chunk — different data regions get different codecs automatically.
+ *
+ * Pure-JS codecs (0-3, 6-7) — zero dependencies, work everywhere.
+ * Platform codecs (4-5) wrap node:zlib for brotli/gzip when available.
+ *
+ * Codec lineup:
+ *   0: Raw (identity)       4: Brotli (node:zlib)
+ *   1: RLE                  5: Gzip (node:zlib)
+ *   2: Delta                6: Huffman (entropy coding)
+ *   3: LZ77                 7: Dictionary (web content)
+ */
+interface CompressionCodec {
+    /** Unique identifier (stored in compressed frame header) */
+    readonly id: number;
+    /** Human-readable name */
+    readonly name: string;
+    /** Compress data. Returns compressed bytes (may be larger than input). */
+    encode(data: Uint8Array): Uint8Array;
+    /** Decompress data back to original. */
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+declare class RawCodec implements CompressionCodec {
+    readonly id = 0;
+    readonly name = "raw";
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array): Uint8Array;
+}
+/**
+ * RLE — excellent for data with long runs of repeated bytes.
+ *
+ * Format: [byte, count_high, count_low] triplets.
+ * Count is u16 (max run = 65535). Non-runs still emit count=1.
+ *
+ * Best for: repeated patterns, sparse data, zeroed buffers.
+ * Worst for: high-entropy data (3x expansion).
+ */
+declare class RLECodec implements CompressionCodec {
+    readonly id = 1;
+    readonly name = "rle";
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+/**
+ * Delta encoding — stores differences between consecutive bytes.
+ *
+ * Best for: sequential/incremental data, sensor readings, coordinates.
+ * Worst for: random data (no benefit, slight overhead from first byte).
+ */
+declare class DeltaCodec implements CompressionCodec {
+    readonly id = 2;
+    readonly name = "delta";
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+/**
+ * Simplified LZ77 — sliding window compression with back-references.
+ *
+ * Format: control byte per group of 8 items.
+ *   - Bit 0 = literal byte follows
+ *   - Bit 1 = back-reference follows: [offset_high:4 | length:4, offset_low:8]
+ *     offset = 12 bits (max 4095), length = 4 bits + 3 (range 3–18)
+ *
+ * Window size: 4096 bytes. Min match: 3. Max match: 18.
+ *
+ * Best for: general-purpose data with repeated patterns.
+ * Worst for: truly random data (slight overhead from control bytes).
+ */
+declare class LZ77Codec implements CompressionCodec {
+    readonly id = 3;
+    readonly name = "lz77";
+    private static readonly WINDOW_SIZE;
+    private static readonly MIN_MATCH;
+    private static readonly MAX_MATCH;
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+/**
+ * Brotli via node:zlib — best general-purpose compression ratio.
+ *
+ * Only available on Node/Bun/Deno. The TopologicalCompressor races it
+ * per-chunk against pure-JS codecs — brotli wins on text, raw wins on
+ * already-compressed binary. This is the key insight: topological
+ * compression adapts per-chunk even when one codec dominates globally.
+ *
+ * Quality 4 matches nginx on-the-fly default.
+ */
+declare class BrotliCodec implements CompressionCodec {
+    readonly id = 4;
+    readonly name = "brotli";
+    private readonly quality;
+    constructor(quality?: number);
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array): Uint8Array;
+}
+/**
+ * Gzip via node:zlib — universal fallback, slightly worse ratio than brotli.
+ *
+ * Level 6 matches nginx default.
+ */
+declare class GzipCodec implements CompressionCodec {
+    readonly id = 5;
+    readonly name = "gzip";
+    private readonly level;
+    constructor(level?: number);
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array): Uint8Array;
+}
+/**
+ * Canonical Huffman coding — entropy-optimal per-byte compression.
+ *
+ * Captures the entropy coding stage of Zstandard/DEFLATE. Pure JS,
+ * works everywhere. Excels on data with skewed byte distributions
+ * where a few byte values dominate.
+ *
+ * Format:
+ *   [0..255]   u8×256  code_lengths (one per possible byte value)
+ *   [256..259] u32     total_bits in the encoded stream
+ *   [260..]    packed bits (MSB-first)
+ *
+ * Overhead: 260 bytes. Only wins on chunks where entropy coding
+ * saves more than 260 bytes — the race handles this automatically.
+ */
+declare class HuffmanCodec implements CompressionCodec {
+    readonly id = 6;
+    readonly name = "huffman";
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+declare class DictionaryCodec implements CompressionCodec {
+    readonly id = 7;
+    readonly name = "dictionary";
+    encode(data: Uint8Array): Uint8Array;
+    decode(data: Uint8Array, originalSize: number): Uint8Array;
+}
+/** Pure-JS codecs — zero dependencies, work everywhere */
+declare const PURE_JS_CODECS: CompressionCodec[];
+/** All built-in codecs including platform codecs (brotli/gzip via node:zlib) */
+declare const BUILTIN_CODECS: CompressionCodec[];
+/** Look up a codec by ID */
+declare function getCodecById(id: number): CompressionCodec;
+
+/**
+ * Topological Compressor — Fork/Race/Fold Applied to Compression
+ *
+ * Two-level fork/race/fold:
+ *
+ *   LEVEL 1 (stream): Fork the entire input into global strategies.
+ *     - Path A: Global brotli on the whole stream (cross-chunk dictionary)
+ *     - Path B: Global gzip on the whole stream
+ *     - Path C: Per-chunk topological compression (Level 2)
+ *     Race all paths. Fold to smallest.
+ *
+ *   LEVEL 2 (chunk): For each chunk, fork all codecs.
+ *     - Race codecs per chunk. Smallest wins.
+ *     - Vent codecs whose output >= raw.
+ *     - Fold: self-describing frame per chunk.
+ *
+ * Stream-level format (when streamRace is enabled):
+ *   [0]       u8    strategy        (0 = per-chunk, N>0 = global codec ID)
+ *   [1..4]    u32   original_size
+ *   [5..]     [u8]  compressed data
+ *
+ * Per-chunk frame format:
+ *   [0]       u8    codec_id
+ *   [1..4]    u32   original_size
+ *   [5..8]    u32   compressed_size
+ *   [9..]     [u8]  compressed_data
+ *
+ * Zero dependencies. Works on CF Workers, Deno, Node, Bun, browsers.
+ */
+
+/** Per-chunk compression result — which codec won and why */
+interface ChunkResult {
+    /** Index of this chunk in the original data */
+    chunkIndex: number;
+    /** The codec that won the race for this chunk */
+    codecId: number;
+    /** Codec name (for diagnostics) */
+    codecName: string;
+    /** Original size of this chunk in bytes */
+    originalSize: number;
+    /** Compressed size of this chunk in bytes (including 9-byte header) */
+    compressedSize: number;
+    /** Compression ratio for this chunk (0 = no compression, 1 = perfect) */
+    ratio: number;
+    /** How many codecs were vented (output >= input) */
+    vented: number;
+}
+/** Overall compression result */
+interface TopologicalCompressionResult {
+    /** The compressed output — concatenated self-describing frames */
+    data: Uint8Array;
+    /** Per-chunk results */
+    chunks: ChunkResult[];
+    /** Total original size */
+    originalSize: number;
+    /** Total compressed size */
+    compressedSize: number;
+    /** Overall compression ratio */
+    ratio: number;
+    /** Number of distinct codecs used across all chunks */
+    codecsUsed: number;
+    /** β₁ during compression (number of parallel codec paths - 1) */
+    bettiNumber: number;
+    /** Compression time in milliseconds */
+    timeMs: number;
+    /** Strategy that won the stream-level race (only set when streamRace=true) */
+    strategy?: string;
+}
+/** Compressor configuration */
+interface TopologicalCompressorConfig {
+    /** Chunk size in bytes. Smaller = more adaptive, larger = better ratio. */
+    chunkSize: number;
+    /** Codecs to race. Default: all built-in codecs. */
+    codecs: CompressionCodec[];
+    /** Enable two-level race: global codecs vs per-chunk topological. Default: false. */
+    streamRace?: boolean;
+}
+declare class TopologicalCompressor {
+    private readonly config;
+    constructor(config?: Partial<TopologicalCompressorConfig>);
+    /**
+     * Compress data using fork/race/fold.
+     *
+     * When streamRace=false (default): per-chunk race only.
+     * When streamRace=true: two-level race — global codecs vs per-chunk topo.
+     */
+    compress(data: Uint8Array): TopologicalCompressionResult;
+    /**
+     * Decompress data produced by compress().
+     */
+    decompress(compressed: Uint8Array): Uint8Array;
+    private compressChunked;
+    private decompressChunked;
+    /**
+     * Two-level fork/race/fold:
+     *
+     *   FORK (stream level):
+     *     ├─ Path 0: Per-chunk topological (Level 2)
+     *     ├─ Path 1: Global codec A on entire stream
+     *     ├─ Path 2: Global codec B on entire stream
+     *     └─ ...
+     *   RACE: Smallest total output wins
+     *   FOLD: 5-byte strategy header + compressed data
+     *
+     * On homogeneous text, global brotli wins (cross-chunk dictionary).
+     * On mixed content, per-chunk topo wins (adapts per region).
+     * The topology decides — not the programmer.
+     */
+    private compressTwoLevel;
+    private decompressTwoLevel;
+    /** Get the codecs available for racing. */
+    getCodecs(): ReadonlyArray<CompressionCodec>;
+    /** Get the chunk size. */
+    getChunkSize(): number;
+}
+
+export { BUILTIN_CODECS, BrotliCodec, type ChunkResult, type CompressedBatch, type CompressedChunk, type CompressionCodec, CompressionEngine, type CompressionStats, type DeltaBatch, DeltaCodec, type DeltaOperation, type DeltaStats, DeltaSyncOptimizer, DictionaryCodec, GzipCodec, HuffmanCodec, LZ77Codec, PURE_JS_CODECS, RLECodec, RawCodec, type TopologicalCompressionResult, TopologicalCompressor, type TopologicalCompressorConfig, getCodecById, getCompressionEngine, getDeltaSyncOptimizer, resetCompressionEngine, resetDeltaSyncOptimizer };