@yoch/frozenminisearch 1.0.0 → 1.0.1

package/dist/es/index.js

@@ -1907,111 +1907,6 @@ function materializeFrozenPostings(params) {
         sparseLengths: new Uint32Array(sparseLengths),
     };
 }
-/** One-pass materialize from {@link FrozenIndexBuilder} scratch (counts known upfront). */
-function materializeFrozenPostingsFromBuilder(state, nextId) {
-    var _a;
-    const { fieldCount, termCount, postingsDocIds, postingsFreqs, totalPostings, maxFreq } = state;
-    const layout = choosePostingsLayout(fieldCount);
-    const docIdWidth = nextId <= 65535 ? 16 : 32;
-    const allDocIds = docIdWidth === 16
-        ? new Uint16Array(totalPostings)
-        : new Uint32Array(totalPostings);
-    const allFreqs = allocateFreqs(totalPostings, maxFreq);
-    if (layout === 'dense') {
-        const slotCount = termCount * fieldCount;
-        const denseOffsets = new Uint32Array(slotCount);
-        const denseLengths = new Uint32Array(slotCount);
-        let write = 0;
-        for (let ti = 0; ti < termCount; ti++) {
-            const base = ti * fieldCount;
-            for (let f = 0; f < fieldCount; f++) {
-                const slot = base + f;
-                const docIds = postingsDocIds[slot];
-                const freqs = postingsFreqs[slot];
-                const len = (_a = docIds === null || docIds === void 0 ? void 0 : docIds.length) !== null && _a !== void 0 ? _a : 0;
-                denseOffsets[slot] = write;
-                denseLengths[slot] = len;
-                for (let i = 0; i < len; i++) {
-                    const docId = docIds[i];
-                    if (docIdWidth === 16) {
-                        allDocIds[write] = docId;
-                    }
-                    else {
-                        allDocIds[write] = docId;
-                    }
-                    allFreqs[write] = freqs[i];
-                    write++;
-                }
-            }
-        }
-        return {
-            fieldCount,
-            termCount,
-            nextId,
-            layout,
-            docIdWidth,
-            sparseFieldIdWidth: null,
-            allDocIds,
-            allFreqs,
-            denseOffsets,
-            denseLengths,
-            sparseTermStarts: null,
-            sparseFieldIds: null,
-            sparseOffsets: null,
-            sparseLengths: null,
-        };
-    }
-    const sparseFieldIdWidth = chooseSparseFieldIdWidth(fieldCount);
-    const sparseFieldIdsScratch = [];
-    const sparseOffsets = [];
-    const sparseLengths = [];
-    const termStarts = new Array(termCount + 1).fill(0);
-    let write = 0;
-    for (let ti = 0; ti < termCount; ti++) {
-        termStarts[ti] = sparseFieldIdsScratch.length;
-        for (let f = 0; f < fieldCount; f++) {
-            const slot = ti * fieldCount + f;
-            const docIds = postingsDocIds[slot];
-            if (docIds == null || docIds.length === 0)
-                continue;
-            const freqs = postingsFreqs[slot];
-            sparseFieldIdsScratch.push(f);
-            sparseOffsets.push(write);
-            sparseLengths.push(docIds.length);
-            for (let i = 0; i < docIds.length; i++) {
-                const docId = docIds[i];
-                if (docIdWidth === 16) {
-                    allDocIds[write] = docId;
-                }
-                else {
-                    allDocIds[write] = docId;
-                }
-                allFreqs[write] = freqs[i];
-                write++;
-            }
-        }
-        termStarts[ti + 1] = sparseFieldIdsScratch.length;
-    }
-    const sparseFieldIds = sparseFieldIdWidth === 16
-        ? new Uint16Array(sparseFieldIdsScratch)
-        : new Uint8Array(sparseFieldIdsScratch);
-    return {
-        fieldCount,
-        termCount,
-        nextId,
-        layout,
-        docIdWidth,
-        sparseFieldIdWidth,
-        allDocIds,
-        allFreqs,
-        denseOffsets: null,
-        denseLengths: null,
-        sparseTermStarts: new Uint32Array(termStarts),
-        sparseFieldIds,
-        sparseOffsets: new Uint32Array(sparseOffsets),
-        sparseLengths: new Uint32Array(sparseLengths),
-    };
-}
 function postingsTypedBytes(layout) {
     const allDocIdsBytes = layout.allDocIds.byteLength;
     const allFreqsBytes = layout.allFreqs.byteLength;
@@ -2228,21 +2123,110 @@ function buildFieldIds(fields) {
     }
     return fieldIds;
 }
