@structured-world/structured-zstd 0.0.36 → 0.0.38

package/index.d.ts

@@ -165,4 +165,57 @@ export declare function createCompressStreamWithDictionary(dict: Uint8Array, lev
  * @param checksum Applies to the whole stream; see {@link createDecompressStream}.
  */
 export declare function createDecompressStreamWithDictionary(dict: Uint8Array, checksum?: ContentChecksum): Promise<DecompressStream>;
+/**
+ * A dictionary prepared once and reused across many compressions,
+ * decompressions, and streams — the recommended way to use dictionaries when
+ * more than one payload is involved.
+ *
+ * Construction parses the dictionary a single time; afterwards
+ * {@link ZstdDict.compress} reuses a primed encoder (the per-frame dictionary
+ * setup cost disappears), {@link ZstdDict.decompress} reuses one decoder
+ * workspace, and the stream factories seed from the prepared tables instead of
+ * re-parsing the blob. Raw content (no dictionary magic) is accepted; such
+ * dictionaries have `id === 0` and produced frames carry no dictionary ID.
+ *
+ * Call {@link ZstdDict.free} when done to release the wasm-side memory
+ * eagerly (it is otherwise reclaimed with the object).
+ *
+ * ```ts
+ * const dict = await ZstdDict.create(dictBytes);
+ * const frame = dict.compress(payload, 19);
+ * const back = dict.decompress(frame);
+ * const stream = dict.compressStream(19);
+ * ```
+ */
+export declare class ZstdDict {
+    private readonly inner;
+    private readonly module;
+    /** @internal */
+    private constructor();
+    /** Parse `dict` once for repeated use. Rejects if a magic-prefixed blob is corrupt. */
+    static create(dict: Uint8Array): Promise<ZstdDict>;
+    /** The dictionary ID (0 for raw content). */
+    get id(): number;
+    /**
+     * Compress `data` at `level` (defaults to {@link DEFAULT_LEVEL}). The first
+     * call at a given level primes the encoder; following calls reuse the primed
+     * state — the hot path for many small frames against one dictionary.
+     */
+    compress(data: Uint8Array, level?: number, checksum?: boolean): Uint8Array;
+    /** Decompress a frame produced with this dictionary. */
+    decompress(data: Uint8Array, checksum?: ContentChecksum): Uint8Array;
+    /**
+     * Open a streaming compressor seeded from this prepared dictionary (no
+     * per-stream re-parse). Same contract as {@link createCompressStream}.
+     */
+    compressStream(level?: number, checksum?: boolean): CompressStream;
+    /**
+     * Open a streaming decompressor against this prepared dictionary (per-stream
+     * setup is a reference-count bump). Also decodes frames whose headers omit
+     * the dictionary ID. Same contract as {@link createDecompressStream}.
+     */
+    decompressStream(checksum?: ContentChecksum): DecompressStream;
+    /** Release the wasm-side dictionary memory eagerly. */
+    free(): void;
+}
 //# 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;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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"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"}

package/index.js

@@ -180,4 +180,76 @@ export async function createDecompressStreamWithDictionary(dict, checksum) {
     loading ??= load();
     return (await loading).ZstdDecompressStream.withDictionary(dict, checksum);
 }
+/**
+ * A dictionary prepared once and reused across many compressions,
+ * decompressions, and streams — the recommended way to use dictionaries when
+ * more than one payload is involved.
+ *
+ * Construction parses the dictionary a single time; afterwards
+ * {@link ZstdDict.compress} reuses a primed encoder (the per-frame dictionary
+ * setup cost disappears), {@link ZstdDict.decompress} reuses one decoder
+ * workspace, and the stream factories seed from the prepared tables instead of
+ * re-parsing the blob. Raw content (no dictionary magic) is accepted; such
+ * dictionaries have `id === 0` and produced frames carry no dictionary ID.
+ *
+ * Call {@link ZstdDict.free} when done to release the wasm-side memory
+ * eagerly (it is otherwise reclaimed with the object).
+ *
+ * ```ts
+ * const dict = await ZstdDict.create(dictBytes);
+ * const frame = dict.compress(payload, 19);
+ * const back = dict.decompress(frame);
+ * const stream = dict.compressStream(19);
+ * ```
+ */
+export class ZstdDict {
+    inner;
+    module;
+    /** @internal */
+    constructor(inner, module) {
+        this.inner = inner;
+        this.module = module;
+    }
+    /** Parse `dict` once for repeated use. Rejects if a magic-prefixed blob is corrupt. */
+    static async create(dict) {
+        loading ??= load();
+        const module = await loading;
+        return new ZstdDict(new module.ZstdDictionary(dict), module);
+    }
+    /** The dictionary ID (0 for raw content). */
+    get id() {
+        return this.inner.id;
+    }
+    /**
+     * Compress `data` at `level` (defaults to {@link DEFAULT_LEVEL}). The first
+     * call at a given level primes the encoder; following calls reuse the primed
+     * state — the hot path for many small frames against one dictionary.
+     */
+    compress(data, level = DEFAULT_LEVEL, checksum) {
+        return this.inner.compress(data, level, checksum);
+    }
+    /** Decompress a frame produced with this dictionary. */
+    decompress(data, checksum) {
+        return this.inner.decompress(data, checksum);
+    }
+    /**
+     * Open a streaming compressor seeded from this prepared dictionary (no
+     * per-stream re-parse). Same contract as {@link createCompressStream}.
+     */
+    compressStream(level = DEFAULT_LEVEL, checksum) {
+        return this.module.ZstdCompressStream.withPreparedDictionary(level, this.inner, checksum);
+    }
+    /**
+     * Open a streaming decompressor against this prepared dictionary (per-stream
+     * setup is a reference-count bump). Also decodes frames whose headers omit
+     * the dictionary ID. Same contract as {@link createDecompressStream}.
+     */
+    decompressStream(checksum) {
+        return this.module.ZstdDecompressStream.withPreparedDictionary(this.inner, checksum);
+    }
+    /** Release the wasm-side dictionary memory eagerly. */
+    free() {
+        this.inner.free();
+    }
+}
 //# 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

@@ -52,6 +52,10 @@ interface Payload {
   ) => Uint8Array;
   ZstdDecompressStream: (new (checksum?: ContentChecksum) => DecompressStream) & {
     withDictionary: (dict: Uint8Array, checksum?: ContentChecksum) => DecompressStream;
+    withPreparedDictionary: (
+      dict: WasmDictionary,
+      checksum?: ContentChecksum,
+    ) => DecompressStream;
   };
   ZstdCompressStream: (new (level: number, checksum?: boolean) => CompressStream) & {
     withDictionary: (
@@ -59,7 +63,21 @@ interface Payload {
       dict: Uint8Array,
       checksum?: boolean,
     ) => CompressStream;
+    withPreparedDictionary: (
+      level: number,
+      dict: WasmDictionary,
+      checksum?: boolean,
+    ) => CompressStream;
   };
+  ZstdDictionary: new (dict: Uint8Array) => WasmDictionary;
+}
+
+/** Raw wasm-side prepared-dictionary handle (see {@link ZstdDict}). */
+interface WasmDictionary {
+  readonly id: number;
+  compress(data: Uint8Array, level: number, checksum?: boolean): Uint8Array;
+  decompress(data: Uint8Array, checksum?: ContentChecksum): Uint8Array;
+  free(): void;
 }
 
 /**
@@ -307,3 +325,81 @@ export async function createDecompressStreamWithDictionary(
   loading ??= load();
   return (await loading).ZstdDecompressStream.withDictionary(dict, checksum);
 }
+
+/**
+ * A dictionary prepared once and reused across many compressions,
+ * decompressions, and streams — the recommended way to use dictionaries when
+ * more than one payload is involved.
+ *
+ * Construction parses the dictionary a single time; afterwards
+ * {@link ZstdDict.compress} reuses a primed encoder (the per-frame dictionary
+ * setup cost disappears), {@link ZstdDict.decompress} reuses one decoder
+ * workspace, and the stream factories seed from the prepared tables instead of
+ * re-parsing the blob. Raw content (no dictionary magic) is accepted; such
+ * dictionaries have `id === 0` and produced frames carry no dictionary ID.
+ *
+ * Call {@link ZstdDict.free} when done to release the wasm-side memory
+ * eagerly (it is otherwise reclaimed with the object).
+ *
+ * ```ts
+ * const dict = await ZstdDict.create(dictBytes);
+ * const frame = dict.compress(payload, 19);
+ * const back = dict.decompress(frame);
+ * const stream = dict.compressStream(19);
+ * ```
+ */
+export class ZstdDict {
+  /** @internal */
+  private constructor(
+    private readonly inner: WasmDictionary,
+    private readonly module: Payload,
+  ) {}
+
+  /** Parse `dict` once for repeated use. Rejects if a magic-prefixed blob is corrupt. */
+  static async create(dict: Uint8Array): Promise<ZstdDict> {
+    loading ??= load();
+    const module = await loading;
+    return new ZstdDict(new module.ZstdDictionary(dict), module);
+  }
+
+  /** The dictionary ID (0 for raw content). */
+  get id(): number {
+    return this.inner.id;
+  }
+
+  /**
+   * Compress `data` at `level` (defaults to {@link DEFAULT_LEVEL}). The first
+   * call at a given level primes the encoder; following calls reuse the primed
+   * state — the hot path for many small frames against one dictionary.
+   */
+  compress(data: Uint8Array, level: number = DEFAULT_LEVEL, checksum?: boolean): Uint8Array {
+    return this.inner.compress(data, level, checksum);
+  }
+
+  /** Decompress a frame produced with this dictionary. */
+  decompress(data: Uint8Array, checksum?: ContentChecksum): Uint8Array {
+    return this.inner.decompress(data, checksum);
+  }
+
+  /**
+   * Open a streaming compressor seeded from this prepared dictionary (no
+   * per-stream re-parse). Same contract as {@link createCompressStream}.
+   */
+  compressStream(level: number = DEFAULT_LEVEL, checksum?: boolean): CompressStream {
+    return this.module.ZstdCompressStream.withPreparedDictionary(level, this.inner, checksum);
+  }
+
+  /**
+   * Open a streaming decompressor against this prepared dictionary (per-stream
+   * setup is a reference-count bump). Also decodes frames whose headers omit
+   * the dictionary ID. Same contract as {@link createDecompressStream}.
+   */
+  decompressStream(checksum?: ContentChecksum): DecompressStream {
+    return this.module.ZstdDecompressStream.withPreparedDictionary(this.inner, checksum);
+  }
+
+  /** Release the wasm-side dictionary memory eagerly. */
+  free(): void {
+    this.inner.free();
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structured-world/structured-zstd",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "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": {

package/scalar/structured_zstd_wasm.d.ts

@@ -62,6 +62,12 @@ export class ZstdCompressStream {
      * `decompressUsingDict`). Throws if the dictionary is invalid.
      */
     static withDictionary(level: number, dict: Uint8Array, checksum?: boolean | null): ZstdCompressStream;
+    /**
+     * Open a streaming compressor at `level` seeded from a [`ZstdDictionary`]
+     * prepared once: per-stream setup copies the prepared tables instead of
+     * re-parsing the dictionary blob (no FSE/HUF table rebuild).
+     */
+    static withPreparedDictionary(level: number, dict: ZstdDictionary, checksum?: boolean | null): ZstdCompressStream;
 }
 
 /**
@@ -112,6 +118,63 @@ export class ZstdDecompressStream {
      * dictionary is malformed.
      */
     static withDictionary(dict: Uint8Array, checksum?: ContentChecksum | null): ZstdDecompressStream;
+    /**
+     * Open a streaming decompressor against a [`ZstdDictionary`] prepared
+     * once: per-stream setup is a reference-count bump, no dictionary
+     * re-parse. Unlike [`Self::with_dictionary`] this also decodes frames
+     * whose headers omit the dictionary ID (raw-content dictionaries).
+     */
+    static withPreparedDictionary(dict: ZstdDictionary, checksum?: ContentChecksum | null): ZstdDecompressStream;
+}
+
+/**
+ * A dictionary prepared once for repeated use across compressions,
+ * decompressions, and streams — the wasm analogue of C's `ZSTD_CDict` +
+ * `ZSTD_DDict` pair behind one object.
+ *
+ * Construction parses the dictionary a single time (entropy decode tables +
+ * encoder conversion). The hot paths then avoid every per-call setup cost:
+ *
+ * * [`compress`](Self::compress) keeps a cached frame compressor whose
+ *   dictionary-primed match-finder snapshot is reused across calls — the
+ *   dominant per-frame cost for small payloads;
+ * * [`decompress`](Self::decompress) reuses one decoder workspace;
+ * * the stream constructors seed from the prepared tables (a table copy on
+ *   the encode side, a reference-count bump on the decode side) instead of
+ *   re-parsing the blob per stream.
+ *
+ * Raw content (bytes without the `0xEC30A437` dictionary magic) is accepted
+ * like upstream's auto mode: such dictionaries have ID 0 and produced frames
+ * carry no dictionary ID.
+ */
+export class ZstdDictionary {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compress `data` with this dictionary at `level` — the hot path for
+     * many small frames against one dictionary: the first call at a given
+     * level attaches the prepared tables and primes the match finder, and
+     * every following call reuses that primed snapshot.
+     *
+     * `checksum` is optional (default `false`).
+     */
+    compress(data: Uint8Array, level: number, checksum?: boolean | null): Uint8Array;
+    /**
+     * Decompress a frame produced with this dictionary, reusing the
+     * prepared tables and one decoder workspace across calls. `checksum`
+     * behaves as in the module-level `decompress`.
+     */
+    decompress(data: Uint8Array, checksum?: ContentChecksum | null): Uint8Array;
+    /**
+     * Parse `dict` once for repeated use. Magic-prefixed blobs (e.g. from
+     * `zstd --train`) parse as full dictionaries; anything else is raw
+     * content. Throws if a magic-prefixed blob is corrupt.
+     */
+    constructor(dict: Uint8Array);
+    /**
+     * The dictionary ID (0 for raw content).
+     */
+    readonly id: number;
 }
 
 /**
@@ -165,6 +228,7 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_zstdcompressstream_free: (a: number, b: number) => void;
     readonly __wbg_zstddecompressstream_free: (a: number, b: number) => void;
+    readonly __wbg_zstddictionary_free: (a: number, b: number) => void;
     readonly compress: (a: number, b: number, c: number, d: number) => [number, number];
     readonly compressUsingDict: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
     readonly decompress: (a: number, b: number, c: number) => [number, number, number, number];
@@ -173,12 +237,18 @@ export interface InitOutput {
     readonly zstdcompressstream_new: (a: number, b: number) => number;
     readonly zstdcompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
     readonly zstdcompressstream_withDictionary: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly zstdcompressstream_withPreparedDictionary: (a: number, b: number, c: number) => [number, number, number];
     readonly zstddecompressstream_calculatedChecksum: (a: number) => number;
     readonly zstddecompressstream_finish: (a: number) => [number, number, number, number];
     readonly zstddecompressstream_new: (a: number) => number;
     readonly zstddecompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
     readonly zstddecompressstream_storedChecksum: (a: number) => number;
     readonly zstddecompressstream_withDictionary: (a: number, b: number, c: number) => [number, number, number];
+    readonly zstddecompressstream_withPreparedDictionary: (a: number, b: number) => number;
+    readonly zstddictionary_compress: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly zstddictionary_decompress: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly zstddictionary_id: (a: number) => number;
+    readonly zstddictionary_new: (a: number, b: number) => [number, number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;

package/scalar/structured_zstd_wasm.js

@@ -116,6 +116,23 @@ export class ZstdCompressStream {
         }
         return ZstdCompressStream.__wrap(ret[0]);
     }
+    /**
+     * Open a streaming compressor at `level` seeded from a [`ZstdDictionary`]
+     * prepared once: per-stream setup copies the prepared tables instead of
+     * re-parsing the dictionary blob (no FSE/HUF table rebuild).
+     * @param {number} level
+     * @param {ZstdDictionary} dict
+     * @param {boolean | null} [checksum]
+     * @returns {ZstdCompressStream}
+     */
+    static withPreparedDictionary(level, dict, checksum) {
+        _assertClass(dict, ZstdDictionary);
+        const ret = wasm.zstdcompressstream_withPreparedDictionary(level, dict.__wbg_ptr, isLikeNone(checksum) ? 0xFFFFFF : checksum ? 1 : 0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ZstdCompressStream.__wrap(ret[0]);
+    }
 }
 if (Symbol.dispose) ZstdCompressStream.prototype[Symbol.dispose] = ZstdCompressStream.prototype.free;
 
@@ -227,9 +244,124 @@ export class ZstdDecompressStream {
         }
         return ZstdDecompressStream.__wrap(ret[0]);
     }
