FrozenMiniSearch

API documentation

Memory-optimized, read-only full-text search for Node.js and browsers. FrozenMiniSearch keeps the serving API close to MiniSearch while using compact, immutable indexes for fixed corpora.

Use it when your documents are built offline, shipped to production, and queried many times. In that shape, frozen indexes use ~98-99% less index RAM in the main benchmark set, save to compact binary snapshots, and load faster than MiniSearch JSON.

If you need live add, remove, or discard, use MiniSearch. If the corpus is fixed, this package is designed to keep the search experience familiar while making each serving replica much smaller.

Why FrozenMiniSearch?

FrozenMiniSearch is for the common production path where search data changes elsewhere, not inside the web process:

• Build or import the index offline.
• Save it as a compact binary snapshot.
• Load it in many read-only Node.js processes.
• Query with MiniSearch-style search, autoSuggest, filters, boosts, prefix/fuzzy search, wildcard, and AND / OR / AND_NOT.

Internally it replaces mutable JavaScript object graphs with packed radix postings, typed arrays, and columnar stored fields. The result is less flexible than MiniSearch, but much cheaper to keep resident.

Measured vs MiniSearch

Same corpora, same BM25-style queries, MiniSearch 7.2.0 as the reference.

| Scenario | Docs | Index RAM | Binary size | Load time | Search p50 | |----------|-----:|-----------|------------:|----------:|-----------:| | Divina, with stored text | 14,097 | 0.3 vs 16.0 MB (~98% less) | ~71% less | ~56% faster | ~21% faster | | Divina, index only | 14,097 | 0.2 vs 14.9 MB (~99% less) | ~74% less | ~80% faster | ~24% faster | | High-frequency terms | 10,000 | 4.4 vs 7.4 MB (~41% less) | ~92% less | ~85% faster | ~41% faster | | Dense numeric ids | 100,000 | 0.9 vs 91.3 MB (~99% less) | ~73% less | ~87% faster | ~33% faster | | Uint16 doc id boundary | 65,535 | 0.6 vs 58.6 MB (~99% less) | ~77% less | ~91% faster | ~53% faster |

Across this full run, frozen is faster on 25/27 search cases. Divina inferno (exact, paired p50): mutable 18.1 µs → frozen 11.4 µs (-7 µs, ratio 0.72).

Numbers are from benchmarks/baselines/reference.json, captured 2026-06-21 on Node v24.16.0, 3 runs per scenario. Heap is measured with one index alive and should be read as a trend, not exact accounting.

Quick start

npm install @yoch/frozenminisearch

import FrozenMiniSearch from '@yoch/frozenminisearch'

const options = { fields: ['title', 'text'], storeFields: ['title'] }
const index = FrozenMiniSearch.fromDocuments(documents, options)

index.search('ishmael', { prefix: true })
index.autoSuggest('zen ar')

const buf = index.saveBinarySync()
const loaded = FrozenMiniSearch.loadBinarySync(buf, options)

For larger imports, use the incremental builder:

import FrozenMiniSearch, {
  createFrozenIndexBuilder,
  freezeFrozenIndexBuilder,
} from '@yoch/frozenminisearch'

const builder = createFrozenIndexBuilder(options, { estimatedDocumentCount: rows.length })
for (const doc of rows) builder.add(doc)
const index = freezeFrozenIndexBuilder(builder)

ESM and CommonJS are both supported on Node (main → CJS, module → ESM). For browsers and bundlers, use the dedicated browser entry (search, build, and async binary I/O):

import FrozenMiniSearch from '@yoch/frozenminisearch/browser'

const index = FrozenMiniSearch.fromDocuments(documents, options)
index.search('ishmael', { prefix: true })

// Load a zlib snapshot from CDN (Uint8Array)
const buf = new Uint8Array(await (await fetch('/index.frozen')).arrayBuffer())
const loaded = await FrozenMiniSearch.loadBinaryAsync(buf, options)

See examples/plain_js_frozen/ for a plain-JS demo (yarn build first).

Migration

For fixed corpora, most serving code can stay the same. Change how the index is built or loaded, then keep calling search, autoSuggest, has, and getStoredFields.

Default and named imports both work:

// ESM
import FrozenMiniSearch from '@yoch/frozenminisearch'
import { FrozenMiniSearch } from '@yoch/frozenminisearch'

// CommonJS
const FrozenMiniSearch = require('@yoch/frozenminisearch')
const { FrozenMiniSearch } = require('@yoch/frozenminisearch')

Build directly:

import FrozenMiniSearch from '@yoch/frozenminisearch'

const frozen = FrozenMiniSearch.fromDocuments(documents, options)

Or freeze an existing MiniSearch index:

import MiniSearch from 'minisearch'
import FrozenMiniSearch from '@yoch/frozenminisearch'

const mutable = new MiniSearch(options)
mutable.addAll(documents)

const frozen = FrozenMiniSearch.fromMiniSearch(mutable, options)
const fromJson = FrozenMiniSearch.fromJson(JSON.stringify(mutable), options)

MiniSearch is only needed if you still build mutable indexes. Frozen instances do not support live add, remove, or discard.

Search API (compatible with MiniSearch)

• search(query, searchOptions?) — string, wildcard (FrozenMiniSearch.wildcard), or nested QueryCombination
• autoSuggest(queryString, options?)
• has(id), getStoredFields(id)
• saveBinarySync / loadBinarySync on Node (async variants too); browser entry supports async binary only (Uint8Array, raw / zlib / auto)

Custom tokenize and processTerm functions are not stored in snapshots; pass the same functions again when loading.

Binary snapshots (Node)

Binary snapshots are the preferred production format on Node.js.

const buf = index.saveBinarySync()
const loaded = FrozenMiniSearch.loadBinarySync(buf, {}) // field names embedded in snapshot

• Node ≥ 20
• compression: 'auto' uses zlib when it shrinks the payload (portable on Node 20+ and in the browser build); falls back to raw when compression does not help.
• Use explicit compression when you need a specific artifact:

const portable = index.saveBinarySync({ compression: 'zlib' }) // CDN / browser
const uncompressed = index.saveBinarySync({ compression: 'raw' })
const bestRatio = index.saveBinarySync({ compression: 'zstd' }) // Node 22.15+ only

Raw snapshots load in the browser without native compression APIs. zlib snapshots in the browser require CompressionStream / DecompressionStream. Browser binary I/O is async because it uses native browser stream APIs, but it still materializes the full compressed/decompressed payload in memory. zstd snapshots require Node 22.15+ (read/write on Node; not supported in the browser build).

Benchmarks

See benchmarks/README.md.

npm run bench -- run --profile=vs-reference   # compare frozen vs minisearch
npm run bench:diff                            # regression vs reference.json
npm run bench:readme -- --from=benchmarks/baselines/latest.json

Development

yarn install
yarn test          # src/ + dev/parity/
yarn build
node scripts/verify-npm-pack.cjs

Parity tests compare against MiniSearch 7. Longer notes and performance work live under dev/docs/README.md and benchmarks/README.md.

Changelog & credits

See CHANGELOG.md.

• MiniSearch — Luca Ongaro (MIT)
• @yoch/frozenminisearch — memory-optimized frozen indexes and compact binary snapshots

Upstream docs: MiniSearch