@structured-world/structured-zstd 0.0.33 → 0.0.35

package/index.d.ts

@@ -14,6 +14,18 @@
  * The codec is initialised lazily on first use; call {@link init} explicitly
  * to pre-warm it (e.g. before a latency-sensitive path).
  */
+/**
+ * How the decoder treats a frame's optional XXH64 content checksum. Numeric
+ * values match the wasm-bindgen `ContentChecksum` enum.
+ */
+export declare enum ContentChecksum {
+    /** Skip the XXH64 pass entirely (fastest; no verification). */
+    None = 0,
+    /** Compute the checksum and expose it via accessors; does not error on a mismatch. */
+    EmitOnly = 1,
+    /** Compute and verify; a mismatch rejects the decode. */
+    Verify = 2
+}
 /**
  * Incremental streaming decompressor handle. Feed compressed chunks with
  * {@link DecompressStream.push} and read decompressed output as it becomes
@@ -24,8 +36,22 @@
 export interface DecompressStream {
     /** Feed compressed bytes; returns decompressed output available so far. */
     push(chunk: Uint8Array): Uint8Array;
-    /** Signal end of input; returns the final bytes. Throws if incomplete. */
+    /**
+     * Signal end of input; returns the final bytes. Throws if incomplete, or
+     * (in {@link ContentChecksum.Verify} mode) if the content checksum is wrong.
+     */
     finish(): Uint8Array;
+    /**
+     * Content checksum stored in the frame trailer, or `undefined` if none.
+     * Meaningful after {@link DecompressStream.finish}.
+     */
+    storedChecksum(): number | undefined;
+    /**
+     * XXH64 digest computed over the output (low 32 bits), or `undefined` under
+     * {@link ContentChecksum.None} or when the frame carried no checksum. Lets
+     * callers verify manually under {@link ContentChecksum.EmitOnly}.
+     */
+    calculatedChecksum(): number | undefined;
     /** Release the underlying wasm handle. */
     free(): void;
 }
