@yoch/frozenminisearch 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## v1.2.0 — `@yoch/frozenminisearch`
+
+Minor release: configurable MSv5 snapshot compression and Node 20 support.
+
+### Added
+
+- **`SaveBinaryOptions`** — `saveBinarySync()` / `saveBinaryAsync()` accept `{ compression: 'auto' | 'raw' | 'zstd' | 'zlib' }`.
+- **`CODEC_ZLIB`** — portable deflate snapshots readable on Node 20+; explicit `compression: 'zlib'` always writes zlib on disk.
+- **Exported types** — `BinaryCompression`, `SaveBinaryOptions`.
+
+### Improved
+
+- **`compression: 'auto'`** — one compression pass: zstd when available (Node 22.15+), otherwise zlib on Node 20–22.14, otherwise raw when compression does not strictly shrink the payload (including payloads under 64 B).
+- **Node engine** — `>=20` (was `>=22.15`); zstd remains available on Node 22.15+ and is required to read zstd snapshots.
+
 ## v1.1.0 — `@yoch/frozenminisearch`
 
 Minor release: MiniSearch JSON wire export and clearer JSON import API. MSv5 binary format unchanged.

package/README.md

@@ -5,6 +5,8 @@
 [![CI](https://github.com/yoch/frozenminisearch/actions/workflows/main.yml/badge.svg)](https://github.com/yoch/frozenminisearch/actions/workflows/main.yml)
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@yoch/frozenminisearch)](https://socket.dev/npm/package/%40yoch%2Ffrozenminisearch)
 
+[API documentation](https://yoch.github.io/frozenminisearch/)
+
 **Memory-optimized, read-only full-text search for Node.js** — the same BM25, prefix/fuzzy, and `autoSuggest` API as [MiniSearch](https://github.com/lucaong/minisearch), with **up to ~98% less index RAM** on real corpora and compact binary snapshots you ship instead of JSON.
 
 **Why it exists:** [MiniSearch](https://github.com/lucaong/minisearch) optimizes for a mutable in-memory index. FrozenMiniSearch optimizes for **retained heap, disk footprint, and cold load** once the corpus is fixed — packed radix postings, columnar `storeFields`, typed-array layouts, and MSv5 binary wire format instead of per-document JS objects.
@@ -186,7 +188,23 @@ const buf = index.saveBinarySync()
 const loaded = FrozenMiniSearch.loadBinarySync(buf, {}) // field names embedded in snapshot
 ```
 
-- **Node ≥ 22.15.0** (zstd via `node:zlib`)
+- **Node ≥ 20**
+- Default snapshot compression (`compression: 'auto'`, one pass):
+  - payloads under 64 B stay raw
+  - `zstd` on Node 22.15+ when it strictly shrinks the payload
+  - otherwise `zlib` on Node 20–22.14 when it strictly shrinks the payload
+  - otherwise `raw` (uncompressed)
+- Explicit snapshot compression always writes the chosen codec, even when compression would not shrink the payload (useful for portability):
+
+```javascript
+const portable = index.saveBinarySync({ compression: 'zlib' })
+const uncompressed = index.saveBinarySync({ compression: 'raw' })
+const bestRatio = index.saveBinarySync({ compression: 'zstd' }) // Node 22.15+
+```
+
+- Snapshot readability depends on the embedded codec:
+  - `raw` and `zlib` snapshots load on Node 20+
+  - `zstd` snapshots require Node 22.15+
 - Snapshots produced by this package version are forward-compatible; re-build from MiniSearch JSON if an older binary fails to load
 - `tokenize` / `processTerm` are not stored — pass the same functions at load when customized
 

package/dist/cjs/index.cjs

@@ -1644,9 +1644,11 @@ const FLAG_FL_U8 = 8;
 const FLAG_FL_U16 = 16;
 const FLAG_FREQ_U16 = 32;
 const CODEC_RAW = 0;
+/** Deflate/inflate (`node:zlib`) on the whole payload. */
+const CODEC_ZLIB = 1;
 /** Zstandard (`node:zlib`) on the whole payload. */
 const CODEC_ZSTD = 3;
-/** Single concatenated payload, one zstd stream (or raw). */
+/** Single concatenated payload, one compressed stream (or raw). */
 const MSV5_FORMAT_REV_PAYLOAD = 1;
 /** Do not compress payloads smaller than this (bytes). */
 const MSV5_MIN_COMPRESS_BYTES = 64;
@@ -2766,33 +2768,43 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     };
 }
 
-/** Hard cap on the uncompressed payload, rejected before allocation (zstd-bomb guard).
+/** Hard cap on the uncompressed payload, rejected before allocation (compressed-bomb guard).
  *  This is the single trust boundary for untrusted snapshots: {@link readPayloadMeta} rejects
  *  headers above this size; sync decompress uses the same cap via `maxOutputLength`.
  *  A malicious header can still declare up to 1 GiB — no tighter native limit helps without
  *  trusting `uncompressedLength` from that same header. Semantic integrity (length match,
  *  payload CRC, per-section CRC) is enforced after decode. */
 const MSV5_MAX_UNCOMPRESSED_BYTES = 1024 * 1024 * 1024;
+const MSV5_COMPRESSED_PAYLOAD_EXCEEDS_LENGTH = 'MSv5 compressed payload exceeds declared length';
+const MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH = 'MSv5 decompressed payload length mismatch';
 // zstd landed in node:zlib at Node 22.15.0 (22.x line) / 23.8.0, where the whole family
 // (zstdCompress[Sync], zstdDecompressSync, createZstdDecompress) ships together — so probing one
 // member is enough to know if the runtime supports zstd. Checked at call time (not captured at
-// module load) so it stays mockable in tests. On older runtimes we degrade gracefully: writes fall
-// back to a raw (uncompressed) payload, reads of a zstd payload throw a clear, actionable error.
+// module load) so it stays mockable in tests. On older runtimes we degrade gracefully: `auto`
+// tries zlib once (or raw if it does not help). When zstd is available, `auto` tries zstd once
+// and stays raw if it does not shrink — no second pass. Reads of a zstd payload throw a clear,
+// actionable error on runtimes without zstd.
 function zstdAvailable() {
     return typeof zlib.zstdCompressSync === 'function';
 }
+function zstdUnavailableWriteError() {
+    return new Error('MSv5 snapshot requested zstd compression, but this Node.js runtime lacks node:zlib zstd '
+        + 'support (added in Node 22.15.0). Upgrade Node.js, or use compression: "auto", "raw", '
+        + 'or "zlib".');
+}
 function zstdUnavailableReadError() {
     return new Error('MSv5 snapshot is zstd-compressed, but this Node.js runtime lacks node:zlib zstd support '
         + '(added in Node 22.15.0). Upgrade Node.js to read this snapshot, or re-save it from a '
-        + 'newer runtime to embed a raw (uncompressed) payload.');
+        + 'newer runtime with compression: "raw" or "zlib".');
 }
 let warnedZstdSaveFallback = false;
 function warnZstdSaveFallbackOnce() {
     if (warnedZstdSaveFallback)
         return;
     warnedZstdSaveFallback = true;
-    process.emitWarning('node:zlib zstd APIs are unavailable (Node.js < 22.15.0); MSv5 snapshots are written with a '
-        + 'raw (uncompressed) payload. Upgrade to Node 22.15.0+ for compressed snapshots.', { code: 'MINISEARCH_MSV5_ZSTD_UNAVAILABLE' });
+    process.emitWarning('node:zlib zstd APIs are unavailable (Node.js < 22.15.0); compression: "auto" falls back to '
+        + 'zlib when it shrinks the payload, otherwise raw (uncompressed). Upgrade to Node 22.15.0+ '
+        + 'for zstd.', { code: 'MINISEARCH_MSV5_ZSTD_UNAVAILABLE' });
 }
 function assertPayloadFormatRev(buf) {
     const rev = buf.readUInt16LE(MSV5_FORMAT_REV_OFFSET);
@@ -2842,23 +2854,26 @@ function msv5ZstdCompressOptions(uncompressed) {
         },
     };
 }
-/** Raw if below {@link MSV5_MIN_COMPRESS_BYTES}; else zstd when strictly smaller than raw. */
-function pickPayloadCodec(uncompressed, compressed) {
-    if (compressed.length < uncompressed.length) {
-        return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
-    }
+function rawPayloadChoice(uncompressed) {
     return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
 }
-function choosePayloadCodecSync(uncompressed) {
-    if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+/** Auto mode: one compression attempt; keep it only when strictly smaller than raw. */
+function pickAutoPayloadCodec(uncompressed, compressed, codec) {
+    if (compressed.length < uncompressed.length) {
+        return {
+            payload: compressed,
+            codec,
+            zstdLevel: codec === CODEC_ZSTD ? MSV5_ZSTD_LEVEL : 0,
+        };
     }
+    return rawPayloadChoice(uncompressed);
+}
+function zstdPayloadChoiceSync(uncompressed) {
     if (!zstdAvailable()) {
-        warnZstdSaveFallbackOnce();
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        throw zstdUnavailableWriteError();
     }
     const compressed = zlib.zstdCompressSync(uncompressed, msv5ZstdCompressOptions(uncompressed));
-    return pickPayloadCodec(uncompressed, compressed);
+    return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
 }
 /**
  * Async zstd via {@link zstdCompress} (not {@link zstdCompressSync}).
@@ -2877,16 +2892,91 @@ function zstdCompressAsync(uncompressed) {
         });
     });
 }
-async function choosePayloadCodecAsync(uncompressed) {
+async function zstdPayloadChoiceAsync(uncompressed) {
+    if (!zstdAvailable()) {
+        throw zstdUnavailableWriteError();
+    }
+    const compressed = await zstdCompressAsync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
+}
+function zlibPayloadChoiceSync(uncompressed) {
+    const compressed = zlib.deflateSync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZLIB, zstdLevel: 0 };
+}
+function zlibCompressAsync(uncompressed) {
+    return new Promise((resolve, reject) => {
+        zlib.deflate(uncompressed, (err, compressed) => {
+            if (err != null) {
+                reject(err);
+                return;
+            }
+            resolve(compressed);
+        });
+    });
+}
+async function zlibPayloadChoiceAsync(uncompressed) {
+    const compressed = await zlibCompressAsync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZLIB, zstdLevel: 0 };
+}
+const autoSyncCompressors = {
+    zstd: (uncompressed) => zlib.zstdCompressSync(uncompressed, msv5ZstdCompressOptions(uncompressed)),
+    zlib: (uncompressed) => zlib.deflateSync(uncompressed),
+};
+const autoAsyncCompressors = {
+    zstd: zstdCompressAsync,
+    zlib: zlibCompressAsync,
+};
+function autoPayloadChoice(uncompressed, compressors) {
     if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        return rawPayloadChoice(uncompressed);
     }
     if (!zstdAvailable()) {
         warnZstdSaveFallbackOnce();
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        return pickAutoPayloadCodec(uncompressed, compressors.zlib(uncompressed), CODEC_ZLIB);
+    }
+    return pickAutoPayloadCodec(uncompressed, compressors.zstd(uncompressed), CODEC_ZSTD);
+}
+async function autoPayloadChoiceAsync(uncompressed, compressors) {
+    if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
+        return rawPayloadChoice(uncompressed);
+    }
+    if (!zstdAvailable()) {
+        warnZstdSaveFallbackOnce();
+        return pickAutoPayloadCodec(uncompressed, await compressors.zlib(uncompressed), CODEC_ZLIB);
+    }
+    return pickAutoPayloadCodec(uncompressed, await compressors.zstd(uncompressed), CODEC_ZSTD);
+}
+function choosePayloadCodecSync(uncompressed, compression = 'auto') {
+    switch (compression) {
+        case 'raw':
+            return rawPayloadChoice(uncompressed);
+        case 'zstd':
+            return zstdPayloadChoiceSync(uncompressed);
+        case 'zlib':
+            return zlibPayloadChoiceSync(uncompressed);
+        case 'auto':
+            return autoPayloadChoice(uncompressed, autoSyncCompressors);
+        default: {
+            const _exhaustive = compression;
+            return _exhaustive;
+        }
+    }
+}
+async function choosePayloadCodecAsync(uncompressed, compression = 'auto') {
+    switch (compression) {
+        case 'raw':
+            return rawPayloadChoice(uncompressed);
+        case 'zstd':
+            return await zstdPayloadChoiceAsync(uncompressed);
+        case 'zlib':
+            return await zlibPayloadChoiceAsync(uncompressed);
+        case 'auto':
+            return await autoPayloadChoiceAsync(uncompressed, autoAsyncCompressors);
+        default: {
+            const _exhaustive = compression;
+            return _exhaustive;
+        }
     }
-    const compressed = await zstdCompressAsync(uncompressed);
-    return pickPayloadCodec(uncompressed, compressed);
 }
 function concatAndValidateSections(rawSections) {
     if (rawSections.length !== MSV5_SECTION_COUNT) {
@@ -2941,16 +3031,16 @@ function buildMsv5AssembledFile(globalFlags, entries, uncompressedLength, payloa
 }
 /**
  * MSv5 on disk: header + catalogue (uncompressed offsets) + **one** payload blob
- * (raw concatenation or a single zstd stream over it).
+ * (raw concatenation or a single compressed stream over it).
  */
-function assembleMsv5File(globalFlags, rawSections) {
+function assembleMsv5File(globalFlags, rawSections, compression = 'auto') {
     const { uncompressed, entries, payloadCrc32 } = concatAndValidateSections(rawSections);
-    const { payload, codec, zstdLevel } = choosePayloadCodecSync(uncompressed);
+    const { payload, codec, zstdLevel } = choosePayloadCodecSync(uncompressed, compression);
     return buildMsv5AssembledFile(globalFlags, entries, uncompressed.length, payloadCrc32, payload, codec, zstdLevel);
 }
-async function assembleMsv5FileAsync(globalFlags, rawSections) {
+async function assembleMsv5FileAsync(globalFlags, rawSections, compression = 'auto') {
     const { uncompressed, entries, payloadCrc32 } = concatAndValidateSections(rawSections);
-    const { payload, codec, zstdLevel } = await choosePayloadCodecAsync(uncompressed);
+    const { payload, codec, zstdLevel } = await choosePayloadCodecAsync(uncompressed, compression);
     return buildMsv5AssembledFile(globalFlags, entries, uncompressed.length, payloadCrc32, payload, codec, zstdLevel);
 }
 function readMsv5SectionDirectory(buf) {
@@ -2994,11 +3084,11 @@ function sectionsFromPayload(payload, directory, payloadCrc32) {
         return out;
     });
 }
-/** Streaming zstd reader: keeps only one section in memory at a time.
- *  No `maxOutputLength` on {@link createZstdDecompress}: output is bounded by accumulating
- *  `streamOffset` against the header's `uncompressedLength` (same 1 GiB cap checked upfront).
- *  Sync load uses `maxOutputLength` instead because it materializes the whole payload at once. */
-function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32) {
+/** Streaming compressed reader: keeps only one section in memory at a time.
+ *  No `maxOutputLength` on Transform streams: output is bounded by accumulating `streamOffset`
+ *  against the header's `uncompressedLength` (same 1 GiB cap checked upfront). Sync load uses
+ *  `maxOutputLength` because it materializes the whole payload at once. */
+function collectCompressedPayloadSections(directory, uncompressedLength, payloadCrc32) {
     if (uncompressedLength > MSV5_MAX_UNCOMPRESSED_BYTES) {
         throw new Error('MSv5 payload exceeds 1 GiB limit');
     }
@@ -3018,7 +3108,7 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     }
     function consume(chunk) {
         if (streamOffset + chunk.length > uncompressedLength) {
-            throw new Error('MSv5 zstd payload exceeds declared length');
+            throw new Error(MSV5_COMPRESSED_PAYLOAD_EXCEEDS_LENGTH);
         }
         payloadCrc = crc32Update(payloadCrc, chunk);
         let off = 0;
@@ -3054,7 +3144,7 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     function finish() {
         emitEmptySections();
         if (streamOffset !== uncompressedLength || sectionId !== directory.length) {
-            throw new Error('MSv5 zstd decompressed length mismatch');
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
         }
         if (payloadCrc !== payloadCrc32) {
             throw new Error('MSv5 payload CRC mismatch');
@@ -3063,9 +3153,15 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     return { sections, consume, finish };
 }
 function loadMsv5SectionsFromZstdStream(compressed, directory, uncompressedLength, payloadCrc32) {
+    return loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, () => zlib.createZstdDecompress());
+}
+function loadMsv5SectionsFromZlibStream(compressed, directory, uncompressedLength, payloadCrc32) {
+    return loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, () => zlib.createInflate());
+}
+function loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, createStream) {
     return new Promise((resolve, reject) => {
-        const collector = collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32);
-        const stream = zlib.createZstdDecompress();
+        const collector = collectCompressedPayloadSections(directory, uncompressedLength, payloadCrc32);
+        const stream = createStream();
         stream.on('data', (chunk) => {
             try {
                 collector.consume(chunk);
@@ -3123,29 +3219,39 @@ function preparePayload(fileBuf, directory) {
         payloadCrc32,
     };
 }
-/** Synchronous load; peak RAM ≈ full uncompressed payload (use the async path to bound it). */
-function loadMsv5Sections(fileBuf, directory) {
-    const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
-    if (payloadCodec === CODEC_RAW) {
-        return sectionsFromPayload(slice, directory, payloadCrc32);
-    }
+function decompressPayloadSync(payloadCodec, slice, uncompressedLength) {
     if (payloadCodec === CODEC_ZSTD) {
         if (!zstdAvailable()) {
             throw zstdUnavailableReadError();
         }
-        // Native cap matches readPayloadMeta's 1 GiB limit (see MSV5_MAX_UNCOMPRESSED_BYTES).
-        // Using header `uncompressedLength` here would only help when the header understates
-        // the zstd stream but the attacker can inflate the header too — same worst case.
         const decoded = zlib.zstdDecompressSync(slice, {
             maxOutputLength: MSV5_MAX_UNCOMPRESSED_BYTES,
         });
         if (decoded.length !== uncompressedLength) {
-            throw new Error('MSv5 zstd decompressed length mismatch');
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
         }
-        return sectionsFromPayload(decoded, directory, payloadCrc32);
+        return decoded;
+    }
+    if (payloadCodec === CODEC_ZLIB) {
+        const decoded = zlib.inflateSync(slice, {
+            maxOutputLength: MSV5_MAX_UNCOMPRESSED_BYTES,
+        });
+        if (decoded.length !== uncompressedLength) {
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
+        }
+        return decoded;
     }
     throw new Error(`MSv5 unknown payload codec ${payloadCodec}`);
 }
+/** Synchronous load; peak RAM ≈ full uncompressed payload (use the async path to bound it). */
+function loadMsv5Sections(fileBuf, directory) {
+    const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
+    if (payloadCodec === CODEC_RAW) {
+        return sectionsFromPayload(slice, directory, payloadCrc32);
+    }
+    const decoded = decompressPayloadSync(payloadCodec, slice, uncompressedLength);
+    return sectionsFromPayload(decoded, directory, payloadCrc32);
+}
 /** Streaming load; peak main-thread RAM ≈ largest single section (+ file buffer). */
 async function loadMsv5SectionsAsync(fileBuf, directory) {
     const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
@@ -3158,6 +3264,9 @@ async function loadMsv5SectionsAsync(fileBuf, directory) {
         }
         return loadMsv5SectionsFromZstdStream(slice, directory, uncompressedLength, payloadCrc32);
     }
+    if (payloadCodec === CODEC_ZLIB) {
+        return loadMsv5SectionsFromZlibStream(slice, directory, uncompressedLength, payloadCrc32);
+    }
     throw new Error(`MSv5 unknown payload codec ${payloadCodec}`);
 }
 function isMsv5Buffer(buf) {
@@ -3446,7 +3555,7 @@ function resolvePackedTree(snap, termTree, packedTermIndex) {
     validateTermTreeLeaves(tree, termCount);
     return fromRadixTree(tree, termCount);
 }
-function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex) {
+function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex, compression) {
     var _a;
     validateFrozenSnapshotNumeric(snap);
     const fieldNames = (_a = snap.fieldNames) !== null && _a !== void 0 ? _a : fieldNamesFromFieldIds(snap.fieldIds);
@@ -3475,9 +3584,9 @@ function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex) {
         postingsWire.docIds,
         postingsWire.freqs,
     ];
-    return assembleMsv5File(globalFlags, rawSections).buffer;
+    return assembleMsv5File(globalFlags, rawSections, compression).buffer;
 }
-async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex) {
+async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex, compression) {
     var _a;
     validateFrozenSnapshotNumeric(snap);
     const fieldNames = (_a = snap.fieldNames) !== null && _a !== void 0 ? _a : fieldNamesFromFieldIds(snap.fieldIds);
@@ -3506,7 +3615,7 @@ async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex) {
         postingsWire.docIds,
         postingsWire.freqs,
     ];
-    return (await assembleMsv5FileAsync(globalFlags, rawSections)).buffer;
+    return (await assembleMsv5FileAsync(globalFlags, rawSections, compression)).buffer;
 }
 
 function validateMsv5Container(buf) {
@@ -3583,12 +3692,12 @@ async function decodeFrozenSnapshotMsv5Async(buf, hints) {
 }
 
 /** Encode a frozen snapshot as a binary buffer. */
-function encodeFrozenSnapshot(snap, termTree, packedTermIndex) {
-    return encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex);
+function encodeFrozenSnapshot(snap, termTree, packedTermIndex, compression) {
+    return encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex, compression);
 }
-/** Async encoder; uses non-blocking zstd compression for large payloads. */
-function encodeFrozenSnapshotAsync(snap, termTree, packedTermIndex) {
-    return encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex);
+/** Async encoder; uses the selected payload compression without blocking the event loop. */
+function encodeFrozenSnapshotAsync(snap, termTree, packedTermIndex, compression) {
+    return encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex, compression);
 }
 
 const LEGACY_MAGICS = new Set(['MSv1', 'MSv2', 'MSv3', 'MSv4']);
@@ -3605,7 +3714,7 @@ function decodeFrozenSnapshot(buf, hints) {
     }
     throw invalidFrozenIndex('Unsupported frozen binary snapshot');
 }
-/** Async frozen snapshot decode (streaming zstd). */
+/** Async frozen snapshot decode (streaming decompression when needed). */
 async function decodeFrozenSnapshotAsync(buf, hints) {
     assertBufferLength(buf, 8);
     const version = buf.readUInt16LE(4);
@@ -4644,7 +4753,7 @@ class FrozenMiniSearch {
         return autoSuggestFromSearch((q, o) => this.search(q, o), queryString, merged);
     }
     /** Serialize this index as a frozen binary snapshot (synchronous). */
-    saveBinarySync() {
+    saveBinarySync(saveOptions = {}) {
         return encodeFrozenSnapshot({
             documentCount: this._documentCount,
             nextId: this._nextId,
@@ -4658,10 +4767,10 @@ class FrozenMiniSearch {
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
-        }, undefined, this._index);
+        }, undefined, this._index, saveOptions.compression);
     }
-    /** Non-blocking zstd compression; same output as {@link saveBinarySync}. */
-    async saveBinaryAsync() {
+    /** Non-blocking snapshot serialization with the selected compression codec. */
+    async saveBinaryAsync(saveOptions = {}) {
         return encodeFrozenSnapshotAsync({
             documentCount: this._documentCount,
             nextId: this._nextId,
@@ -4675,7 +4784,7 @@ class FrozenMiniSearch {
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
-        }, undefined, this._index);
+        }, undefined, this._index, saveOptions.compression);
     }
     /** Load a frozen binary snapshot. */
     static loadBinarySync(buffer, options = {}) {
@@ -4684,7 +4793,7 @@ class FrozenMiniSearch {
         const snap = decodeFrozenSnapshot(buffer, { storeFields });
         return FrozenMiniSearch.fromBinarySnapshot(snap, options);
     }
-    /** Load a frozen binary snapshot with streaming zstd decompression (bounded memory). */
+    /** Load a frozen binary snapshot with streaming decompression when needed (bounded memory). */
     static async loadBinaryAsync(buffer, options = {}) {
         var _a;
         const storeFields = (_a = options.storeFields) !== null && _a !== void 0 ? _a : defaultFrozenLoadOptions.storeFields;

package/dist/es/index.d.ts

@@ -113,7 +113,7 @@ type SearchOptionsWithDefaults = SearchOptions & {
     bm25: BM25Params;
 };
 /**
- * Configuration options passed to the {@link MiniSearch} constructor.
+ * Configuration options compatible with the MiniSearch constructor.
  *
  * @typeParam T  The type of documents being indexed.
  */
@@ -134,7 +134,7 @@ type Options<T = any> = {
     processTerm?: (term: string, fieldName?: string) => string | string[] | null | undefined | false;
     /** Function called to log messages from the library. */
     logger?: (level: LogLevel, message: string, code?: string) => void;
-    /** Auto-vacuum behaviour after {@link MiniSearch.discard}; defaults to `true`. */
+    /** Auto-vacuum behaviour after MiniSearch `discard`; defaults to `true`. */
     autoVacuum?: boolean | AutoVacuumOptions;
     /** Default search options. */
     searchOptions?: SearchOptions;
@@ -158,6 +158,20 @@ type OptionsWithDefaults<T = any> = Options<T> & {
     searchOptions: SearchOptionsWithDefaults;
     autoSuggestOptions: SearchOptions;
 };
+/** Compression codec selection for frozen binary snapshots. */
+type BinaryCompression = 'auto' | 'raw' | 'zstd' | 'zlib';
+/** Options for `saveBinarySync()` / `saveBinaryAsync()`. */
+type SaveBinaryOptions = {
+    /**
+     * Compression codec for the payload.
+     * - `auto`: one pass; payloads under 64 B stay raw; otherwise zstd when available
+     *   (else zlib on Node < 22.15), kept only when strictly smaller than raw
+     * - `raw`: never compress
+     * - `zstd`: always zstd-compress, even when larger than raw; requires Node 22.15+ to write
+     * - `zlib`: always deflate, even when larger than raw; readable on Node 20+
+     */
+    compression?: BinaryCompression;
+};
 /**
  * A search-completion suggestion.
  */
@@ -596,12 +610,12 @@ declare class FrozenMiniSearch<T = any> {
     search(query: Query, searchOptions?: SearchOptions): SearchResult[];
     autoSuggest(queryString: string, options?: SearchOptions): Suggestion[];
     /** Serialize this index as a frozen binary snapshot (synchronous). */
-    saveBinarySync(): Buffer;
-    /** Non-blocking zstd compression; same output as {@link saveBinarySync}. */
-    saveBinaryAsync(): Promise<Buffer>;
+    saveBinarySync(saveOptions?: SaveBinaryOptions): Buffer;
+    /** Non-blocking snapshot serialization with the selected compression codec. */
+    saveBinaryAsync(saveOptions?: SaveBinaryOptions): Promise<Buffer>;
     /** Load a frozen binary snapshot. */
     static loadBinarySync<T>(buffer: Buffer, options?: Options<T>): FrozenMiniSearch<T>;
-    /** Load a frozen binary snapshot with streaming zstd decompression (bounded memory). */
+    /** Load a frozen binary snapshot with streaming decompression when needed (bounded memory). */
     static loadBinaryAsync<T>(buffer: Buffer, options?: Options<T>): Promise<FrozenMiniSearch<T>>;
     private static fromBinarySnapshot;
     /** Build a read-only index in one pass from documents. */
@@ -643,4 +657,4 @@ declare class FrozenMiniSearch<T = any> {
 }
 
 export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, freezeFrozenIndexBuilder, frozenMemoryBreakdown };
-export type { BM25Params, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };
+export type { BM25Params, BinaryCompression, CombinationOperator, FrozenAssembleParams, FrozenIndexBuilderHints, FrozenMemoryBreakdown, LogLevel, LowercaseCombinationOperator, MatchInfo, MiniSearchSnapshot, Options, Query, QueryCombination, SaveBinaryOptions, SearchOptions, SearchResult, SerializedIndexEntry, Suggestion, Wildcard };

package/dist/es/index.js

@@ -1640,9 +1640,11 @@ const FLAG_FL_U8 = 8;
 const FLAG_FL_U16 = 16;
 const FLAG_FREQ_U16 = 32;
 const CODEC_RAW = 0;
+/** Deflate/inflate (`node:zlib`) on the whole payload. */
+const CODEC_ZLIB = 1;
 /** Zstandard (`node:zlib`) on the whole payload. */
 const CODEC_ZSTD = 3;
-/** Single concatenated payload, one zstd stream (or raw). */
+/** Single concatenated payload, one compressed stream (or raw). */
 const MSV5_FORMAT_REV_PAYLOAD = 1;
 /** Do not compress payloads smaller than this (bytes). */
 const MSV5_MIN_COMPRESS_BYTES = 64;
@@ -2762,33 +2764,43 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     };
 }
 
-/** Hard cap on the uncompressed payload, rejected before allocation (zstd-bomb guard).
+/** Hard cap on the uncompressed payload, rejected before allocation (compressed-bomb guard).
  *  This is the single trust boundary for untrusted snapshots: {@link readPayloadMeta} rejects
  *  headers above this size; sync decompress uses the same cap via `maxOutputLength`.
  *  A malicious header can still declare up to 1 GiB — no tighter native limit helps without
  *  trusting `uncompressedLength` from that same header. Semantic integrity (length match,
  *  payload CRC, per-section CRC) is enforced after decode. */
 const MSV5_MAX_UNCOMPRESSED_BYTES = 1024 * 1024 * 1024;
+const MSV5_COMPRESSED_PAYLOAD_EXCEEDS_LENGTH = 'MSv5 compressed payload exceeds declared length';
+const MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH = 'MSv5 decompressed payload length mismatch';
 // zstd landed in node:zlib at Node 22.15.0 (22.x line) / 23.8.0, where the whole family
 // (zstdCompress[Sync], zstdDecompressSync, createZstdDecompress) ships together — so probing one
 // member is enough to know if the runtime supports zstd. Checked at call time (not captured at
-// module load) so it stays mockable in tests. On older runtimes we degrade gracefully: writes fall
-// back to a raw (uncompressed) payload, reads of a zstd payload throw a clear, actionable error.
+// module load) so it stays mockable in tests. On older runtimes we degrade gracefully: `auto`
+// tries zlib once (or raw if it does not help). When zstd is available, `auto` tries zstd once
+// and stays raw if it does not shrink — no second pass. Reads of a zstd payload throw a clear,
+// actionable error on runtimes without zstd.
 function zstdAvailable() {
     return typeof zlib.zstdCompressSync === 'function';
 }
+function zstdUnavailableWriteError() {
+    return new Error('MSv5 snapshot requested zstd compression, but this Node.js runtime lacks node:zlib zstd '
+        + 'support (added in Node 22.15.0). Upgrade Node.js, or use compression: "auto", "raw", '
+        + 'or "zlib".');
+}
 function zstdUnavailableReadError() {
     return new Error('MSv5 snapshot is zstd-compressed, but this Node.js runtime lacks node:zlib zstd support '
         + '(added in Node 22.15.0). Upgrade Node.js to read this snapshot, or re-save it from a '
-        + 'newer runtime to embed a raw (uncompressed) payload.');
+        + 'newer runtime with compression: "raw" or "zlib".');
 }
 let warnedZstdSaveFallback = false;
 function warnZstdSaveFallbackOnce() {
     if (warnedZstdSaveFallback)
         return;
     warnedZstdSaveFallback = true;
-    process.emitWarning('node:zlib zstd APIs are unavailable (Node.js < 22.15.0); MSv5 snapshots are written with a '
-        + 'raw (uncompressed) payload. Upgrade to Node 22.15.0+ for compressed snapshots.', { code: 'MINISEARCH_MSV5_ZSTD_UNAVAILABLE' });
+    process.emitWarning('node:zlib zstd APIs are unavailable (Node.js < 22.15.0); compression: "auto" falls back to '
+        + 'zlib when it shrinks the payload, otherwise raw (uncompressed). Upgrade to Node 22.15.0+ '
+        + 'for zstd.', { code: 'MINISEARCH_MSV5_ZSTD_UNAVAILABLE' });
 }
 function assertPayloadFormatRev(buf) {
     const rev = buf.readUInt16LE(MSV5_FORMAT_REV_OFFSET);
@@ -2838,23 +2850,26 @@ function msv5ZstdCompressOptions(uncompressed) {
         },
     };
 }
-/** Raw if below {@link MSV5_MIN_COMPRESS_BYTES}; else zstd when strictly smaller than raw. */
-function pickPayloadCodec(uncompressed, compressed) {
-    if (compressed.length < uncompressed.length) {
-        return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
-    }
+function rawPayloadChoice(uncompressed) {
     return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
 }
-function choosePayloadCodecSync(uncompressed) {
-    if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+/** Auto mode: one compression attempt; keep it only when strictly smaller than raw. */
+function pickAutoPayloadCodec(uncompressed, compressed, codec) {
+    if (compressed.length < uncompressed.length) {
+        return {
+            payload: compressed,
+            codec,
+            zstdLevel: codec === CODEC_ZSTD ? MSV5_ZSTD_LEVEL : 0,
+        };
     }
+    return rawPayloadChoice(uncompressed);
+}
+function zstdPayloadChoiceSync(uncompressed) {
     if (!zstdAvailable()) {
-        warnZstdSaveFallbackOnce();
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        throw zstdUnavailableWriteError();
     }
     const compressed = zlib.zstdCompressSync(uncompressed, msv5ZstdCompressOptions(uncompressed));
-    return pickPayloadCodec(uncompressed, compressed);
+    return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
 }
 /**
  * Async zstd via {@link zstdCompress} (not {@link zstdCompressSync}).
@@ -2873,16 +2888,91 @@ function zstdCompressAsync(uncompressed) {
         });
     });
 }
-async function choosePayloadCodecAsync(uncompressed) {
+async function zstdPayloadChoiceAsync(uncompressed) {
+    if (!zstdAvailable()) {
+        throw zstdUnavailableWriteError();
+    }
+    const compressed = await zstdCompressAsync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZSTD, zstdLevel: MSV5_ZSTD_LEVEL };
+}
+function zlibPayloadChoiceSync(uncompressed) {
+    const compressed = zlib.deflateSync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZLIB, zstdLevel: 0 };
+}
+function zlibCompressAsync(uncompressed) {
+    return new Promise((resolve, reject) => {
+        zlib.deflate(uncompressed, (err, compressed) => {
+            if (err != null) {
+                reject(err);
+                return;
+            }
+            resolve(compressed);
+        });
+    });
+}
+async function zlibPayloadChoiceAsync(uncompressed) {
+    const compressed = await zlibCompressAsync(uncompressed);
+    return { payload: compressed, codec: CODEC_ZLIB, zstdLevel: 0 };
+}
+const autoSyncCompressors = {
+    zstd: (uncompressed) => zlib.zstdCompressSync(uncompressed, msv5ZstdCompressOptions(uncompressed)),
+    zlib: (uncompressed) => zlib.deflateSync(uncompressed),
+};
+const autoAsyncCompressors = {
+    zstd: zstdCompressAsync,
+    zlib: zlibCompressAsync,
+};
+function autoPayloadChoice(uncompressed, compressors) {
     if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        return rawPayloadChoice(uncompressed);
     }
     if (!zstdAvailable()) {
         warnZstdSaveFallbackOnce();
-        return { payload: uncompressed, codec: CODEC_RAW, zstdLevel: 0 };
+        return pickAutoPayloadCodec(uncompressed, compressors.zlib(uncompressed), CODEC_ZLIB);
+    }
+    return pickAutoPayloadCodec(uncompressed, compressors.zstd(uncompressed), CODEC_ZSTD);
+}
+async function autoPayloadChoiceAsync(uncompressed, compressors) {
+    if (uncompressed.length < MSV5_MIN_COMPRESS_BYTES) {
+        return rawPayloadChoice(uncompressed);
+    }
+    if (!zstdAvailable()) {
+        warnZstdSaveFallbackOnce();
+        return pickAutoPayloadCodec(uncompressed, await compressors.zlib(uncompressed), CODEC_ZLIB);
+    }
+    return pickAutoPayloadCodec(uncompressed, await compressors.zstd(uncompressed), CODEC_ZSTD);
+}
+function choosePayloadCodecSync(uncompressed, compression = 'auto') {
+    switch (compression) {
+        case 'raw':
+            return rawPayloadChoice(uncompressed);
+        case 'zstd':
+            return zstdPayloadChoiceSync(uncompressed);
+        case 'zlib':
+            return zlibPayloadChoiceSync(uncompressed);
+        case 'auto':
+            return autoPayloadChoice(uncompressed, autoSyncCompressors);
+        default: {
+            const _exhaustive = compression;
+            return _exhaustive;
+        }
+    }
+}
+async function choosePayloadCodecAsync(uncompressed, compression = 'auto') {
+    switch (compression) {
+        case 'raw':
+            return rawPayloadChoice(uncompressed);
+        case 'zstd':
+            return await zstdPayloadChoiceAsync(uncompressed);
+        case 'zlib':
+            return await zlibPayloadChoiceAsync(uncompressed);
+        case 'auto':
+            return await autoPayloadChoiceAsync(uncompressed, autoAsyncCompressors);
+        default: {
+            const _exhaustive = compression;
+            return _exhaustive;
+        }
     }
-    const compressed = await zstdCompressAsync(uncompressed);
-    return pickPayloadCodec(uncompressed, compressed);
 }
 function concatAndValidateSections(rawSections) {
     if (rawSections.length !== MSV5_SECTION_COUNT) {
@@ -2937,16 +3027,16 @@ function buildMsv5AssembledFile(globalFlags, entries, uncompressedLength, payloa
 }
 /**
  * MSv5 on disk: header + catalogue (uncompressed offsets) + **one** payload blob
- * (raw concatenation or a single zstd stream over it).
+ * (raw concatenation or a single compressed stream over it).
  */
-function assembleMsv5File(globalFlags, rawSections) {
+function assembleMsv5File(globalFlags, rawSections, compression = 'auto') {
     const { uncompressed, entries, payloadCrc32 } = concatAndValidateSections(rawSections);
-    const { payload, codec, zstdLevel } = choosePayloadCodecSync(uncompressed);
+    const { payload, codec, zstdLevel } = choosePayloadCodecSync(uncompressed, compression);
     return buildMsv5AssembledFile(globalFlags, entries, uncompressed.length, payloadCrc32, payload, codec, zstdLevel);
 }
-async function assembleMsv5FileAsync(globalFlags, rawSections) {
+async function assembleMsv5FileAsync(globalFlags, rawSections, compression = 'auto') {
     const { uncompressed, entries, payloadCrc32 } = concatAndValidateSections(rawSections);
-    const { payload, codec, zstdLevel } = await choosePayloadCodecAsync(uncompressed);
+    const { payload, codec, zstdLevel } = await choosePayloadCodecAsync(uncompressed, compression);
     return buildMsv5AssembledFile(globalFlags, entries, uncompressed.length, payloadCrc32, payload, codec, zstdLevel);
 }
 function readMsv5SectionDirectory(buf) {
@@ -2990,11 +3080,11 @@ function sectionsFromPayload(payload, directory, payloadCrc32) {
         return out;
     });
 }
-/** Streaming zstd reader: keeps only one section in memory at a time.
- *  No `maxOutputLength` on {@link createZstdDecompress}: output is bounded by accumulating
- *  `streamOffset` against the header's `uncompressedLength` (same 1 GiB cap checked upfront).
- *  Sync load uses `maxOutputLength` instead because it materializes the whole payload at once. */
-function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32) {
+/** Streaming compressed reader: keeps only one section in memory at a time.
+ *  No `maxOutputLength` on Transform streams: output is bounded by accumulating `streamOffset`
+ *  against the header's `uncompressedLength` (same 1 GiB cap checked upfront). Sync load uses
+ *  `maxOutputLength` because it materializes the whole payload at once. */
+function collectCompressedPayloadSections(directory, uncompressedLength, payloadCrc32) {
     if (uncompressedLength > MSV5_MAX_UNCOMPRESSED_BYTES) {
         throw new Error('MSv5 payload exceeds 1 GiB limit');
     }
@@ -3014,7 +3104,7 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     }
     function consume(chunk) {
         if (streamOffset + chunk.length > uncompressedLength) {
-            throw new Error('MSv5 zstd payload exceeds declared length');
+            throw new Error(MSV5_COMPRESSED_PAYLOAD_EXCEEDS_LENGTH);
         }
         payloadCrc = crc32Update(payloadCrc, chunk);
         let off = 0;
@@ -3050,7 +3140,7 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     function finish() {
         emitEmptySections();
         if (streamOffset !== uncompressedLength || sectionId !== directory.length) {
-            throw new Error('MSv5 zstd decompressed length mismatch');
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
         }
         if (payloadCrc !== payloadCrc32) {
             throw new Error('MSv5 payload CRC mismatch');
@@ -3059,9 +3149,15 @@ function collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32)
     return { sections, consume, finish };
 }
 function loadMsv5SectionsFromZstdStream(compressed, directory, uncompressedLength, payloadCrc32) {
+    return loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, () => zlib.createZstdDecompress());
+}
+function loadMsv5SectionsFromZlibStream(compressed, directory, uncompressedLength, payloadCrc32) {
+    return loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, () => zlib.createInflate());
+}
+function loadMsv5SectionsFromCompressedStream(compressed, directory, uncompressedLength, payloadCrc32, createStream) {
     return new Promise((resolve, reject) => {
-        const collector = collectZstdPayloadSections(directory, uncompressedLength, payloadCrc32);
-        const stream = zlib.createZstdDecompress();
+        const collector = collectCompressedPayloadSections(directory, uncompressedLength, payloadCrc32);
+        const stream = createStream();
         stream.on('data', (chunk) => {
             try {
                 collector.consume(chunk);
@@ -3119,29 +3215,39 @@ function preparePayload(fileBuf, directory) {
         payloadCrc32,
     };
 }
-/** Synchronous load; peak RAM ≈ full uncompressed payload (use the async path to bound it). */
-function loadMsv5Sections(fileBuf, directory) {
-    const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
-    if (payloadCodec === CODEC_RAW) {
-        return sectionsFromPayload(slice, directory, payloadCrc32);
-    }
+function decompressPayloadSync(payloadCodec, slice, uncompressedLength) {
     if (payloadCodec === CODEC_ZSTD) {
         if (!zstdAvailable()) {
             throw zstdUnavailableReadError();
         }
-        // Native cap matches readPayloadMeta's 1 GiB limit (see MSV5_MAX_UNCOMPRESSED_BYTES).
-        // Using header `uncompressedLength` here would only help when the header understates
-        // the zstd stream but the attacker can inflate the header too — same worst case.
         const decoded = zlib.zstdDecompressSync(slice, {
             maxOutputLength: MSV5_MAX_UNCOMPRESSED_BYTES,
         });
         if (decoded.length !== uncompressedLength) {
-            throw new Error('MSv5 zstd decompressed length mismatch');
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
         }
-        return sectionsFromPayload(decoded, directory, payloadCrc32);
+        return decoded;
+    }
+    if (payloadCodec === CODEC_ZLIB) {
+        const decoded = zlib.inflateSync(slice, {
+            maxOutputLength: MSV5_MAX_UNCOMPRESSED_BYTES,
+        });
+        if (decoded.length !== uncompressedLength) {
+            throw new Error(MSV5_DECOMPRESSED_PAYLOAD_LENGTH_MISMATCH);
+        }
+        return decoded;
     }
     throw new Error(`MSv5 unknown payload codec ${payloadCodec}`);
 }
+/** Synchronous load; peak RAM ≈ full uncompressed payload (use the async path to bound it). */
+function loadMsv5Sections(fileBuf, directory) {
+    const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
+    if (payloadCodec === CODEC_RAW) {
+        return sectionsFromPayload(slice, directory, payloadCrc32);
+    }
+    const decoded = decompressPayloadSync(payloadCodec, slice, uncompressedLength);
+    return sectionsFromPayload(decoded, directory, payloadCrc32);
+}
 /** Streaming load; peak main-thread RAM ≈ largest single section (+ file buffer). */
 async function loadMsv5SectionsAsync(fileBuf, directory) {
     const { payloadCodec, slice, uncompressedLength, payloadCrc32 } = preparePayload(fileBuf, directory);
@@ -3154,6 +3260,9 @@ async function loadMsv5SectionsAsync(fileBuf, directory) {
         }
         return loadMsv5SectionsFromZstdStream(slice, directory, uncompressedLength, payloadCrc32);
     }
+    if (payloadCodec === CODEC_ZLIB) {
+        return loadMsv5SectionsFromZlibStream(slice, directory, uncompressedLength, payloadCrc32);
+    }
     throw new Error(`MSv5 unknown payload codec ${payloadCodec}`);
 }
 function isMsv5Buffer(buf) {
@@ -3442,7 +3551,7 @@ function resolvePackedTree(snap, termTree, packedTermIndex) {
     validateTermTreeLeaves(tree, termCount);
     return fromRadixTree(tree, termCount);
 }
-function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex) {
+function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex, compression) {
     var _a;
     validateFrozenSnapshotNumeric(snap);
     const fieldNames = (_a = snap.fieldNames) !== null && _a !== void 0 ? _a : fieldNamesFromFieldIds(snap.fieldIds);
@@ -3471,9 +3580,9 @@ function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex) {
         postingsWire.docIds,
         postingsWire.freqs,
     ];
-    return assembleMsv5File(globalFlags, rawSections).buffer;
+    return assembleMsv5File(globalFlags, rawSections, compression).buffer;
 }
-async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex) {
+async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex, compression) {
     var _a;
     validateFrozenSnapshotNumeric(snap);
     const fieldNames = (_a = snap.fieldNames) !== null && _a !== void 0 ? _a : fieldNamesFromFieldIds(snap.fieldIds);
@@ -3502,7 +3611,7 @@ async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex) {
         postingsWire.docIds,
         postingsWire.freqs,
     ];
-    return (await assembleMsv5FileAsync(globalFlags, rawSections)).buffer;
+    return (await assembleMsv5FileAsync(globalFlags, rawSections, compression)).buffer;
 }
 
 function validateMsv5Container(buf) {
@@ -3579,12 +3688,12 @@ async function decodeFrozenSnapshotMsv5Async(buf, hints) {
 }
 
 /** Encode a frozen snapshot as a binary buffer. */
-function encodeFrozenSnapshot(snap, termTree, packedTermIndex) {
-    return encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex);
+function encodeFrozenSnapshot(snap, termTree, packedTermIndex, compression) {
+    return encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex, compression);
 }
-/** Async encoder; uses non-blocking zstd compression for large payloads. */
-function encodeFrozenSnapshotAsync(snap, termTree, packedTermIndex) {
-    return encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex);
+/** Async encoder; uses the selected payload compression without blocking the event loop. */
+function encodeFrozenSnapshotAsync(snap, termTree, packedTermIndex, compression) {
+    return encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex, compression);
 }
 
 const LEGACY_MAGICS = new Set(['MSv1', 'MSv2', 'MSv3', 'MSv4']);
@@ -3601,7 +3710,7 @@ function decodeFrozenSnapshot(buf, hints) {
     }
     throw invalidFrozenIndex('Unsupported frozen binary snapshot');
 }
-/** Async frozen snapshot decode (streaming zstd). */
+/** Async frozen snapshot decode (streaming decompression when needed). */
 async function decodeFrozenSnapshotAsync(buf, hints) {
     assertBufferLength(buf, 8);
     const version = buf.readUInt16LE(4);
@@ -4640,7 +4749,7 @@ class FrozenMiniSearch {
         return autoSuggestFromSearch((q, o) => this.search(q, o), queryString, merged);
     }
     /** Serialize this index as a frozen binary snapshot (synchronous). */
-    saveBinarySync() {
+    saveBinarySync(saveOptions = {}) {
         return encodeFrozenSnapshot({
             documentCount: this._documentCount,
             nextId: this._nextId,
@@ -4654,10 +4763,10 @@ class FrozenMiniSearch {
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
-        }, undefined, this._index);
+        }, undefined, this._index, saveOptions.compression);
     }
-    /** Non-blocking zstd compression; same output as {@link saveBinarySync}. */
-    async saveBinaryAsync() {
+    /** Non-blocking snapshot serialization with the selected compression codec. */
+    async saveBinaryAsync(saveOptions = {}) {
         return encodeFrozenSnapshotAsync({
             documentCount: this._documentCount,
             nextId: this._nextId,
@@ -4671,7 +4780,7 @@ class FrozenMiniSearch {
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
-        }, undefined, this._index);
+        }, undefined, this._index, saveOptions.compression);
     }
     /** Load a frozen binary snapshot. */
     static loadBinarySync(buffer, options = {}) {
@@ -4680,7 +4789,7 @@ class FrozenMiniSearch {
         const snap = decodeFrozenSnapshot(buffer, { storeFields });
         return FrozenMiniSearch.fromBinarySnapshot(snap, options);
     }
-    /** Load a frozen binary snapshot with streaming zstd decompression (bounded memory). */
+    /** Load a frozen binary snapshot with streaming decompression when needed (bounded memory). */
     static async loadBinaryAsync(buffer, options = {}) {
         var _a;
         const storeFields = (_a = options.storeFields) !== null && _a !== void 0 ? _a : defaultFrozenLoadOptions.storeFields;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoch/frozenminisearch",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Read-only Node.js full-text search — compact frozen indexes and binary snapshots",
   "main": "dist/cjs/index.cjs",
   "module": "dist/es/index.js",
@@ -37,7 +37,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=22.15.0"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
@@ -101,6 +101,8 @@
   "scripts": {
     "test": "jest",
     "test-watch": "jest --watch",
+    "test:fuzzysearch": "jest --testMatch='<rootDir>/dev/internal/**/*.test.(ts|js)' --testPathIgnorePatterns=/node_modules/",
+    "test:benchmarks": "jest --testMatch='<rootDir>/benchmarks/**/*.test.(ts|js)' --testPathIgnorePatterns=/node_modules/",
     "coverage": "jest --coverage",
     "bench": "npm run build && node --expose-gc benchmarks/framework/cli.mjs",
     "bench:record": "npm run build && node --expose-gc benchmarks/framework/cli.mjs record",
@@ -143,8 +145,9 @@
     "clean-build": "rm -rf dist",
     "build-minified": "MINIFY=true npm run build",
     "sync-docs-media": "node scripts/sync-docs-media.cjs",
-    "build-docs": "typedoc --options typedoc.json && npm run sync-docs-media && npm run build-demo",
-    "build-demo": "mkdir -p ./docs/demo && cp -r ./examples/plain_js/. ./docs/demo",
+    "build-docs": "node scripts/build-docs.cjs",
+    "build-docs:pages": "DOCS_PAGES=1 node scripts/build-docs.cjs",
+    "build-demo": "rm -rf ./docs/demo && mkdir -p ./docs/demo && cp -rL ./examples/plain_js/. ./docs/demo",
     "lint": "eslint 'src/**/*.{js,ts}'",
     "lintfix": "eslint --fix 'src/**/*.{js,ts}'",
     "prepublishOnly": "npm test && npm run build && node scripts/verify-npm-pack.cjs",