@yoch/frozenminisearch 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## v1.1.0 — `@yoch/frozenminisearch`
+
+Minor release: MiniSearch JSON wire export and clearer JSON import API. MSv5 binary format unchanged.
+
+### Added
+
+- **`toJSON()`** — export MiniSearch wire snapshots (`serializationVersion: 2`); import via `fromJson` / `fromMiniSearchSnapshot`. Production persistence remains `saveBinarySync`.
+
+### Breaking
+
+- **`fromMiniSearchJson` → `fromJson`** — rename for clearer semantics (JSON import vs binary load). Update call sites: `FrozenMiniSearch.fromMiniSearchJson(json)` → `FrozenMiniSearch.fromJson(json)`.
+
 ## v1.0.2 — `@yoch/frozenminisearch`
 
 Patch release: lower retained heap when `storeFields` has one field. No API or MSv5 wire-format changes.
@@ -23,7 +35,7 @@ Patch release: lower build-time peak memory and migration ergonomics. No API or
 
 ### Fixed
 
-- **Default tokenizer parity** — leading delimiter produces an empty token (e.g. `::a` → `["", "a"]`), matching lucaong `split` behaviour.
+- **Default tokenizer parity** — leading delimiter produces an empty token (e.g. `::a` → `["", "a"]`), matching MiniSearch `split` behaviour.
 - **Named export** — `FrozenMiniSearch` is exported again alongside the default export (ESM and CJS).
 
 ## v1.0.0 — `@yoch/frozenminisearch`
@@ -32,7 +44,7 @@ First stable release on npm. Frozen-only read-only search for Node.js.
 
 ### Breaking
 
-- **Binary snapshots** — `loadBinarySync` / `loadBinaryAsync` read only the current frozen binary format; re-build from lucaong JSON if an older snapshot fails to load.
+- **Binary snapshots** — `loadBinarySync` / `loadBinaryAsync` read only the current frozen binary format; re-build from MiniSearch JSON if an older snapshot fails to load.
 - **Removed `saveBinary()` / `loadBinary()`** — use `saveBinarySync` / `saveBinaryAsync` and `loadBinarySync` / `loadBinaryAsync`.
 
 ## v1.0.0-beta.0 — `@yoch/frozenminisearch`
@@ -42,16 +54,16 @@ New standalone package (frozen-only) for read-only serving workloads.
 ### Added
 
 - **`FrozenMiniSearch`** as the default export — `fromDocuments`, builder, `saveBinarySync` / `loadBinarySync`
-- **Migration loaders** — `fromMiniSearch`, `fromMiniSearchJson`, `fromMiniSearchSnapshot` (lucaong JSON wire format)
+- **Migration loaders** — `fromMiniSearch`, `fromJson`, `fromMiniSearchSnapshot` (MiniSearch JSON wire format)
 - **Modular benchmarks** — `npm run bench` with profiles `vs-reference`, `regression`, `dev`
 - **Parity suite** — `dev/parity/` vs `minisearch` npm (functional invariants)
 
 ### Removed from published API
 
 - Mutable `MiniSearch` class and `freeze()` on the fork
-- `freezeFromMiniSearch` (use `fromMiniSearchJson`)
+- `freezeFromMiniSearch` (use `fromJson`)
 - Read-only mutation stubs (`add`, `remove`, …)
 
 ### Migration
 
-- `new MiniSearch(opts).addAll(docs)` (lucaong) → `FrozenMiniSearch.fromDocuments(docs, opts)` or `fromMiniSearch(mutable, opts)` — see README
+- `new MiniSearch(opts).addAll(docs)` → `FrozenMiniSearch.fromDocuments(docs, opts)` or `fromMiniSearch(mutable, opts)` — see README

package/README.md

@@ -1,21 +1,36 @@
-# @yoch/frozenminisearch
+# FrozenMiniSearch
 
