FrozenMiniSearch

API documentation · Live demo

Memory-optimized, read-only full-text search for Node.js and browsers. FrozenMiniSearch is built for fixed corpora, with compact immutable indexes and MiniSearch-compatible query semantics.

Try the demo application (Billboard Hot 100 search and auto-suggest in the browser).

Use it when your documents are built offline, shipped to production, and queried many times. In that shape, frozen indexes use ~94–95% less index RAM (totalResident = heapUsed + external on both sides) in the main benchmark set, save to compact binary snapshots, and load faster than MiniSearch JSON.

This package is intentionally focused on fixed-corpus serving: build frozen directly, persist binary snapshots, then load and query them many times.

npm install @yoch/frozenminisearch   # or: pnpm add @yoch/frozenminisearch

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-compatible search, autoSuggest, filters, boosts, prefix/fuzzy search, wildcard, and AND / OR / AND_NOT.
• Paginate with searchPage, which returns a page and the exact total after filtering in one call.
• Skip what you do not read: bounded results, results without match information, or bare matching ids.

Internally it uses packed radix postings, typed arrays, and columnar stored fields instead of large JavaScript object graphs. The result is a search engine tuned for resident efficiency, fast loads, and repeatable serving workflows.

Measured vs MiniSearch

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

| Scenario | Docs | Index RAM | Binary size | Load JSON | Load binary | Freeze import | Search p50 | |----------|-----:|-----------|------------:|----------:|------------:|--------------:|-----------:| | Divina, with stored text | 14,097 | 0.80 vs 16.1 MB (~95% less) | ~71% less | 82 ms | 40 ms | 98 ms | ~45% faster | | Divina, index only | 14,097 | 4.62 vs 14.9 MB (~69% less) | ~75% less | 111 ms | 20 ms | 121 ms | ~39% faster | | Giant vocabulary (50k terms) | 50,000 | 1.45 vs 47.2 MB (~97% less) | ~81% less | 214 ms | 38 ms | 214 ms | ~52% faster | | Dense numeric ids | 100,000 | 4.14 vs 91.3 MB (~96% less) | ~73% less | 511 ms | 60 ms | 429 ms | ~55% faster | | Generic string ids | 100,000 | 4.91 vs 91.3 MB (~95% less) | ~74% less | 573 ms | 80 ms | 432 ms | ~58% faster | | Uint16 doc id boundary | 65,535 | 2.39 vs 58.6 MB (~96% less) | ~77% less | 373 ms | 46 ms | 290 ms | ~62% faster | | Uint32 doc id boundary | 65,536 | 3.01 vs 58.6 MB (~95% less) | ~74% less | 377 ms | 85 ms | 291 ms | ~54% faster |

Load JSON = MiniSearch.loadJSON on the same toJSON snapshot. Load binary = loadBinarySync after saveBinarySync. Freeze import = one-time FrozenMiniSearch.fromJSON (not the hot reload path).

Across this full run, frozen is faster on 27/27 search cases. Divina inferno (exact, paired p50): mutable 16.9 µs → frozen 11.1 µs (-6 µs, ratio 0.67).

Numbers are from benchmarks/baselines/reference.json @ d1a4020, captured 2026-10-29 on Node v24.18.0, 3 runs per scenario. Heap protocol v4 (isolated scenario processes, in-process trials, median+MAD; totalResident = heapUsed + external on both sides) — trend, not exact accounting. Index RAM column shows — for scenarios outside the heap allowlist.

Detailed tables for all 13 scenarios (search, load, migrate, heap, drift, …): benchmarks/VS_REFERENCE.md.

Quick start

pnpm add @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 })
builder.addAll(rows) // `addAllAsync` for chunked, non-blocking ingestion (browser)
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 the hosted demo or examples/plain_js_frozen/README.md locally (pnpm docs:demo:frozen then serve the repo root).

Usage

Basic usage

