zstdify 1.0.2 → 1.1.1

package/README.md

@@ -5,6 +5,8 @@
 [![Tests][tests-badge]][tests-url]
 [![Coverage][coverage-badge]][coverage-url]
 
+![Zstdify Logo](/logo.webp)
+
 Pure JavaScript/TypeScript zstd compression/decompression library. No native dependencies, works in Node.js and browsers.
 
 ## Features
@@ -19,6 +21,10 @@ Pure JavaScript/TypeScript zstd compression/decompression library. No native dep
   - Raw blocks, RLE blocks, and compressed blocks.
   - Compression-level driven behavior with automatic raw fallback when compressed output is not smaller.
   - Optional frame content checksums.
+  - Optional dictionary-aware frame headers (`dictID`) for dictionary workflows.
+- **Dictionary generation**:
+  - Pure TypeScript dictionary training from sample payloads.
+  - Zstd-inspired training options (`fastcover`/`cover`/`legacy` style knobs).
 - **Interop-focused**: `zstdify` output is decoded by the official `zstd` CLI, and `zstd` CLI output is decoded by `zstdify`.
 - **Extensively tested**:
   - Round-trip and property-based tests.
@@ -39,8 +45,29 @@ const restored = decompress(compressed);
 
 ## API
 
-- `compress(input: Uint8Array, options?: { level?: number; checksum?: boolean }): Uint8Array`
+- `compress(input: Uint8Array, options?: { level?: number; checksum?: boolean; dictionary?: Uint8Array | { bytes: Uint8Array; id?: number }; noDictId?: boolean }): Uint8Array`
 - `decompress(input: Uint8Array, options?: { maxSize?: number; dictionary?: Uint8Array | { bytes: Uint8Array; id?: number } }): Uint8Array`
+- `generateDictionary(samples: Uint8Array[], options?: { maxDictSize?: number; dictId?: number; algorithm?: "fastcover" | "cover" | "legacy"; k?: number; d?: number; steps?: number; split?: number; f?: number; accel?: number; selectivity?: number; shrink?: boolean | number }): Uint8Array`
+
+Dictionary generation outputs a raw-content dictionary. If you want a specific `dictID` written into compressed frames, pass it to `compress()` via `dictionary: { bytes, id }`.
+
+### Dictionary workflow example
+
+```ts
+import { compress, decompress, generateDictionary } from 'zstdify';
+
+const encoder = new TextEncoder();
+const samples = [
+  encoder.encode('alpha beta gamma delta'),
+  encoder.encode('header vertex texture normal index'),
+  encoder.encode('offset match literal sequence table'),
+];
+const dictionary = generateDictionary(samples, { maxDictSize: 2048, algorithm: 'fastcover' });
+
+const payload = encoder.encode('header vertex texture offset match literal');
+const compressed = compress(payload, { dictionary: { bytes: dictionary, id: 42 } });
+const restored = decompress(compressed, { dictionary: { bytes: dictionary, id: 42 } });
+```
 
 ## CLI Tool
 
