rapid-fuzzy 0.3.0 → 0.5.0

package/README.md

@@ -69,6 +69,9 @@ search('app', items, 5);
 const [match] = search('hlo', ['hello world'], { includePositions: true });
 // → { item: 'hello world', score: 0.75, index: 0, positions: [0, 2, 4] }
 
+// Case-sensitive matching (default: smart case)
+search('Type', items, { isCaseSensitive: true });
+
 // Find the single best match
 closest('tsc', ['TypeScript', 'JavaScript', 'Python']);
 // → 'TypeScript'
@@ -78,6 +81,91 @@ closest('xyz', items, 0.5);
 // → null
 ```
 
+### Object Search
+
+Search across object properties with weighted keys — a drop-in replacement for fuse.js's `keys` option:
+
+```typescript
+import { searchObjects } from 'rapid-fuzzy';
+
+const users = [
+  { name: 'John Smith', email: 'john@example.com' },
+  { name: 'Jane Doe', email: 'jane@example.com' },
+  { name: 'Bob Johnson', email: 'bob@test.com' },
+];
+
+// Search across multiple keys
+const results = searchObjects('john', users, {
+  keys: ['name', 'email'],
+});
+// → [{ item: { name: 'John Smith', ... }, score: 0.95, keyScores: [0.98, 0.85], index: 0 }]
+
+// Weighted keys — prioritize name matches over email
+searchObjects('john', users, {
+  keys: [
+    { name: 'name', weight: 2.0 },
+    { name: 'email', weight: 1.0 },
+  ],
+});
+
+// Nested key paths
+searchObjects('new york', items, { keys: ['address.city'] });
+```
+
+### Persistent Index
+
+For applications that search the same dataset repeatedly (autocomplete, file finders, etc.), use `FuzzyIndex` or `FuzzyObjectIndex` to keep data on the Rust side and eliminate per-search FFI overhead:
+
+```typescript
+import { FuzzyIndex, FuzzyObjectIndex } from 'rapid-fuzzy';
+
+// String search index — up to 5x faster than standalone search()
+const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python', ...]);
+
+index.search('typscript', { maxResults: 5 });
+index.closest('tsc');
+
+// Mutate the index without rebuilding
+index.add('Rust');
+index.remove(2); // swap-remove by index
+
+// Object search index — keeps objects on the JS side, keys on the Rust side
+const userIndex = new FuzzyObjectIndex(users, {
+  keys: [
+    { name: 'name', weight: 2.0 },
+    { name: 'email', weight: 1.0 },
+  ],
+});
+
+userIndex.search('john', { maxResults: 10 });
+
+// Free Rust-side memory when done
+index.destroy();
+userIndex.destroy();
+```
+
+### Match Highlighting
+
+Convert matched positions into highlighted markup for UI rendering:
+
+```typescript
+import { search, highlight, highlightRanges } from 'rapid-fuzzy';
+
+const results = search('fzy', ['fuzzy'], { includePositions: true });
+const { item, positions } = results[0];
+
+// String markers
+highlight(item, positions, '<b>', '</b>');
+// → '<b>f</b>u<b>zy</b>'
+
+// Callback (React, JSX, custom DOM)
+highlight(item, positions, (matched) => `<mark>${matched}</mark>`);
+
+// Raw ranges for custom rendering
+highlightRanges(item, positions);
+// → [{ start: 0, end: 1, matched: true }, { start: 1, end: 2, matched: false }, ...]
+```
+
 ### Token-Based Matching
 
 Order-independent and partial string matching, inspired by Python's [RapidFuzz](https://github.com/rapidfuzz/RapidFuzz):
@@ -133,37 +221,52 @@ Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.
 
 ### Distance Functions
 
+<img src=".github/assets/bench-distance.svg" alt="Distance function performance chart" width="680" />
+
+<details>
+<summary>Raw numbers</summary>
+
 | Function | rapid-fuzzy | fastest-levenshtein | leven | string-similarity |
 |---|---:|---:|---:|---:|
-| Levenshtein | 193,593 ops/s | **774,820 ops/s** | 204,047 ops/s | — |
-| Normalized Levenshtein | **136,854 ops/s** | — | — | — |
-| Sorensen-Dice | **144,698 ops/s** | — | — | 84,108 ops/s |
-| Jaro-Winkler | **291,673 ops/s** | — | — | — |
-| Damerau-Levenshtein | **72,238 ops/s** | — | — | — |
+| 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** | — | — | — |
+
+</details>
 
-> **Note**: For single-pair Levenshtein distance, fastest-levenshtein is faster due to its highly optimized pure-JS implementation that avoids FFI overhead. rapid-fuzzy provides broader algorithm coverage and excels in 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.4x faster** than leven, and provides broader algorithm coverage plus batch / search scenarios.
 
 ### Search Performance
 
-| Dataset size | rapid-fuzzy | fuse.js | fuzzysort |
-|---|---:|---:|---:|
-| Small (20 items) | 179,222 ops/s | 109,059 ops/s | **2,501,773 ops/s** |
-| Medium (1K items) | 6,614 ops/s | 381 ops/s | **63,032 ops/s** |
-| Large (10K items) | 794 ops/s | 20 ops/s | **28,616 ops/s** |
+<img src=".github/assets/bench-search.svg" alt="Search performance chart — rapid-fuzzy vs fuse.js vs fuzzysort" width="680" />
+
+<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** |
+
+</details>
 
 ### Closest Match (Levenshtein-based)
 
-| Dataset size | rapid-fuzzy | fastest-levenshtein |
-|---|---:|---:|
-| Medium (1K items) | 8,416 ops/s | **8,762 ops/s** |
-| Large (10K items) | **905 ops/s** | 662 ops/s |
+| Dataset size | rapid-fuzzy | FuzzyIndex | 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 |
 
-> rapid-fuzzy is up to **1.4x faster** than fastest-levenshtein for closest-match lookups on large datasets.
+> With `FuzzyIndex`, rapid-fuzzy is up to **6.8x 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.
-- **vs fastest-levenshtein**: rapid-fuzzy wins on closest-match at scale where batch FFI overhead is amortized.
+- **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.
 
 Run benchmarks yourself:
@@ -185,6 +288,7 @@ cargo bench           # Rust internal benchmarks
 | 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:**
 
@@ -196,22 +300,25 @@ cargo bench           # Rust internal benchmarks
 ## Why rapid-fuzzy?
 
 | | rapid-fuzzy | fuse.js | fastest-levenshtein | fuzzysort |
-|---|---|---|---|---|
-| **Algorithms** | Levenshtein, Jaro-Winkler, Sorensen-Dice, Damerau-Levenshtein, token sort/set, partial ratio, fuzzy search | Bitap-based fuzzy | Levenshtein only | Substring fuzzy |
-| **Runtime** | Rust (native + WASM) | Pure JS | Pure JS | Pure JS |
-| **Score threshold** | Yes (minScore) | Yes (threshold) | No | Yes (threshold) |
-| **Match positions** | Yes (includePositions) | Yes | No | Yes |
-| **Batch API** | Yes | No | No | No |
-| **Node.js native** | Yes (napi-rs) | No | No | No |
-| **Browser support** | Yes (WASM) | Yes | Yes | Yes |
-| **TypeScript** | Full (auto-generated) | Full | Yes | Yes |
+|---|:---:|:---:|:---:|:---:|
+| **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 | ✅ | ✅ |
 
 ## 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) — 13–41x faster fuzzy search with a simpler API
+- [**From fuse.js**](docs/migration/from-fuse-js.md) — 17–40x faster fuzzy search with a simpler API
 - [**From leven / fastest-levenshtein**](docs/migration/from-leven.md) — Multi-algorithm upgrade with batch APIs
 
 ## License

package/browser.js

@@ -1 +1,4 @@
 export * from 'rapid-fuzzy-wasm32-wasi'
+
+// --- JS utilities (appended by scripts/patch-binding.js) ---
+export { highlight, highlightRanges } from './highlight.mjs';

package/highlight.d.ts

@@ -0,0 +1,55 @@
+/** A range within a string, indicating whether it was matched. */
+export interface HighlightRange {
+  /** Start index (inclusive). */
+  start: number;
+  /** End index (exclusive). */
+  end: number;
+  /** Whether this range was part of the match. */
+  matched: boolean;
+}
+
+/**
+ * Highlight matched characters in a search result string.
+ *
+ * Use with `SearchResult.positions` from a search with `includePositions: true`.
+ *
+ * @example String markers
+ * ```typescript
+ * const results = search('fzy', ['fuzzy'], { includePositions: true });
+ * highlight(results[0].item, results[0].positions, '<b>', '</b>');
+ * // → '<b>f</b>u<b>zy</b>'
+ * ```
+ *
+ * @example Callback (React, custom DOM, etc.)
+ * ```typescript
+ * highlight(result.item, result.positions, (matched) => `<mark>${matched}</mark>`);
+ * ```
+ */
+export declare function highlight(
+  item: string,
+  positions: Array<number>,
+  open: string,
+  close: string,
+): string;
+export declare function highlight(
+  item: string,
+  positions: Array<number>,
+  callback: (matched: string) => string,
+): string;
+
+/**
+ * Convert matched positions into an array of ranges for custom rendering.
+ *
+ * Each range indicates a contiguous segment of the string and whether it was
+ * part of the match. Useful for building custom highlight components.
+ *
+ * @example
+ * ```typescript
+ * const ranges = highlightRanges(result.item, result.positions);
+ * // → [{ start: 0, end: 1, matched: true }, { start: 1, end: 2, matched: false }, ...]
+ * ```
+ */
+export declare function highlightRanges(
+  item: string,
+  positions: Array<number>,
+): Array<HighlightRange>;

package/highlight.js

@@ -0,0 +1,58 @@
+// Pure JS highlight utilities — works in both Node.js and browser environments.
+// This file is manually maintained (not auto-generated by napi-rs).
+
+'use strict';
+
+/**
+ * @param {string} item
+ * @param {number[]} positions
+ * @returns {Array<{start: number, end: number, matched: boolean}>}
+ */
+function highlightRanges(item, positions) {
+  if (!item) return [];
+  if (!positions || positions.length === 0) {
+    return [{ start: 0, end: item.length, matched: false }];
+  }
+
+  const set = new Set(positions);
+  const ranges = [];
+  let i = 0;
+
+  while (i < item.length) {
+    const matched = set.has(i);
+    const start = i;
+    while (i < item.length && set.has(i) === matched) i++;
+    ranges.push({ start, end: i, matched });
+  }
+
+  return ranges;
+}
+
+/**
+ * @param {string} item
+ * @param {number[]} positions
+ * @param {string | ((substring: string) => string)} openOrCallback
+ * @param {string} [close]
+ * @returns {string}
+ */
+function highlight(item, positions, openOrCallback, close) {
+  if (!positions || positions.length === 0) return item;
+
+  const ranges = highlightRanges(item, positions);
+  const useCallback = typeof openOrCallback === 'function';
+
+  const parts = [];
+  for (const range of ranges) {
+    const segment = item.slice(range.start, range.end);
+    if (range.matched) {
+      parts.push(useCallback ? openOrCallback(segment) : openOrCallback + segment + (close ?? ''));
+    } else {
+      parts.push(segment);
+    }
+  }
+
+  return parts.join('');
+}
+
+module.exports.highlight = highlight;
+module.exports.highlightRanges = highlightRanges;

package/highlight.mjs

@@ -0,0 +1,4 @@
+// ESM re-export — single source of truth is highlight.js (CJS).
+// Node.js detects named exports from CJS via static analysis.
+// Bundlers (webpack, vite, rollup) handle CJS interop natively.
+export { highlight, highlightRanges } from './highlight.js';

package/index.d.mts

@@ -1 +1,11 @@
 export * from './index.d.ts';
+export { highlight, highlightRanges } from './highlight.d.ts';
+export type { HighlightRange } from './highlight.d.ts';
+export { searchObjects, FuzzyObjectIndex } from './objects';
+export type {
+  KeyConfig,
+  ObjectSearchOptions,
+  ObjectSearchResult,
+  ObjectIndexOptions,
+  ObjectIndexSearchOptions,
+} from './objects';

package/index.d.ts

@@ -5,6 +5,8 @@
  *
  * Holds items in memory on the Rust side, avoiding repeated FFI overhead
  * for applications that search the same dataset multiple times.
+ * Pre-computes Utf32String representations for each item, eliminating
+ * per-search string conversion overhead.
  * Memory is freed when the JavaScript garbage collector collects the instance
  * or when `destroy()` is called explicitly.
  */
@@ -41,6 +43,56 @@ export declare class FuzzyIndex {
   destroy(): void
 }
 
+/**
+ * A persistent multi-key fuzzy search index backed by Rust-side data.
+ *
+ * Holds key text arrays and weights in memory on the Rust side,
+ * avoiding repeated FFI overhead for applications that search the
+ * same dataset multiple times with multiple keys.
+ * Pre-computes Utf32String representations and reuses the Matcher
+ * instance for optimal repeated-search performance.
+ *
+ * Typically wrapped by a JS-side `FuzzyObjectIndex` class that maps
+ * results back to original objects.
+ */
+export declare class KeyedFuzzyIndex {
+  /**
+   * Create a new KeyedFuzzyIndex.
+   *
+   * `key_texts[k]` is an array of strings for key `k`, one per item.
+   * All inner arrays must have the same length (the number of items).
+   */
+  constructor(keyTexts: Array<Array<string>>, weights: Array<number>)
+  /** Return the number of items in the index. */
+  get size(): number
+  /**
+   * Search the index for items matching the query.
+   *
+   * Returns results sorted by combined weighted score (best match first).
+   */
+  search(query: string, options?: SearchOptions | undefined | null): Array<KeySearchResult>
+  /**
+   * Add a single item to the index.
+   *
+   * `key_values` must have the same length as the number of keys.
+   */
+  add(keyValues: Array<string>): void
+  /**
+   * Add multiple items to the index at once.
+   *
+   * Each element of `items_key_values` is an array of key values for one item.
+   */
+  addMany(itemsKeyValues: Array<Array<string>>): void
+  /**
+   * Remove the item at the given index.
+   *
+   * Uses swap-remove for O(1) performance. Returns false if out of bounds.
+   */
+  remove(index: number): boolean
+  /** Free the internal data. After calling this, the index is empty. */
+  destroy(): void
+}
+
 /**
  * Find the closest matching string from a list.
  *
@@ -114,6 +166,19 @@ export declare function jaroWinklerBatch(pairs: Array<Array<string>>): Array<num
  */
 export declare function jaroWinklerMany(reference: string, candidates: Array<string>): Array<number>
 
+/** A single result from multi-key fuzzy search. */
+export interface KeySearchResult {
+  /** The index of the item in the original input array. */
+  index: number
+  /** The combined weighted score normalized to 0.0-1.0 range. */
+  score: number
+  /**
+   * Per-key scores in the same order as the input keys.
+   * A score of 0.0 means the item did not match on that key.
+   */
+  keyScores: Array<number>
+}
+
 /**
  * Compute the Levenshtein distance between two strings.
  *
@@ -196,6 +261,17 @@ export declare function partialRatioMany(reference: string, candidates: Array<st
  */
 export declare function search(query: string, items: Array<string>, options?: number | SearchOptions | undefined | null): Array<SearchResult>
 
+/**
+ * Perform fuzzy search across multiple text keys with weights.
+ *
+ * `key_texts[k]` is an array of strings for key `k`, one per item.
+ * All inner arrays must have the same length (the number of items).
+ * `weights` specifies the relative importance of each key.
+ *
+ * Returns results sorted by combined weighted score (best match first).
+ */
+export declare function searchKeys(query: string, keyTexts: Array<Array<string>>, weights: Array<number>, options?: SearchOptions | undefined | null): Array<KeySearchResult>
+
 /** Options for the search function. */
 export interface SearchOptions {
   /** Maximum number of results to return. */
@@ -204,6 +280,11 @@ export interface SearchOptions {
   minScore?: number
   /** If true, include matched character positions in results. */
   includePositions?: boolean
+  /**
+   * If true, matching is case-sensitive. Default is smart case
+   * (case-insensitive unless the query contains uppercase characters).
+   */
+  isCaseSensitive?: boolean
 }
 
 /** A single fuzzy search result with the matched item and its score. */
@@ -314,3 +395,6 @@ export declare function weightedRatioBatch(pairs: Array<Array<string>>): Array<n
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
  */
 export declare function weightedRatioMany(reference: string, candidates: Array<string>): Array<number>
+
+// --- JS utilities (appended by scripts/patch-binding.js) ---
+export { highlight, highlightRanges, HighlightRange } from './highlight';

package/index.js

@@ -77,8 +77,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-android-arm64')
         const bindingPackageVersion = require('rapid-fuzzy-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -93,8 +93,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-android-arm-eabi')
         const bindingPackageVersion = require('rapid-fuzzy-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -114,8 +114,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-win32-x64-gnu')
         const bindingPackageVersion = require('rapid-fuzzy-win32-x64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -130,8 +130,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-win32-x64-msvc')
         const bindingPackageVersion = require('rapid-fuzzy-win32-x64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -147,8 +147,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-win32-ia32-msvc')
         const bindingPackageVersion = require('rapid-fuzzy-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -163,8 +163,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-win32-arm64-msvc')
         const bindingPackageVersion = require('rapid-fuzzy-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -182,8 +182,8 @@ function requireNative() {
     try {
       const binding = require('rapid-fuzzy-darwin-universal')
       const bindingPackageVersion = require('rapid-fuzzy-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -198,8 +198,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-darwin-x64')
         const bindingPackageVersion = require('rapid-fuzzy-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -214,8 +214,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-darwin-arm64')
         const bindingPackageVersion = require('rapid-fuzzy-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-freebsd-x64')
         const bindingPackageVersion = require('rapid-fuzzy-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -250,8 +250,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-freebsd-arm64')
         const bindingPackageVersion = require('rapid-fuzzy-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -271,8 +271,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-x64-musl')
           const bindingPackageVersion = require('rapid-fuzzy-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -287,8 +287,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-x64-gnu')
           const bindingPackageVersion = require('rapid-fuzzy-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -305,8 +305,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-arm64-musl')
           const bindingPackageVersion = require('rapid-fuzzy-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -321,8 +321,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-arm64-gnu')
           const bindingPackageVersion = require('rapid-fuzzy-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -339,8 +339,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-arm-musleabihf')
           const bindingPackageVersion = require('rapid-fuzzy-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -355,8 +355,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-arm-gnueabihf')
           const bindingPackageVersion = require('rapid-fuzzy-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -373,8 +373,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-loong64-musl')
           const bindingPackageVersion = require('rapid-fuzzy-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -389,8 +389,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-loong64-gnu')
           const bindingPackageVersion = require('rapid-fuzzy-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -407,8 +407,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-riscv64-musl')
           const bindingPackageVersion = require('rapid-fuzzy-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -423,8 +423,8 @@ function requireNative() {
         try {
           const binding = require('rapid-fuzzy-linux-riscv64-gnu')
           const bindingPackageVersion = require('rapid-fuzzy-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -440,8 +440,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-linux-ppc64-gnu')
         const bindingPackageVersion = require('rapid-fuzzy-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -456,8 +456,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-linux-s390x-gnu')
         const bindingPackageVersion = require('rapid-fuzzy-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-openharmony-arm64')
         const bindingPackageVersion = require('rapid-fuzzy-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-openharmony-x64')
         const bindingPackageVersion = require('rapid-fuzzy-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -508,8 +508,8 @@ function requireNative() {
       try {
         const binding = require('rapid-fuzzy-openharmony-arm')
         const bindingPackageVersion = require('rapid-fuzzy-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.4.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.4.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -577,6 +577,7 @@ if (!nativeBinding) {
 
 module.exports = nativeBinding
 module.exports.FuzzyIndex = nativeBinding.FuzzyIndex
+module.exports.KeyedFuzzyIndex = nativeBinding.KeyedFuzzyIndex
 module.exports.closest = nativeBinding.closest
 module.exports.damerauLevenshtein = nativeBinding.damerauLevenshtein
 module.exports.damerauLevenshteinBatch = nativeBinding.damerauLevenshteinBatch
@@ -597,6 +598,7 @@ module.exports.partialRatio = nativeBinding.partialRatio
 module.exports.partialRatioBatch = nativeBinding.partialRatioBatch
 module.exports.partialRatioMany = nativeBinding.partialRatioMany
 module.exports.search = nativeBinding.search
+module.exports.searchKeys = nativeBinding.searchKeys
 module.exports.sorensenDice = nativeBinding.sorensenDice
 module.exports.sorensenDiceBatch = nativeBinding.sorensenDiceBatch
 module.exports.sorensenDiceMany = nativeBinding.sorensenDiceMany
@@ -609,3 +611,8 @@ module.exports.tokenSortRatioMany = nativeBinding.tokenSortRatioMany
 module.exports.weightedRatio = nativeBinding.weightedRatio
 module.exports.weightedRatioBatch = nativeBinding.weightedRatioBatch
 module.exports.weightedRatioMany = nativeBinding.weightedRatioMany
+
+// --- JS utilities (appended by scripts/patch-binding.js) ---
+const _hl = require('./highlight.js');
+module.exports.highlight = _hl.highlight;
+module.exports.highlightRanges = _hl.highlightRanges;

package/index.mjs

@@ -6,6 +6,7 @@ const binding = require('./index.js');
 export const {
   FuzzyIndex,
   closest,
+  searchKeys,
   damerauLevenshtein,
   damerauLevenshteinBatch,
   damerauLevenshteinMany,
@@ -37,4 +38,8 @@ export const {
   weightedRatio,
   weightedRatioBatch,
   weightedRatioMany,
-} = binding;
+  highlight,
+  highlightRanges,
+} = { ...binding, ...require('./highlight.js') };
+
+export const { searchObjects, FuzzyObjectIndex } = require('./objects.js');

package/objects.d.ts

@@ -0,0 +1,104 @@
+import type { SearchOptions } from './index';
+
+export interface KeyConfig {
+  name: string;
+  weight?: number;
+}
+
+export interface ObjectSearchOptions extends SearchOptions {
+  keys: Array<string | KeyConfig>;
+}
+
+export interface ObjectSearchResult<T> {
+  item: T;
+  index: number;
+  score: number;
+  keyScores: Array<number>;
+  /**
+   * Indices of matched characters in the best-matching key string.
+   * Empty unless `includePositions` is set to true in ObjectSearchOptions.
+   */
+  positions: Array<number>;
+}
+
+/**
+ * Perform fuzzy search across object arrays with weighted keys.
+ *
+ * Wraps `searchKeys()` with an ergonomic API that accepts row-oriented
+ * objects and returns matched items directly.
+ *
+ * @example
+ * ```typescript
+ * const users = [
+ *   { name: 'John Smith', email: 'john@example.com' },
+ *   { name: 'Jane Doe', email: 'jane@example.com' },
+ * ];
+ *
+ * const results = searchObjects('john', users, {
+ *   keys: [{ name: 'name', weight: 2.0 }, 'email'],
+ * });
+ * // results[0].item → { name: 'John Smith', email: 'john@example.com' }
+ * ```
+ */
+export declare function searchObjects<T>(
+  query: string,
+  items: Array<T>,
+  options: ObjectSearchOptions,
+): Array<ObjectSearchResult<T>>;
+
+export interface ObjectIndexOptions {
+  keys: Array<string | KeyConfig>;
+}
+
+export interface ObjectIndexSearchOptions {
+  maxResults?: number;
+  minScore?: number;
+  isCaseSensitive?: boolean;
+}
+
+/**
+ * A persistent fuzzy search index for object collections with weighted keys.
+ *
+ * Pre-computes key texts and stores them on the Rust side for fast repeated
+ * searches. Use this when searching the same collection multiple times.
+ *
+ * @example
+ * ```typescript
+ * const index = new FuzzyObjectIndex(users, {
+ *   keys: [{ name: 'name', weight: 2.0 }, 'email'],
+ * });
+ *
+ * const results = index.search('john');
+ * // results[0].item → { name: 'John Smith', ... }
+ *
+ * index.add({ name: 'New User', email: 'new@example.com' });
+ * index.destroy(); // free Rust-side memory
+ * ```
+ */
+export declare class FuzzyObjectIndex<T> {
+  constructor(items: Array<T>, options: ObjectIndexOptions);
+
+  /** Number of items in the index. */
+  get size(): number;
+
+  /** Search for objects matching the query. */
+  search(
+    query: string,
+    options?: ObjectIndexSearchOptions,
+  ): Array<Omit<ObjectSearchResult<T>, 'positions'>>;
+
+  /** Find the closest matching object, or null if no match. */
+  closest(query: string, minScore?: number): T | null;
+
+  /** Add a single item to the index. */
+  add(item: T): void;
+
+  /** Add multiple items at once. */
+  addMany(items: Array<T>): void;
+
+  /** Remove the item at the given index (swap-remove semantics). */
+  remove(index: number): boolean;
+
+  /** Free all internal data. */
+  destroy(): void;
+}

package/objects.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const { searchKeys, KeyedFuzzyIndex } = require('./index.js');
+
+/**
+ * Get a nested property value from an object using a dot-separated path.
+ * @param {Record<string, unknown>} obj
+ * @param {string} path
+ * @returns {string}
+ */
+function getNestedValue(obj, path) {
+  let current = obj;
+  for (const key of path.split('.')) {
+    if (current == null) return '';
+    current = current[key];
+  }
+  return current == null ? '' : String(current);
+}
+
+/**
+ * Perform fuzzy search across object arrays with weighted keys.
+ *
+ * Wraps `searchKeys()` with an ergonomic API that accepts row-oriented
+ * objects and returns matched items directly.
+ *
+ * @template T
+ * @param {string} query - The search query.
+ * @param {T[]} items - Array of objects to search.
+ * @param {object} options - Search options with keys configuration.
+ * @param {Array<string | { name: string; weight?: number }>} options.keys - Keys to search.
+ * @param {number} [options.maxResults] - Maximum results to return.
+ * @param {number} [options.minScore] - Minimum score threshold.
+ * @param {boolean} [options.isCaseSensitive] - Enable case-sensitive matching.
+ * @returns {Array<{ item: T; index: number; score: number; keyScores: number[]; positions: number[] }>}
+ */
+function searchObjects(query, items, options) {
+  const { keys, ...searchOpts } = options;
+
+  const normalizedKeys = keys.map((k) =>
+    typeof k === 'string' ? { name: k, weight: 1.0 } : { name: k.name, weight: k.weight ?? 1.0 },
+  );
+
+  const keyTexts = normalizedKeys.map((k) => items.map((item) => getNestedValue(item, k.name)));
+  const weights = normalizedKeys.map((k) => k.weight);
+
+  const nativeOpts = Object.keys(searchOpts).length > 0 ? searchOpts : undefined;
+
+  const results = searchKeys(query, keyTexts, weights, nativeOpts);
+
+  return results.map((r) => ({
+    item: items[r.index],
+    index: r.index,
+    score: r.score,
+    keyScores: r.keyScores,
+    positions: r.positions ?? [],
+  }));
+}
+
+/**
+ * A persistent fuzzy search index for object collections with weighted keys.
+ *
+ * Pre-computes key texts and stores them on the Rust side for fast repeated
+ * searches. Use this when searching the same collection multiple times.
+ *
+ * @template T
+ */
+class FuzzyObjectIndex {
+  /** @type {T[]} */
+  #items;
+  /** @type {KeyedFuzzyIndex} */
+  #index;
+  /** @type {Array<{ name: string; weight: number }>} */
+  #keys;
+
+  /**
+   * @param {T[]} items - Array of objects to index.
+   * @param {object} options - Index configuration.
+   * @param {Array<string | { name: string; weight?: number }>} options.keys - Keys to search.
+   */
+  constructor(items, options) {
+    this.#keys = options.keys.map((k) =>
+      typeof k === 'string' ? { name: k, weight: 1.0 } : { name: k.name, weight: k.weight ?? 1.0 },
+    );
+    this.#items = [...items];
+
+    const keyTexts = this.#keys.map((k) => items.map((item) => getNestedValue(item, k.name)));
+    const weights = this.#keys.map((k) => k.weight);
+    this.#index = new KeyedFuzzyIndex(keyTexts, weights);
+  }
+
+  /** Return the number of items in the index. */
+  get size() {
+    return this.#index.size;
+  }
+
+  /**
+   * Search the index for objects matching the query.
+   * @param {string} query
+   * @param {object} [options]
+   * @param {number} [options.maxResults]
+   * @param {number} [options.minScore]
+   * @param {boolean} [options.isCaseSensitive]
+   * @returns {Array<{ item: T; index: number; score: number; keyScores: number[] }>}
+   */
+  search(query, options) {
+    const results = this.#index.search(query, options);
+    return results.map((r) => ({
+      item: this.#items[r.index],
+      index: r.index,
+      score: r.score,
+      keyScores: r.keyScores,
+    }));
+  }
+
+  /**
+   * Find the closest matching object.
+   * @param {string} query
+   * @param {number} [minScore]
+   * @returns {T | null}
+   */
+  closest(query, minScore) {
+    const results = this.#index.search(query, { maxResults: 1, minScore });
+    return results.length > 0 ? this.#items[results[0].index] : null;
+  }
+
+  /**
+   * Add a single item to the index.
+   * @param {T} item
+   */
+  add(item) {
+    this.#items.push(item);
+    this.#index.add(this.#keys.map((k) => getNestedValue(item, k.name)));
+  }
+
+  /**
+   * Add multiple items to the index at once.
+   * @param {T[]} items
+   */
+  addMany(items) {
+    for (const item of items) {
+      this.#items.push(item);
+    }
+    this.#index.addMany(items.map((item) => this.#keys.map((k) => getNestedValue(item, k.name))));
+  }
+
+  /**
+   * Remove the item at the given index.
+   * Uses swap-remove semantics for O(1) performance.
+   * @param {number} index
+   * @returns {boolean}
+   */
+  remove(index) {
+    if (index < 0 || index >= this.#items.length) return false;
+    // Swap-remove to match Rust-side behavior
+    const lastIdx = this.#items.length - 1;
+    if (index !== lastIdx) {
+      this.#items[index] = this.#items[lastIdx];
+    }
+    this.#items.pop();
+    return this.#index.remove(index);
+  }
+
+  /** Free all internal data. */
+  destroy() {
+    this.#items = [];
+    this.#index.destroy();
+  }
+}
+
+module.exports = { searchObjects, FuzzyObjectIndex };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapid-fuzzy",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Rust-powered fuzzy search and string distance for JavaScript/TypeScript. 10-50x faster than fuse.js/leven.",
   "license": "MIT",
   "author": "derodero24",
@@ -46,7 +46,12 @@
     "index.mjs",
     "index.d.ts",
     "index.d.mts",
-    "browser.js"
+    "objects.js",
+    "objects.d.ts",
+    "browser.js",
+    "highlight.js",
+    "highlight.mjs",
+    "highlight.d.ts"
   ],
   "napi": {
     "binaryName": "rapid-fuzzy",
@@ -68,6 +73,7 @@
   "packageManager": "pnpm@10.32.1",
   "scripts": {
     "build": "napi build --manifest-path crates/core/Cargo.toml --platform --release --js index.js --dts index.d.ts --output-dir .",
+    "postbuild": "node scripts/patch-binding.js",
     "build:debug": "napi build --manifest-path crates/core/Cargo.toml --platform --js index.js --dts index.d.ts --output-dir .",
     "build:wasm": "napi build --manifest-path crates/core/Cargo.toml --platform --release --js index.js --dts index.d.ts --output-dir . --target wasm32-wasip1-threads",
     "artifacts": "napi artifacts",
@@ -80,9 +86,13 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:wasm": "vitest run __test__/wasm.spec.ts",
+    "test:browser": "playwright test",
+    "test:bun": "bun test e2e/wasm-bun.test.ts",
+    "test:deno": "deno test --allow-read --allow-env --allow-net --node-modules-dir=auto e2e/wasm-deno.test.ts",
     "test:watch": "vitest watch",
     "bench": "vitest bench",
     "bench:readme": "npx tsx scripts/update-bench-readme.ts",
+    "bench:charts": "npx tsx scripts/generate-bench-charts.ts",
     "publint": "publint",
     "bench:rust": "cargo bench -p rapid-fuzzy-bench",
     "verify": "pnpm run check && cargo clippy -- -W clippy::all && cargo test && pnpm run build && pnpm run typecheck && pnpm test",
@@ -99,6 +109,7 @@
     "@emnapi/runtime": "^1.9.0",
     "@napi-rs/cli": "^3.5.1",
     "@napi-rs/wasm-runtime": "^1.1.1",
+    "@playwright/test": "^1.58.2",
     "@tybys/wasm-util": "^0.10.1",
     "@types/node": "^24.0.0",
     "@types/string-similarity": "^4.0.2",
@@ -111,6 +122,7 @@
     "publint": "^0.3.18",
     "string-similarity": "^4.0.4",
     "typescript": "^5.9.3",
+    "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
   "pnpm": {
@@ -119,14 +131,14 @@
     ]
   },
   "optionalDependencies": {
-    "rapid-fuzzy-darwin-x64": "0.3.0",
-    "rapid-fuzzy-darwin-arm64": "0.3.0",
-    "rapid-fuzzy-linux-x64-gnu": "0.3.0",
-    "rapid-fuzzy-linux-x64-musl": "0.3.0",
-    "rapid-fuzzy-linux-arm64-gnu": "0.3.0",
-    "rapid-fuzzy-linux-arm64-musl": "0.3.0",
-    "rapid-fuzzy-win32-x64-msvc": "0.3.0",
-    "rapid-fuzzy-win32-arm64-msvc": "0.3.0",
-    "rapid-fuzzy-wasm32-wasi": "0.3.0"
+    "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"
   }
 }