+    /**
+     * Open a streaming decompressor against a [`ZstdDictionary`] prepared
+     * once: per-stream setup is a reference-count bump, no dictionary
+     * re-parse. Unlike [`Self::with_dictionary`] this also decodes frames
+     * whose headers omit the dictionary ID (raw-content dictionaries).
+     * @param {ZstdDictionary} dict
+     * @param {ContentChecksum | null} [checksum]
+     * @returns {ZstdDecompressStream}
+     */
+    static withPreparedDictionary(dict, checksum) {
+        _assertClass(dict, ZstdDictionary);
+        const ret = wasm.zstddecompressstream_withPreparedDictionary(dict.__wbg_ptr, isLikeNone(checksum) ? 3 : checksum);
+        return ZstdDecompressStream.__wrap(ret);
+    }
 }
 if (Symbol.dispose) ZstdDecompressStream.prototype[Symbol.dispose] = ZstdDecompressStream.prototype.free;
 
+/**
+ * A dictionary prepared once for repeated use across compressions,
+ * decompressions, and streams — the wasm analogue of C's `ZSTD_CDict` +
+ * `ZSTD_DDict` pair behind one object.
+ *
+ * Construction parses the dictionary a single time (entropy decode tables +
+ * encoder conversion). The hot paths then avoid every per-call setup cost:
+ *
+ * * [`compress`](Self::compress) keeps a cached frame compressor whose
+ *   dictionary-primed match-finder snapshot is reused across calls — the
+ *   dominant per-frame cost for small payloads;
+ * * [`decompress`](Self::decompress) reuses one decoder workspace;
+ * * the stream constructors seed from the prepared tables (a table copy on
+ *   the encode side, a reference-count bump on the decode side) instead of
+ *   re-parsing the blob per stream.
+ *
+ * Raw content (bytes without the `0xEC30A437` dictionary magic) is accepted
+ * like upstream's auto mode: such dictionaries have ID 0 and produced frames
+ * carry no dictionary ID.
+ */
+export class ZstdDictionary {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ZstdDictionaryFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_zstddictionary_free(ptr, 0);
+    }
+    /**
+     * Compress `data` with this dictionary at `level` — the hot path for
+     * many small frames against one dictionary: the first call at a given
+     * level attaches the prepared tables and primes the match finder, and
+     * every following call reuses that primed snapshot.
+     *
+     * `checksum` is optional (default `false`).
+     * @param {Uint8Array} data
+     * @param {number} level
+     * @param {boolean | null} [checksum]
+     * @returns {Uint8Array}
+     */
+    compress(data, level, checksum) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_compress(this.__wbg_ptr, ptr0, len0, level, isLikeNone(checksum) ? 0xFFFFFF : checksum ? 1 : 0);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
+    /**
+     * Decompress a frame produced with this dictionary, reusing the
+     * prepared tables and one decoder workspace across calls. `checksum`
+     * behaves as in the module-level `decompress`.
+     * @param {Uint8Array} data
+     * @param {ContentChecksum | null} [checksum]
+     * @returns {Uint8Array}
+     */
+    decompress(data, checksum) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_decompress(this.__wbg_ptr, ptr0, len0, isLikeNone(checksum) ? 3 : checksum);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
+    /**
+     * The dictionary ID (0 for raw content).
+     * @returns {number}
+     */
+    get id() {
+        const ret = wasm.zstddictionary_id(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Parse `dict` once for repeated use. Magic-prefixed blobs (e.g. from
+     * `zstd --train`) parse as full dictionaries; anything else is raw
+     * content. Throws if a magic-prefixed blob is corrupt.
+     * @param {Uint8Array} dict
+     */
+    constructor(dict) {
+        const ptr0 = passArray8ToWasm0(dict, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        ZstdDictionaryFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) ZstdDictionary.prototype[Symbol.dispose] = ZstdDictionary.prototype.free;
+
 /**
  * Compress `data` into a standard Zstandard frame at compression `level`.
  *
@@ -334,11 +466,11 @@ export function decompressUsingDict(data, dict, checksum) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_9dc85fe1bc224456: function(arg0, arg1) {
+        __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg___wbindgen_throw_bbadd78c1bac3a77: function(arg0, arg1) {
+        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
         __wbindgen_init_externref_table: function() {
@@ -363,6 +495,15 @@ const ZstdCompressStreamFinalization = (typeof FinalizationRegistry === 'undefin
 const ZstdDecompressStreamFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_zstddecompressstream_free(ptr, 1));
+const ZstdDictionaryFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_zstddictionary_free(ptr, 1));
+
+function _assertClass(instance, klass) {
+    if (!(instance instanceof klass)) {
+        throw new Error(`expected instance of ${klass.name}`);
+    }
+}
 
 function getArrayU8FromWasm0(ptr, len) {
     ptr = ptr >>> 0;

package/scalar/structured_zstd_wasm_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_zstdcompressstream_free: (a: number, b: number) => void;
 export const __wbg_zstddecompressstream_free: (a: number, b: number) => void;
+export const __wbg_zstddictionary_free: (a: number, b: number) => void;
 export const compress: (a: number, b: number, c: number, d: number) => [number, number];
 export const compressUsingDict: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
 export const decompress: (a: number, b: number, c: number) => [number, number, number, number];
@@ -11,12 +12,18 @@ export const zstdcompressstream_finish: (a: number) => [number, number, number,
 export const zstdcompressstream_new: (a: number, b: number) => number;
 export const zstdcompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
 export const zstdcompressstream_withDictionary: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const zstdcompressstream_withPreparedDictionary: (a: number, b: number, c: number) => [number, number, number];
 export const zstddecompressstream_calculatedChecksum: (a: number) => number;
 export const zstddecompressstream_finish: (a: number) => [number, number, number, number];
 export const zstddecompressstream_new: (a: number) => number;
 export const zstddecompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
 export const zstddecompressstream_storedChecksum: (a: number) => number;
 export const zstddecompressstream_withDictionary: (a: number, b: number, c: number) => [number, number, number];
+export const zstddecompressstream_withPreparedDictionary: (a: number, b: number) => number;
+export const zstddictionary_compress: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const zstddictionary_decompress: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const zstddictionary_id: (a: number) => number;
+export const zstddictionary_new: (a: number, b: number) => [number, number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;

package/simd/structured_zstd_wasm.d.ts

@@ -62,6 +62,12 @@ export class ZstdCompressStream {
      * `decompressUsingDict`). Throws if the dictionary is invalid.
      */
     static withDictionary(level: number, dict: Uint8Array, checksum?: boolean | null): ZstdCompressStream;
+    /**
+     * Open a streaming compressor at `level` seeded from a [`ZstdDictionary`]
+     * prepared once: per-stream setup copies the prepared tables instead of
+     * re-parsing the dictionary blob (no FSE/HUF table rebuild).
+     */
+    static withPreparedDictionary(level: number, dict: ZstdDictionary, checksum?: boolean | null): ZstdCompressStream;
 }
 
 /**
@@ -112,6 +118,63 @@ export class ZstdDecompressStream {
      * dictionary is malformed.
      */
     static withDictionary(dict: Uint8Array, checksum?: ContentChecksum | null): ZstdDecompressStream;
+    /**
+     * Open a streaming decompressor against a [`ZstdDictionary`] prepared
+     * once: per-stream setup is a reference-count bump, no dictionary
+     * re-parse. Unlike [`Self::with_dictionary`] this also decodes frames
+     * whose headers omit the dictionary ID (raw-content dictionaries).
+     */
+    static withPreparedDictionary(dict: ZstdDictionary, checksum?: ContentChecksum | null): ZstdDecompressStream;
+}
+
+/**
+ * A dictionary prepared once for repeated use across compressions,
+ * decompressions, and streams — the wasm analogue of C's `ZSTD_CDict` +
+ * `ZSTD_DDict` pair behind one object.
+ *
+ * Construction parses the dictionary a single time (entropy decode tables +
+ * encoder conversion). The hot paths then avoid every per-call setup cost:
+ *
+ * * [`compress`](Self::compress) keeps a cached frame compressor whose
+ *   dictionary-primed match-finder snapshot is reused across calls — the
+ *   dominant per-frame cost for small payloads;
+ * * [`decompress`](Self::decompress) reuses one decoder workspace;
+ * * the stream constructors seed from the prepared tables (a table copy on
+ *   the encode side, a reference-count bump on the decode side) instead of
+ *   re-parsing the blob per stream.
+ *
+ * Raw content (bytes without the `0xEC30A437` dictionary magic) is accepted
+ * like upstream's auto mode: such dictionaries have ID 0 and produced frames
+ * carry no dictionary ID.
+ */
+export class ZstdDictionary {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Compress `data` with this dictionary at `level` — the hot path for
+     * many small frames against one dictionary: the first call at a given
+     * level attaches the prepared tables and primes the match finder, and
+     * every following call reuses that primed snapshot.
+     *
+     * `checksum` is optional (default `false`).
+     */
+    compress(data: Uint8Array, level: number, checksum?: boolean | null): Uint8Array;
+    /**
+     * Decompress a frame produced with this dictionary, reusing the
+     * prepared tables and one decoder workspace across calls. `checksum`
+     * behaves as in the module-level `decompress`.
+     */
+    decompress(data: Uint8Array, checksum?: ContentChecksum | null): Uint8Array;
+    /**
+     * Parse `dict` once for repeated use. Magic-prefixed blobs (e.g. from
+     * `zstd --train`) parse as full dictionaries; anything else is raw
+     * content. Throws if a magic-prefixed blob is corrupt.
+     */
+    constructor(dict: Uint8Array);
+    /**
+     * The dictionary ID (0 for raw content).
+     */
+    readonly id: number;
 }
 
 /**
@@ -165,6 +228,7 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_zstdcompressstream_free: (a: number, b: number) => void;
     readonly __wbg_zstddecompressstream_free: (a: number, b: number) => void;
+    readonly __wbg_zstddictionary_free: (a: number, b: number) => void;
     readonly compress: (a: number, b: number, c: number, d: number) => [number, number];
     readonly compressUsingDict: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
     readonly decompress: (a: number, b: number, c: number) => [number, number, number, number];
@@ -173,12 +237,18 @@ export interface InitOutput {
     readonly zstdcompressstream_new: (a: number, b: number) => number;
     readonly zstdcompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
     readonly zstdcompressstream_withDictionary: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly zstdcompressstream_withPreparedDictionary: (a: number, b: number, c: number) => [number, number, number];
     readonly zstddecompressstream_calculatedChecksum: (a: number) => number;
     readonly zstddecompressstream_finish: (a: number) => [number, number, number, number];
     readonly zstddecompressstream_new: (a: number) => number;
     readonly zstddecompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
     readonly zstddecompressstream_storedChecksum: (a: number) => number;
     readonly zstddecompressstream_withDictionary: (a: number, b: number, c: number) => [number, number, number];
+    readonly zstddecompressstream_withPreparedDictionary: (a: number, b: number) => number;
+    readonly zstddictionary_compress: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly zstddictionary_decompress: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly zstddictionary_id: (a: number) => number;
+    readonly zstddictionary_new: (a: number, b: number) => [number, number, number];
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;

package/simd/structured_zstd_wasm.js

@@ -116,6 +116,23 @@ export class ZstdCompressStream {
         }
         return ZstdCompressStream.__wrap(ret[0]);
     }
+    /**
+     * Open a streaming compressor at `level` seeded from a [`ZstdDictionary`]
+     * prepared once: per-stream setup copies the prepared tables instead of
+     * re-parsing the dictionary blob (no FSE/HUF table rebuild).
+     * @param {number} level
+     * @param {ZstdDictionary} dict
+     * @param {boolean | null} [checksum]
+     * @returns {ZstdCompressStream}
+     */
+    static withPreparedDictionary(level, dict, checksum) {
+        _assertClass(dict, ZstdDictionary);
+        const ret = wasm.zstdcompressstream_withPreparedDictionary(level, dict.__wbg_ptr, isLikeNone(checksum) ? 0xFFFFFF : checksum ? 1 : 0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ZstdCompressStream.__wrap(ret[0]);
+    }
 }
 if (Symbol.dispose) ZstdCompressStream.prototype[Symbol.dispose] = ZstdCompressStream.prototype.free;
 
@@ -227,9 +244,124 @@ export class ZstdDecompressStream {
         }
         return ZstdDecompressStream.__wrap(ret[0]);
     }
