@yoch/frozenminisearch 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## v1.0.1 — `@yoch/frozenminisearch`
+
+Patch release: lower build-time peak memory and migration ergonomics. No API or wire-format changes.
+
+### Improved
+
+- **`FrozenIndexBuilder` peak heap** — incremental typed-array posting accumulators replace per-term `number[][]` scratch; token and term-frequency buffers are reused across `add()` calls.
+- **Default tokenization during build** — single-pass field scan when the default splitter is in use (`collectFieldTermFreqsFromFieldInto`).
+
+### Fixed
+
+- **Default tokenizer parity** — leading delimiter produces an empty token (e.g. `::a` → `["", "a"]`), matching lucaong `split` behaviour.
+- **Named export** — `FrozenMiniSearch` is exported again alongside the default export (ESM and CJS).
+
 ## v1.0.0 — `@yoch/frozenminisearch`
 
 First stable release on npm. Frozen-only read-only search for Node.js.

package/README.md

@@ -1,10 +1,10 @@
 # @yoch/frozenminisearch
 
-**Read-only full-text search for Node.js** — compact frozen indexes, fast binary snapshots, and the same search API as [MiniSearch](https://github.com/lucaong/minisearch) by [Luca Ongaro](https://github.com/lucaong).
+**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).
 
-> **Current release:** `1.0.0` on npm
+> **Current release:** `1.0.1` on npm
 
-This package is a **standalone product**: no mutable `MiniSearch` class is published. Build indexes with `fromDocuments`, the incremental builder, or migrate from an existing lucaong index via `fromMiniSearchJson`.
+**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`.
 
 ---
 
@@ -19,15 +19,15 @@ Same BM25 queries on identical corpora. **Frozen wins on what we optimize for**:
 
 | Scenario | Docs | Index RAM¹ | Disk (binary vs JSON)² | Cold load³ | Search p50⁴ |
 |----------|-----:|------------|------------------------:|-----------:|------------:|
-| Divina with storeFields | 14,097 | 1.1 vs 16.0 MB (~93% less) | ~73% less | ~71% faster | ~14% faster |
-| Divina index only | 14,097 | 0.3 vs 14.9 MB (~98% less) | ~77% less | ~86% faster | ~3% faster |
-| high-frequency terms (10k docs) | 10,000 | 0.2 vs 7.4 MB (~97% less) | ~94% less | ~90% faster | ~32% faster |
-| Dense numeric ids (100k, identity lookup) | 100,000 | 1.7 vs 91.2 MB (~98% less) | ~88% less | ~90% faster | ~21% faster |
-| Doc id Uint16 boundary (65535 docs) | 65,535 | 1.1 vs 58.6 MB (~98% less) | ~91% less | ~94% faster | ~38% faster |
+| Divina with storeFields | 14,097 | 1.1 vs 16.0 MB (~93% less) | ~73% less | ~70% faster | ~13% faster |
+| Divina index only | 14,097 | 0.3 vs 14.9 MB (~98% less) | ~77% less | ~86% faster | ~8% faster |
+| high-frequency terms (10k docs) | 10,000 | 0.2 vs 7.4 MB (~98% less) | ~94% less | ~93% faster | ~29% faster |
+| Dense numeric ids (100k, identity lookup) | 100,000 | 1.6 vs 91.2 MB (~98% less) | ~88% less | ~91% faster | ~18% faster |
+| Doc id Uint16 boundary (65535 docs) | 65,535 | 1.1 vs 58.6 MB (~98% less) | ~91% less | ~93% faster | ~43% faster |
 
-**Headline:** 22/27 query benchmarks favor frozen (paired **hrtime** protocol v2). Divina `inferno` (exact, paired p50): mutable 16.3 µs → frozen 13.8 µs (**-2 µs**, ratio 0.87).
+**Headline:** 22/27 query benchmarks favor frozen (paired **hrtime** protocol v2). Divina `inferno` (exact, paired p50): mutable 16.2 µs → frozen 13.7 µs (**-2 µs**, ratio 0.90).
 
-Decomposition (Divina exact): L0 lookup ~300 ns frozen, L1 `executeQuery` ~8.1 µs, L2 full `search` ~11.5 µs (finalize ≈ 3 µs).
+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` |
 |---|------------------------|---------------------------|
@@ -38,7 +38,7 @@ Decomposition (Divina exact): L0 lookup ~300 ns frozen, L1 `executeQuery` ~8.1
 <details>
 <summary><strong>How to read these numbers (limits &amp; protocol)</strong></summary>
 
-- **Captured:** 2026-06-07 · commit `2a9a90d` · Node v24.16.0 · minisearch **7.2.0** · **3** run(s)/scenario · protocol **v2** (hrtime-paired, batch target 3 ms).
+- **Captured:** 2026-06-07 · commit `9f32207` · Node v24.16.0 · minisearch **7.2.0** · **3** run(s)/scenario · protocol **v2** (hrtime-paired, batch target 3 ms).
 - ¹ **Index RAM** — `measureHeap` with `--expose-gc`, one index alive. V8 overhead is extra; treat as **trend**, not accounting. Sporadic outliers happen (e.g. index-only Divina).
 - ² **Disk** — `JSON.stringify(mutable)` vs `saveBinarySync`.
 - ³ **Cold load** — median wall time to searchable index after read from disk format.
@@ -89,6 +89,36 @@ 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.
+
+**Change only:**
+
+| What | Before | After |
+|------|--------|-------|
+| Package | lucaong `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` |
+
+**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):
+
+```javascript
+// ESM
+import FrozenMiniSearch from '@yoch/frozenminisearch'
+import { FrozenMiniSearch } from '@yoch/frozenminisearch'
+
+// CommonJS
+const FrozenMiniSearch = require('@yoch/frozenminisearch')
+const { FrozenMiniSearch } = require('@yoch/frozenminisearch')
+```
+
+**Intentionally not drop-in:** live `add` / `remove` / `discard` (frozen is read-only); browser builds; custom `tokenize` / `processTerm` are not stored in JSON or binary snapshots — pass the same functions at load when you customized them.
+
+---
+
 ## Migration
 
 ### From lucaong `minisearch` JSON