-/** Token frequencies for one document field (after processTerm). */
-function collectFieldTermFreqs(tokens, fieldName, processTerm) {
-    const localFreqs = new Map();
+function accumulateProcessedTerm(localFreqs, processedTerm) {
+    if (Array.isArray(processedTerm)) {
+        for (const t of processedTerm) {
+            localFreqs.set(t, (localFreqs.get(t) || 0) + 1);
+        }
+    }
+    else if (processedTerm) {
+        localFreqs.set(processedTerm, (localFreqs.get(processedTerm) || 0) + 1);
+    }
+}
+/**
+ * Accumulate token frequencies for one document field into `localFreqs` (cleared first).
+ * Returns the number of distinct processed terms (replaces a separate `Set(tokens)` pass).
+ */
+function collectFieldTermFreqsInto(localFreqs, tokens, fieldName, processTerm) {
+    localFreqs.clear();
     for (const term of tokens) {
-        const processedTerm = processTerm(term, fieldName);
-        if (Array.isArray(processedTerm)) {
-            for (const t of processedTerm) {
-                localFreqs.set(t, (localFreqs.get(t) || 0) + 1);
-            }
+        accumulateProcessedTerm(localFreqs, processTerm(term, fieldName));
+    }
+    return localFreqs.size;
+}
+/** Global delimiter pattern for incremental `exec` (must not reuse {@link SPACE_OR_PUNCTUATION} — no `g` flag). */
+const DEFAULT_TOKENIZE_DELIMITERS = /[\n\r\p{Z}\p{P}]+/gu;
+const defaultTokenizeProbe = 'a b';
+const defaultTokenizeProbeField = 'f';
+const tokenizeBehaviorCache = new WeakMap();
+/**
+ * True when `tokenize` matches the library default (reference equality or split-equivalent
+ * on a fixed probe). Custom tokenizers that pass the probe but diverge on other inputs
+ * (e.g. leading delimiters) still take the fast path — use the default reference in prod.
+ */
+function isDefaultTokenize(tokenize) {
+    if (tokenize === defaultFrozenLoadOptions.tokenize)
+        return true;
+    const cached = tokenizeBehaviorCache.get(tokenize);
+    if (cached != null)
+        return cached;
+    const splitTokens = defaultTokenizeProbe.split(SPACE_OR_PUNCTUATION);
+    const customTokens = tokenize(defaultTokenizeProbe, defaultTokenizeProbeField);
+    const ok = splitTokens.length === customTokens.length
+        && splitTokens.every((t, i) => t === customTokens[i]);
+    tokenizeBehaviorCache.set(tokenize, ok);
+    return ok;
+}
+function forEachDefaultToken(text, onToken) {
+    if (text.length === 0) {
+        onToken('');
+        return;
+    }
+    let start = 0;
+    const re = DEFAULT_TOKENIZE_DELIMITERS;
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(text)) !== null) {
+        if (match.index > start) {
+            onToken(text.slice(start, match.index));
         }
-        else if (processedTerm) {
-            localFreqs.set(processedTerm, (localFreqs.get(processedTerm) || 0) + 1);
+        else if (match.index === start) {
+            onToken('');
         }
+        start = match.index + match[0].length;
+    }
+    if (start < text.length) {
+        onToken(text.slice(start));
+    }
+    else if (start === 0) {
+        onToken(text);
+    }
+    else if (start === text.length) {
+        onToken('');
     }
-    return localFreqs;
+}
+/** Default tokenizer into a reusable buffer (avoids `text.split()` array allocation). */
+function tokenizeDefaultInto(out, text) {
+    out.length = 0;
+    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) {
+    if (isDefaultTokenize(tokenize)) {
+        tokenizeDefaultInto(out, text);
+        return;
+    }
+    const tokens = tokenize(text, fieldName);
+    out.length = 0;
+    out.push(...tokens);
+}
+function collectDefaultFieldTermFreqsInto(localFreqs, text, fieldName, processTerm) {
+    localFreqs.clear();
+    forEachDefaultToken(text, (token) => {
+        accumulateProcessedTerm(localFreqs, processTerm(token, fieldName));
+    });
+    return localFreqs.size;
+}
+/**
+ * Tokenize + accumulate field term frequencies in one pass when the default tokenizer is used.
+ * `tokenScratch` is only used for custom tokenizers (two-phase fallback).
+ */
+function collectFieldTermFreqsFromFieldInto(localFreqs, tokenScratch, tokenize, text, fieldName, processTerm) {
+    if (isDefaultTokenize(tokenize)) {
+        return collectDefaultFieldTermFreqsInto(localFreqs, text, fieldName, processTerm);
+    }
+    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) {
@@ -3442,50 +3426,260 @@ async function decodeFrozenSnapshotAsync(buf) {
     return decodeFrozenSnapshot(buf);
 }
 
-function getOrCreateTermIndex(state, index, term) {
+const DEFAULT_CAPACITY = 16;
+/** Growable unsigned 32-bit column (build scratch; narrowed to u16 at finalize when possible). */
+class GrowableUint32Column {
+    constructor(initialCapacity = DEFAULT_CAPACITY) {
+        this._len = 0;
+        this._buf = new Uint32Array(Math.max(1, initialCapacity));
+    }
+    get length() {
+        return this._len;
+    }
+    push(value) {
+        if (this._len >= this._buf.length) {
+            const grown = new Uint32Array(Math.max(1, this._buf.length * 2));
+            grown.set(this._buf);
+            this._buf = grown;
+        }
+        this._buf[this._len++] = value;
+    }
+    copyRangeInto(sourceOffset, length, target, targetOffset, docIdWidth) {
+        if (docIdWidth === 16) {
+            const out = target;
+            for (let i = 0; i < length; i++)
+                out[targetOffset + i] = this._buf[sourceOffset + i];
+        }
+        else {
+            const out = target;
+            for (let i = 0; i < length; i++)
+                out[targetOffset + i] = this._buf[sourceOffset + i];
+        }
+    }
+    truncate(length) {
+        this._len = length;
+        if (length > 0 && length < this._buf.length) {
+            this._buf = this._buf.slice(0, length);
+        }
+    }
+}
+/** Growable frequency column (u16 cells; matches frozen clamp range). */
+class GrowableFreqColumn {
+    constructor(initialCapacity = DEFAULT_CAPACITY) {
+        this._len = 0;
+        this._buf = new Uint16Array(Math.max(1, initialCapacity));
+    }
+    get length() {
+        return this._len;
+    }
+    push(freq) {
+        if (this._len >= this._buf.length) {
+            const grown = new Uint16Array(Math.max(1, this._buf.length * 2));
+            grown.set(this._buf);
+            this._buf = grown;
+        }
+        this._buf[this._len++] = clampFreq(freq);
+    }
+    copyRangeInto(sourceOffset, length, target, targetOffset) {
+        for (let i = 0; i < length; i++) {
+            target[targetOffset + i] = this._buf[sourceOffset + i];
+        }
+    }
+    truncate(length) {
+        this._len = length;
+        if (length > 0 && length < this._buf.length) {
+            this._buf = this._buf.slice(0, length);
+        }
+    }
+}
+/**
+ * Single-pass postings accumulator for {@link FrozenIndexBuilder}.
+ * One global TypedArray stream per docIds/freqs; per-slot range metadata only.
+ */
+class IncrementalPostingsAccumulator {
+    constructor(fieldCount, hints) {
+        var _a;
+        this._slots = new Map();
+        this._totalPostings = 0;
+        this._maxFreq = 0;
+        this._fieldCount = fieldCount;
+        const cap = Math.max(DEFAULT_CAPACITY, (_a = hints === null || hints === void 0 ? void 0 : hints.estimatedTotalPostings) !== null && _a !== void 0 ? _a : 0);
+        this._docIds = new GrowableUint32Column(cap);
+        this._freqs = new GrowableFreqColumn(cap);
+    }
+    get totalPostings() {
+        return this._totalPostings;
+    }
+    get maxFreq() {
+        return this._maxFreq;
+    }
+    append(termIndex, fieldId, docId, freq) {
+        const slot = termIndex * this._fieldCount + fieldId;
+        const writeIdx = this._docIds.length;
+        this._docIds.push(docId);
+        const v = clampFreq(freq);
+        this._freqs.push(v);
+        if (v > this._maxFreq)
+            this._maxFreq = v;
+        this._totalPostings++;
+        let ranges = this._slots.get(slot);
+        if (ranges == null) {
+            ranges = { starts: [writeIdx], lengths: [1] };
+            this._slots.set(slot, ranges);
+            return;
+        }
+        const last = ranges.starts.length - 1;
+        const end = ranges.starts[last] + ranges.lengths[last];
+        if (end === writeIdx) {
+            ranges.lengths[last]++;
+        }
+        else {
+            ranges.starts.push(writeIdx);
+            ranges.lengths.push(1);
+        }
+    }
+    clear() {
+        this._slots.clear();
+        // Drop global scratch backing so finalize does not retain duplicate posting bytes.
+        this._docIds.truncate(0);
+        this._freqs.truncate(0);
+    }
+    copySlot(ranges, allDocIds, allFreqs, write, docIdWidth) {
+        for (let r = 0; r < ranges.starts.length; r++) {
+            const start = ranges.starts[r];
+            const len = ranges.lengths[r];
+            this._docIds.copyRangeInto(start, len, allDocIds, write, docIdWidth);
+            this._freqs.copyRangeInto(start, len, allFreqs, write);
+            write += len;
+        }
+        return write;
+    }
+    slotLength(ranges) {
+        let n = 0;
+        for (let i = 0; i < ranges.lengths.length; i++)
+            n += ranges.lengths[i];
+        return n;
+    }
+    finalize(termCount, nextId) {
+        const fieldCount = this._fieldCount;
+        const totalPostings = this._totalPostings;
+        const maxFreq = this._maxFreq;
+        const slots = this._slots;
+        const layout = choosePostingsLayout(fieldCount);
+        const docIdWidth = nextId <= 65535 ? 16 : 32;
+        const allDocIds = docIdWidth === 16
+            ? new Uint16Array(totalPostings)
+            : new Uint32Array(totalPostings);
+        const allFreqs = allocateFreqs(totalPostings, maxFreq);
+        if (layout === 'dense') {
+            const slotCount = termCount * fieldCount;
+            const denseOffsets = new Uint32Array(slotCount);
+            const denseLengths = new Uint32Array(slotCount);
+            let write = 0;
+            for (let ti = 0; ti < termCount; ti++) {
+                const base = ti * fieldCount;
+                for (let f = 0; f < fieldCount; f++) {
+                    const slot = base + f;
+                    const ranges = slots.get(slot);
+                    const len = ranges == null ? 0 : this.slotLength(ranges);
+                    denseOffsets[slot] = write;
+                    denseLengths[slot] = len;
+                    if (len > 0) {
+                        write = this.copySlot(ranges, allDocIds, allFreqs, write, docIdWidth);
+                        slots.delete(slot);
+                    }
+                }
+            }
+            slots.clear();
+            this.clear();
+            return {
+                fieldCount,
+                termCount,
+                nextId,
+                layout,
+                docIdWidth,
+                sparseFieldIdWidth: null,
+                allDocIds,
+                allFreqs,
+                denseOffsets,
+                denseLengths,
+                sparseTermStarts: null,
+                sparseFieldIds: null,
+                sparseOffsets: null,
+                sparseLengths: null,
+            };
+        }
+        const sparseFieldIdWidth = chooseSparseFieldIdWidth(fieldCount);
+        const sparseFieldIdsScratch = [];
+        const sparseOffsets = [];
+        const sparseLengths = [];
+        const termStarts = new Array(termCount + 1).fill(0);
+        let write = 0;
+        for (let ti = 0; ti < termCount; ti++) {
+            termStarts[ti] = sparseFieldIdsScratch.length;
+            for (let f = 0; f < fieldCount; f++) {
+                const slot = ti * fieldCount + f;
+                const ranges = slots.get(slot);
+                const len = ranges == null ? 0 : this.slotLength(ranges);
+                if (len === 0)
+                    continue;
+                sparseFieldIdsScratch.push(f);
+                sparseOffsets.push(write);
+                sparseLengths.push(len);
+                write = this.copySlot(ranges, allDocIds, allFreqs, write, docIdWidth);
+                slots.delete(slot);
+            }
+            termStarts[ti + 1] = sparseFieldIdsScratch.length;
+        }
+        slots.clear();
+        this.clear();
+        const sparseFieldIds = sparseFieldIdWidth === 16
+            ? new Uint16Array(sparseFieldIdsScratch)
+            : new Uint8Array(sparseFieldIdsScratch);
+        return {
+            fieldCount,
+            termCount,
+            nextId,
+            layout,
+            docIdWidth,
+            sparseFieldIdWidth,
+            allDocIds,
+            allFreqs,
+            denseOffsets: null,
+            denseLengths: null,
+            sparseTermStarts: new Uint32Array(termStarts),
+            sparseFieldIds,
+            sparseOffsets: new Uint32Array(sparseOffsets),
+            sparseLengths: new Uint32Array(sparseLengths),
+        };
+    }
+}
+
+function getOrCreateTermIndex(termCount, index, term) {
     const existing = index.get(term);
     if (existing != null)
         return existing;
-    const ti = state.terms.length;
-    state.terms.push(term);
+    const ti = termCount.value;
+    termCount.value++;
     index.set(term, ti);
     return ti;
 }
-function appendPosting(state, termIndex, fieldId, docId, freq) {
-    const slot = termIndex * state.fieldCount + fieldId;
-    let docIds = state.postingsDocIds[slot];
-    if (docIds == null) {
-        docIds = [];
-        state.postingsDocIds[slot] = docIds;
-        state.postingsFreqs[slot] = [];
-    }
-    docIds.push(docId);
-    state.postingsFreqs[slot].push(freq);
-    const v = clampFreq(freq);
-    if (v > state.maxFreq)
-        state.maxFreq = v;
-    state.totalPostings++;
-}
-function finalizeFlatPostings(state, nextId) {
-    return materializeFrozenPostingsFromBuilder({
-        fieldCount: state.fieldCount,
-        termCount: state.terms.length,
-        postingsDocIds: state.postingsDocIds,
-        postingsFreqs: state.postingsFreqs,
-        totalPostings: state.totalPostings,
-        maxFreq: state.maxFreq,
-    }, nextId);
-}
 /** Incremental builder for {@link FrozenMiniSearch} without materializing a full `documents[]` array. */
 class FrozenIndexBuilder {
     constructor(options, hints) {
+        var _a, _b;
+        this._termCount = { value: 0 };
+        this._fieldTermFreqScratch = new Map();
+        this._tokenScratch = [];
         this._options = resolveIndexingOptions(options);
         this._fieldIds = buildFieldIds(this._options.fields);
         this._fieldCount = this._options.fields.length;
         this._index = new SearchableMap();
-        this._terms = [];
-        this._postingsDocIds = [];
-        this._postingsFreqs = [];
+        const estimatedDocs = (_a = hints === null || hints === void 0 ? void 0 : hints.estimatedDocumentCount) !== null && _a !== void 0 ? _a : 0;
+        const perSlot = (_b = hints === null || hints === void 0 ? void 0 : hints.estimatedPostingsPerSlot) !== null && _b !== void 0 ? _b : 4;
+        this._postings = new IncrementalPostingsAccumulator(this._fieldCount, {
+            estimatedTotalPostings: estimatedDocs > 0 ? estimatedDocs * perSlot : undefined,
+        });
         this._avgFieldLength = [];
         this._seenIds = new Set();
         this._nextId = 0;
@@ -3501,14 +3695,6 @@ class FrozenIndexBuilder {
             this._storedFields = [];
             this._fieldLengthData = [];
         }
-        this._postingsState = {
-            fieldCount: this._fieldCount,
-            terms: this._terms,
-            postingsDocIds: this._postingsDocIds,
-            postingsFreqs: this._postingsFreqs,
-            totalPostings: 0,
-            maxFreq: 0,
-        };
     }
     /** Number of documents indexed so far (not yet frozen). */
     get documentCount() {
@@ -3535,16 +3721,17 @@ class FrozenIndexBuilder {
             const fieldValue = extractField(document, field);
             if (fieldValue == null)
                 continue;
-            const tokens = tokenize(stringifyField(fieldValue, field), field);
+            const fieldText = typeof fieldValue === 'string'
+                ? fieldValue
+                : stringifyField(fieldValue, field);
             const fieldId = this._fieldIds[field];
-            const uniqueTerms = new Set(tokens).size;
-            const localFreqs = collectFieldTermFreqs(tokens, field, processTerm);
+            const uniqueTerms = collectFieldTermFreqsFromFieldInto(this._fieldTermFreqScratch, this._tokenScratch, tokenize, fieldText, field, processTerm);
             this._fieldLengthData[shortId * this._fieldCount + fieldId] = uniqueTerms;
             updateAvgFieldLength(this._avgFieldLength, fieldId, documentCount - 1, uniqueTerms);
-            for (const [term, freq] of localFreqs) {
-                const ti = getOrCreateTermIndex(this._postingsState, this._index, term);
-                appendPosting(this._postingsState, ti, fieldId, shortId, freq);
-            }
+            this._fieldTermFreqScratch.forEach((freq, term) => {
+                const ti = getOrCreateTermIndex(this._termCount, this._index, term);
+                this._postings.append(ti, fieldId, shortId, freq);
+            });
         }
     }
     /**
@@ -3601,7 +3788,11 @@ class FrozenIndexBuilder {
         }
         this._frozen = true;
         const documentCount = this._nextId;
-        const postings = finalizeFlatPostings(this._postingsState, documentCount);
+        const termCount = this._termCount.value;
+        const postings = this._postings.finalize(termCount, documentCount);
+        const radixTree = this._index.radixTree;
+        this._index = null;
+        const index = fromRadixTree(radixTree, termCount);
         const avgFieldLength = new Float32Array(this._fieldCount);
         for (let f = 0; f < this._fieldCount; f++) {
             avgFieldLength[f] = (_a = this._avgFieldLength[f]) !== null && _a !== void 0 ? _a : 0;
@@ -3614,8 +3805,6 @@ class FrozenIndexBuilder {
             ? this._storedFields.slice(0, documentCount)
             : this._storedFields;
         const idLookup = createIdToShortIdLookup(externalIds, documentCount);
-        // Incremental builder: numeric radix leaves + build-time terms[] for postings.
-        // freezeFromMiniSearch packs Map leaves in one radix pass (no resident terms[]).
         return {
             options: this._options,
             documentCount,
@@ -3627,8 +3816,8 @@ class FrozenIndexBuilder {
             storedFields,
             fieldLengthMatrix: materializeFieldLengthMatrix(this._fieldLengthData, documentCount * this._fieldCount),
             avgFieldLength,
-            index: fromRadixTree(this._index.radixTree, this._terms.length),
-            termCount: this._terms.length,
+            index,
+            termCount,
             postings,
         };
     }
@@ -4334,4 +4523,4 @@ class FrozenMiniSearch {
 }
 FrozenMiniSearch.wildcard = WILDCARD_QUERY;
 
-export { AND, AND_NOT, FrozenIndexBuilder, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, freezeFrozenIndexBuilder, frozenMemoryBreakdown };
+export { AND, AND_NOT, FrozenIndexBuilder, FrozenMiniSearch, OR, assembleFrozen, buildFrozenFromDocuments, createFrozenIndexBuilder, FrozenMiniSearch as default, freezeFrozenIndexBuilder, frozenMemoryBreakdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoch/frozenminisearch",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Read-only Node.js full-text search — compact frozen indexes and binary snapshots",
   "main": "dist/cjs/index.cjs",
   "module": "dist/es/index.js",
@@ -100,6 +100,9 @@
     "bench:history": "node --expose-gc benchmarks/framework/cli.mjs history",
     "bench:micro": "node benchmarks/micro/run.mjs",
     "bench:readme": "node benchmarks/scripts/generate-readme-comparison.mjs",
+    "bench:build-peak": "npm run build && node --expose-gc benchmarks/scripts/build-peak-heap.mjs",
+    "bench:medicaments-build-peak": "npm run build && NODE_OPTIONS='--expose-gc' npx --yes tsx benchmarks/scripts/medicaments-build-peak-heap.mjs",
+    "bench:build-heap-profile": "npm run build && NODE_OPTIONS='--expose-gc' npx --yes tsx benchmarks/scripts/build-heap-profile.mjs",
     "bench:reference:update": "npm run build && RUNS=3 node --expose-gc benchmarks/framework/cli.mjs record --profile=vs-reference && node benchmarks/scripts/promote-latest-to-reference.mjs && npm run bench:readme",
     "benchmark:compare": "npm run build && node --expose-gc benchmarks/compare.js",
     "benchmark:calibrate-batches": "npm run build && node --expose-gc benchmarks/scripts/calibrate-search-batches.mjs",
@@ -132,7 +135,7 @@
     "clean-build": "rm -rf dist",
     "build-minified": "MINIFY=true npm run build",
     "sync-docs-media": "node scripts/sync-docs-media.cjs",
-    "build-docs": "npm run sync-docs-media && typedoc --options typedoc.json && npm run build-demo",
+    "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",
     "lint": "eslint 'src/**/*.{js,ts}'",
     "lintfix": "eslint --fix 'src/**/*.{js,ts}'",