+    /**
+     * Open a streaming decompressor against a [`ZstdDictionary`] prepared
+     * once: per-stream setup is a reference-count bump, no dictionary
+     * re-parse. Unlike [`Self::with_dictionary`] this also decodes frames
+     * whose headers omit the dictionary ID (raw-content dictionaries).
+     * @param {ZstdDictionary} dict
+     * @param {ContentChecksum | null} [checksum]
+     * @returns {ZstdDecompressStream}
+     */
+    static withPreparedDictionary(dict, checksum) {
+        _assertClass(dict, ZstdDictionary);
+        const ret = wasm.zstddecompressstream_withPreparedDictionary(dict.__wbg_ptr, isLikeNone(checksum) ? 3 : checksum);
+        return ZstdDecompressStream.__wrap(ret);
+    }
 }
 if (Symbol.dispose) ZstdDecompressStream.prototype[Symbol.dispose] = ZstdDecompressStream.prototype.free;
 
+/**
+ * A dictionary prepared once for repeated use across compressions,
+ * decompressions, and streams — the wasm analogue of C's `ZSTD_CDict` +
+ * `ZSTD_DDict` pair behind one object.
+ *
+ * Construction parses the dictionary a single time (entropy decode tables +
+ * encoder conversion). The hot paths then avoid every per-call setup cost:
+ *
+ * * [`compress`](Self::compress) keeps a cached frame compressor whose
+ *   dictionary-primed match-finder snapshot is reused across calls — the
+ *   dominant per-frame cost for small payloads;
+ * * [`decompress`](Self::decompress) reuses one decoder workspace;
+ * * the stream constructors seed from the prepared tables (a table copy on
+ *   the encode side, a reference-count bump on the decode side) instead of
+ *   re-parsing the blob per stream.
+ *
+ * Raw content (bytes without the `0xEC30A437` dictionary magic) is accepted
+ * like upstream's auto mode: such dictionaries have ID 0 and produced frames
+ * carry no dictionary ID.
+ */
+export class ZstdDictionary {
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ZstdDictionaryFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_zstddictionary_free(ptr, 0);
+    }
+    /**
+     * Compress `data` with this dictionary at `level` — the hot path for
+     * many small frames against one dictionary: the first call at a given
+     * level attaches the prepared tables and primes the match finder, and
+     * every following call reuses that primed snapshot.
+     *
+     * `checksum` is optional (default `false`).
+     * @param {Uint8Array} data
+     * @param {number} level
+     * @param {boolean | null} [checksum]
+     * @returns {Uint8Array}
+     */
+    compress(data, level, checksum) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_compress(this.__wbg_ptr, ptr0, len0, level, isLikeNone(checksum) ? 0xFFFFFF : checksum ? 1 : 0);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
+    /**
+     * Decompress a frame produced with this dictionary, reusing the
+     * prepared tables and one decoder workspace across calls. `checksum`
+     * behaves as in the module-level `decompress`.
+     * @param {Uint8Array} data
+     * @param {ContentChecksum | null} [checksum]
+     * @returns {Uint8Array}
+     */
+    decompress(data, checksum) {
+        const ptr0 = passArray8ToWasm0(data, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_decompress(this.__wbg_ptr, ptr0, len0, isLikeNone(checksum) ? 3 : checksum);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v2;
+    }
+    /**
+     * The dictionary ID (0 for raw content).
+     * @returns {number}
+     */
+    get id() {
+        const ret = wasm.zstddictionary_id(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Parse `dict` once for repeated use. Magic-prefixed blobs (e.g. from
+     * `zstd --train`) parse as full dictionaries; anything else is raw
+     * content. Throws if a magic-prefixed blob is corrupt.
+     * @param {Uint8Array} dict
+     */
+    constructor(dict) {
+        const ptr0 = passArray8ToWasm0(dict, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.zstddictionary_new(ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        this.__wbg_ptr = ret[0];
+        ZstdDictionaryFinalization.register(this, this.__wbg_ptr, this);
+        return this;
+    }
+}
+if (Symbol.dispose) ZstdDictionary.prototype[Symbol.dispose] = ZstdDictionary.prototype.free;
+
 /**
  * Compress `data` into a standard Zstandard frame at compression `level`.
  *
@@ -334,11 +466,11 @@ export function decompressUsingDict(data, dict, checksum) {
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_9dc85fe1bc224456: function(arg0, arg1) {
+        __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return ret;
         },
-        __wbg___wbindgen_throw_bbadd78c1bac3a77: function(arg0, arg1) {
+        __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
         __wbindgen_init_externref_table: function() {
@@ -363,6 +495,15 @@ const ZstdCompressStreamFinalization = (typeof FinalizationRegistry === 'undefin
 const ZstdDecompressStreamFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_zstddecompressstream_free(ptr, 1));
+const ZstdDictionaryFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_zstddictionary_free(ptr, 1));
+
+function _assertClass(instance, klass) {
+    if (!(instance instanceof klass)) {
+        throw new Error(`expected instance of ${klass.name}`);
+    }
+}
 
 function getArrayU8FromWasm0(ptr, len) {
     ptr = ptr >>> 0;

package/simd/structured_zstd_wasm_bg.wasm.d.ts

@@ -3,6 +3,7 @@
 export const memory: WebAssembly.Memory;
 export const __wbg_zstdcompressstream_free: (a: number, b: number) => void;
 export const __wbg_zstddecompressstream_free: (a: number, b: number) => void;
+export const __wbg_zstddictionary_free: (a: number, b: number) => void;
 export const compress: (a: number, b: number, c: number, d: number) => [number, number];
 export const compressUsingDict: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
 export const decompress: (a: number, b: number, c: number) => [number, number, number, number];
@@ -11,12 +12,18 @@ export const zstdcompressstream_finish: (a: number) => [number, number, number,
 export const zstdcompressstream_new: (a: number, b: number) => number;
 export const zstdcompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
 export const zstdcompressstream_withDictionary: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const zstdcompressstream_withPreparedDictionary: (a: number, b: number, c: number) => [number, number, number];
 export const zstddecompressstream_calculatedChecksum: (a: number) => number;
 export const zstddecompressstream_finish: (a: number) => [number, number, number, number];
 export const zstddecompressstream_new: (a: number) => number;
 export const zstddecompressstream_push: (a: number, b: number, c: number) => [number, number, number, number];
 export const zstddecompressstream_storedChecksum: (a: number) => number;
 export const zstddecompressstream_withDictionary: (a: number, b: number, c: number) => [number, number, number];
+export const zstddecompressstream_withPreparedDictionary: (a: number, b: number) => number;
+export const zstddictionary_compress: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const zstddictionary_decompress: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const zstddictionary_id: (a: number) => number;
+export const zstddictionary_new: (a: number, b: number) => [number, number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_free: (a: number, b: number, c: number) => void;