@@ -72,7 +99,7 @@ All of the following run as part of the test suite (`pnpm test` / `pnpm vitest`)
 
 - **Round-trip**: `decompress(compress(x)) === x` for a variety of payloads and levels, plus property-based tests with [fast-check](https://fast-check.dev/).
 - **Conformance fixtures**: Pre-generated `.zst` files from the official zstd CLI (legacy fixtures and a committed decodecorpus-style **corpus** with manifest); we decompress and compare. See [packages/zstdify-tests/fixtures/README.md](packages/zstdify-tests/fixtures/README.md).
-- **Differential (zstd ↔ zstdify)**: When the zstd CLI is installed, we test zstd compress → zstdify decompress and zstdify compress → zstd decompress across payloads and levels.
+- **Differential (zstd ↔ zstdify)**: We test zstd compress → zstdify decompress and zstdify compress → zstd decompress across payloads and levels.
 - **Corruption**: Truncation, checksum mismatch, invalid header bits, and related error paths.
 - **Compression regression**: Compressed sizes for fixed payloads are checked against golden values (ratio stability).
 - **Decompress robustness**: Each corpus fixture is decompressed in its own test (one test per file), so the suite tracks decompress behavior per input. See [upstream zstd TESTING.md](https://github.com/facebook/zstd/blob/dev/TESTING.md) for comparison.
@@ -93,6 +120,11 @@ pnpm make-release:cli
 - `packages/cli` - CLI tool (`zstdify-cli` on npm)
 - `packages/cli-tests` - Tests of the CLI tool
 
+## Acknowledgements
+
+This project is made possible by the original [zstd](https://github.com/facebook/zstd) project by Meta and its contributors.
+The monorepo, project, and CLI structure were bootstrapped from [hdrify](https://github.com/bhouston/hdrify), which made this project much easier to build.
+
 # License
 
 MIT

package/dist/compress.d.ts

@@ -5,5 +5,10 @@
 export type CompressOptions = {
     level?: number;
     checksum?: boolean;
+    dictionary?: Uint8Array | {
+        bytes: Uint8Array;
+        id?: number;
+    };
+    noDictId?: boolean;
 };
 export declare function compress(input: Uint8Array, options?: CompressOptions): Uint8Array;

package/dist/compress.js

@@ -2,17 +2,29 @@
  * Compress input data using zstd.
  * Level 0: raw blocks only (no compression, fast).
  */
+import { normalizeDecoderDictionary } from './dictionary/decoderDictionary.js';
 import { writeRawBlock, writeRLEBlock } from './encode/blockWriter.js';
 import { buildCompressedBlockPayload, writeCompressedBlock } from './encode/compressedBlock.js';
 import { writeFrameHeader } from './encode/frameWriter.js';
 import { buildGreedySequences } from './encode/greedySequences.js';
+import { ZstdError } from './errors.js';
 import { computeContentChecksum32 } from './frame/checksum.js';
 const BLOCK_MAX = 128 * 1024;
 export function compress(input, options) {
     const level = options?.level ?? 0;
     const hasChecksum = options?.checksum ?? false;
+    const dictionary = options?.dictionary;
+    const dictionaryBytes = dictionary instanceof Uint8Array ? dictionary : dictionary?.bytes;
+    const providedDictionaryId = dictionary instanceof Uint8Array ? null : (dictionary?.id ?? null);
+    const normalizedDictionary = dictionaryBytes && dictionaryBytes.length > 0
+        ? normalizeDecoderDictionary(dictionaryBytes, providedDictionaryId)
+        : null;
+    const dictionaryId = options?.noDictId ? null : (normalizedDictionary?.dictionaryId ?? providedDictionaryId);
+    if (dictionaryId !== null && (!Number.isInteger(dictionaryId) || dictionaryId <= 0 || dictionaryId > 0xffff_ffff)) {
+        throw new ZstdError('dictionary.id must be a 32-bit positive integer', 'parameter_unsupported');
+    }
     const chunks = [];
-    chunks.push(writeFrameHeader(input.length, hasChecksum));
+    chunks.push(writeFrameHeader(input.length, hasChecksum, dictionaryId));
     let offset = 0;
     const blockCount = input.length === 0 ? 1 : Math.ceil(input.length / BLOCK_MAX);
     let blockIndex = 0;

package/dist/compress.js.map

@@ -1 +1 @@
-{"version":3,"file":"compress.js","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"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"}

package/dist/dictionary/generateDictionary.d.ts

@@ -0,0 +1,59 @@
+export type DictionaryTrainingAlgorithm = 'fastcover' | 'cover' | 'legacy';
+export interface GenerateDictionaryOptions {
+    /**
+     * Target maximum output size for dictionary bytes.
+     * Similar to zstd CLI --maxdict.
+     */
+    maxDictSize?: number;
+    /**
+     * Included for API parity with zstd terminology.
+     * Raw-content dictionaries don't embed an ID in bytes; pass this value
+     * separately to compress/decompress options when needed.
+     */
+    dictId?: number;
+    /**
+     * Training mode selector inspired by zstd dictionary builders.
+     * This implementation is deterministic and uses algorithm-specific scoring.
+     */
+    algorithm?: DictionaryTrainingAlgorithm;
+    /**
+     * Candidate segment size (bytes) used while harvesting patterns.
+     */
+    k?: number;
+    /**
+     * Distance step (bytes) between candidate probes.
+     */
+    d?: number;
+    /**
+     * Number of score-curve refinement passes.
+     */
+    steps?: number;
+    /**
+     * Percent of each sample used for candidate harvesting (1-100).
+     */
+    split?: number;
+    /**
+     * Additional fastcover-style score multiplier.
+     */
+    f?: number;
+    /**
+     * Probe stride accelerator (1-10).
+     */
+    accel?: number;
+    /**
+     * Legacy-style density control (1-10), where lower means denser.
+     */
+    selectivity?: number;
+    /**
+     * Optional shrink pass. If true, applies default shrink factor.
+     * If number, interpreted as target shrink factor >= 1.
+     */
+    shrink?: boolean | number;
+}
+/**
+ * Generate a deterministic raw-content dictionary from training samples.
+ *
+ * The output is intentionally a raw-content dictionary byte sequence, which is
+ * compatible with zstd's -D usage and zstdify dictionary decode paths.
+ */
+export declare function generateDictionary(samples: Uint8Array[], options?: GenerateDictionaryOptions): Uint8Array;

package/dist/dictionary/generateDictionary.js

@@ -0,0 +1,187 @@
+import { ZstdError } from '../errors.js';
+const DEFAULT_MAX_DICT_SIZE = 112_640;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function hashBytes(bytes) {
+    // FNV-1a 32-bit
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < bytes.length; i++) {
+        hash ^= bytes[i] ?? 0;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+function normalizeOptions(sampleCount, options) {
+    const algorithm = options?.algorithm ?? 'fastcover';
+    const maxDictSize = options?.maxDictSize ?? DEFAULT_MAX_DICT_SIZE;
+    const kDefault = algorithm === 'cover' ? 64 : algorithm === 'legacy' ? 32 : 48;
+    const dDefault = algorithm === 'cover' ? 8 : algorithm === 'legacy' ? 4 : 8;
+    const stepsDefault = algorithm === 'cover' ? 6 : algorithm === 'legacy' ? 3 : 4;
+    const splitDefault = algorithm === 'legacy' ? 100 : 75;
+    const accelDefault = 1;
+    const fDefault = 20;
+    const selectivityDefault = 9;
+    const shrinkDefault = false;
+    if (!Number.isInteger(maxDictSize) || maxDictSize <= 0) {
+        throw new ZstdError('maxDictSize must be a positive integer', 'parameter_unsupported');
+    }
+    if (options?.dictId !== undefined) {
+        if (!Number.isInteger(options.dictId) || options.dictId <= 0 || options.dictId > 0xffff_ffff) {
+            throw new ZstdError('dictId must be a 32-bit positive integer', 'parameter_unsupported');
+        }
+    }
+    const k = clamp(Math.trunc(options?.k ?? kDefault), 8, 1024);
+    const d = clamp(Math.trunc(options?.d ?? dDefault), 1, 64);
+    const steps = clamp(Math.trunc(options?.steps ?? stepsDefault), 1, 1000);
+    const split = clamp(Math.trunc(options?.split ?? splitDefault), 1, 100);
+    const f = clamp(Math.trunc(options?.f ?? fDefault), 1, 1000);
+    const accel = clamp(Math.trunc(options?.accel ?? accelDefault), 1, 10);
+    const selectivity = clamp(Math.trunc(options?.selectivity ?? selectivityDefault), 1, 10);
+    const shrink = options?.shrink ?? shrinkDefault;
+    if (sampleCount === 0) {
+        throw new ZstdError('Training requires at least one sample', 'parameter_unsupported');
+    }
+    return {
+        algorithm,
+        maxDictSize,
+        k,
+        d,
+        steps,
+        split,
+        f,
+        accel,
+        selectivity,
+        shrink,
+    };
+}
+function toHex(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i++) {
+        out += (bytes[i] ?? 0).toString(16).padStart(2, '0');
+    }
+    return out;
+}
+function preprocessSamples(samples, splitPercent) {
+    const preprocessed = [];
+    for (const sample of samples) {
+        if (!(sample instanceof Uint8Array)) {
+            throw new ZstdError('All samples must be Uint8Array', 'parameter_unsupported');
+        }
+        if (sample.length === 0)
+            continue;
+        const usable = Math.max(1, Math.floor((sample.length * splitPercent) / 100));
+        preprocessed.push(sample.subarray(0, usable));
+    }
+    if (preprocessed.length === 0) {
+        throw new ZstdError('Training requires at least one non-empty sample', 'parameter_unsupported');
+    }
+    return preprocessed;
+}
+function scoreWeight(algorithm, bytes, hits, step, f, selectivity) {
+    const entropyBias = 1 + (hashBytes(bytes) % 13) / 32;
+    const length = bytes.length;
+    if (algorithm === 'legacy') {
+        const density = 11 - selectivity;
+        return hits * (1 + density / 4) + length * 0.5 + entropyBias;
+    }
+    if (algorithm === 'cover') {
+        return hits * (1 + step / 10) + length * 1.1 + entropyBias;
+    }
+    // fastcover
+    return hits * (1 + f / 40) + length * 0.9 + entropyBias;
+}
+function harvestCandidates(samples, k, d, accel, algorithm, steps, f, selectivity) {
+    const map = new Map();
+    for (let step = 0; step < steps; step++) {
+        const size = clamp(k + step * d, 8, 2048);
+        const stride = Math.max(1, Math.floor((d * accel) / Math.max(1, step + 1)));
+        for (const sample of samples) {
+            if (sample.length < size)
+                continue;
+            for (let i = 0; i + size <= sample.length; i += stride) {
+                const bytes = sample.subarray(i, i + size);
+                const key = toHex(bytes);
+                const existing = map.get(key);
+                if (existing) {
+                    existing.hits += 1;
+                    existing.score = scoreWeight(algorithm, existing.bytes, existing.hits, step + 1, f, selectivity);
+                    continue;
+                }
+                const cloned = bytes.slice();
+                map.set(key, {
+                    key,
+                    bytes: cloned,
+                    hits: 1,
+                    score: scoreWeight(algorithm, cloned, 1, step + 1, f, selectivity),
+                });
+            }
+        }
+    }
+    return [...map.values()];
+}
+function maybeShrink(target, shrink) {
+    if (shrink === false)
+        return target;
+    if (shrink === true)
+        return Math.max(256, Math.floor(target * 0.75));
+    if (Number.isFinite(shrink) && shrink >= 1) {
+        return Math.max(256, Math.floor(target / shrink));
+    }
+    throw new ZstdError('shrink must be boolean or number >= 1', 'parameter_unsupported');
+}
+function buildDictionaryBytes(candidates, maxDictSize) {
+    const sorted = [...candidates].sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (b.hits !== a.hits)
+            return b.hits - a.hits;
+        if (b.bytes.length !== a.bytes.length)
+            return b.bytes.length - a.bytes.length;
+        return a.key.localeCompare(b.key);
+    });
+    const chunks = [];
+    let total = 0;
+    for (const candidate of sorted) {
+        if (total >= maxDictSize)
+            break;
+        if (candidate.hits <= 1 && candidate.bytes.length < 24)
+            continue;
+        const remaining = maxDictSize - total;
+        if (remaining < 8)
+            break;
+        const piece = candidate.bytes.length <= remaining ? candidate.bytes : candidate.bytes.subarray(0, remaining);
+        if (piece.length < 8)
+            break;
+        chunks.push(piece.slice());
+        total += piece.length;
+    }
+    if (chunks.length === 0) {
+        // Fallback: ensure at least one deterministic dictionary segment exists.
+        const fallback = new Uint8Array(Math.min(256, maxDictSize));
+        for (let i = 0; i < fallback.length; i++)
+            fallback[i] = i & 0xff;
+        return fallback;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/**
+ * Generate a deterministic raw-content dictionary from training samples.
+ *
+ * The output is intentionally a raw-content dictionary byte sequence, which is
+ * compatible with zstd's -D usage and zstdify dictionary decode paths.
+ */
+export function generateDictionary(samples, options) {
+    const normalized = normalizeOptions(samples.length, options);
+    const preprocessed = preprocessSamples(samples, normalized.split);
+    const candidates = harvestCandidates(preprocessed, normalized.k, normalized.d, normalized.accel, normalized.algorithm, normalized.steps, normalized.f, normalized.selectivity);
+    const targetSize = maybeShrink(normalized.maxDictSize, normalized.shrink);
+    return buildDictionaryBytes(candidates, targetSize);
+}
+//# sourceMappingURL=generateDictionary.js.map

package/dist/dictionary/generateDictionary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateDictionary.js","sourceRoot":"","sources":["../../src/dictionary/generateDictionary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA+DzC,MAAM,qBAAqB,GAAG,OAAO,CAAC;AAEtC,SAAS,KAAK,CAAC,KAAa,EAAE,GAAW,EAAE,GAAW,EAAU;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAAA,CAC5C;AAED,SAAS,SAAS,CAAC,KAAiB,EAAU;IAC5C,gBAAgB;IAChB,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAC;AAAA,CACnB;AAED,SAAS,gBAAgB,CAAC,WAAmB,EAAE,OAAmC,EAAE;IAClF,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,WAAW,CAAC;IACpD,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,qBAAqB,CAAC;IAClE,MAAM,QAAQ,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/E,MAAM,QAAQ,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,YAAY,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,MAAM,YAAY,GAAG,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvD,MAAM,YAAY,GAAG,CAAC,CAAC;IACvB,MAAM,QAAQ,GAAG,EAAE,CAAC;IACpB,MAAM,kBAAkB,GAAG,CAAC,CAAC;IAC7B,MAAM,aAAa,GAAG,KAAK,CAAC;IAE5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,SAAS,CAAC,wCAAwC,EAAE,uBAAuB,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,OAAO,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YAC7F,MAAM,IAAI,SAAS,CAAC,0CAA0C,EAAE,uBAAuB,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7D,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IACxE,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,IAAI,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACzF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,aAAa,CAAC;IAEhD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,uCAAuC,EAAE,uBAAuB,CAAC,CAAC;IACxF,CAAC;IAED,OAAO;QACL,SAAS;QACT,WAAW;QACX,CAAC;QACD,CAAC;QACD,KAAK;QACL,KAAK;QACL,CAAC;QACD,KAAK;QACL,WAAW;QACX,MAAM;KACP,CAAC;AAAA,CACH;AAED,SAAS,KAAK,CAAC,KAAiB,EAAU;IACxC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACZ;AAED,SAAS,iBAAiB,CAAC,OAAqB,EAAE,YAAoB,EAAgB;IACpF,MAAM,YAAY,GAAiB,EAAE,CAAC;IACtC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,CAAC,MAAM,YAAY,UAAU,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,SAAS,CAAC,gCAAgC,EAAE,uBAAuB,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,YAAY,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAC7E,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,SAAS,CAAC,iDAAiD,EAAE,uBAAuB,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,YAAY,CAAC;AAAA,CACrB;AAED,SAAS,WAAW,CAClB,SAAsC,EACtC,KAAiB,EACjB,IAAY,EACZ,IAAY,EACZ,CAAS,EACT,WAAmB,EACX;IACR,MAAM,WAAW,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;IACrD,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,EAAE,GAAG,WAAW,CAAC;QACjC,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,WAAW,CAAC;IAC/D,CAAC;IACD,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,WAAW,CAAC;IAC7D,CAAC;IACD,YAAY;IACZ,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,GAAG,GAAG,WAAW,CAAC;AAAA,CACzD;AAED,SAAS,iBAAiB,CACxB,OAAqB,EACrB,CAAS,EACT,CAAS,EACT,KAAa,EACb,SAAsC,EACtC,KAAa,EACb,CAAS,EACT,WAAmB,EACD;IAClB,MAAM,GAAG,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC9C,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM,CAAC,MAAM,GAAG,IAAI;gBAAE,SAAS;YACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC;gBACvD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;gBAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;gBACzB,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC9B,IAAI,QAAQ,EAAE,CAAC;oBACb,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;oBACnB,QAAQ,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC;oBACjG,SAAS;gBACX,CAAC;gBACD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;gBAC7B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE;oBACX,GAAG;oBACH,KAAK,EAAE,MAAM;oBACb,IAAI,EAAE,CAAC;oBACP,KAAK,EAAE,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;iBACnE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AAAA,CAC1B;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,MAAwB,EAAU;IACrE,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,MAAM,CAAC;IACpC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACrE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,SAAS,CAAC,uCAAuC,EAAE,uBAAuB,CAAC,CAAC;AAAA,CACvF;AAED,SAAS,oBAAoB,CAAC,UAA4B,EAAE,WAAmB,EAAc;IAC3F,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QAClD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;QAC9C,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM;YAAE,OAAO,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;QAC9E,OAAO,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAAA,CACnC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,KAAK,IAAI,WAAW;YAAE,MAAM;QAChC,IAAI,SAAS,CAAC,IAAI,IAAI,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE;YAAE,SAAS;QACjE,MAAM,SAAS,GAAG,WAAW,GAAG,KAAK,CAAC;QACtC,IAAI,SAAS,GAAG,CAAC;YAAE,MAAM;QACzB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QAC7G,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM;QAC5B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3B,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;IACxB,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,yEAAyE;QACzE,MAAM,QAAQ,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;QAC5D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;QACjE,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC;IACzB,CAAC;IACD,OAAO,GAAG,CAAC;AAAA,CACZ;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAqB,EAAE,OAAmC,EAAc;IACzG,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7D,MAAM,YAAY,GAAG,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;IAClE,MAAM,UAAU,GAAG,iBAAiB,CAClC,YAAY,EACZ,UAAU,CAAC,CAAC,EACZ,UAAU,CAAC,CAAC,EACZ,UAAU,CAAC,KAAK,EAChB,UAAU,CAAC,SAAS,EACpB,UAAU,CAAC,KAAK,EAChB,UAAU,CAAC,CAAC,EACZ,UAAU,CAAC,WAAW,CACvB,CAAC;IACF,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC1E,OAAO,oBAAoB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;AAAA,CACrD"}

package/dist/encode/frameWriter.d.ts

@@ -1,4 +1,4 @@
 /**
  * Write zstd frame header.
  */
-export declare function writeFrameHeader(contentSize: number, hasChecksum: boolean): Uint8Array;
+export declare function writeFrameHeader(contentSize: number, hasChecksum: boolean, dictionaryId?: number | null): Uint8Array;

package/dist/encode/frameWriter.js

@@ -2,7 +2,18 @@
  * Write zstd frame header.
  */
 const ZSTD_MAGIC = 0xfd2fb528;
-export function writeFrameHeader(contentSize, hasChecksum) {
+function writeDictionaryId(chunks, dictionaryId) {
+    if (dictionaryId <= 0xff) {
+        chunks.push(dictionaryId & 0xff);
+        return;
+    }
+    if (dictionaryId <= 0xffff) {
+        chunks.push(dictionaryId & 0xff, (dictionaryId >>> 8) & 0xff);
+        return;
+    }
+    chunks.push(dictionaryId & 0xff, (dictionaryId >>> 8) & 0xff, (dictionaryId >>> 16) & 0xff, (dictionaryId >>> 24) & 0xff);
+}
+export function writeFrameHeader(contentSize, hasChecksum, dictionaryId = null) {
     const chunks = [];
     chunks.push(ZSTD_MAGIC & 0xff, (ZSTD_MAGIC >> 8) & 0xff, (ZSTD_MAGIC >> 16) & 0xff, (ZSTD_MAGIC >> 24) & 0xff);
     let fhd = 0;
@@ -18,8 +29,22 @@ export function writeFrameHeader(contentSize, hasChecksum) {
         fhd |= 2 << 6;
         fhd |= 1 << 5;
     }
+    if (dictionaryId !== null) {
+        if (!Number.isInteger(dictionaryId) || dictionaryId <= 0 || dictionaryId > 0xffff_ffff) {
+            throw new Error('Invalid dictionaryId in frame header');
+        }
+        if (dictionaryId <= 0xff)
+            fhd |= 1;
+        else if (dictionaryId <= 0xffff)
+            fhd |= 2;
+        else
+            fhd |= 3;
+    }
     fhd |= (hasChecksum ? 1 : 0) << 2;
     chunks.push(fhd);
+    if (dictionaryId !== null) {
+        writeDictionaryId(chunks, dictionaryId >>> 0);
+    }
     if (contentSize <= 255) {
         chunks.push(contentSize & 0xff);
     }

package/dist/encode/frameWriter.js.map

@@ -1 +1 @@
-{"version":3,"file":"frameWriter.js","sourceRoot":"","sources":["../../src/encode/frameWriter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B,MAAM,UAAU,gBAAgB,CAAC,WAAmB,EAAE,WAAoB,EAAc;IACtF,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,IAAI,EAAE,CAAC,UAAU,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,UAAU,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,UAAU,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAE/G,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,WAAW,IAAI,GAAG,EAAE,CAAC;QACvB,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;SAAM,IAAI,WAAW,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;SAAM,CAAC;QACN,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEjB,IAAI,WAAW,IAAI,GAAG,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAClC,CAAC;SAAM,IAAI,WAAW,IAAI,GAAG,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,CAAC,IAAI,CAAC,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,WAAW,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7E,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,EAAE,CAAC,WAAW,IAAI,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IACrH,CAAC;IAED,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;AAAA,CAC/B"}
+{"version":3,"file":"frameWriter.js","sourceRoot":"","sources":["../../src/encode/frameWriter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { type CompressOptions, compress } from './compress.js';
 export { type DecompressOptions, decompress } from './decompress.js';
+export { type DictionaryTrainingAlgorithm, type GenerateDictionaryOptions, generateDictionary, } from './dictionary/generateDictionary.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { compress } from './compress.js';
 export { decompress } from './decompress.js';
+export { generateDictionary, } from './dictionary/generateDictionary.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAA0B,UAAU,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAA0B,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAGL,kBAAkB,GACnB,MAAM,oCAAoC,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "zstdify",
   "description": "Pure TypeScript zstd compression library",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",