rapid-fuzzy 0.5.0 → 0.6.0

package/README.md

@@ -8,18 +8,36 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
 
-Rust-powered fuzzy search and string distance for JavaScript/TypeScript.
+Blazing-fast fuzzy search for JavaScript — powered by Rust, works everywhere.
 
-> **Status**: Early release (v0.x). API may change between minor versions.
+<img src=".github/assets/demo.svg" alt="rapid-fuzzy demo — fuzzy search, query syntax, FuzzyIndex, and string distance" width="580" />
 
 ## Features
 
-- **Fast**: Up to 40x faster than fuse.js for large datasets (Rust + napi-rs)
+- **Fast**: Up to 7,000x faster than fuse.js with FuzzyIndex (Rust + napi-rs)
 - **Universal**: Works in Node.js (native), browsers (WASM), Deno, and Bun
 - **Zero JS dependencies**: Pure Rust core with napi-rs bindings
 - **Type-safe**: Full TypeScript support with auto-generated type definitions
 - **Drop-in**: API compatible with popular fuzzy search libraries
 
+## Quick Start
+
+```typescript
+import { search } from 'rapid-fuzzy';
+
+const results = search('typscript', ['TypeScript', 'JavaScript', 'Python']);
+// → [{ item: 'TypeScript', score: 0.85, index: 0 }, ...]
+```
+
+For repeated searches, use `FuzzyIndex` for up to 182x faster lookups:
+
+```typescript
+import { FuzzyIndex } from 'rapid-fuzzy';
+
+const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python', ...]);
+index.search('typscript'); // sub-millisecond with incremental cache
+```
+
 ## Installation
 
 ```bash
@@ -33,17 +51,7 @@ pnpm add rapid-fuzzy
 - **Node.js** (>=20): Uses native bindings via napi-rs for best performance.
 - **Browser / Deno / Bun**: Falls back to a WASM build automatically.
 
-## Usage
-
-### String Distance
-
-```typescript
-import { levenshtein, jaroWinkler, sorensenDice } from 'rapid-fuzzy';
-
-levenshtein('kitten', 'sitting');     // 3
-jaroWinkler('MARTHA', 'MARHTA');      // 0.961
-sorensenDice('night', 'nacht');       // 0.25
-```
+> **Note**: rapid-fuzzy is pre-1.0 — the API is stable but minor versions may include additions.
 
 ### Fuzzy Search
 
@@ -81,6 +89,32 @@ closest('xyz', items, 0.5);
 // → null
 ```
 
