@yoch/frozenminisearch 1.0.1 → 1.0.2

package/dist/cjs/index.cjs

@@ -2020,24 +2020,33 @@ function findSparseSlotByFieldId(fieldIds, start, end, fieldId) {
     }
     return -1;
 }
-/** Resolve one (termIndex, fieldId) posting run in flat buffers; shared by flyweight and docId collect. */
-function frozenPostingSlice(layout, termIndex, fieldId) {
+/** Reusable scratch for {@link resolvePostingSlice} (scoring is synchronous). */
+const postingSliceScratch = { offset: 0, length: 0 };
+/**
+ * Resolve one (termIndex, fieldId) posting run in flat buffers; writes into `out` without allocating.
+ * @returns false when the slot is empty or missing
+ */
+function resolvePostingSlice(layout, termIndex, fieldId, out) {
     if (layout.layout === 'dense') {
         const base = termIndex * layout.fieldCount + fieldId;
         const len = layout.denseLengths[base];
         if (len === 0)
-            return undefined;
-        return { offset: layout.denseOffsets[base], length: len };
+            return false;
+        out.offset = layout.denseOffsets[base];
+        out.length = len;
+        return true;
     }
     const start = layout.sparseTermStarts[termIndex];
     const end = layout.sparseTermStarts[termIndex + 1];
     const slot = findSparseSlotByFieldId(layout.sparseFieldIds, start, end, fieldId);
     if (slot < 0)
-        return undefined;
+        return false;
     const len = layout.sparseLengths[slot];
     if (len === 0)
-        return undefined;
-    return { offset: layout.sparseOffsets[slot], length: len };
+        return false;
+    out.offset = layout.sparseOffsets[slot];
+    out.length = len;
+    return true;
 }
 /**
  * One flyweight wrapper for the lifetime of a frozen index. Call {@link bind} before each
@@ -2053,10 +2062,9 @@ function createFrozenFieldTermFlyweight(layout) {
             return flyweight;
         },
         get(fieldId) {
-            const slice = frozenPostingSlice(layout, termIndex, fieldId);
-            if (slice == null)
+            if (!resolvePostingSlice(layout, termIndex, fieldId, postingSliceScratch))
                 return undefined;
-            return segment.rebind(slice.offset, slice.length);
+            return segment.rebind(postingSliceScratch.offset, postingSliceScratch.length);
         },
     };
     return flyweight;
@@ -2075,10 +2083,9 @@ function collectDocIdsFromFrozenSegment(allDocIds, offset, length, context, docI
 function collectDocIdsFromFrozenLayout(layout, termIndex, fieldBoosts, context, docIds, allowedDocs) {
     const { fieldIds } = context;
     for (const field of fieldBoosts.names) {
-        const slice = frozenPostingSlice(layout, termIndex, fieldIds[field]);
-        if (slice == null)
+        if (!resolvePostingSlice(layout, termIndex, fieldIds[field], postingSliceScratch))
             continue;
-        collectDocIdsFromFrozenSegment(layout.allDocIds, slice.offset, slice.length, context, docIds, allowedDocs);
+        collectDocIdsFromFrozenSegment(layout.allDocIds, postingSliceScratch.offset, postingSliceScratch.length, context, docIds, allowedDocs);
     }
 }
 
@@ -2232,22 +2239,387 @@ function collectFieldTermFreqsFromFieldInto(localFreqs, tokenScratch, tokenize,
     tokenizeFieldInto(tokenScratch, tokenize, text, fieldName);
     return collectFieldTermFreqsInto(localFreqs, tokenScratch, fieldName, processTerm);
 }
-/** Same running average as {@link MiniSearch} private addFieldLength. */
 function updateAvgFieldLength(avgFieldLength, fieldId, count, length) {
     const averageFieldLength = avgFieldLength[fieldId] || 0;
     const totalFieldLength = (averageFieldLength * count) + length;
     avgFieldLength[fieldId] = totalFieldLength / (count + 1);
 }
-function saveStoredFieldsForDocument(storeFields, extractField, document) {
+
+function validateTreeShape(shape, termCount) {
+    if (!Array.isArray(shape)) {
+        throw invalidFrozenIndex('treeShape node must be an array');
+    }
+    for (const entry of shape) {
+        if (!Array.isArray(entry) || entry.length !== 2) {
+            throw invalidFrozenIndex('treeShape entry must be a [key, value] pair');
+        }
+        const [key, value] = entry;
+        if (key === LEAF) {
+            const idx = value;
+            if (!Number.isInteger(idx) || idx < 0 || idx >= termCount) {
+                throw invalidFrozenIndex(`treeShape leaf term index out of range: ${idx}`);
+            }
+        }
+        else {
+            validateTreeShape(value, termCount);
+        }
+    }
+}
+function termCountOf(snap) {
+    return snap.postings.termCount;
+}
+/**
+ * Numeric/structural invariants shared by both the decode path (untrusted binary)
+ * and the build path (trusted internal code).
+ */
+function validateFrozenSnapshotNumeric(snap) {
+    if (snap.fieldCount <= 0) {
+        throw invalidFrozenIndex('fieldCount must be positive');
+    }
+    if (snap.nextId < 0 || snap.nextId >= 0xffffffff) {
+        throw invalidFrozenIndex('nextId out of range');
+    }
+    if (snap.documentCount < 0 || snap.documentCount > snap.nextId) {
+        throw invalidFrozenIndex('documentCount inconsistent with nextId');
+    }
+    if (snap.fieldLengthMatrix.length !== snap.nextId * snap.fieldCount) {
+        throw invalidFrozenIndex('fieldLengthMatrix size mismatch');
+    }
+    if (snap.avgFieldLength.length !== snap.fieldCount) {
+        throw invalidFrozenIndex('avgFieldLength size mismatch');
+    }
+    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, detail => {
+        throw invalidFrozenIndex(detail);
+    });
+    const indexedFields = Object.keys(snap.fieldIds);
+    if (indexedFields.length !== snap.fieldCount) {
+        throw invalidFrozenIndex('fieldIds count mismatch');
+    }
+    for (let f = 0; f < snap.fieldCount; f++) {
+        const found = indexedFields.some(name => snap.fieldIds[name] === f);
+        if (!found) {
+            throw invalidFrozenIndex(`missing field id ${f}`);
+        }
+    }
+}
+function readFieldNamesSection(buf, fieldNamesOff, fieldCount, externalIdsOff) {
+    const fieldNames = [];
+    let o = fieldNamesOff;
+    for (let f = 0; f < fieldCount; f++) {
+        const { value, next } = readLengthPrefixedUtf8(buf, o);
+        fieldNames.push(value);
+        o = next;
+    }
+    if (o !== externalIdsOff) {
+        throw invalidFrozenIndex('field names section size mismatch');
+    }
+    return fieldNames;
+}
+function readExternalIdsSection(buf, externalIdsOff, nextId, storedOff) {
+    const externalIds = new Array(nextId);
+    let o = externalIdsOff;
+    for (let i = 0; i < nextId; i++) {
+        const { value, next } = readExternalId(buf, o);
+        externalIds[i] = value;
+        o = next;
+    }
+    if (o !== storedOff) {
+        throw invalidFrozenIndex('external ids section size mismatch');
+    }
+    return externalIds;
+}
+function readStoredFieldsSection(buf, storedOff, nextId, sectionEnd) {
+    const storedFields = new Array(nextId);
+    const tableEnd = storedOff + nextId * 4;
+    if (tableEnd > sectionEnd) {
+        throw invalidFrozenIndex('stored fields table out of bounds');
+    }
+    for (let i = 0; i < nextId; i++) {
+        const rel = buf.readUInt32LE(storedOff + i * 4);
+        if (rel === 0) {
+            storedFields[i] = undefined;
+            continue;
+        }
+        const entryOff = tableEnd + rel - 1;
+        if (entryOff + 4 > sectionEnd) {
+            throw invalidFrozenIndex('stored fields entry offset out of bounds');
+        }
+        const jsonLen = buf.readUInt32LE(entryOff);
+        const jsonStart = entryOff + 4;
+        const jsonEnd = jsonStart + jsonLen;
+        if (jsonEnd > sectionEnd) {
+            throw invalidFrozenIndex('stored fields JSON out of bounds');
+        }
+        storedFields[i] = JSON.parse(buf.toString('utf8', jsonStart, jsonEnd));
+    }
+    return storedFields;
+}
+/** Validate structural invariants of a decoded or assembled frozen snapshot. */
+function validateFrozenSnapshot(snap) {
+    validateFrozenSnapshotNumeric(snap);
+    const termCount = termCountOf(snap);
+    if (snap.packedTermIndex != null) {
+        validateFrozenTermIndexLeaves(snap.packedTermIndex, termCount);
+    }
+    else if (snap.termTree != null) {
+        validateTermTreeLeaves(snap.termTree, termCount);
+    }
+    else {
+        validateTreeShape(snap.treeShape, termCount);
+    }
+}
+function fieldNamesFromFieldIds(fieldIds) {
+    const names = Object.keys(fieldIds);
+    names.sort((a, b) => fieldIds[a] - fieldIds[b]);
+    return names;
+}
+/** Core with explicit {@link termCountOf} (no dictionary section). */
+function buildCoreSectionWithTermCount(snap) {
+    const out = Buffer.alloc(16);
+    out.writeUInt32LE(snap.documentCount, 0);
+    out.writeUInt32LE(snap.nextId, 4);
+    out.writeUInt32LE(snap.fieldCount, 8);
+    out.writeUInt32LE(termCountOf(snap), 12);
+    return out;
+}
+function buildFieldNamesSection(fieldNames) {
+    const chunks = [];
+    for (const name of fieldNames) {
+        const body = Buffer.from(name, 'utf8');
+        const header = Buffer.alloc(4);
+        header.writeUInt32LE(body.length, 0);
+        chunks.push(header, body);
+    }
+    return Buffer.concat(chunks);
+}
+function buildExternalIdsSection(externalIds, nextId) {
+    const chunks = [];
+    for (let i = 0; i < nextId; i++) {
+        writeExternalId(chunks, externalIds[i]);
+    }
+    return Buffer.concat(chunks);
+}
+function buildStoredFieldsSection(storedFields, nextId) {
+    const table = Buffer.alloc(nextId * 4);
+    const heapChunks = [];
+    let heapOff = 0;
+    for (let i = 0; i < nextId; i++) {
+        const row = storedFields[i];
+        if (row == null) {
+            table.writeUInt32LE(0, i * 4);
+            continue;
+        }
+        table.writeUInt32LE(heapOff + 1, i * 4);
+        const json = Buffer.from(JSON.stringify(row), 'utf8');
+        const entry = Buffer.alloc(4 + json.length);
+        entry.writeUInt32LE(json.length, 0);
+        json.copy(entry, 4);
+        heapChunks.push(entry);
+        heapOff += entry.length;
+    }
+    return Buffer.concat([table, ...heapChunks]);
+}
+function validateTermTreeLeaves(tree, termCount) {
+    for (const [key, val] of tree) {
+        if (key === LEAF) {
+            const idx = val;
+            if (!Number.isInteger(idx) || idx < 0 || idx >= termCount) {
+                throw invalidFrozenIndex(`term tree leaf index out of range: ${idx}`);
+            }
+        }
+        else {
+            validateTermTreeLeaves(val, termCount);
+        }
+    }
+}
+function deserializeTermIndexTree(shape) {
+    const tree = new Map();
+    for (const [key, value] of shape) {
+        if (key === LEAF) {
+            tree.set(LEAF, value);
+        }
+        else {
+            tree.set(key, deserializeTermIndexTree(value));
+        }
+    }
+    return tree;
+}
+
+/**
+ * Runtime stored fields. Single store field → one column (no per-doc Record at rest).
+ * Wire format stays row JSON; encode/decode can skip intermediate row arrays when layout is known.
+ */
+function createStoredFieldsLayout(storeFields, capacity = 0) {
     if (storeFields.length === 0)
+        return { kind: 'none' };
+    if (storeFields.length === 1) {
+        return { kind: 'single', field: storeFields[0], values: new Array(capacity) };
+    }
+    return { kind: 'multi', rows: new Array(capacity) };
+}
+function writeStoredField(layout, shortId, storeFields, extractField, document) {
+    if (layout.kind === 'none')
+        return;
+    if (layout.kind === 'single') {
+        layout.values[shortId] = extractField(document, layout.field);
+        return;
+    }
+    const row = {};
+    for (const name of storeFields) {
+        const value = extractField(document, name);
+        if (value !== undefined)
+            row[name] = value;
+    }
+    layout.rows[shortId] = row;
+}
+/** Materialize API/wire row for one document. */
+function readStoredFields(layout, shortId) {
+    if (layout.kind === 'none')
         return undefined;
-    const documentFields = {};
-    for (const fieldName of storeFields) {
-        const fieldValue = extractField(document, fieldName);
-        if (fieldValue !== undefined)
-            documentFields[fieldName] = fieldValue;
+    if (layout.kind === 'multi')
+        return layout.rows[shortId];
+    const value = layout.values[shortId];
+    if (value === undefined)
+        return {};
+    return { [layout.field]: value };
+}
+function resizeStoredFields(layout, length) {
+    if (layout.kind === 'none')
+        return layout;
+    if (layout.kind === 'single') {
+        return layout.values.length <= length
+            ? layout
+            : { kind: 'single', field: layout.field, values: layout.values.slice(0, length) };
+    }
+    return layout.rows.length <= length
+        ? layout
+        : { kind: 'multi', rows: layout.rows.slice(0, length) };
+}
+function cloneStoredFields(layout) {
+    if (layout.kind === 'none')
+        return layout;
+    if (layout.kind === 'single') {
+        return { kind: 'single', field: layout.field, values: layout.values.slice() };
+    }
+    return { kind: 'multi', rows: layout.rows.slice() };
+}
+/** Import from wire rows or lucaong 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);
+        return hasAny ? { kind: 'multi', rows } : { kind: 'none' };
+    }
+    if (storeFields.length === 1) {
+        const field = storeFields[0];
+        const values = rows.map(row => row === null || row === void 0 ? void 0 : row[field]);
+        return { kind: 'single', field, values };
+    }
+    return { kind: 'multi', rows };
+}
+function storedFieldsJsonBytes(layout) {
+    if (layout.kind === 'none')
+        return 0;
+    if (layout.kind === 'multi') {
+        let total = 0;
+        for (const row of layout.rows) {
+            if (row != null)
+                total += JSON.stringify(row).length;
+        }
+        return total;
+    }
+    let total = 0;
+    const { field, values } = layout;
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i];
+        if (value !== undefined)
+            total += JSON.stringify({ [field]: value }).length;
     }
-    return documentFields;
+    return total;
+}
+function storedFieldsSlotCount(layout) {
+    if (layout.kind === 'none')
+        return 0;
+    return layout.kind === 'single' ? layout.values.length : layout.rows.length;
+}
+function appendStoredFieldJsonEntry(table, heapChunks, heapOffRef, docIndex, jsonUtf8) {
+    table.writeUInt32LE(heapOffRef.value + 1, docIndex * 4);
+    const entry = Buffer.alloc(4 + jsonUtf8.length);
+    entry.writeUInt32LE(jsonUtf8.length, 0);
+    jsonUtf8.copy(entry, 4);
+    heapChunks.push(entry);
+    heapOffRef.value += entry.length;
+}
+/** MSv5 StoredFields section from {@link StoredFieldsLayout} (no intermediate row array). */
+function buildStoredFieldsWireSection(layout, nextId) {
+    if (layout.kind === 'multi') {
+        const rows = layout.rows.length >= nextId
+            ? layout.rows
+            : layout.rows.concat(new Array(nextId - layout.rows.length));
+        return buildStoredFieldsSection(rows, nextId);
+    }
+    const table = Buffer.alloc(nextId * 4);
+    if (layout.kind === 'none')
+        return table;
+    const heapChunks = [];
+    const heapOffRef = { value: 0 };
+    const { field, values } = layout;
+    for (let i = 0; i < nextId; i++) {
+        const value = values[i];
+        if (value === undefined)
+            continue;
+        const jsonUtf8 = Buffer.from(JSON.stringify({ [field]: value }), 'utf8');
+        appendStoredFieldJsonEntry(table, heapChunks, heapOffRef, i, jsonUtf8);
+    }
+    return heapChunks.length === 0 ? table : Buffer.concat([table, ...heapChunks]);
+}
+function storedFieldsTableEnd(storedOff, nextId, sectionEnd) {
+    const tableEnd = storedOff + nextId * 4;
+    if (tableEnd > sectionEnd) {
+        throw invalidFrozenIndex('stored fields table out of bounds');
+    }
+    return tableEnd;
+}
+function readStoredFieldJsonAt(buf, tableEnd, sectionEnd, rel) {
+    const entryOff = tableEnd + rel - 1;
+    if (entryOff + 4 > sectionEnd) {
+        throw invalidFrozenIndex('stored fields entry offset out of bounds');
+    }
+    const jsonLen = buf.readUInt32LE(entryOff);
+    const jsonStart = entryOff + 4;
+    const jsonEnd = jsonStart + jsonLen;
+    if (jsonEnd > sectionEnd) {
+        throw invalidFrozenIndex('stored fields JSON out of bounds');
+    }
+    return JSON.parse(buf.toString('utf8', jsonStart, jsonEnd));
+}
+/** MSv5 StoredFields section → layout (skips row materialization when storeFields hint allows). */
+function readStoredFieldsWireSection(buf, storedOff, nextId, sectionEnd, storeFields) {
+    const tableEnd = storedFieldsTableEnd(storedOff, nextId, sectionEnd);
+    if (storeFields.length === 1) {
+        const field = storeFields[0];
+        const values = new Array(nextId);
+        for (let i = 0; i < nextId; i++) {
+            const rel = buf.readUInt32LE(storedOff + i * 4);
+            if (rel === 0)
+                continue;
+            const row = readStoredFieldJsonAt(buf, tableEnd, sectionEnd, rel);
+            values[i] = row[field];
+        }
+        return { kind: 'single', field, values };
+    }
+    if (storeFields.length === 0) {
+        let hasAny = false;
+        for (let i = 0; i < nextId; i++) {
+            if (buf.readUInt32LE(storedOff + i * 4) !== 0) {
+                hasAny = true;
+                break;
+            }
+        }
+        if (!hasAny)
+            return { kind: 'none' };
+    }
+    const rows = readStoredFieldsSection(buf, storedOff, nextId, sectionEnd);
+    return storedFieldsFromRows(rows, storeFields);
 }
 
 const SUPPORTED_SERIALIZATION_VERSIONS = new Set([1, 2]);
@@ -2333,7 +2705,7 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     let shortIdRemap = null;
     const resolvedNextId = useDense ? documentCount : nextId;
     const externalIds = new Array(resolvedNextId);
-    const storedFields = new Array(externalIds.length);
+    const storedFieldRows = new Array(externalIds.length);
     if (useDense) {
         shortIdRemap = new Uint32Array(nextId);
         shortIdRemap.fill(DISCARDED_DOC_ID);
@@ -2345,7 +2717,7 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
             const shortIdStr = String(shortId);
             shortIdRemap[shortId] = dense;
             externalIds[dense] = snapshot.documentIds[shortIdStr];
-            storedFields[dense] = snapshot.storedFields[shortIdStr];
+            storedFieldRows[dense] = snapshot.storedFields[shortIdStr];
             dense++;
         }
     }
@@ -2353,7 +2725,7 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
         for (const [shortIdStr, id] of Object.entries(snapshot.documentIds)) {
             const shortId = parseInt(shortIdStr, 10);
             externalIds[shortId] = id;
-            storedFields[shortId] = snapshot.storedFields[shortIdStr];
+            storedFieldRows[shortId] = snapshot.storedFields[shortIdStr];
         }
     }
     const idLookup = createIdToShortIdLookup(externalIds, resolvedNextId);
