rapid-fuzzy 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,7 @@
 # rapid-fuzzy
 
 [![CI](https://github.com/derodero24/rapid-fuzzy/actions/workflows/ci.yml/badge.svg)](https://github.com/derodero24/rapid-fuzzy/actions/workflows/ci.yml)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/derodero24/rapid-fuzzy)
 [![codecov](https://codecov.io/gh/derodero24/rapid-fuzzy/branch/develop/graph/badge.svg)](https://codecov.io/gh/derodero24/rapid-fuzzy)
 [![npm version](https://img.shields.io/npm/v/rapid-fuzzy)](https://www.npmjs.com/package/rapid-fuzzy)
 [![npm downloads](https://img.shields.io/npm/dm/rapid-fuzzy)](https://www.npmjs.com/package/rapid-fuzzy)
@@ -56,13 +57,110 @@ const results = search('typscript', [
   'Python',
   'TypeSpec',
 ]);
-// → [{ item: 'TypeScript', score: 0.85, index: 0 }, ...]
+// → [{ item: 'TypeScript', score: 0.85, index: 0, positions: [] }, ...]
+
+// With options: filter by minimum score and limit results
+search('app', items, { maxResults: 5, minScore: 0.3 });
+
+// Backward compatible: pass a number for maxResults
+search('app', items, 5);
+
+// Get matched character positions for highlighting
+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'
+
+// With minimum score threshold (returns null if no match is good enough)
+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'] });
+```
+
+### 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):
+
+```typescript
+import {
+  tokenSortRatio,
+  tokenSetRatio,
+  partialRatio,
+  weightedRatio,
+} from 'rapid-fuzzy';
+
+// Token Sort: order-independent comparison
+tokenSortRatio('New York Mets', 'Mets New York'); // 1.0
+
+// Token Set: handles extra/missing tokens
+tokenSetRatio('Great Gatsby', 'The Great Gatsby by Fitzgerald'); // ~0.85
+
+// Partial: best substring match
+partialRatio('hello', 'hello world'); // 1.0
+
+// Weighted: best score across all methods
+weightedRatio('John Smith', 'Smith, John'); // 1.0
 ```
 
+All token-based functions include `Batch` and `Many` variants (e.g., `tokenSortRatioBatch`, `tokenSortRatioMany`).
+
 ### Batch Operations
 
 All distance functions have `Batch` and `Many` variants that amortize FFI overhead:
@@ -93,11 +191,11 @@ Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.
 
 | Function | rapid-fuzzy | fastest-levenshtein | leven | string-similarity |
 |---|---:|---:|---:|---:|
-| Levenshtein | 67,346 ops/s | **243,026 ops/s** | 51,789 ops/s | — |
-| Normalized Levenshtein | **64,592 ops/s** | — | — | — |
-| Sorensen-Dice | **61,050 ops/s** | — | — | 40,241 ops/s |
-| Jaro-Winkler | **198,140 ops/s** | — | — | — |
-| Damerau-Levenshtein | **58,888 ops/s** | — | — | — |
+| 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** | — | — | — |
 
 > **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.
 
@@ -105,23 +203,23 @@ Measured on Apple M-series with Node.js v22 using [Vitest bench](https://vitest.
 
 | Dataset size | rapid-fuzzy | fuse.js | fuzzysort |
 |---|---:|---:|---:|
-| 20 items | 171,967 ops/s | 121,978 ops/s | **2,537,323 ops/s** |
-| 1,000 items | 4,941 ops/s | 376 ops/s | **55,388 ops/s** |
-| 10,000 items | 588 ops/s | 14 ops/s | **15,005 ops/s** |
+| 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** |
 
 ### Closest Match (Levenshtein-based)
 
 | Dataset size | rapid-fuzzy | fastest-levenshtein |
 |---|---:|---:|
-| 1,000 items | **5,912 ops/s** | 3,974 ops/s |
-| 10,000 items | **387 ops/s** | 126 ops/s |
+| Medium (1K items) | 8,416 ops/s | **8,762 ops/s** |
+| Large (10K items) | **905 ops/s** | 662 ops/s |
 
-> rapid-fuzzy is up to **3x faster** than fastest-levenshtein for closest-match lookups on large datasets.
+> rapid-fuzzy is up to **1.4x faster** than fastest-levenshtein for closest-match lookups on large datasets.
 
 ### Why these numbers matter
 
-- **vs fuse.js**: rapid-fuzzy is **13x faster** on medium datasets and **41x faster** on large datasets for fuzzy search.
-- **vs fastest-levenshtein**: rapid-fuzzy wins on closest-match (1.5–3x faster) where batch FFI overhead is amortized.
+- **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.
 - **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:
@@ -136,28 +234,44 @@ cargo bench           # Rust internal benchmarks
 | Use case | Recommended | Why |
 |---|---|---|
 | Typo detection / spell check | `levenshtein`, `damerauLevenshtein` | Counts edits; Damerau adds transposition support |
-| Name / address matching | `jaroWinkler` | Prefix-weighted similarity for short strings |
+| 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) |
 
 **Return types:**
 
 - `levenshtein`, `damerauLevenshtein` → integer (edit count)
 - `jaro`, `jaroWinkler`, `sorensenDice`, `normalizedLevenshtein` → float between 0.0 (no match) and 1.0 (identical)
-- `search` → array of `{ item, score, index }` sorted by relevance (score: 0.0–1.0)
+- `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** | Levenshtein, Jaro-Winkler, Sorensen-Dice, Damerau-Levenshtein, fuzzy search | Bitap-based fuzzy | Levenshtein only | Substring fuzzy |
+| **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 |
+| **Object search** | Yes (searchObjects with weighted keys) | Yes (keys option) | No | Yes (keys) |
+| **Score threshold** | Yes (minScore) | Yes (threshold) | No | Yes (threshold) |
+| **Match positions** | Yes (includePositions) | Yes | No | Yes |
+| **Highlight utility** | Yes (highlight, highlightRanges) | No (manual) | No | Yes (highlight) |
 | **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 |
 
+## 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 leven / fastest-levenshtein**](docs/migration/from-leven.md) — Multi-algorithm upgrade with batch APIs
+
 ## License
 
 MIT

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,57 @@
+// ESM version of highlight utilities — for browser bundlers and ESM-only environments.
+// Keep in sync with highlight.js (CJS version).
+
+/**
+ * Convert matched positions into an array of ranges for custom rendering.
+ *
+ * @param {string} item - The original string from the search result.
+ * @param {number[]} positions - Array of matched character indices.
+ * @returns {Array<{start: number, end: number, matched: boolean}>} Array of ranges.
+ */
+export 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;
+}
+
+/**
+ * Highlight matched characters in a search result string.
+ *
+ * @param {string} item - The original string from the search result.
+ * @param {number[]} positions - Array of matched character indices.
+ * @param {string | ((substring: string) => string)} openOrCallback - Opening tag or callback.
+ * @param {string} [close] - Closing tag (required when openOrCallback is a string).
+ * @returns {string} The highlighted string.
+ */
+export 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('');
+}

package/index.d.mts

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

package/index.d.ts

@@ -1,11 +1,53 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+/**
+ * A persistent fuzzy search index backed by Rust-side data.
+ *
+ * Holds items in memory on the Rust side, avoiding repeated FFI overhead
+ * for applications that search the same dataset multiple times.
+ * Memory is freed when the JavaScript garbage collector collects the instance
+ * or when `destroy()` is called explicitly.
+ */
+export declare class FuzzyIndex {
+  /** Create a new FuzzyIndex from an array of strings. */
+  constructor(items: Array<string>)
+  /** Return the number of items in the index. */
+  get size(): number
+  /**
+   * Search the index for items matching the query.
+   *
+   * Returns matches sorted by score (best match first).
+   * Scores are normalized to a 0.0-1.0 range where 1.0 is a perfect match.
+   */
+  search(query: string, options?: number | SearchOptions | undefined | null): Array<SearchResult>
+  /**
+   * Find the closest matching string in the index.
+   *
+   * Returns the best match, or null if no match is found.
+   * If minScore is provided, returns null when the best match scores below the threshold.
+   */
+  closest(query: string, minScore?: number | undefined | null): string | null
+  /** Add a single item to the index. */
+  add(item: string): void
+  /** Add multiple items to the index at once. */
+  addMany(items: Array<string>): void
+  /**
+   * Remove the item at the given index.
+   *
+   * Returns false if the index is 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.
  *
  * Returns the best match, or null if no match is found.
+ * If minScore is provided, returns null when the best match scores below the threshold.
  */
-export declare function closest(query: string, items: Array<string>): string | null
+export declare function closest(query: string, items: Array<string>, minScore?: number | undefined | null): string | null
 
 /**
  * Compute the Damerau-Levenshtein distance between two strings.
@@ -72,6 +114,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.
  *
@@ -117,6 +172,30 @@ export declare function normalizedLevenshteinBatch(pairs: Array<Array<string>>):
  */
 export declare function normalizedLevenshteinMany(reference: string, candidates: Array<string>): Array<number>
 
+/**
+ * Compute the partial ratio between two strings.
+ *
+ * Finds the best matching substring of the shorter string within the longer string
+ * using a sliding window approach. Returns the highest normalized Levenshtein
+ * similarity across all windows. Useful for matching when one string is a
+ * substring or abbreviation of the other. Returns a value between 0.0 and 1.0.
+ */
+export declare function partialRatio(a: string, b: string): number
+
+/**
+ * Compute the partial ratio for multiple pairs of strings in a single call.
+ *
+ * Returns an array of similarity scores in the same order as the input pairs.
+ */
+export declare function partialRatioBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the partial ratio from one reference string to many candidates.
+ *
+ * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ */
+export declare function partialRatioMany(reference: string, candidates: Array<string>): Array<number>
+
 /**
  * Perform fuzzy search over a list of strings.
  *
@@ -124,8 +203,37 @@ export declare function normalizedLevenshteinMany(reference: string, candidates:
  * Scores are normalized to a 0.0-1.0 range where 1.0 is a perfect match.
  * Uses the nucleo algorithm (same as Helix editor), which is
  * significantly faster than fzf/skim for large datasets.
+ *
+ * The third argument accepts either a number (maxResults for backward
+ * compatibility) or a SearchOptions object with maxResults and minScore.
  */
-export declare function search(query: string, items: Array<string>, maxResults?: number | undefined | null): Array<SearchResult>
+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. */
+  maxResults?: number
+  /** Minimum normalized score (0.0-1.0) to include in results. */
+  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. */
 export interface SearchResult {
@@ -135,6 +243,11 @@ export interface SearchResult {
   score: number
   /** The index of the item in the original input array. */
   index: number
+  /**
+   * Indices of matched characters in the item string.
+   * Empty unless `includePositions` is set to true in SearchOptions.
+   */
+  positions: Array<number>
 }
 
 /**
@@ -158,3 +271,78 @@ export declare function sorensenDiceBatch(pairs: Array<Array<string>>): Array<nu
  * Returns an array of similarity scores, one per candidate, in the same order as the input.
  */
 export declare function sorensenDiceMany(reference: string, candidates: Array<string>): Array<number>
+
+/**
+ * Compute the token set ratio between two strings.
+ *
+ * Compares the intersection and differences of token sets from both strings.
+ * Returns the maximum similarity among comparisons of the intersection with
+ * each remainder. Highly effective for strings with shared tokens but
+ * different lengths. Returns a value between 0.0 and 1.0.
+ */
+export declare function tokenSetRatio(a: string, b: string): number
+
+/**
+ * Compute the token set ratio for multiple pairs of strings in a single call.
+ *
+ * Returns an array of similarity scores in the same order as the input pairs.
+ */
+export declare function tokenSetRatioBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the token set ratio from one reference string to many candidates.
+ *
+ * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ */
+export declare function tokenSetRatioMany(reference: string, candidates: Array<string>): Array<number>
+
+/**
+ * Compute the token sort ratio between two strings.
+ *
+ * Splits both strings into tokens, sorts them alphabetically, then computes
+ * the normalized Levenshtein similarity. This makes the comparison
+ * order-independent, ideal for matching names or addresses where word order varies.
+ * Returns a value between 0.0 (completely different) and 1.0 (identical after sorting).
+ */
+export declare function tokenSortRatio(a: string, b: string): number
+
+/**
+ * Compute the token sort ratio for multiple pairs of strings in a single call.
+ *
+ * Returns an array of similarity scores in the same order as the input pairs.
+ */
+export declare function tokenSortRatioBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the token sort ratio from one reference string to many candidates.
+ *
+ * Returns an array of similarity scores, one per candidate, in the same order as the input.
+ */
+export declare function tokenSortRatioMany(reference: string, candidates: Array<string>): Array<number>
+
+/**
+ * Compute the weighted ratio between two strings.
+ *
+ * Returns the maximum score across normalized Levenshtein, token sort ratio,
+ * token set ratio, and partial ratio. This provides a single "best effort"
+ * similarity score that automatically selects the most appropriate algorithm.
+ * Returns a value between 0.0 and 1.0.
+ */
+export declare function weightedRatio(a: string, b: string): number
+
+/**
+ * Compute the weighted ratio for multiple pairs of strings in a single call.
+ *
+ * Returns an array of similarity scores in the same order as the input pairs.
+ */
+export declare function weightedRatioBatch(pairs: Array<Array<string>>): Array<number>
+
+/**
+ * Compute the weighted ratio from one reference string to many candidates.
+ *
+ * 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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      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.`)
       }
       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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          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.`)
           }
           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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         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.1.1' && 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.1.1 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        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.`)
         }
         return binding
       } catch (e) {
@@ -576,6 +576,7 @@ if (!nativeBinding) {
 }
 
 module.exports = nativeBinding
+module.exports.FuzzyIndex = nativeBinding.FuzzyIndex
 module.exports.closest = nativeBinding.closest
 module.exports.damerauLevenshtein = nativeBinding.damerauLevenshtein
 module.exports.damerauLevenshteinBatch = nativeBinding.damerauLevenshteinBatch
@@ -592,7 +593,25 @@ module.exports.levenshteinMany = nativeBinding.levenshteinMany
 module.exports.normalizedLevenshtein = nativeBinding.normalizedLevenshtein
 module.exports.normalizedLevenshteinBatch = nativeBinding.normalizedLevenshteinBatch
 module.exports.normalizedLevenshteinMany = nativeBinding.normalizedLevenshteinMany
+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
+module.exports.tokenSetRatio = nativeBinding.tokenSetRatio
+module.exports.tokenSetRatioBatch = nativeBinding.tokenSetRatioBatch
+module.exports.tokenSetRatioMany = nativeBinding.tokenSetRatioMany
+module.exports.tokenSortRatio = nativeBinding.tokenSortRatio
+module.exports.tokenSortRatioBatch = nativeBinding.tokenSortRatioBatch
+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

@@ -4,7 +4,9 @@ const require = createRequire(import.meta.url);
 const binding = require('./index.js');
 
 export const {
+  FuzzyIndex,
   closest,
+  searchKeys,
   damerauLevenshtein,
   damerauLevenshteinBatch,
   damerauLevenshteinMany,
@@ -20,8 +22,24 @@ export const {
   normalizedLevenshtein,
   normalizedLevenshteinBatch,
   normalizedLevenshteinMany,
+  partialRatio,
+  partialRatioBatch,
+  partialRatioMany,
   search,
   sorensenDice,
   sorensenDiceBatch,
   sorensenDiceMany,
-} = binding;
+  tokenSetRatio,
+  tokenSetRatioBatch,
+  tokenSetRatioMany,
+  tokenSortRatio,
+  tokenSortRatioBatch,
+  tokenSortRatioMany,
+  weightedRatio,
+  weightedRatioBatch,
+  weightedRatioMany,
+  highlight,
+  highlightRanges,
+} = { ...binding, ...require('./highlight.js') };
+
+export const { searchObjects } = require('./objects.js');

package/objects.d.ts

@@ -0,0 +1,42 @@
+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>;
+}
+
+/**
+ * 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>>;

package/objects.js

@@ -0,0 +1,58 @@
+'use strict';
+
+const { searchKeys } = 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[] }>}
+ */
+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,
+  }));
+}
+
+module.exports = { searchObjects };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapid-fuzzy",
-  "version": "0.2.0",
+  "version": "0.4.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,8 +86,12 @@
     "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",
     "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",
@@ -91,12 +101,14 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
     "@changesets/cli": "^2.30.0",
+    "@codspeed/vitest-plugin": "^5.2.0",
     "@commitlint/cli": "^20.4.4",
     "@commitlint/config-conventional": "^20.4.4",
     "@emnapi/core": "^1.9.0",
     "@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",
@@ -109,6 +121,7 @@
     "publint": "^0.3.18",
     "string-similarity": "^4.0.4",
     "typescript": "^5.9.3",
+    "vite": "^8.0.0",
     "vitest": "^4.1.0"
   },
   "pnpm": {
@@ -117,14 +130,14 @@
     ]
   },
   "optionalDependencies": {
-    "rapid-fuzzy-darwin-x64": "0.2.0",
-    "rapid-fuzzy-darwin-arm64": "0.2.0",
-    "rapid-fuzzy-linux-x64-gnu": "0.2.0",
-    "rapid-fuzzy-linux-x64-musl": "0.2.0",
-    "rapid-fuzzy-linux-arm64-gnu": "0.2.0",
-    "rapid-fuzzy-linux-arm64-musl": "0.2.0",
-    "rapid-fuzzy-win32-x64-msvc": "0.2.0",
-    "rapid-fuzzy-win32-arm64-msvc": "0.2.0",
-    "rapid-fuzzy-wasm32-wasi": "0.2.0"
+    "rapid-fuzzy-darwin-x64": "0.4.0",
+    "rapid-fuzzy-darwin-arm64": "0.4.0",
+    "rapid-fuzzy-linux-x64-gnu": "0.4.0",
+    "rapid-fuzzy-linux-x64-musl": "0.4.0",
+    "rapid-fuzzy-linux-arm64-gnu": "0.4.0",
+    "rapid-fuzzy-linux-arm64-musl": "0.4.0",
+    "rapid-fuzzy-win32-x64-msvc": "0.4.0",
+    "rapid-fuzzy-win32-arm64-msvc": "0.4.0",
+    "rapid-fuzzy-wasm32-wasi": "0.4.0"
   }
 }