+### String Distance
+
+```typescript
+import { levenshtein, jaroWinkler, sorensenDice } from 'rapid-fuzzy';
+
+levenshtein('kitten', 'sitting');     // 3
+jaroWinkler('MARTHA', 'MARHTA');      // 0.961
+sorensenDice('night', 'nacht');       // 0.25
+```
+
+### Query Syntax
+
+Queries support extended syntax powered by the [nucleo](https://github.com/helix-editor/nucleo) pattern parser:
+
+| Pattern | Match type | Example |
+|---|---|---|
+| `foo bar` | AND (order-independent) | `john smith` matches "Smith, John" |
+| `!term` | Exclude | `apple !pie` excludes "apple pie" |
+| `^term` | Starts with | `^app` matches "apple" but not "pineapple" |
+| `term$` | Ends with | `pie$` matches "apple pie" |
+| `'term` | Exact substring | `'pie` matches "pie" literally |
+
+Diacritics are handled automatically — `cafe` matches `café`, `uber` matches `über`, and `naive` matches `naïve` with no configuration needed.
+
+> **Note**: These patterns apply to all search functions: `search()`, `closest()`, `FuzzyIndex.search()`, `FuzzyObjectIndex.search()`, and `searchObjects()`. They do **not** apply to distance functions (`levenshtein`, `jaro`, etc.).
+
 ### Object Search
 
 Search across object properties with weighted keys — a drop-in replacement for fuse.js's `keys` option:
@@ -119,7 +153,7 @@ For applications that search the same dataset repeatedly (autocomplete, file fin
 ```typescript
 import { FuzzyIndex, FuzzyObjectIndex } from 'rapid-fuzzy';
 
-// String search index — up to 5x faster than standalone search()
+// String search index — up to 182x faster than standalone search()
 const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python', ...]);
 
 index.search('typscript', { maxResults: 5 });
@@ -215,6 +249,27 @@ levenshteinMany('kitten', ['sitting', 'kittens', 'kitchen']);
 
 > **Tip**: Prefer batch/many variants over calling single-pair functions in a loop — they are significantly faster for multiple comparisons.
 
+## Choosing an Algorithm
+
+| Use case | Recommended | Why |
+|---|---|---|
+| Typo detection / spell check | `levenshtein`, `damerauLevenshtein` | Counts edits; Damerau adds transposition support |
+| Name / address matching | `jaroWinkler`, `tokenSortRatio` | Prefix-weighted or order-independent matching |
+| Document / text similarity | `sorensenDice` | Bigram-based; handles longer text well |
+| Normalized comparison (0–1) | `normalizedLevenshtein` | Length-independent similarity score |
+| Reordered words / messy data | `tokenSortRatio`, `tokenSetRatio` | Handles word order differences and extra tokens |
+| Substring / abbreviation matching | `partialRatio` | Finds best partial match within longer strings |
+| Best-effort similarity | `weightedRatio` | Picks the best score across all methods automatically |
+| Interactive fuzzy search | `search`, `closest` | Nucleo algorithm (same as Helix editor) |
+| Repeated search on same data | `FuzzyIndex`, `FuzzyObjectIndex` | Persistent Rust-side index with incremental cache, up to 182x faster |
+
+**Return types:**
+
+- `levenshtein`, `damerauLevenshtein` → integer (edit count)
+- `jaro`, `jaroWinkler`, `sorensenDice`, `normalizedLevenshtein` → float between 0.0 (no match) and 1.0 (identical)
+- `tokenSortRatio`, `tokenSetRatio`, `partialRatio`, `weightedRatio` → float between 0.0 and 1.0
+- `search` → array of `{ item, score, index, positions }` sorted by relevance (score: 0.0–1.0)
+
 ## Benchmarks
 
 Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.dev/guide/features.html#benchmarking). Each benchmark processes 6 realistic string pairs of varying length and similarity.
@@ -228,46 +283,50 @@ Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.
 
 | Function | rapid-fuzzy | fastest-levenshtein | leven | string-similarity |
 |---|---:|---:|---:|---:|
-| Levenshtein | 528,195 ops/s | **739,107 ops/s** | 221,817 ops/s | — |
-| Normalized Levenshtein | **534,231 ops/s** | — | — | — |
-| Sorensen-Dice | **149,567 ops/s** | — | — | 82,908 ops/s |
-| Jaro-Winkler | **278,554 ops/s** | — | — | — |
-| Damerau-Levenshtein | **112,370 ops/s** | — | — | — |
+| Levenshtein | 562,063 ops/s | **794,298 ops/s** | 228,688 ops/s | — |
+| Normalized Levenshtein | **546,107 ops/s** | — | — | — |
+| Sorensen-Dice | **147,850 ops/s** | — | — | 84,308 ops/s |
+| Jaro-Winkler | **293,403 ops/s** | — | — | — |
+| Damerau-Levenshtein | **116,153 ops/s** | — | — | — |
 
 </details>
 
-> **Note**: For single-pair Levenshtein, fastest-levenshtein is ~1.4x faster due to its optimized pure-JS implementation that avoids FFI overhead. rapid-fuzzy is **2.4x faster** than leven, and provides broader algorithm coverage plus batch / search scenarios.
+> **Note**: For single-pair Levenshtein, fastest-levenshtein is ~1.4x faster due to its optimized pure-JS implementation that avoids FFI overhead. rapid-fuzzy is **2.5x faster** than leven, and provides broader algorithm coverage plus batch / search scenarios.
 
 ### Search Performance
 
-<img src=".github/assets/bench-search.svg" alt="Search performance chart — rapid-fuzzy vs fuse.js vs fuzzysort" width="680" />
+<img src=".github/assets/bench-search.svg" alt="Search performance chart — rapid-fuzzy vs fuse.js vs fuzzysort vs uFuzzy" width="680" />
+
+> Both `rapid-fuzzy` columns below show the same library: standalone `search()` vs `FuzzyIndex` (indexed mode for repeated searches).
 
 <details>
 <summary>Raw numbers</summary>
 
-| Dataset size | rapid-fuzzy | FuzzyIndex | fuse.js | fuzzysort |
-|---|---:|---:|---:|---:|
-| Small (20 items) | 174,812 ops/s | 406,269 ops/s | 127,167 ops/s | **2,502,299 ops/s** |
-| Medium (1K items) | 6,531 ops/s | 22,014 ops/s | 395 ops/s | **62,845 ops/s** |
-| Large (10K items) | 794 ops/s | 3,985 ops/s | 20 ops/s | **28,846 ops/s** |
+| Dataset size | rapid-fuzzy | rapid-fuzzy (indexed) | fuse.js | fuzzysort | uFuzzy |
+|---|---:|---:|---:|---:|---:|
+| Small (20 items) | 303,982 ops/s | 405,604 ops/s | 105,568 ops/s | **2,606,394 ops/s** | 923,069 ops/s |
+| Medium (1K items) | 6,787 ops/s | **80,579 ops/s** | 367 ops/s | 64,372 ops/s | 28,953 ops/s |
+| Large (10K items) | 751 ops/s | **136,528 ops/s** | 19 ops/s | 26,112 ops/s | 6,393 ops/s |
+| XL (50K items) | — | **31,903 ops/s** | — | 5,916 ops/s | 1,292 ops/s |
 
 </details>
 
 ### Closest Match (Levenshtein-based)
 
-| Dataset size | rapid-fuzzy | FuzzyIndex | fastest-levenshtein |
+| Dataset size | rapid-fuzzy | rapid-fuzzy (indexed) | fastest-levenshtein |
 |---|---:|---:|---:|
-| Medium (1K items) | 8,304 ops/s | **60,469 ops/s** | 8,946 ops/s |
-| Large (10K items) | 757 ops/s | **4,103 ops/s** | 604 ops/s |
+| Medium (1K items) | 8,611 ops/s | **989,095 ops/s** | 6,797 ops/s |
+| Large (10K items) | 924 ops/s | **156,014 ops/s** | 658 ops/s |
 
-> With `FuzzyIndex`, rapid-fuzzy is up to **6.8x faster** than fastest-levenshtein for closest-match lookups.
+> In indexed mode (`FuzzyIndex`), rapid-fuzzy is up to **237x faster** than fastest-levenshtein for closest-match lookups.
 
 ### Why these numbers matter
 
-- **vs fuse.js**: rapid-fuzzy is **17x faster** on medium datasets and **40x faster** on large datasets for fuzzy search.
-- **FuzzyIndex**: Pre-computing string data on the Rust side gives an additional **3–5x speedup** over standalone `search()`, making it the recommended approach for repeated searches.
-- **vs fastest-levenshtein**: With `FuzzyIndex`, closest-match is **6.8x faster** at scale. Even standalone `closest()` wins on large datasets.
-- **fuzzysort** uses a different (substring-based) matching algorithm that is extremely fast but produces different ranking results. Choose based on your matching needs.
+- **vs fuse.js**: `FuzzyIndex` is **219x faster** on medium datasets and **6,869x faster** on large datasets. Even standalone `search()` is 18x / 40x faster.
+- **Indexed mode**: `FuzzyIndex` keeps data on the Rust side with an incremental search cache, delivering sub-millisecond autocomplete. On large datasets this is **182x faster** than standalone `search()`.
+- **vs fuzzysort**: `FuzzyIndex` now **outperforms fuzzysort** on medium-and-above datasets — 1.25x faster at 1K, 5.2x at 10K, and 5.4x at 50K.
+- **vs uFuzzy**: `FuzzyIndex` is **2.8x faster** at medium and **21x faster** at large datasets.
+- **vs fastest-levenshtein**: With `FuzzyIndex`, closest-match is **145x faster** at 1K and **237x faster** at 10K.
 
 Run benchmarks yourself:
 
@@ -276,50 +335,34 @@ pnpm run bench        # JavaScript benchmarks
 cargo bench           # Rust internal benchmarks
 ```
 
-## Choosing an Algorithm
-
-| Use case | Recommended | Why |
-|---|---|---|
-| Typo detection / spell check | `levenshtein`, `damerauLevenshtein` | Counts edits; Damerau adds transposition support |
-| Name / address matching | `jaroWinkler`, `tokenSortRatio` | Prefix-weighted or order-independent matching |
-| Document / text similarity | `sorensenDice` | Bigram-based; handles longer text well |
-| Normalized comparison (0–1) | `normalizedLevenshtein` | Length-independent similarity score |
-| Reordered words / messy data | `tokenSortRatio`, `tokenSetRatio` | Handles word order differences and extra tokens |
-| Substring / abbreviation matching | `partialRatio` | Finds best partial match within longer strings |
-| Best-effort similarity | `weightedRatio` | Picks the best score across all methods automatically |
-| Interactive fuzzy search | `search`, `closest` | Nucleo algorithm (same as Helix editor) |
-| Repeated search on same data | `FuzzyIndex`, `FuzzyObjectIndex` | Persistent Rust-side index, 3–5x faster than standalone |
-
-**Return types:**
-
-- `levenshtein`, `damerauLevenshtein` → integer (edit count)
-- `jaro`, `jaroWinkler`, `sorensenDice`, `normalizedLevenshtein` → float between 0.0 (no match) and 1.0 (identical)
-- `tokenSortRatio`, `tokenSetRatio`, `partialRatio`, `weightedRatio` → float between 0.0 and 1.0
-- `search` → array of `{ item, score, index, positions }` sorted by relevance (score: 0.0–1.0)
-
 ## Why rapid-fuzzy?
 
-| | rapid-fuzzy | fuse.js | fastest-levenshtein | fuzzysort |
-|---|:---:|:---:|:---:|:---:|
-| **Algorithms** | 9 (Levenshtein, Jaro, Dice, …) | Bitap | Levenshtein | Substring |
-| **Runtime** | Rust native + WASM | Pure JS | Pure JS | Pure JS |
-| **Object search** | ✅ weighted keys | ✅ | — | ✅ |
-| **Persistent index** | ✅ FuzzyIndex / FuzzyObjectIndex | — | — | ✅ prepared targets |
-| **Score threshold** | ✅ | ✅ | — | ✅ |
-| **Match positions** | ✅ | ✅ | — | ✅ |
-| **Highlight utility** | ✅ | — | — | ✅ |
-| **Batch API** | ✅ | — | — | — |
-| **Node.js native** | ✅ napi-rs | — | — | — |
-| **Browser** | ✅ WASM | ✅ | ✅ | ✅ |
-| **TypeScript** | ✅ full | ✅ full | ✅ | ✅ |
+| | rapid-fuzzy | fuse.js | fastest-levenshtein | fuzzysort | uFuzzy |
+|---|:---:|:---:|:---:|:---:|:---:|
+| **Algorithms** | 9 (Levenshtein, Jaro, Dice, …) | Bitap | Levenshtein | Substring | Regex-based |
+| **Runtime** | Rust native + WASM | Pure JS | Pure JS | Pure JS | Pure JS |
+| **Object search** | ✅ weighted keys | ✅ | — | ✅ | — |
+| **Persistent index** | ✅ FuzzyIndex / FuzzyObjectIndex | — | — | ✅ prepared targets | — |
+| **Query syntax** | ✅ exclude, prefix, suffix, exact | ✅ extended search | — | — | partial (`-` only) |
+| **Out-of-order matching** | ✅ automatic | — | — | — | ✅ with option |
+| **Diacritics** | ✅ automatic | ✅ option | — | ✅ auto | ✅ `latinize()` |
+| **Score threshold** | ✅ | ✅ | — | ✅ | — |
+| **Match positions** | ✅ | ✅ | — | ✅ | ✅ |
+| **Highlight utility** | ✅ | — | — | ✅ | ✅ |
+| **Batch API** | ✅ | — | — | — | — |
+| **Node.js native** | ✅ napi-rs | — | — | — | — |
+| **Browser** | ✅ WASM | ✅ | ✅ | ✅ | ✅ |
+| **TypeScript** | ✅ full | ✅ full | ✅ | ✅ | ✅ |
 
 ## Migration Guides
 
 Switching from another library? These guides provide API mapping tables, code examples, and performance comparisons:
 
 - [**From string-similarity**](docs/migration/from-string-similarity.md) — Same Dice coefficient algorithm, now maintained and faster
-- [**From fuse.js**](docs/migration/from-fuse-js.md) — 17–40x faster fuzzy search with a simpler API
+- [**From fuse.js**](docs/migration/from-fuse-js.md) — Up to 7,000x faster fuzzy search with FuzzyIndex
 - [**From leven / fastest-levenshtein**](docs/migration/from-leven.md) — Multi-algorithm upgrade with batch APIs
+- [**From fuzzysort**](docs/migration/from-fuzzysort.md) — Richer matching with query syntax and 9 distance algorithms
+- [**From uFuzzy**](docs/migration/from-ufuzzy.md) — Weighted object search, batch APIs, and persistent indexes
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapid-fuzzy",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Rust-powered fuzzy search and string distance for JavaScript/TypeScript. 10-50x faster than fuse.js/leven.",
   "license": "MIT",
   "author": "derodero24",
@@ -107,6 +107,7 @@
     "@commitlint/config-conventional": "^20.4.4",
     "@emnapi/core": "^1.9.0",
     "@emnapi/runtime": "^1.9.0",
+    "@leeoniya/ufuzzy": "^1.0.19",
     "@napi-rs/cli": "^3.5.1",
     "@napi-rs/wasm-runtime": "^1.1.1",
     "@playwright/test": "^1.58.2",
@@ -131,14 +132,14 @@
     ]
   },
   "optionalDependencies": {
-    "rapid-fuzzy-darwin-x64": "0.5.0",
-    "rapid-fuzzy-darwin-arm64": "0.5.0",
-    "rapid-fuzzy-linux-x64-gnu": "0.5.0",
-    "rapid-fuzzy-linux-x64-musl": "0.5.0",
-    "rapid-fuzzy-linux-arm64-gnu": "0.5.0",
-    "rapid-fuzzy-linux-arm64-musl": "0.5.0",
-    "rapid-fuzzy-win32-x64-msvc": "0.5.0",
-    "rapid-fuzzy-win32-arm64-msvc": "0.5.0",
-    "rapid-fuzzy-wasm32-wasi": "0.5.0"
+    "rapid-fuzzy-darwin-x64": "0.6.0",
+    "rapid-fuzzy-darwin-arm64": "0.6.0",
+    "rapid-fuzzy-linux-x64-gnu": "0.6.0",
+    "rapid-fuzzy-linux-x64-musl": "0.6.0",
+    "rapid-fuzzy-linux-arm64-gnu": "0.6.0",
+    "rapid-fuzzy-linux-arm64-musl": "0.6.0",
+    "rapid-fuzzy-win32-x64-msvc": "0.6.0",
+    "rapid-fuzzy-win32-arm64-msvc": "0.6.0",
+    "rapid-fuzzy-wasm32-wasi": "0.6.0"
   }
 }