@yoch/frozenminisearch 1.0.2 → 1.2.0

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;
@@ -1938,7 +1940,7 @@ function postingsTypedBytes(layout) {
         slotCount,
     };
 }
-function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = detail => { throw new Error(detail); }) {
+function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = (detail) => { throw new Error(detail); }) {
     if (layout.fieldCount <= 0)
         fail('fieldCount must be positive');
     if (layout.nextId !== nextId)
@@ -2209,7 +2211,7 @@ function forEachDefaultToken(text, onToken) {
 /** Default tokenizer into a reusable buffer (avoids `text.split()` array allocation). */
 function tokenizeDefaultInto(out, text) {
     out.length = 0;
-    forEachDefaultToken(text, (token) => out.push(token));
+    forEachDefaultToken(text, token => out.push(token));
 }
 /** Tokenize field text into `out` (reused). Fast path when `tokenize` is the library default. */
 function tokenizeFieldInto(out, tokenize, text, fieldName) {
@@ -2288,7 +2290,7 @@ function validateFrozenSnapshotNumeric(snap) {
     if (snap.avgFieldLength.length !== snap.fieldCount) {
         throw invalidFrozenIndex('avgFieldLength size mismatch');
     }
-    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, detail => {
+    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, (detail) => {
         throw invalidFrozenIndex(detail);
     });
     const indexedFields = Object.keys(snap.fieldIds);
@@ -2503,7 +2505,7 @@ function cloneStoredFields(layout) {
     }
     return { kind: 'multi', rows: layout.rows.slice() };
 }
-/** Import from wire rows or lucaong snapshot. Empty storeFields + non-empty rows → multi (binary load without options). */
+/** Import from wire rows or MiniSearch snapshot. Empty storeFields + non-empty rows → multi (binary load without options). */
 function storedFieldsFromRows(rows, storeFields) {
     if (storeFields.length === 0) {
         const hasAny = rows.some(row => row != null && Object.keys(row).length > 0);
@@ -2687,7 +2689,7 @@ function buildFlatPostingsFromSearchableMap(searchableMap, fieldCount, nextId, s
     });
     return { termCount, index: packedIndex, postings };
 }
-/** Build frozen assemble params from a lucaong MiniSearch JSON snapshot. */
+/** Build frozen assemble params from a MiniSearch JSON snapshot. */
 function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     var _a, _b, _c;
     if (!SUPPORTED_SERIALIZATION_VERSIONS.has(snapshot.serializationVersion)) {
@@ -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 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 sectionsFromPayload(decoded, directory, payloadCrc32);
+        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']);
@@ -3601,11 +3710,11 @@ function decodeFrozenSnapshot(buf, hints) {
         return decodeFrozenSnapshotMsv5(buf, hints);
     }
     if (LEGACY_MAGICS.has(magic)) {
-        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from lucaong JSON');
+        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from MiniSearch JSON');
     }
     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);
@@ -4302,7 +4411,7 @@ function executeQueryInternal(query, searchOptions, params, allowedDocs, run) {
         return executeWildcardQuery(searchOptions, params);
     }
     if (isQueryCombination(query)) {
-        // Spread inherits parent combineWith into child branches (lucaong 7.2 behavior).
+        // Spread inherits parent combineWith into child branches (MiniSearch 7.2 behavior).
         const options = { ...searchOptions, ...query, queries: undefined };
         const operator = ((_b = (_a = query.combineWith) !== null && _a !== void 0 ? _a : options.combineWith) !== null && _b !== void 0 ? _b : params.globalSearchOptions.combineWith);
         if (useGatedEvaluation(run, query.queries.length, operator, combinationHasWildcard(query))) {
@@ -4352,6 +4461,73 @@ function autoSuggestFromSearch(search, queryString, options = {}) {
     return suggestFromSearchResults(search(queryString, options));
 }
 
+/** Visit shortIds with a defined external id (holes in `externalIds` are skipped). */
+function forEachLiveShortId(nextId, externalIds, callback) {
+    for (let shortId = 0; shortId < nextId; shortId++) {
+        const externalId = externalIds[shortId];
+        if (externalId === undefined)
+            continue;
+        callback(shortId, externalId);
+    }
+}
+
+/**
+ * Build a MiniSearch `toJSON` wire snapshot (`serializationVersion: 2`) from frozen index parts.
+ * Alloc-heavy (plain objects per term/field) — migration/interop only, not production persistence.
+ * All input parts must belong to the same frozen index instance.
+ */
+function miniSearchSnapshotFromFrozen(input) {
+    const { documentCount, nextId, fieldIds, fieldCount, externalIds, fieldLengthMatrix, avgFieldLength, storedFields, index, fieldTermFlyweight, } = input;
+    const documentIds = {};
+    const fieldLength = {};
+    const storedFieldsOut = {};
+    const hasStoredFields = storedFields.kind !== 'none';
+    forEachLiveShortId(nextId, externalIds, (shortId, externalId) => {
+        var _a;
+        const shortIdStr = String(shortId);
+        documentIds[shortIdStr] = externalId;
+        const lengths = new Array(fieldCount);
+        const rowBase = shortId * fieldCount;
+        for (let f = 0; f < fieldCount; f++) {
+            lengths[f] = (_a = fieldLengthMatrix[rowBase + f]) !== null && _a !== void 0 ? _a : 0;
+        }
+        fieldLength[shortIdStr] = lengths;
+        if (hasStoredFields) {
+            storedFieldsOut[shortIdStr] = readStoredFields(storedFields, shortId);
+        }
+    });
+    const indexEntries = [];
+    for (const [term, termIndex] of index.entries()) {
+        fieldTermFlyweight.bind(termIndex);
+        const fieldData = {};
+        for (let f = 0; f < fieldCount; f++) {
+            const segment = fieldTermFlyweight.get(f);
+            if (segment == null || segment.size === 0)
+                continue;
+            const entry = {};
+            segment.forEachDoc((docId, freq) => {
+                entry[String(docId)] = freq;
+            });
+            fieldData[String(f)] = entry;
+        }
+        if (Object.keys(fieldData).length > 0) {
+            indexEntries.push([term, fieldData]);
+        }
+    }
+    return {
+        documentCount,
+        nextId,
+        documentIds,
+        fieldIds,
+        fieldLength,
+        averageFieldLength: Array.from(avgFieldLength),
+        storedFields: storedFieldsOut,
+        dirtCount: 0,
+        index: indexEntries,
+        serializationVersion: 2,
+    };
+}
+
 function ownedIndexArray(arr) {
     if (arr instanceof Uint8Array)
         return new Uint8Array(arr);
@@ -4510,12 +4686,9 @@ class FrozenMiniSearch {
             tokenize: this._options.tokenize,
             processTerm: this._options.processTerm,
             indexView: createFrozenQueryIndexView(this._index, this._postings, this._fieldTermFlyweight, (callback) => {
-                for (let shortId = 0; shortId < this._nextId; shortId++) {
-                    const id = this._externalIds[shortId];
-                    if (id === undefined)
-                        continue;
+                forEachLiveShortId(this._nextId, this._externalIds, (shortId, id) => {
                     callback(shortId, id, readStoredFields(this._storedFields, shortId));
-                }
+                });
             }),
             aggregateContext: this._aggregateContext,
         };
@@ -4580,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,
@@ -4594,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,
@@ -4611,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 = {}) {
@@ -4620,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;
@@ -4669,21 +4842,43 @@ class FrozenMiniSearch {
         return buildFrozenFromDocuments(documents, options);
     }
     /**
-     * Convert a lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format) into a
-     * frozen index. No runtime dependency on the `minisearch` package.
+     * Export this index as a MiniSearch wire snapshot (`serializationVersion: 2`).
+     * Use for migration or interchange with the `minisearch` package (`JSON.stringify` works via this method).
+     * Not the primary persistence format — prefer {@link saveBinarySync} for production (size and load time).
+     * Term order in `index` may differ from MiniSearch native `toJSON`; search scores stay equivalent.
+     */
+    toJSON() {
+        return miniSearchSnapshotFromFrozen({
+            documentCount: this._documentCount,
+            nextId: this._nextId,
+            fieldIds: this._fieldIds,
+            fieldCount: this._fieldCount,
+            externalIds: this._externalIds,
+            fieldLengthMatrix: this._fieldLengthMatrix,
+            avgFieldLength: this._avgFieldLength,
+            storedFields: this._storedFields,
+            index: this._index,
+            fieldTermFlyweight: this._fieldTermFlyweight,
+        });
+    }
+    /**
+     * Build a new frozen index **from** a MiniSearch JSON snapshot string (import / migration).
+     * Accepts the wire format produced by MiniSearch `toJSON` or by {@link toJSON} on this class.
+     * Distinct from {@link loadBinarySync}: JSON is MiniSearch interchange, not the native frozen binary.
+     * No runtime dependency on the `minisearch` package.
      */
-    static fromMiniSearchJson(json, options = {}) {
+    static fromJson(json, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(JSON.parse(json), options);
     }
     /**
-     * Same as {@link fromMiniSearchJson} with a pre-parsed snapshot object.
+     * Same as {@link fromJson} with a pre-parsed snapshot object.
      * `storedFields` are shallow-copied; callers must not mutate nested values
      * after load if they intend to keep the index immutable.
      */
     static fromMiniSearchSnapshot(snapshot, options = {}) {
         return assembleFrozenTrusted(buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options), 'minisearch-json');
     }
-    /** Accepts any object exposing `toJSON()` in lucaong MiniSearch snapshot shape. */
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
     static fromMiniSearch(source, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(source.toJSON(), options);
     }