-**Read-only full-text search for Node.js** — compact frozen indexes, fast binary snapshots, and a **drop-in** search API for frozen workloads: same `search`, `autoSuggest`, scoring, and query options as [MiniSearch](https://github.com/lucaong/minisearch) by [Luca Ongaro](https://github.com/lucaong).
+[![npm version](https://img.shields.io/npm/v/@yoch/frozenminisearch.svg)](https://www.npmjs.com/package/@yoch/frozenminisearch)
+[![coverage](https://codecov.io/gh/yoch/frozenminisearch/graph/badge.svg)](https://codecov.io/gh/yoch/frozenminisearch)
+[![CI](https://github.com/yoch/frozenminisearch/actions/workflows/main.yml/badge.svg)](https://github.com/yoch/frozenminisearch/actions/workflows/main.yml)
+[![Socket Badge](https://socket.dev/api/badge/npm/package/@yoch/frozenminisearch)](https://socket.dev/npm/package/%40yoch%2Ffrozenminisearch)
 
-> **Current release:** `1.0.2` on npm
+**Memory-optimized, read-only full-text search for Node.js** — the same BM25, prefix/fuzzy, and `autoSuggest` API as [MiniSearch](https://github.com/lucaong/minisearch), with **up to ~98% less index RAM** on real corpora and compact binary snapshots you ship instead of JSON.
 
-**Design goal:** once an index is built or loaded, migrate with the minimum code change — package name and index construction only; serving code stays the same. No mutable `MiniSearch` class is published here; build indexes with `fromDocuments`, the incremental builder, or migrate from an existing lucaong index via `fromMiniSearchJson`.
+**Why it exists:** [MiniSearch](https://github.com/lucaong/minisearch) optimizes for a mutable in-memory index. FrozenMiniSearch optimizes for **retained heap, disk footprint, and cold load** once the corpus is fixed — packed radix postings, columnar `storeFields`, typed-array layouts, and MSv5 binary wire format instead of per-document JS objects.
+
+**Design goal:** migrate with minimal code change — package name and index construction only; serving code stays the same. Build with `fromDocuments`, the incremental builder, or `fromJson`; no mutable `MiniSearch` class is published here.
 
 ---
 
 ## Why frozen instead of MiniSearch?
 
-**Mutable** lucaong `minisearch` when documents change (`add`, `remove`, `discard`). **Frozen** when the corpus is fixed or shipped as a binary snapshot — same BM25, prefix/fuzzy, `autoSuggest`, wildcard, and `AND` / `OR` / `AND_NOT`. Parity with `minisearch@7` is validated in `dev/parity/` (scores `toBeCloseTo` precision 6).
+Choose **mutable MiniSearch** when documents change at runtime (`add`, `remove`, `discard`). Choose **frozen** when memory and snapshot size matter: fixed corpus, deploy from binary, many replicas loading the same index. Search semantics stay the same — BM25, prefix/fuzzy, `autoSuggest`, wildcard, `AND` / `OR` / `AND_NOT` — with parity vs MiniSearch 7 validated in `dev/parity/` (scores `toBeCloseTo` precision 6).
+
+### Memory-first design
+
+| Technique | What it saves |
+|-----------|---------------|
+| **Packed radix tree + flat postings** | Term dictionary and posting lists without per-entry JS wrappers |
+| **Columnar `storeFields`** | One dense column per field instead of a `Record` per document (~75% less heap for a single stored field) |
+| **MSv5 binary snapshots** | ~73–94% smaller on disk than MiniSearch JSON; faster cold load |
+| **Read-only freeze** | No mutation bookkeeping — layouts sized for serve-time, not incremental edit |
+| **Incremental builder** | Typed-array accumulators during build; lower peak heap than materializing `number[][]` per term |
 
 <!-- vs-reference:start — npm run bench:readme -->
-### Measured vs lucaong MiniSearch (reference baseline)
+### Measured vs MiniSearch (reference baseline)
 
-Same BM25 queries on identical corpora. **Frozen wins on what we optimize for**: RAM, disk, cold load, and search throughput on real workloads.
+Same BM25 queries on identical corpora. **Index RAM is the headline metric** — frozen uses a fraction of mutable heap on every scenario below; disk and cold load follow from the compact binary format.
 
 | Scenario | Docs | Index RAM¹ | Disk (binary vs JSON)² | Cold load³ | Search p50⁴ |
 |----------|-----:|------------|------------------------:|-----------:|------------:|
@@ -29,9 +44,10 @@ Same BM25 queries on identical corpora. **Frozen wins on what we optimize for**:
 
 Decomposition (Divina exact): L0 lookup ~300 ns frozen, L1 `executeQuery` ~8.3 µs, L2 full `search` ~11.6 µs (finalize ≈ 3 µs).
 
-| | lucaong `minisearch` | `@yoch/frozenminisearch` |
+| | MiniSearch | `@yoch/frozenminisearch` |
 |---|------------------------|---------------------------|
-| **Sweet spot** | Live index mutations | Fixed corpus, deploy from binary |
+| **Optimizes for** | Live mutations, flexibility | **Retained RAM**, snapshot size, cold load |
+| **Sweet spot** | Documents change at runtime | Fixed corpus, many replicas, tight memory budget |
 | **Production path** | `addAll` → `toJSON` | `fromDocuments` / `fromMiniSearch` → `saveBinarySync` → `loadBinarySync` |
 | **Typical trade-off** | Higher RAM, JSON snapshots | One-time freeze, then compact binary |
 
@@ -91,17 +107,17 @@ ESM and CommonJS are both supported (`main` → CJS, `module` → ESM).
 
 ## Drop-in
 
-For **fixed corpora** (build once, serve read-only), treat this package as a drop-in replacement for lucaong `minisearch` on the serving path.
+For **fixed corpora** (build once, serve read-only), treat this package as a drop-in replacement for MiniSearch on the serving path — same queries, far less memory per replica.
 
 **Change only:**
 
 | What | Before | After |
 |------|--------|-------|
-| Package | lucaong `minisearch` | `@yoch/frozenminisearch` |
+| Package | `minisearch` | `@yoch/frozenminisearch` |
 | Construction | `new MiniSearch(opts).addAll(docs)` | `FrozenMiniSearch.fromDocuments(docs, opts)` or `fromMiniSearch(mutable, opts)` |
-| JSON snapshot | `MiniSearch.loadJSON(json)` / `toJSON()` wire format | `FrozenMiniSearch.fromMiniSearchJson(json, opts)` or `fromMiniSearchSnapshot(obj)` — no runtime dependency on lucaong `minisearch` |
+| JSON snapshot | `toJSON()` / `loadJSON()` wire format | `FrozenMiniSearch.toJSON()` / `fromJson(json, opts)` or `fromMiniSearchSnapshot(obj)` — no runtime dependency on `minisearch` |
 
-**Keep unchanged** after load: `search`, `autoSuggest`, `has`, `getStoredFields`, query options (`prefix`, `fuzzy`, `AND` / `OR` / `AND_NOT`, filters, boosts). Parity vs `minisearch@7` is enforced in `dev/parity/`.
+**Keep unchanged** after load: `search`, `autoSuggest`, `has`, `getStoredFields`, query options (`prefix`, `fuzzy`, `AND` / `OR` / `AND_NOT`, filters, boosts). Parity vs MiniSearch 7 is enforced in `dev/parity/`.
 
 **Imports** — default and named both work (ESM and CJS):
 
@@ -121,7 +137,7 @@ const { FrozenMiniSearch } = require('@yoch/frozenminisearch')
 
 ## Migration
 
-### From lucaong `minisearch` JSON
+### From MiniSearch JSON
 
 ```javascript
 import MiniSearch from 'minisearch' // build-time only
@@ -135,18 +151,18 @@ const frozen = FrozenMiniSearch.fromMiniSearch(mutable, options)
 
 // Option B — serialized index (offline / ETL)
 const json = JSON.stringify(mutable)
-const frozen2 = FrozenMiniSearch.fromMiniSearchJson(json, options)
+const frozen2 = FrozenMiniSearch.fromJson(json, options)
 ```
 
 `options.fields` must match the indexed fields in the snapshot when provided.
 
-### From lucaong `minisearch` (mutable → frozen)
+### From MiniSearch (mutable → frozen)
 
 | Before (mutable) | After (`@yoch/frozenminisearch`) |
 |------------------|----------------------------------|
 | `new MiniSearch(opts).addAll(docs)` then serve | `FrozenMiniSearch.fromDocuments(docs, opts)` or `fromMiniSearch(mutable, opts)` |
-| lucaong JSON snapshot | `FrozenMiniSearch.fromMiniSearchJson(json)` or `fromMiniSearchSnapshot(obj)` |
-| `import MiniSearch from 'minisearch'` | `import FrozenMiniSearch from '@yoch/frozenminisearch'` (+ lucaong `minisearch` only if you still build mutable indexes) |
+| MiniSearch JSON snapshot | `FrozenMiniSearch.fromJson(json)` or `fromMiniSearchSnapshot(obj)` |
+| `import MiniSearch from 'minisearch'` | `import FrozenMiniSearch from '@yoch/frozenminisearch'` (+ `minisearch` only if you still build mutable indexes) |
 
 ---
 
@@ -163,13 +179,15 @@ Indexing is **not** available on a frozen instance — use `fromDocuments`, the
 
 ## Binary snapshots
 
+The primary way to **persist and ship a memory-compact index** — smaller than MiniSearch JSON and faster to load into a low-RAM serving process.
+
 ```javascript
 const buf = index.saveBinarySync()
 const loaded = FrozenMiniSearch.loadBinarySync(buf, {}) // field names embedded in snapshot
 ```
 
 - **Node ≥ 22.15.0** (zstd via `node:zlib`)
-- Snapshots produced by this package version are forward-compatible; re-build from lucaong JSON if an older binary fails to load
+- Snapshots produced by this package version are forward-compatible; re-build from MiniSearch JSON if an older binary fails to load
 - `tokenize` / `processTerm` are not stored — pass the same functions at load when customized
 
 ---
@@ -206,6 +224,6 @@ Design notes (freq adaptive, AND gating): [dev/docs/README.md](dev/docs/README.m
 See [CHANGELOG.md](./CHANGELOG.md).
 
 - **MiniSearch** — [Luca Ongaro](https://github.com/lucaong/minisearch) (MIT)
-- **@yoch/frozenminisearch** — frozen indexes, packed radix tree, compact binary snapshots
+- **@yoch/frozenminisearch** — memory-optimized frozen indexes, packed radix tree, compact binary snapshots
 
 Upstream docs: [MiniSearch](https://lucaong.github.io/minisearch/)

package/dist/cjs/index.cjs

@@ -1938,7 +1938,7 @@ function postingsTypedBytes(layout) {
         slotCount,
     };
 }
-function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = detail => { throw new Error(detail); }) {
+function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = (detail) => { throw new Error(detail); }) {
     if (layout.fieldCount <= 0)
         fail('fieldCount must be positive');
     if (layout.nextId !== nextId)
@@ -2209,7 +2209,7 @@ function forEachDefaultToken(text, onToken) {
 /** Default tokenizer into a reusable buffer (avoids `text.split()` array allocation). */
 function tokenizeDefaultInto(out, text) {
     out.length = 0;
-    forEachDefaultToken(text, (token) => out.push(token));
+    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) {
@@ -2288,7 +2288,7 @@ function validateFrozenSnapshotNumeric(snap) {
     if (snap.avgFieldLength.length !== snap.fieldCount) {
         throw invalidFrozenIndex('avgFieldLength size mismatch');
     }
-    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, detail => {
+    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, (detail) => {
         throw invalidFrozenIndex(detail);
     });
     const indexedFields = Object.keys(snap.fieldIds);
@@ -2503,7 +2503,7 @@ function cloneStoredFields(layout) {
     }
     return { kind: 'multi', rows: layout.rows.slice() };
 }
-/** Import from wire rows or lucaong snapshot. Empty storeFields + non-empty rows → multi (binary load without options). */
+/** Import from wire rows or MiniSearch 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);
@@ -2687,7 +2687,7 @@ function buildFlatPostingsFromSearchableMap(searchableMap, fieldCount, nextId, s
     });
     return { termCount, index: packedIndex, postings };
 }
-/** Build frozen assemble params from a lucaong MiniSearch JSON snapshot. */
+/** Build frozen assemble params from a MiniSearch JSON snapshot. */
 function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     var _a, _b, _c;
     if (!SUPPORTED_SERIALIZATION_VERSIONS.has(snapshot.serializationVersion)) {
@@ -3601,7 +3601,7 @@ function decodeFrozenSnapshot(buf, hints) {
         return decodeFrozenSnapshotMsv5(buf, hints);
     }
     if (LEGACY_MAGICS.has(magic)) {
-        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from lucaong JSON');
+        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from MiniSearch JSON');
     }
     throw invalidFrozenIndex('Unsupported frozen binary snapshot');
 }
@@ -4302,7 +4302,7 @@ function executeQueryInternal(query, searchOptions, params, allowedDocs, run) {
         return executeWildcardQuery(searchOptions, params);
     }
     if (isQueryCombination(query)) {
-        // Spread inherits parent combineWith into child branches (lucaong 7.2 behavior).
+        // Spread inherits parent combineWith into child branches (MiniSearch 7.2 behavior).
         const options = { ...searchOptions, ...query, queries: undefined };
         const operator = ((_b = (_a = query.combineWith) !== null && _a !== void 0 ? _a : options.combineWith) !== null && _b !== void 0 ? _b : params.globalSearchOptions.combineWith);
         if (useGatedEvaluation(run, query.queries.length, operator, combinationHasWildcard(query))) {
@@ -4352,6 +4352,73 @@ function autoSuggestFromSearch(search, queryString, options = {}) {
     return suggestFromSearchResults(search(queryString, options));
 }
 
+/** Visit shortIds with a defined external id (holes in `externalIds` are skipped). */
+function forEachLiveShortId(nextId, externalIds, callback) {
+    for (let shortId = 0; shortId < nextId; shortId++) {
+        const externalId = externalIds[shortId];
+        if (externalId === undefined)
+            continue;
+        callback(shortId, externalId);
+    }
+}
+
+/**
+ * Build a MiniSearch `toJSON` wire snapshot (`serializationVersion: 2`) from frozen index parts.
+ * Alloc-heavy (plain objects per term/field) — migration/interop only, not production persistence.
+ * All input parts must belong to the same frozen index instance.
+ */
+function miniSearchSnapshotFromFrozen(input) {
+    const { documentCount, nextId, fieldIds, fieldCount, externalIds, fieldLengthMatrix, avgFieldLength, storedFields, index, fieldTermFlyweight, } = input;
+    const documentIds = {};
+    const fieldLength = {};
+    const storedFieldsOut = {};
+    const hasStoredFields = storedFields.kind !== 'none';
+    forEachLiveShortId(nextId, externalIds, (shortId, externalId) => {
+        var _a;
+        const shortIdStr = String(shortId);
+        documentIds[shortIdStr] = externalId;
+        const lengths = new Array(fieldCount);
+        const rowBase = shortId * fieldCount;
+        for (let f = 0; f < fieldCount; f++) {
+            lengths[f] = (_a = fieldLengthMatrix[rowBase + f]) !== null && _a !== void 0 ? _a : 0;
+        }
+        fieldLength[shortIdStr] = lengths;
+        if (hasStoredFields) {
+            storedFieldsOut[shortIdStr] = readStoredFields(storedFields, shortId);
+        }
+    });
+    const indexEntries = [];
+    for (const [term, termIndex] of index.entries()) {
+        fieldTermFlyweight.bind(termIndex);
+        const fieldData = {};
+        for (let f = 0; f < fieldCount; f++) {
+            const segment = fieldTermFlyweight.get(f);
+            if (segment == null || segment.size === 0)
+                continue;
+            const entry = {};
+            segment.forEachDoc((docId, freq) => {
+                entry[String(docId)] = freq;
+            });
+            fieldData[String(f)] = entry;
+        }
+        if (Object.keys(fieldData).length > 0) {
+            indexEntries.push([term, fieldData]);
+        }
+    }
+    return {
+        documentCount,
+        nextId,
+        documentIds,
+        fieldIds,
+        fieldLength,
+        averageFieldLength: Array.from(avgFieldLength),
+        storedFields: storedFieldsOut,
+        dirtCount: 0,
+        index: indexEntries,
+        serializationVersion: 2,
+    };
+}
+
 function ownedIndexArray(arr) {
     if (arr instanceof Uint8Array)
         return new Uint8Array(arr);
@@ -4510,12 +4577,9 @@ class FrozenMiniSearch {
             tokenize: this._options.tokenize,
             processTerm: this._options.processTerm,
             indexView: createFrozenQueryIndexView(this._index, this._postings, this._fieldTermFlyweight, (callback) => {
-                for (let shortId = 0; shortId < this._nextId; shortId++) {
-                    const id = this._externalIds[shortId];
-                    if (id === undefined)
-                        continue;
+                forEachLiveShortId(this._nextId, this._externalIds, (shortId, id) => {
                     callback(shortId, id, readStoredFields(this._storedFields, shortId));
-                }
+                });
             }),
             aggregateContext: this._aggregateContext,
         };
@@ -4669,21 +4733,43 @@ class FrozenMiniSearch {
         return buildFrozenFromDocuments(documents, options);
     }
     /**
-     * Convert a lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format) into a
-     * frozen index. No runtime dependency on the `minisearch` package.
+     * Export this index as a MiniSearch wire snapshot (`serializationVersion: 2`).
+     * Use for migration or interchange with the `minisearch` package (`JSON.stringify` works via this method).
+     * Not the primary persistence format — prefer {@link saveBinarySync} for production (size and load time).
+     * Term order in `index` may differ from MiniSearch native `toJSON`; search scores stay equivalent.
+     */
+    toJSON() {
+        return miniSearchSnapshotFromFrozen({
+            documentCount: this._documentCount,
+            nextId: this._nextId,
+            fieldIds: this._fieldIds,
+            fieldCount: this._fieldCount,
+            externalIds: this._externalIds,
+            fieldLengthMatrix: this._fieldLengthMatrix,
+            avgFieldLength: this._avgFieldLength,
+            storedFields: this._storedFields,
+            index: this._index,
+            fieldTermFlyweight: this._fieldTermFlyweight,
+        });
+    }
+    /**
+     * Build a new frozen index **from** a MiniSearch JSON snapshot string (import / migration).
+     * Accepts the wire format produced by MiniSearch `toJSON` or by {@link toJSON} on this class.
+     * Distinct from {@link loadBinarySync}: JSON is MiniSearch interchange, not the native frozen binary.
+     * No runtime dependency on the `minisearch` package.
      */
-    static fromMiniSearchJson(json, options = {}) {
+    static fromJson(json, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(JSON.parse(json), options);
     }
     /**
-     * Same as {@link fromMiniSearchJson} with a pre-parsed snapshot object.
+     * Same as {@link fromJson} with a pre-parsed snapshot object.
      * `storedFields` are shallow-copied; callers must not mutate nested values
      * after load if they intend to keep the index immutable.
      */
     static fromMiniSearchSnapshot(snapshot, options = {}) {
         return assembleFrozenTrusted(buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options), 'minisearch-json');
     }
-    /** Accepts any object exposing `toJSON()` in lucaong MiniSearch snapshot shape. */
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
     static fromMiniSearch(source, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(source.toJSON(), options);
     }

package/dist/es/index.d.ts

@@ -459,7 +459,7 @@ interface FrozenMemoryBreakdown {
 /**
  * Low-level parameters for {@link assembleFrozen} (custom frozen index pipelines).
  * Field types are part of the public surface for advanced assembly; typical apps use
- * {@link buildFrozenFromDocuments}, {@link FrozenMiniSearch.fromMiniSearchJson}, or binary load instead.
+ * {@link buildFrozenFromDocuments}, {@link FrozenMiniSearch.fromJson}, or binary load instead.
  */
 interface FrozenAssembleParams<T = any> {
     options: OptionsWithDefaults<T>;
@@ -479,7 +479,7 @@ interface FrozenAssembleParams<T = any> {
     postings: FrozenPostingsLayout;
 }
 
-/** Lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format). */
+/** MiniSearch JSON snapshot (`toJSON` wire format, `serializationVersion` 1 or 2). */
 type SerializedIndexEntry = Record<string, number>;
 type MiniSearchSnapshot = {
     documentCount: number;
@@ -607,17 +607,26 @@ declare class FrozenMiniSearch<T = any> {
     /** Build a read-only index in one pass from documents. */
     static fromDocuments<T>(documents: readonly T[], options: Options<T>): FrozenMiniSearch<T>;
     /**
-     * Convert a lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format) into a
-     * frozen index. No runtime dependency on the `minisearch` package.
+     * Export this index as a MiniSearch wire snapshot (`serializationVersion: 2`).
+     * Use for migration or interchange with the `minisearch` package (`JSON.stringify` works via this method).
+     * Not the primary persistence format — prefer {@link saveBinarySync} for production (size and load time).
+     * Term order in `index` may differ from MiniSearch native `toJSON`; search scores stay equivalent.
      */
-    static fromMiniSearchJson<T>(json: string, options?: Options<T>): FrozenMiniSearch<T>;
+    toJSON(): MiniSearchSnapshot;
     /**
-     * Same as {@link fromMiniSearchJson} with a pre-parsed snapshot object.
+     * Build a new frozen index **from** a MiniSearch JSON snapshot string (import / migration).
+     * Accepts the wire format produced by MiniSearch `toJSON` or by {@link toJSON} on this class.
+     * Distinct from {@link loadBinarySync}: JSON is MiniSearch interchange, not the native frozen binary.
+     * No runtime dependency on the `minisearch` package.
+     */
+    static fromJson<T>(json: string, options?: Options<T>): FrozenMiniSearch<T>;
+    /**
+     * Same as {@link fromJson} with a pre-parsed snapshot object.
      * `storedFields` are shallow-copied; callers must not mutate nested values
      * after load if they intend to keep the index immutable.
      */
     static fromMiniSearchSnapshot<T>(snapshot: MiniSearchSnapshot, options?: Options<T>): FrozenMiniSearch<T>;
-    /** Accepts any object exposing `toJSON()` in lucaong MiniSearch snapshot shape. */
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
     static fromMiniSearch<T>(source: {
         toJSON(): MiniSearchSnapshot;
     }, options?: Options<T>): FrozenMiniSearch<T>;

package/dist/es/index.js

@@ -1934,7 +1934,7 @@ function postingsTypedBytes(layout) {
         slotCount,
     };
 }
-function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = detail => { throw new Error(detail); }) {
+function validateFrozenPostingsLayout(layout, documentCount, nextId, fail = (detail) => { throw new Error(detail); }) {
     if (layout.fieldCount <= 0)
         fail('fieldCount must be positive');
     if (layout.nextId !== nextId)
@@ -2205,7 +2205,7 @@ function forEachDefaultToken(text, onToken) {
 /** Default tokenizer into a reusable buffer (avoids `text.split()` array allocation). */
 function tokenizeDefaultInto(out, text) {
     out.length = 0;
-    forEachDefaultToken(text, (token) => out.push(token));
+    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) {
@@ -2284,7 +2284,7 @@ function validateFrozenSnapshotNumeric(snap) {
     if (snap.avgFieldLength.length !== snap.fieldCount) {
         throw invalidFrozenIndex('avgFieldLength size mismatch');
     }
-    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, detail => {
+    validateFrozenPostingsLayout(snap.postings, snap.documentCount, snap.nextId, (detail) => {
         throw invalidFrozenIndex(detail);
     });
     const indexedFields = Object.keys(snap.fieldIds);
@@ -2499,7 +2499,7 @@ function cloneStoredFields(layout) {
     }
     return { kind: 'multi', rows: layout.rows.slice() };
 }
-/** Import from wire rows or lucaong snapshot. Empty storeFields + non-empty rows → multi (binary load without options). */
+/** Import from wire rows or MiniSearch 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);
@@ -2683,7 +2683,7 @@ function buildFlatPostingsFromSearchableMap(searchableMap, fieldCount, nextId, s
     });
     return { termCount, index: packedIndex, postings };
 }
-/** Build frozen assemble params from a lucaong MiniSearch JSON snapshot. */
+/** Build frozen assemble params from a MiniSearch JSON snapshot. */
 function buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options) {
     var _a, _b, _c;
     if (!SUPPORTED_SERIALIZATION_VERSIONS.has(snapshot.serializationVersion)) {
@@ -3597,7 +3597,7 @@ function decodeFrozenSnapshot(buf, hints) {
         return decodeFrozenSnapshotMsv5(buf, hints);
     }
     if (LEGACY_MAGICS.has(magic)) {
-        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from lucaong JSON');
+        throw invalidFrozenIndex('Unsupported frozen binary snapshot; re-build with saveBinarySync() or from MiniSearch JSON');
     }
     throw invalidFrozenIndex('Unsupported frozen binary snapshot');
 }
@@ -4298,7 +4298,7 @@ function executeQueryInternal(query, searchOptions, params, allowedDocs, run) {
         return executeWildcardQuery(searchOptions, params);
     }
     if (isQueryCombination(query)) {
-        // Spread inherits parent combineWith into child branches (lucaong 7.2 behavior).
+        // Spread inherits parent combineWith into child branches (MiniSearch 7.2 behavior).
         const options = { ...searchOptions, ...query, queries: undefined };
         const operator = ((_b = (_a = query.combineWith) !== null && _a !== void 0 ? _a : options.combineWith) !== null && _b !== void 0 ? _b : params.globalSearchOptions.combineWith);
         if (useGatedEvaluation(run, query.queries.length, operator, combinationHasWildcard(query))) {
@@ -4348,6 +4348,73 @@ function autoSuggestFromSearch(search, queryString, options = {}) {
     return suggestFromSearchResults(search(queryString, options));
 }
 
+/** Visit shortIds with a defined external id (holes in `externalIds` are skipped). */
+function forEachLiveShortId(nextId, externalIds, callback) {
+    for (let shortId = 0; shortId < nextId; shortId++) {
+        const externalId = externalIds[shortId];
+        if (externalId === undefined)
+            continue;
+        callback(shortId, externalId);
+    }
+}
+
+/**
+ * Build a MiniSearch `toJSON` wire snapshot (`serializationVersion: 2`) from frozen index parts.
+ * Alloc-heavy (plain objects per term/field) — migration/interop only, not production persistence.
+ * All input parts must belong to the same frozen index instance.
+ */
+function miniSearchSnapshotFromFrozen(input) {
+    const { documentCount, nextId, fieldIds, fieldCount, externalIds, fieldLengthMatrix, avgFieldLength, storedFields, index, fieldTermFlyweight, } = input;
+    const documentIds = {};
+    const fieldLength = {};
+    const storedFieldsOut = {};
+    const hasStoredFields = storedFields.kind !== 'none';
+    forEachLiveShortId(nextId, externalIds, (shortId, externalId) => {
+        var _a;
+        const shortIdStr = String(shortId);
+        documentIds[shortIdStr] = externalId;
+        const lengths = new Array(fieldCount);
+        const rowBase = shortId * fieldCount;
+        for (let f = 0; f < fieldCount; f++) {
+            lengths[f] = (_a = fieldLengthMatrix[rowBase + f]) !== null && _a !== void 0 ? _a : 0;
+        }
+        fieldLength[shortIdStr] = lengths;
+        if (hasStoredFields) {
+            storedFieldsOut[shortIdStr] = readStoredFields(storedFields, shortId);
+        }
+    });
+    const indexEntries = [];
+    for (const [term, termIndex] of index.entries()) {
+        fieldTermFlyweight.bind(termIndex);
+        const fieldData = {};
+        for (let f = 0; f < fieldCount; f++) {
+            const segment = fieldTermFlyweight.get(f);
+            if (segment == null || segment.size === 0)
+                continue;
+            const entry = {};
+            segment.forEachDoc((docId, freq) => {
+                entry[String(docId)] = freq;
+            });
+            fieldData[String(f)] = entry;
+        }
+        if (Object.keys(fieldData).length > 0) {
+            indexEntries.push([term, fieldData]);
+        }
+    }
+    return {
+        documentCount,
+        nextId,
+        documentIds,
+        fieldIds,
+        fieldLength,
+        averageFieldLength: Array.from(avgFieldLength),
+        storedFields: storedFieldsOut,
+        dirtCount: 0,
+        index: indexEntries,
+        serializationVersion: 2,
+    };
+}
+
 function ownedIndexArray(arr) {
     if (arr instanceof Uint8Array)
         return new Uint8Array(arr);
@@ -4506,12 +4573,9 @@ class FrozenMiniSearch {
             tokenize: this._options.tokenize,
             processTerm: this._options.processTerm,
             indexView: createFrozenQueryIndexView(this._index, this._postings, this._fieldTermFlyweight, (callback) => {
-                for (let shortId = 0; shortId < this._nextId; shortId++) {
-                    const id = this._externalIds[shortId];
-                    if (id === undefined)
-                        continue;
+                forEachLiveShortId(this._nextId, this._externalIds, (shortId, id) => {
                     callback(shortId, id, readStoredFields(this._storedFields, shortId));
-                }
+                });
             }),
             aggregateContext: this._aggregateContext,
         };
@@ -4665,21 +4729,43 @@ class FrozenMiniSearch {
         return buildFrozenFromDocuments(documents, options);
     }
     /**
-     * Convert a lucaong MiniSearch JSON snapshot (`toJSON` / `loadJSON` wire format) into a
-     * frozen index. No runtime dependency on the `minisearch` package.
+     * Export this index as a MiniSearch wire snapshot (`serializationVersion: 2`).
+     * Use for migration or interchange with the `minisearch` package (`JSON.stringify` works via this method).
+     * Not the primary persistence format — prefer {@link saveBinarySync} for production (size and load time).
+     * Term order in `index` may differ from MiniSearch native `toJSON`; search scores stay equivalent.
+     */
+    toJSON() {
+        return miniSearchSnapshotFromFrozen({
+            documentCount: this._documentCount,
+            nextId: this._nextId,
+            fieldIds: this._fieldIds,
+            fieldCount: this._fieldCount,
+            externalIds: this._externalIds,
+            fieldLengthMatrix: this._fieldLengthMatrix,
+            avgFieldLength: this._avgFieldLength,
+            storedFields: this._storedFields,
+            index: this._index,
+            fieldTermFlyweight: this._fieldTermFlyweight,
+        });
+    }
+    /**
+     * Build a new frozen index **from** a MiniSearch JSON snapshot string (import / migration).
+     * Accepts the wire format produced by MiniSearch `toJSON` or by {@link toJSON} on this class.
+     * Distinct from {@link loadBinarySync}: JSON is MiniSearch interchange, not the native frozen binary.
+     * No runtime dependency on the `minisearch` package.
      */
-    static fromMiniSearchJson(json, options = {}) {
+    static fromJson(json, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(JSON.parse(json), options);
     }
     /**
-     * Same as {@link fromMiniSearchJson} with a pre-parsed snapshot object.
+     * Same as {@link fromJson} with a pre-parsed snapshot object.
      * `storedFields` are shallow-copied; callers must not mutate nested values
      * after load if they intend to keep the index immutable.
      */
     static fromMiniSearchSnapshot(snapshot, options = {}) {
         return assembleFrozenTrusted(buildFrozenAssembleParamsFromMiniSearchSnapshot(snapshot, options), 'minisearch-json');
     }
-    /** Accepts any object exposing `toJSON()` in lucaong MiniSearch snapshot shape. */
+    /** Accepts any object exposing `toJSON()` in MiniSearch snapshot shape. */
     static fromMiniSearch(source, options = {}) {
         return FrozenMiniSearch.fromMiniSearchSnapshot(source.toJSON(), options);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yoch/frozenminisearch",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Read-only Node.js full-text search — compact frozen indexes and binary snapshots",
   "main": "dist/cjs/index.cjs",
   "module": "dist/es/index.js",
@@ -49,7 +49,6 @@
     "@types/benchmark": "^2.1.1",
     "benchmark": "^2.1.4",
     "core-js": "^3.1.4",
-    "coveralls-next": "^6.0.1",
     "crc-32": "^1.2.2",
     "eslint": "^10.4.0",
     "fast-check": "^4.8.0",
@@ -88,6 +87,15 @@
       "<rootDir>/src/**/*.test.(ts|js)",
       "<rootDir>/dev/parity/**/*.test.(ts|js)"
     ],
+    "collectCoverageFrom": [
+      "src/**/*.{ts,js}",
+      "!src/**/*.test.{ts,js}"
+    ],
+    "coveragePathIgnorePatterns": [
+      "/benchmarks/",
+      "/dev/",
+      "/testSupport/"
+    ],
     "setupFilesAfterEnv": []
   },
   "scripts": {