@@ -2376,6 +2748,7 @@ function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     }
     const searchableMap = buildSearchableMapFromSnapshot(snapshot);
     const flat = buildFlatPostingsFromSearchableMap(searchableMap, fieldCount, resolvedNextId, shortIdRemap);
+    const storedFields = storedFieldsFromRows(storedFieldRows, opts.storeFields);
     return {
         options: opts,
         documentCount,
@@ -2794,206 +3167,6 @@ function readMsv5GlobalFlags(buf) {
     return buf.readUInt16LE(6);
 }
 
-function validateTreeShape(shape, termCount) {
-    if (!Array.isArray(shape)) {
-        throw invalidFrozenIndex('treeShape node must be an array');
-    }
-    for (const entry of shape) {
-        if (!Array.isArray(entry) || entry.length !== 2) {
-            throw invalidFrozenIndex('treeShape entry must be a [key, value] pair');
-        }
-        const [key, value] = entry;
-        if (key === LEAF) {
-            const idx = value;
-            if (!Number.isInteger(idx) || idx < 0 || idx >= termCount) {
-                throw invalidFrozenIndex(`treeShape leaf term index out of range: ${idx}`);
-            }
-        }
-        else {
-            validateTreeShape(value, termCount);
-        }
-    }
-}
-function termCountOf(snap) {
-    return snap.postings.termCount;
-}
-/**
- * Numeric/structural invariants shared by both the decode path (untrusted binary)
- * and the build path (trusted internal code).
- */
-function validateFrozenSnapshotNumeric(snap) {
-    if (snap.fieldCount <= 0) {
-        throw invalidFrozenIndex('fieldCount must be positive');
-    }
-    if (snap.nextId < 0 || snap.nextId >= 0xffffffff) {
-        throw invalidFrozenIndex('nextId out of range');
-    }
-    if (snap.documentCount < 0 || snap.documentCount > snap.nextId) {
-        throw invalidFrozenIndex('documentCount inconsistent with nextId');
-    }
-    if (snap.fieldLengthMatrix.length !== snap.nextId * snap.fieldCount) {
-        throw invalidFrozenIndex('fieldLengthMatrix size mismatch');
-    }
-    if (snap.avgFieldLength.length !== snap.fieldCount) {
-        throw invalidFrozenIndex('avgFieldLength size mismatch');
-    }
-    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, detail => {
-        throw invalidFrozenIndex(detail);
-    });
-    const indexedFields = Object.keys(snap.fieldIds);
-    if (indexedFields.length !== snap.fieldCount) {
-        throw invalidFrozenIndex('fieldIds count mismatch');
-    }
-    for (let f = 0; f < snap.fieldCount; f++) {
-        const found = indexedFields.some(name => snap.fieldIds[name] === f);
-        if (!found) {
-            throw invalidFrozenIndex(`missing field id ${f}`);
-        }
-    }
-}
-function readFieldNamesSection(buf, fieldNamesOff, fieldCount, externalIdsOff) {
-    const fieldNames = [];
-    let o = fieldNamesOff;
-    for (let f = 0; f < fieldCount; f++) {
-        const { value, next } = readLengthPrefixedUtf8(buf, o);
-        fieldNames.push(value);
-        o = next;
-    }
-    if (o !== externalIdsOff) {
-        throw invalidFrozenIndex('field names section size mismatch');
-    }
-    return fieldNames;
-}
-function readExternalIdsSection(buf, externalIdsOff, nextId, storedOff) {
-    const externalIds = new Array(nextId);
-    let o = externalIdsOff;
-    for (let i = 0; i < nextId; i++) {
-        const { value, next } = readExternalId(buf, o);
-        externalIds[i] = value;
-        o = next;
-    }
-    if (o !== storedOff) {
-        throw invalidFrozenIndex('external ids section size mismatch');
-    }
-    return externalIds;
-}
-function readStoredFieldsSection(buf, storedOff, nextId, sectionEnd) {
-    const storedFields = new Array(nextId);
-    const tableEnd = storedOff + nextId * 4;
-    if (tableEnd > sectionEnd) {
-        throw invalidFrozenIndex('stored fields table out of bounds');
-    }
-    for (let i = 0; i < nextId; i++) {
-        const rel = buf.readUInt32LE(storedOff + i * 4);
-        if (rel === 0) {
-            storedFields[i] = undefined;
-            continue;
-        }
-        const entryOff = tableEnd + rel - 1;
-        if (entryOff + 4 > sectionEnd) {
-            throw invalidFrozenIndex('stored fields entry offset out of bounds');
-        }
-        const jsonLen = buf.readUInt32LE(entryOff);
-        const jsonStart = entryOff + 4;
-        const jsonEnd = jsonStart + jsonLen;
-        if (jsonEnd > sectionEnd) {
-            throw invalidFrozenIndex('stored fields JSON out of bounds');
-        }
-        storedFields[i] = JSON.parse(buf.toString('utf8', jsonStart, jsonEnd));
-    }
-    return storedFields;
-}
-/** Validate structural invariants of a decoded or assembled frozen snapshot. */
-function validateFrozenSnapshot(snap) {
-    validateFrozenSnapshotNumeric(snap);
-    const termCount = termCountOf(snap);
-    if (snap.packedTermIndex != null) {
-        validateFrozenTermIndexLeaves(snap.packedTermIndex, termCount);
-    }
-    else if (snap.termTree != null) {
-        validateTermTreeLeaves(snap.termTree, termCount);
-    }
-    else {
-        validateTreeShape(snap.treeShape, termCount);
-    }
-}
-function fieldNamesFromFieldIds(fieldIds) {
-    const names = Object.keys(fieldIds);
-    names.sort((a, b) => fieldIds[a] - fieldIds[b]);
-    return names;
-}
-/** Core with explicit {@link termCountOf} (no dictionary section). */
-function buildCoreSectionWithTermCount(snap) {
-    const out = Buffer.alloc(16);
-    out.writeUInt32LE(snap.documentCount, 0);
-    out.writeUInt32LE(snap.nextId, 4);
-    out.writeUInt32LE(snap.fieldCount, 8);
-    out.writeUInt32LE(termCountOf(snap), 12);
-    return out;
-}
-function buildFieldNamesSection(fieldNames) {
-    const chunks = [];
-    for (const name of fieldNames) {
-        const body = Buffer.from(name, 'utf8');
-        const header = Buffer.alloc(4);
-        header.writeUInt32LE(body.length, 0);
-        chunks.push(header, body);
-    }
-    return Buffer.concat(chunks);
-}
-function buildExternalIdsSection(externalIds, nextId) {
-    const chunks = [];
-    for (let i = 0; i < nextId; i++) {
-        writeExternalId(chunks, externalIds[i]);
-    }
-    return Buffer.concat(chunks);
-}
-function buildStoredFieldsSection(storedFields, nextId) {
-    const table = Buffer.alloc(nextId * 4);
-    const heapChunks = [];
-    let heapOff = 0;
-    for (let i = 0; i < nextId; i++) {
-        const row = storedFields[i];
-        if (row == null) {
-            table.writeUInt32LE(0, i * 4);
-            continue;
-        }
-        table.writeUInt32LE(heapOff + 1, i * 4);
-        const json = Buffer.from(JSON.stringify(row), 'utf8');
-        const entry = Buffer.alloc(4 + json.length);
-        entry.writeUInt32LE(json.length, 0);
-        json.copy(entry, 4);
-        heapChunks.push(entry);
-        heapOff += entry.length;
-    }
-    return Buffer.concat([table, ...heapChunks]);
-}
-function validateTermTreeLeaves(tree, termCount) {
-    for (const [key, val] of tree) {
-        if (key === LEAF) {
-            const idx = val;
-            if (!Number.isInteger(idx) || idx < 0 || idx >= termCount) {
-                throw invalidFrozenIndex(`term tree leaf index out of range: ${idx}`);
-            }
-        }
-        else {
-            validateTermTreeLeaves(val, termCount);
-        }
-    }
-}
-function deserializeTermIndexTree(shape) {
-    const tree = new Map();
-    for (const [key, value] of shape) {
-        if (key === LEAF) {
-            tree.set(LEAF, value);
-        }
-        else {
-            tree.set(key, deserializeTermIndexTree(value));
-        }
-    }
-    return tree;
-}
-
 /** Global wire flags for {@link FreqArray} width. */
 function freqWireFlags(freqs) {
     if (freqs instanceof Uint16Array)
@@ -3285,11 +3458,14 @@ function encodeFrozenSnapshotMsv5(snap, termTree, packedTermIndex) {
     const flFlags = fieldLengthMatrixWireFlags(snap.fieldLengthMatrix);
     const freqFlags = freqWireFlags(snap.postings.allFreqs);
     const globalFlags = postingsWire.flags | flFlags | freqFlags;
+    const storedFieldsSection = snap.storedFieldsLayout != null
+        ? buildStoredFieldsWireSection(snap.storedFieldsLayout, snap.nextId)
+        : buildStoredFieldsSection(snap.storedFields, snap.nextId);
     const rawSections = [
         buildCoreSectionWithTermCount(snap),
         buildFieldNamesSection(fieldNames),
         buildExternalIdsSection(snap.externalIds, snap.nextId),
-        buildStoredFieldsSection(snap.storedFields, snap.nextId),
+        storedFieldsSection,
         buildTermTreeSectionColumnar(packed),
         bufferFromView(snap.avgFieldLength),
         buildFieldLengthMatrixSection(snap.fieldLengthMatrix),
@@ -3313,11 +3489,14 @@ async function encodeFrozenSnapshotMsv5Async(snap, termTree, packedTermIndex) {
     const flFlags = fieldLengthMatrixWireFlags(snap.fieldLengthMatrix);
     const freqFlags = freqWireFlags(snap.postings.allFreqs);
     const globalFlags = postingsWire.flags | flFlags | freqFlags;
+    const storedFieldsSection = snap.storedFieldsLayout != null
+        ? buildStoredFieldsWireSection(snap.storedFieldsLayout, snap.nextId)
+        : buildStoredFieldsSection(snap.storedFields, snap.nextId);
     const rawSections = [
         buildCoreSectionWithTermCount(snap),
         buildFieldNamesSection(fieldNames),
         buildExternalIdsSection(snap.externalIds, snap.nextId),
-        buildStoredFieldsSection(snap.storedFields, snap.nextId),
+        storedFieldsSection,
         buildTermTreeSectionColumnar(packed),
         bufferFromView(snap.avgFieldLength),
         buildFieldLengthMatrixSection(snap.fieldLengthMatrix),
@@ -3347,7 +3526,7 @@ function validateMsv5Container(buf) {
     }
     return { globalFlags, directory };
 }
-function decodeMsv5Sections(globalFlags, sections) {
+function decodeMsv5Sections(globalFlags, sections, hints) {
     const core = sections[0 /* Msv5SectionId.Core */];
     if (core.length !== 16) {
         throw invalidFrozenIndex('core section size mismatch');
@@ -3362,7 +3541,12 @@ function decodeMsv5Sections(globalFlags, sections) {
         fieldIds[fieldNames[f]] = f;
     }
     const externalIds = readExternalIdsSection(sections[2 /* Msv5SectionId.ExternalIds */], 0, nextId, sections[2 /* Msv5SectionId.ExternalIds */].length);
-    const storedFields = readStoredFieldsSection(sections[3 /* Msv5SectionId.StoredFields */], 0, nextId, sections[3 /* Msv5SectionId.StoredFields */].length);
+    const storedFieldsLayout = hints != null
+        ? readStoredFieldsWireSection(sections[3 /* Msv5SectionId.StoredFields */], 0, nextId, sections[3 /* Msv5SectionId.StoredFields */].length, hints.storeFields)
+        : undefined;
+    const storedFields = storedFieldsLayout != null
+        ? new Array(nextId)
+        : readStoredFieldsSection(sections[3 /* Msv5SectionId.StoredFields */], 0, nextId, sections[3 /* Msv5SectionId.StoredFields */].length);
     const packedTermIndex = readPackedTermTreeSectionColumnar(sections[4 /* Msv5SectionId.TermTree */], termCount);
     const avgBuf = sections[5 /* Msv5SectionId.AvgFieldLength */];
     const avgFieldLength = readFloat32Array(avgBuf, 0, avgBuf.length);
@@ -3380,6 +3564,7 @@ function decodeMsv5Sections(globalFlags, sections) {
         avgFieldLength,
         externalIds,
         storedFields,
+        storedFieldsLayout,
         fieldLengthMatrix,
         treeShape: [],
         packedTermIndex,
@@ -3388,13 +3573,13 @@ function decodeMsv5Sections(globalFlags, sections) {
     validateFrozenSnapshot(snap);
     return snap;
 }
-function decodeFrozenSnapshotMsv5(buf) {
+function decodeFrozenSnapshotMsv5(buf, hints) {
     const { globalFlags, directory } = validateMsv5Container(buf);
-    return decodeMsv5Sections(globalFlags, loadMsv5Sections(buf, directory));
+    return decodeMsv5Sections(globalFlags, loadMsv5Sections(buf, directory), hints);
 }
-async function decodeFrozenSnapshotMsv5Async(buf) {
+async function decodeFrozenSnapshotMsv5Async(buf, hints) {
     const { globalFlags, directory } = validateMsv5Container(buf);
-    return decodeMsv5Sections(globalFlags, await loadMsv5SectionsAsync(buf, directory));
+    return decodeMsv5Sections(globalFlags, await loadMsv5SectionsAsync(buf, directory), hints);
 }
 
 /** Encode a frozen snapshot as a binary buffer. */
@@ -3408,12 +3593,12 @@ function encodeFrozenSnapshotAsync(snap, termTree, packedTermIndex) {
 
 const LEGACY_MAGICS = new Set(['MSv1', 'MSv2', 'MSv3', 'MSv4']);
 /** Decode a frozen binary snapshot buffer. */
-function decodeFrozenSnapshot(buf) {
+function decodeFrozenSnapshot(buf, hints) {
     assertBufferLength(buf, 8);
     const magic = buf.toString('ascii', 0, 4);
     const version = buf.readUInt16LE(4);
     if (isMsv5Buffer(buf) && version === 5) {
-        return decodeFrozenSnapshotMsv5(buf);
+        return decodeFrozenSnapshotMsv5(buf, hints);
     }
     if (LEGACY_MAGICS.has(magic)) {
         throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from lucaong JSON');
@@ -3421,13 +3606,13 @@ function decodeFrozenSnapshot(buf) {
     throw invalidFrozenIndex('Unsupported frozen binary snapshot');
 }
 /** Async frozen snapshot decode (streaming zstd). */
-async function decodeFrozenSnapshotAsync(buf) {
+async function decodeFrozenSnapshotAsync(buf, hints) {
     assertBufferLength(buf, 8);
     const version = buf.readUInt16LE(4);
     if (isMsv5Buffer(buf) && version === 5) {
-        return decodeFrozenSnapshotMsv5Async(buf);
+        return decodeFrozenSnapshotMsv5Async(buf, hints);
     }
-    return decodeFrozenSnapshot(buf);
+    return decodeFrozenSnapshot(buf, hints);
 }
 
 const DEFAULT_CAPACITY = 16;
@@ -3689,14 +3874,13 @@ class FrozenIndexBuilder {
         this._nextId = 0;
         this._frozen = false;
         const estimated = hints === null || hints === void 0 ? void 0 : hints.estimatedDocumentCount;
+        this._storedFields = createStoredFieldsLayout(this._options.storeFields, estimated !== null && estimated !== void 0 ? estimated : 0);
         if (estimated != null && estimated > 0) {
             this._externalIds = new Array(estimated);
-            this._storedFields = new Array(estimated);
             this._fieldLengthData = new Array(estimated * this._fieldCount).fill(0);
         }
         else {
             this._externalIds = [];
-            this._storedFields = [];
             this._fieldLengthData = [];
         }
     }
@@ -3719,7 +3903,7 @@ class FrozenIndexBuilder {
         this._seenIds.add(id);
         const shortId = this._nextId++;
         this._externalIds[shortId] = id;
-        this._storedFields[shortId] = saveStoredFieldsForDocument(storeFields, extractField, document);
+        writeStoredField(this._storedFields, shortId, storeFields, extractField, document);
         const documentCount = shortId + 1;
         for (const field of fields) {
             const fieldValue = extractField(document, field);
@@ -3805,9 +3989,7 @@ class FrozenIndexBuilder {
         const externalIds = this._externalIds.length > documentCount
             ? this._externalIds.slice(0, documentCount)
             : this._externalIds;
-        const storedFields = this._storedFields.length > documentCount
-            ? this._storedFields.slice(0, documentCount)
-            : this._storedFields;
+        const storedFields = resizeStoredFields(this._storedFields, documentCount);
         const idLookup = createIdToShortIdLookup(externalIds, documentCount);
         return {
             options: this._options,
@@ -4235,7 +4417,7 @@ function shallowCopyJsSnapshotFields(params) {
     return {
         fieldIds: { ...params.fieldIds },
         options: shallowCopyOptions(params.options),
-        storedFields: params.storedFields.slice(),
+        storedFields: cloneStoredFields(params.storedFields),
     };
 }
 /**
@@ -4320,7 +4502,7 @@ class FrozenMiniSearch {
             fieldIds: this._fieldIds,
             getFieldLength: (docId, fieldId) => this.getFieldLength(docId, fieldId),
             getExternalId: docId => this._externalIds[docId],
-            getStoredFields: docId => this._storedFields[docId],
+            getStoredFields: docId => readStoredFields(this._storedFields, docId),
         };
         this._queryEngineParams = {
             fields: this._options.fields,
@@ -4332,7 +4514,7 @@ class FrozenMiniSearch {
                     const id = this._externalIds[shortId];
                     if (id === undefined)
                         continue;
-                    callback(shortId, id, this._storedFields[shortId]);
+                    callback(shortId, id, readStoredFields(this._storedFields, shortId));
                 }
             }),
             aggregateContext: this._aggregateContext,
@@ -4343,11 +4525,7 @@ class FrozenMiniSearch {
     memoryBreakdown() {
         const termCount = this.termCount;
         const postingsStats = postingsTypedBytes(this._postings);
-        let storedJson = 0;
-        for (const row of this._storedFields) {
-            if (row != null)
-                storedJson += JSON.stringify(row).length;
-        }
+        const storedJson = storedFieldsJsonBytes(this._storedFields);
         const radixEst = this._index.packedByteLength();
         const idMapBytes = this._idLookup.mode === 'lazy-map' ? this._idLookup.mapEntryCount * 32 : 0;
         const estimatedStructuredBytes = postingsStats.totalTypedBytes
@@ -4377,7 +4555,7 @@ class FrozenMiniSearch {
             },
             documents: {
                 externalIdsSlots: this._externalIds.length,
-                storedFieldsSlots: this._storedFields.length,
+                storedFieldsSlots: storedFieldsSlotCount(this._storedFields),
                 idLookupMode: this._idLookup.mode,
                 idToShortIdEntries: this._idLookup.mapEntryCount,
                 fieldLengthMatrixBytes: this._fieldLengthMatrix.byteLength,
@@ -4392,10 +4570,10 @@ class FrozenMiniSearch {
     }
     getStoredFields(id) {
         const shortId = this._idLookup.get(id);
-        return shortId == null ? undefined : this._storedFields[shortId];
+        return shortId == null ? undefined : readStoredFields(this._storedFields, shortId);
     }
     search(query, searchOptions = {}) {
-        return finalizeRawSearchResults(this.executeQuery(query, searchOptions), query, searchOptions, this._options.searchOptions, docId => this._externalIds[docId], docId => this._storedFields[docId]);
+        return finalizeRawSearchResults(this.executeQuery(query, searchOptions), query, searchOptions, this._options.searchOptions, docId => this._externalIds[docId], docId => readStoredFields(this._storedFields, docId));
     }
     autoSuggest(queryString, options = {}) {
         const merged = { ...this._options.autoSuggestOptions, ...options };
@@ -4411,7 +4589,8 @@ class FrozenMiniSearch {
             fieldNames: fieldNamesFromFieldIds(this._fieldIds),
             avgFieldLength: this._avgFieldLength,
             externalIds: this._externalIds,
-            storedFields: this._storedFields,
+            storedFields: new Array(this._nextId),
+            storedFieldsLayout: this._storedFields,
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
@@ -4427,7 +4606,8 @@ class FrozenMiniSearch {
             fieldNames: fieldNamesFromFieldIds(this._fieldIds),
             avgFieldLength: this._avgFieldLength,
             externalIds: this._externalIds,
-            storedFields: this._storedFields,
+            storedFields: new Array(this._nextId),
+            storedFieldsLayout: this._storedFields,
             fieldLengthMatrix: fieldLengthMatrixForWire(this._fieldLengthMatrix),
             treeShape: [],
             postings: this._postings,
@@ -4435,16 +4615,20 @@ class FrozenMiniSearch {
     }
     /** Load a frozen binary snapshot. */
     static loadBinarySync(buffer, options = {}) {
-        const snap = decodeFrozenSnapshot(buffer);
+        var _a;
+        const storeFields = (_a = options.storeFields) !== null && _a !== void 0 ? _a : defaultFrozenLoadOptions.storeFields;
+        const snap = decodeFrozenSnapshot(buffer, { storeFields });
         return FrozenMiniSearch.fromBinarySnapshot(snap, options);
     }
     /** Load a frozen binary snapshot with streaming zstd decompression (bounded memory). */
     static async loadBinaryAsync(buffer, options = {}) {
-        const snap = await decodeFrozenSnapshotAsync(buffer);
+        var _a;
+        const storeFields = (_a = options.storeFields) !== null && _a !== void 0 ? _a : defaultFrozenLoadOptions.storeFields;
+        const snap = await decodeFrozenSnapshotAsync(buffer, { storeFields });
         return FrozenMiniSearch.fromBinarySnapshot(snap, options);
     }
     static fromBinarySnapshot(snap, options) {
-        var _a, _b;
+        var _a, _b, _c;
         const snapshotFields = (_a = snap.fieldNames) !== null && _a !== void 0 ? _a : fieldNamesFromFieldIds(snap.fieldIds);
         if (options.fields != null) {
             assertFieldsMatchSnapshot(options.fields, snap.fieldIds);
@@ -4472,7 +4656,7 @@ class FrozenMiniSearch {
             fieldCount: snap.fieldCount,
             externalIds: snap.externalIds,
             idLookup,
-            storedFields: snap.storedFields,
+            storedFields: (_c = snap.storedFieldsLayout) !== null && _c !== void 0 ? _c : storedFieldsFromRows(snap.storedFields, opts.storeFields),
             fieldLengthMatrix: snap.fieldLengthMatrix,
             avgFieldLength: snap.avgFieldLength,
             index,