const documents = [
  { id: 1, title: 'Moby Dick', text: 'Call me Ishmael. Some years ago...', category: 'fiction' },
  { id: 2, title: 'Zen and the Art of Motorcycle Maintenance', text: 'I can see by my watch...', category: 'fiction' },
  // ...
]

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

index.search('zen art motorcycle')
// => [{ id, title, category, score, match, ... }, ...]

Frozen indexes are read-only: there is no add, remove, or discard. Rebuild offline or use createFrozenIndexBuilder for incremental ingestion before finalizing the index.

Search options

MiniSearch-compatible options work on search(), searchPage(), and autoSuggest():

index.search('zen', { fields: ['title'] })
index.search('zen', { boost: { title: 2 } })
index.search('moto', { prefix: true })
index.search('ismael', { fuzzy: 0.2 })
index.search('zen', { filter: (result) => result.category === 'fiction' })
index.search('zen', { combineWith: 'AND' }) // OR, AND_NOT

const index = FrozenMiniSearch.fromDocuments(documents, {
  fields: ['title', 'text'],
  searchOptions: { prefix: true, fuzzy: 0.2 },
})

Wildcard and nested query combinations are supported (FrozenMiniSearch.wildcard, QueryCombination). FrozenMiniSearch adds a few options of its own; see Beyond MiniSearch.

Auto-suggestions

index.autoSuggest('zen ar')
// => [{ suggestion: 'zen archery art', terms: [...], score }, ...]

index.autoSuggest('neromancer', { fuzzy: 0.2 })
index.autoSuggest('zen ar', { filter: (result) => result.category === 'fiction' })

Field extraction

For nested or computed fields, pass extractField at index build time (and again when loading binary snapshots if you override defaults):

const options = {
  fields: ['title', 'author.name', 'pubYear'],
  extractField: (document, fieldName) => {
    if (fieldName === 'pubYear') {
      return document.pubDate?.getFullYear().toString()
    }
    return fieldName.split('.').reduce((doc, key) => doc && doc[key], document)
  },
}

The default extractor is available via FrozenMiniSearch.getDefault('extractField').

Tokenization

const options = {
  fields: ['title', 'text'],
  tokenize: (string, _fieldName) => string.split('-'),
  searchOptions: {
    tokenize: (string) => string.split(/[\s-]+/),
  },
}

FrozenMiniSearch.getDefault('tokenize') returns the built-in Unicode space/punctuation splitter. Only that exact function reference enables the fastest indexing path; equivalent wrappers use the general path.

Term processing

const stopWords = new Set(['and', 'or', 'the'])

const options = {
  fields: ['title', 'text'],
  processTerm: (term) => (stopWords.has(term) ? null : term.toLowerCase()),
  searchOptions: {
    processTerm: (term) => term.toLowerCase(),
  },
}

FrozenMiniSearch.getDefault('processTerm') downcases terms (no stemming or stop-word list by default).

Default helpers

FrozenMiniSearch.getDefault('tokenize')
FrozenMiniSearch.getDefault('processTerm')
FrozenMiniSearch.getDefault('extractField')
FrozenMiniSearch.getDefault('stringifyField')

Use these when wrapping a custom function and delegating to the library default.

Beyond MiniSearch

These extensions are not in MiniSearch. They find the same matches as search(), and save CPU and allocations when you need less than the full sorted list of results: its first results, a page, results without match information, or only the matching ids.

Bounded results (limit)

limit returns the same results as search(...).slice(0, limit), but only materializes and sorts the results it returns, which saves CPU and allocations on broad queries. With filter, the predicate runs in descending score order and stops once limit results are kept, so it should be deterministic and not depend on how often it is called. limit: 0 returns [] without running the query, and an invalid limit throws before any callback runs. autoSuggest() ignores it.

index.search('zen', { prefix: true, limit: 10 })

Pagination and exact totals

searchPage() returns a page in the same score order as an unbounded search(), plus the exact number of matches after filtering and before pagination:

const { results, total } = index.searchPage('zen', {
  prefix: true,
  offset: 20,
  limit: 10,
  filter: result => result.category === 'fiction',
})

offset defaults to zero and must be a non-negative integer. limit is required and overrides the index-level default; it accepts a non-negative integer or Infinity (all remaining matches). Other search options and nested queries work as with search(). Empty pages, including limit: 0, still return the total.

Candidate scores are computed once per call. Deep pages select their window without sorting the matches ranked before it, and unboosted wildcard pages scan documents in insertion order. Without a filter, only the page is materialized. With a filter, every candidate is materialized and evaluated once to obtain the exact total, even when the page is empty. Filters should be deterministic. The score ordering assumes finite scores, as with bounded search. No search state is retained between page requests.

Results without match information

Pass matchInfo: false to search() or searchPage() when you do not read terms or match. Results keep the same scores, order and stored fields, and the search skips building the match information:

index.search('zen', { prefix: true, matchInfo: false })
// => [{ id, score, queryTerms: ['zen'], title, category }, ...]

Filters, including an index-level one, receive these reduced results. The option is read from each call only, and autoSuggest() ignores it.

Matching ids without scores

matchIds() returns the ids of the matching documents in insertion order, without scores or result objects. It finds the same documents as an unbounded search() with the same options, in a fraction of the time and memory. Use it when you rank or merge matches yourself:

index.matchIds('zen art', { prefix: true, combineWith: 'AND' })
// => [2]

It takes the options that select documents: fields, prefix, fuzzy, maxFuzzy, combineWith, tokenize, processTerm and boostDocument.

• A filter throws, whether passed to the call or set in the index-level searchOptions. Pass filter: undefined to disable an index-level filter.
• A limit passed to the call throws; an index-level limit is ignored.
• boostDocument should be deterministic. As in search(), a document does not match a query term when it returns a falsy value for every term derived from it, and a wildcard query returns every document.

Migration and interoperability

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')

The native workflow is to build frozen directly:

import FrozenMiniSearch from '@yoch/frozenminisearch'

const frozen = FrozenMiniSearch.fromDocuments(documents, options)

Existing MiniSearch JSON snapshots can be imported through the compatibility path:

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

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

const frozen = FrozenMiniSearch.fromJSON(JSON.stringify(upstream), options)

This path is useful for migration and interchange. In normal frozen deployments, you typically build with fromDocuments, the builder API, or binary snapshots directly.

Search API

MiniSearch-compatible, with the extensions marked:

• search(query, searchOptions?) — string, wildcard (FrozenMiniSearch.wildcard), or nested QueryCombination; extension options limit and matchInfo
• searchPage(query, { offset?, limit, ...searchOptions }) — extension returning { results, total }; see Pagination and exact totals
• matchIds(query, options?) — extension returning the matching ids in insertion order; see Matching ids without scores
• autoSuggest(queryString, options?)
• has(id), getStoredFields(id)
• getDefault(optionName) — built-in tokenize, processTerm, extractField, stringifyField, …
• 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.

See Usage above for examples.

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.

pnpm bench                                 # quick smoke (dev profile)
pnpm bench:run                             # full suite (regression profile)
NODE_OPTIONS='--expose-gc' node benchmarks/framework/cli.mjs run --profile=vs-reference
pnpm bench:record && pnpm bench:diff       # capture then diff vs reference.json
node benchmarks/scripts/generate-readme-comparison.mjs --from=benchmarks/baselines/latest.json

Development

Use Node 24 and the pnpm version pinned in package.json for development tools, tests, builds, and documentation. The published package supports Node 20+; CI tests its built ESM, CommonJS, and browser entries on Node 20, 22, and 24 without installing the development tools.

pnpm install
pnpm test          # src/ + dev/parity/
pnpm build
pnpm test:runtime  # built package compatibility; also runs directly on Node 20+
node scripts/verify-npm-pack.cjs

Parity tests compare against MiniSearch 7. Longer notes and performance work live under dev/docs/ (repository only) 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