@yoch/frozenminisearch v1.12.1
    Preparing search index...

    @yoch/frozenminisearch v1.12.1

    FrozenMiniSearch

    npm version coverage CI Docs

    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

    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.

    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 4.73 vs 16.1 MB (~71% less) ~71% less 92 ms 41 ms 97 ms ~41% faster
    Divina, index only 14,097 4.62 vs 14.9 MB (~69% less) ~75% less 90 ms 19 ms 101 ms ~43% faster
    Giant vocabulary (50k terms) 50,000 1.44 vs 47.2 MB (~97% less) ~81% less 222 ms 45 ms 228 ms ~57% faster
    Dense numeric ids 100,000 4.14 vs 91.3 MB (~96% less) ~73% less 540 ms 68 ms 429 ms ~57% faster
    Generic string ids 100,000 4.90 vs 91.3 MB (~95% less) ~74% less 585 ms 89 ms 408 ms ~46% faster
    Uint16 doc id boundary 65,535 2.39 vs 58.6 MB (~96% less) ~77% less 377 ms 51 ms 350 ms ~66% faster
    Uint32 doc id boundary 65,536 3.01 vs 58.6 MB (~95% less) ~74% less 397 ms 49 ms 280 ms ~71% 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 15.0 µs → frozen 8.9 µs (-6 µs, ratio 0.56).

    Numbers are from benchmarks/baselines/reference.json @ 6b43b15, captured 2026-09-27 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.

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

    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.

    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.

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

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

    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.

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

    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.

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

    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.

    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.

    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.

    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.

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

    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

    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.

    See CHANGELOG.md.

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

    Upstream docs: MiniSearch

    Settings
    Member Visibility

    On This Page
    FrozenMiniSearch