@@ -33,7 +59,8 @@ export interface DecompressStream {
  * Incremental streaming compressor handle. Feed plaintext chunks with
  * {@link CompressStream.push} and read complete compressed blocks as the
  * matcher window fills; call {@link CompressStream.finish} to seal the frame
- * (final block + checksum). Peak memory is O(window), not O(input) — the frame
+ * (final block, plus the 4-byte XXH64 trailer only if the stream was created
+ * with `checksum` enabled). Peak memory is O(window), not O(input) — the frame
  * is emitted block-by-block instead of buffered whole. The frame omits
  * `Frame_Content_Size` (unknown while streaming) yet decodes in any compliant
  * zstd decoder. Call {@link CompressStream.free} when done.
@@ -41,7 +68,11 @@ export interface DecompressStream {
 export interface CompressStream {
     /** Feed plaintext; returns compressed bytes complete so far (may be empty). */
     push(chunk: Uint8Array): Uint8Array;
-    /** Seal the frame; returns the final block + checksum. */
+    /**
+     * Seal the frame; returns the final block, followed by the 4-byte XXH64
+     * content-checksum trailer only when the stream was created with `checksum`
+     * enabled (otherwise just the final block, no trailer).
+     */
     finish(): Uint8Array;
     /** Release the underlying wasm handle. */
     free(): void;
@@ -55,33 +86,51 @@ export declare function init(): Promise<void>;
  * Compress `data` into a Zstandard frame at `level` (zstd scale: `1..=22`,
  * negatives for the ultra-fast tier; defaults to {@link DEFAULT_LEVEL}). The
  * frame decodes in any compliant zstd decoder, including the native C library.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
-export declare function compress(data: Uint8Array, level?: number): Promise<Uint8Array>;
+export declare function compress(data: Uint8Array, level?: number, checksum?: boolean): Promise<Uint8Array>;
 /**
  * Decompress a complete Zstandard frame. Rejects if the input is not a valid,
- * complete frame.
+ * complete frame, or — when `checksum` is {@link ContentChecksum.Verify} — if
+ * the content checksum does not match. Defaults to
+ * {@link ContentChecksum.None} (the XXH64 pass is skipped for speed); pass
+ * {@link ContentChecksum.Verify} to validate.
  */
-export declare function decompress(data: Uint8Array): Promise<Uint8Array>;
+export declare function decompress(data: Uint8Array, checksum?: ContentChecksum): Promise<Uint8Array>;
 /**
  * Compress `data` against a raw Zstandard `dict` (e.g. from `zstd --train`) at
  * `level` (defaults to {@link DEFAULT_LEVEL}). Mirrors C
  * `ZSTD_compress_usingDict` — small, similar payloads compress far better.
  * Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
-export declare function compressUsingDict(data: Uint8Array, dict: Uint8Array, level?: number): Promise<Uint8Array>;
+export declare function compressUsingDict(data: Uint8Array, dict: Uint8Array, level?: number, checksum?: boolean): Promise<Uint8Array>;
 /**
  * Decompress a dictionary-encoded frame. `dict` must be the same raw
  * dictionary used to compress it. Mirrors C `ZSTD_decompress_usingDict`.
  * Rejects on a malformed frame or dictionary mismatch.
+ *
+ * @param checksum Defaults to {@link ContentChecksum.None} (skip the XXH64
+ * pass); {@link ContentChecksum.Verify} rejects on a checksum mismatch.
  */
-export declare function decompressUsingDict(data: Uint8Array, dict: Uint8Array): Promise<Uint8Array>;
+export declare function decompressUsingDict(data: Uint8Array, dict: Uint8Array, checksum?: ContentChecksum): Promise<Uint8Array>;
 /**
  * Create an incremental streaming decompressor. Push compressed chunks and
  * read decompressed output as it arrives, then `finish()`; `free()` when done.
  * Unlike the common npm wasm zstd packages, the frame need not be fully
  * buffered — the decoder window lives on the wasm side across chunks.
+ *
+ * @param checksum Applies to the whole stream (set at construction). Defaults
+ * to {@link ContentChecksum.None}; {@link ContentChecksum.Verify} validates the
+ * content checksum at `finish()`.
  */
-export declare function createDecompressStream(): Promise<DecompressStream>;
+export declare function createDecompressStream(checksum?: ContentChecksum): Promise<DecompressStream>;
 /**
  * Create an incremental streaming compressor at `level` (zstd scale: `1..=22`,
  * negatives for the ultra-fast tier; defaults to {@link DEFAULT_LEVEL}). Push
@@ -90,6 +139,30 @@ export declare function createDecompressStream(): Promise<DecompressStream>;
  * frame is emitted block-by-block rather than buffered whole — and the result
  * decodes in any compliant zstd decoder. Symmetric with
  * {@link createDecompressStream}.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to seal the frame with a
+ * trailing XXH64 content checksum.
+ */
+export declare function createCompressStream(level?: number, checksum?: boolean): Promise<CompressStream>;
+/**
+ * Create an incremental streaming compressor seeded with a raw zstd `dict`
+ * (e.g. from `zstd --train`), at `level`. Mirrors `ZSTD_CCtx_loadDictionary` on
+ * a streaming context: the dictionary primes the matcher and the first block's
+ * entropy, so small / similar payloads compress far better. Decode the produced
+ * frames with {@link createDecompressStreamWithDictionary} (same `dict`) or the
+ * one-shot {@link decompressUsingDict}. Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false`; pass `true` for a trailing XXH64 checksum.
+ */
+export declare function createCompressStreamWithDictionary(dict: Uint8Array, level?: number, checksum?: boolean): Promise<CompressStream>;
+/**
+ * Create an incremental streaming decompressor primed with a raw zstd `dict`.
+ * `dict` must be the same dictionary the frame was compressed with (e.g. via
+ * {@link createCompressStreamWithDictionary}). Mirrors
+ * `ZSTD_DCtx_loadDictionary`. Rejects if the dictionary is malformed.
+ *
+ * @param checksum Applies to the whole stream; see {@link createDecompressStream}.
  */
-export declare function createCompressStream(level?: number): Promise<CompressStream>;
+export declare function createDecompressStreamWithDictionary(dict: Uint8Array, checksum?: ContentChecksum): Promise<DecompressStream>;
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAmBH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,0EAA0E;IAC1E,MAAM,IAAI,UAAU,CAAC;IACrB,0CAA0C;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC,0DAA0D;IAC1D,MAAM,IAAI,UAAU,CAAC;IACrB,0CAA0C;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AA2CD;;;GAGG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1C;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAsB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAGtE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAsB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAGxE;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,GAAE,MAAsB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAGzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;GAGG;AACH,oBAAY,eAAe;IACzB,+DAA+D;IAC/D,IAAI,IAAI;IACR,sFAAsF;IACtF,QAAQ,IAAI;IACZ,yDAAyD;IACzD,MAAM,IAAI;CACX;AAkCD;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC;;;OAGG;IACH,MAAM,IAAI,UAAU,CAAC;IACrB;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,SAAS,CAAC;IACrC;;;;OAIG;IACH,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAAC;IACzC,0CAA0C;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAC;IACpC;;;;OAIG;IACH,MAAM,IAAI,UAAU,CAAC;IACrB,0CAA0C;IAC1C,IAAI,IAAI,IAAI,CAAC;CACd;AA2CD;;;GAGG;AACH,wBAAsB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAG1C;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAsB,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAsB,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAG3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,GAAE,MAAsB,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kCAAkC,CACtD,IAAI,EAAE,UAAU,EAChB,KAAK,GAAE,MAAsB,EAC7B,QAAQ,CAAC,EAAE,OAAO,GACjB,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED;;;;;;;GAOG;AACH,wBAAsB,oCAAoC,CACxD,IAAI,EAAE,UAAU,EAChB,QAAQ,CAAC,EAAE,eAAe,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAG3B"}

package/index.js

@@ -15,6 +15,19 @@
  * to pre-warm it (e.g. before a latency-sensitive path).
  */
 import { simd } from "wasm-feature-detect";
+/**
+ * How the decoder treats a frame's optional XXH64 content checksum. Numeric
+ * values match the wasm-bindgen `ContentChecksum` enum.
+ */
+export var ContentChecksum;
+(function (ContentChecksum) {
+    /** Skip the XXH64 pass entirely (fastest; no verification). */
+    ContentChecksum[ContentChecksum["None"] = 0] = "None";
+    /** Compute the checksum and expose it via accessors; does not error on a mismatch. */
+    ContentChecksum[ContentChecksum["EmitOnly"] = 1] = "EmitOnly";
+    /** Compute and verify; a mismatch rejects the decode. */
+    ContentChecksum[ContentChecksum["Verify"] = 2] = "Verify";
+})(ContentChecksum || (ContentChecksum = {}));
 /** Default compression level when the caller does not pass one. */
 const DEFAULT_LEVEL = 3;
 let loaded;
@@ -64,47 +77,65 @@ export async function init() {
  * Compress `data` into a Zstandard frame at `level` (zstd scale: `1..=22`,
  * negatives for the ultra-fast tier; defaults to {@link DEFAULT_LEVEL}). The
  * frame decodes in any compliant zstd decoder, including the native C library.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
-export async function compress(data, level = DEFAULT_LEVEL) {
+export async function compress(data, level = DEFAULT_LEVEL, checksum) {
     loading ??= load();
-    return (await loading).compress(data, level);
+    return (await loading).compress(data, level, checksum);
 }
 /**
  * Decompress a complete Zstandard frame. Rejects if the input is not a valid,
- * complete frame.
+ * complete frame, or — when `checksum` is {@link ContentChecksum.Verify} — if
+ * the content checksum does not match. Defaults to
+ * {@link ContentChecksum.None} (the XXH64 pass is skipped for speed); pass
+ * {@link ContentChecksum.Verify} to validate.
  */
-export async function decompress(data) {
+export async function decompress(data, checksum) {
     loading ??= load();
-    return (await loading).decompress(data);
+    return (await loading).decompress(data, checksum);
 }
 /**
  * Compress `data` against a raw Zstandard `dict` (e.g. from `zstd --train`) at
  * `level` (defaults to {@link DEFAULT_LEVEL}). Mirrors C
  * `ZSTD_compress_usingDict` — small, similar payloads compress far better.
  * Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
-export async function compressUsingDict(data, dict, level = DEFAULT_LEVEL) {
+export async function compressUsingDict(data, dict, level = DEFAULT_LEVEL, checksum) {
     loading ??= load();
-    return (await loading).compressUsingDict(data, dict, level);
+    return (await loading).compressUsingDict(data, dict, level, checksum);
 }
 /**
  * Decompress a dictionary-encoded frame. `dict` must be the same raw
  * dictionary used to compress it. Mirrors C `ZSTD_decompress_usingDict`.
  * Rejects on a malformed frame or dictionary mismatch.
+ *
+ * @param checksum Defaults to {@link ContentChecksum.None} (skip the XXH64
+ * pass); {@link ContentChecksum.Verify} rejects on a checksum mismatch.
  */
-export async function decompressUsingDict(data, dict) {
+export async function decompressUsingDict(data, dict, checksum) {
     loading ??= load();
-    return (await loading).decompressUsingDict(data, dict);
+    return (await loading).decompressUsingDict(data, dict, checksum);
 }
 /**
  * Create an incremental streaming decompressor. Push compressed chunks and
  * read decompressed output as it arrives, then `finish()`; `free()` when done.
  * Unlike the common npm wasm zstd packages, the frame need not be fully
  * buffered — the decoder window lives on the wasm side across chunks.
+ *
+ * @param checksum Applies to the whole stream (set at construction). Defaults
+ * to {@link ContentChecksum.None}; {@link ContentChecksum.Verify} validates the
+ * content checksum at `finish()`.
  */
-export async function createDecompressStream() {
+export async function createDecompressStream(checksum) {
     loading ??= load();
-    return new (await loading).ZstdDecompressStream();
+    return new (await loading).ZstdDecompressStream(checksum);
 }
 /**
  * Create an incremental streaming compressor at `level` (zstd scale: `1..=22`,
@@ -114,9 +145,39 @@ export async function createDecompressStream() {
  * frame is emitted block-by-block rather than buffered whole — and the result
  * decodes in any compliant zstd decoder. Symmetric with
  * {@link createDecompressStream}.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to seal the frame with a
+ * trailing XXH64 content checksum.
+ */
+export async function createCompressStream(level = DEFAULT_LEVEL, checksum) {
+    loading ??= load();
+    return new (await loading).ZstdCompressStream(level, checksum);
+}
+/**
+ * Create an incremental streaming compressor seeded with a raw zstd `dict`
+ * (e.g. from `zstd --train`), at `level`. Mirrors `ZSTD_CCtx_loadDictionary` on
+ * a streaming context: the dictionary primes the matcher and the first block's
+ * entropy, so small / similar payloads compress far better. Decode the produced
+ * frames with {@link createDecompressStreamWithDictionary} (same `dict`) or the
+ * one-shot {@link decompressUsingDict}. Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false`; pass `true` for a trailing XXH64 checksum.
+ */
+export async function createCompressStreamWithDictionary(dict, level = DEFAULT_LEVEL, checksum) {
+    loading ??= load();
+    return (await loading).ZstdCompressStream.withDictionary(level, dict, checksum);
+}
+/**
+ * Create an incremental streaming decompressor primed with a raw zstd `dict`.
+ * `dict` must be the same dictionary the frame was compressed with (e.g. via
+ * {@link createCompressStreamWithDictionary}). Mirrors
+ * `ZSTD_DCtx_loadDictionary`. Rejects if the dictionary is malformed.
+ *
+ * @param checksum Applies to the whole stream; see {@link createDecompressStream}.
  */
-export async function createCompressStream(level = DEFAULT_LEVEL) {
+export async function createDecompressStreamWithDictionary(dict, checksum) {
     loading ??= load();
-    return new (await loading).ZstdCompressStream(level);
+    return (await loading).ZstdDecompressStream.withDictionary(dict, checksum);
 }
 //# sourceMappingURL=index.js.map

package/index.js.map

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

package/index.ts

@@ -17,6 +17,19 @@
 
 import { simd } from "wasm-feature-detect";
 
+/**
+ * How the decoder treats a frame's optional XXH64 content checksum. Numeric
+ * values match the wasm-bindgen `ContentChecksum` enum.
+ */
+export enum ContentChecksum {
+  /** Skip the XXH64 pass entirely (fastest; no verification). */
+  None = 0,
+  /** Compute the checksum and expose it via accessors; does not error on a mismatch. */
+  EmitOnly = 1,
+  /** Compute and verify; a mismatch rejects the decode. */
+  Verify = 2,
+}
+
 /** Shape of a wasm-pack `web`-target payload glue module (simd or scalar). */
 interface Payload {
   /** Async wasm initialiser. Accepts wasm bytes / a URL, or nothing (browser). */
@@ -24,12 +37,29 @@ interface Payload {
   // (bytes / URL / Response / Module), and Node's `fs.readFile` returns
   // `Buffer<ArrayBufferLike>`, wider than the DOM `BufferSource` in the .d.ts.
   default: (moduleOrPath?: unknown) => Promise<unknown>;
-  compress: (data: Uint8Array, level: number) => Uint8Array;
-  decompress: (data: Uint8Array) => Uint8Array;
-  compressUsingDict: (data: Uint8Array, dict: Uint8Array, level: number) => Uint8Array;
-  decompressUsingDict: (data: Uint8Array, dict: Uint8Array) => Uint8Array;
-  ZstdDecompressStream: new () => DecompressStream;
-  ZstdCompressStream: new (level: number) => CompressStream;
+  compress: (data: Uint8Array, level: number, checksum?: boolean) => Uint8Array;
+  decompress: (data: Uint8Array, checksum?: ContentChecksum) => Uint8Array;
+  compressUsingDict: (
+    data: Uint8Array,
+    dict: Uint8Array,
+    level: number,
+    checksum?: boolean,
+  ) => Uint8Array;
+  decompressUsingDict: (
+    data: Uint8Array,
+    dict: Uint8Array,
+    checksum?: ContentChecksum,
+  ) => Uint8Array;
+  ZstdDecompressStream: (new (checksum?: ContentChecksum) => DecompressStream) & {
+    withDictionary: (dict: Uint8Array, checksum?: ContentChecksum) => DecompressStream;
+  };
+  ZstdCompressStream: (new (level: number, checksum?: boolean) => CompressStream) & {
+    withDictionary: (
+      level: number,
+      dict: Uint8Array,
+      checksum?: boolean,
+    ) => CompressStream;
+  };
 }
 
 /**
@@ -42,8 +72,22 @@ interface Payload {
 export interface DecompressStream {
   /** Feed compressed bytes; returns decompressed output available so far. */
   push(chunk: Uint8Array): Uint8Array;
-  /** Signal end of input; returns the final bytes. Throws if incomplete. */
+  /**
+   * Signal end of input; returns the final bytes. Throws if incomplete, or
+   * (in {@link ContentChecksum.Verify} mode) if the content checksum is wrong.
+   */
   finish(): Uint8Array;
+  /**
+   * Content checksum stored in the frame trailer, or `undefined` if none.
+   * Meaningful after {@link DecompressStream.finish}.
+   */
+  storedChecksum(): number | undefined;
+  /**
+   * XXH64 digest computed over the output (low 32 bits), or `undefined` under
+   * {@link ContentChecksum.None} or when the frame carried no checksum. Lets
+   * callers verify manually under {@link ContentChecksum.EmitOnly}.
+   */
+  calculatedChecksum(): number | undefined;
   /** Release the underlying wasm handle. */
   free(): void;
 }
@@ -52,7 +96,8 @@ export interface DecompressStream {
  * Incremental streaming compressor handle. Feed plaintext chunks with
  * {@link CompressStream.push} and read complete compressed blocks as the
  * matcher window fills; call {@link CompressStream.finish} to seal the frame
- * (final block + checksum). Peak memory is O(window), not O(input) — the frame
+ * (final block, plus the 4-byte XXH64 trailer only if the stream was created
+ * with `checksum` enabled). Peak memory is O(window), not O(input) — the frame
  * is emitted block-by-block instead of buffered whole. The frame omits
  * `Frame_Content_Size` (unknown while streaming) yet decodes in any compliant
  * zstd decoder. Call {@link CompressStream.free} when done.
@@ -60,7 +105,11 @@ export interface DecompressStream {
 export interface CompressStream {
   /** Feed plaintext; returns compressed bytes complete so far (may be empty). */
   push(chunk: Uint8Array): Uint8Array;
-  /** Seal the frame; returns the final block + checksum. */
+  /**
+   * Seal the frame; returns the final block, followed by the 4-byte XXH64
+   * content-checksum trailer only when the stream was created with `checksum`
+   * enabled (otherwise just the final block, no trailer).
+   */
   finish(): Uint8Array;
   /** Release the underlying wasm handle. */
   free(): void;
@@ -120,22 +169,33 @@ export async function init(): Promise<void> {
  * Compress `data` into a Zstandard frame at `level` (zstd scale: `1..=22`,
  * negatives for the ultra-fast tier; defaults to {@link DEFAULT_LEVEL}). The
  * frame decodes in any compliant zstd decoder, including the native C library.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
 export async function compress(
   data: Uint8Array,
   level: number = DEFAULT_LEVEL,
+  checksum?: boolean,
 ): Promise<Uint8Array> {
   loading ??= load();
-  return (await loading).compress(data, level);
+  return (await loading).compress(data, level, checksum);
 }
 
 /**
  * Decompress a complete Zstandard frame. Rejects if the input is not a valid,
- * complete frame.
+ * complete frame, or — when `checksum` is {@link ContentChecksum.Verify} — if
+ * the content checksum does not match. Defaults to
+ * {@link ContentChecksum.None} (the XXH64 pass is skipped for speed); pass
+ * {@link ContentChecksum.Verify} to validate.
  */
-export async function decompress(data: Uint8Array): Promise<Uint8Array> {
+export async function decompress(
+  data: Uint8Array,
+  checksum?: ContentChecksum,
+): Promise<Uint8Array> {
   loading ??= load();
-  return (await loading).decompress(data);
+  return (await loading).decompress(data, checksum);
 }
 
 /**
@@ -143,27 +203,36 @@ export async function decompress(data: Uint8Array): Promise<Uint8Array> {
  * `level` (defaults to {@link DEFAULT_LEVEL}). Mirrors C
  * `ZSTD_compress_usingDict` — small, similar payloads compress far better.
  * Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to append the XXH64
+ * content checksum.
  */
 export async function compressUsingDict(
   data: Uint8Array,
   dict: Uint8Array,
   level: number = DEFAULT_LEVEL,
+  checksum?: boolean,
 ): Promise<Uint8Array> {
   loading ??= load();
-  return (await loading).compressUsingDict(data, dict, level);
+  return (await loading).compressUsingDict(data, dict, level, checksum);
 }
 
 /**
  * Decompress a dictionary-encoded frame. `dict` must be the same raw
  * dictionary used to compress it. Mirrors C `ZSTD_decompress_usingDict`.
  * Rejects on a malformed frame or dictionary mismatch.
+ *
+ * @param checksum Defaults to {@link ContentChecksum.None} (skip the XXH64
+ * pass); {@link ContentChecksum.Verify} rejects on a checksum mismatch.
  */
 export async function decompressUsingDict(
   data: Uint8Array,
   dict: Uint8Array,
+  checksum?: ContentChecksum,
 ): Promise<Uint8Array> {
   loading ??= load();
-  return (await loading).decompressUsingDict(data, dict);
+  return (await loading).decompressUsingDict(data, dict, checksum);
 }
 
 /**
@@ -171,10 +240,16 @@ export async function decompressUsingDict(
  * read decompressed output as it arrives, then `finish()`; `free()` when done.
  * Unlike the common npm wasm zstd packages, the frame need not be fully
  * buffered — the decoder window lives on the wasm side across chunks.
+ *
+ * @param checksum Applies to the whole stream (set at construction). Defaults
+ * to {@link ContentChecksum.None}; {@link ContentChecksum.Verify} validates the
+ * content checksum at `finish()`.
  */
-export async function createDecompressStream(): Promise<DecompressStream> {
+export async function createDecompressStream(
+  checksum?: ContentChecksum,
+): Promise<DecompressStream> {
   loading ??= load();
-  return new (await loading).ZstdDecompressStream();
+  return new (await loading).ZstdDecompressStream(checksum);
 }
 
 /**
@@ -185,10 +260,50 @@ export async function createDecompressStream(): Promise<DecompressStream> {
  * frame is emitted block-by-block rather than buffered whole — and the result
  * decodes in any compliant zstd decoder. Symmetric with
  * {@link createDecompressStream}.
+ *
+ * @param checksum Defaults to `false` (no trailing checksum, matching
+ * libzstd's `ZSTD_c_checksumFlag = 0`); pass `true` to seal the frame with a
+ * trailing XXH64 content checksum.
  */
 export async function createCompressStream(
   level: number = DEFAULT_LEVEL,
+  checksum?: boolean,
 ): Promise<CompressStream> {
   loading ??= load();
-  return new (await loading).ZstdCompressStream(level);
+  return new (await loading).ZstdCompressStream(level, checksum);
+}
+
+/**
+ * Create an incremental streaming compressor seeded with a raw zstd `dict`
+ * (e.g. from `zstd --train`), at `level`. Mirrors `ZSTD_CCtx_loadDictionary` on
+ * a streaming context: the dictionary primes the matcher and the first block's
+ * entropy, so small / similar payloads compress far better. Decode the produced
+ * frames with {@link createDecompressStreamWithDictionary} (same `dict`) or the
+ * one-shot {@link decompressUsingDict}. Rejects if the dictionary is invalid.
+ *
+ * @param checksum Defaults to `false`; pass `true` for a trailing XXH64 checksum.
+ */
+export async function createCompressStreamWithDictionary(
+  dict: Uint8Array,
+  level: number = DEFAULT_LEVEL,
+  checksum?: boolean,
+): Promise<CompressStream> {
+  loading ??= load();
+  return (await loading).ZstdCompressStream.withDictionary(level, dict, checksum);
+}
+
+/**
+ * Create an incremental streaming decompressor primed with a raw zstd `dict`.
+ * `dict` must be the same dictionary the frame was compressed with (e.g. via
+ * {@link createCompressStreamWithDictionary}). Mirrors
+ * `ZSTD_DCtx_loadDictionary`. Rejects if the dictionary is malformed.
+ *
+ * @param checksum Applies to the whole stream; see {@link createDecompressStream}.
+ */
+export async function createDecompressStreamWithDictionary(
+  dict: Uint8Array,
+  checksum?: ContentChecksum,
+): Promise<DecompressStream> {
+  loading ??= load();
+  return (await loading).ZstdDecompressStream.withDictionary(dict, checksum);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-world/structured-zstd",
-  "version": "0.0.33",
+  "version": "0.0.35",
   "description": "Pure-Rust Zstandard (zstd) codec compiled to WebAssembly — compress and decompress in the browser, Node.js and Deno, with automatic SIMD (simd128) acceleration and a scalar fallback. No native addons, no FFI.",
   "type": "module",
   "exports": {