rapid-fuzzy

Blazing-fast fuzzy search for JavaScript — powered by Rust, works everywhere.

Features

• Fast: Up to 7,000x faster than fuse.js with FuzzyIndex (Rust + napi-rs)
• Universal: Works in Node.js (native), browsers (WASM), Deno, and Bun
• Zero JS dependencies: Pure Rust core with napi-rs bindings
• Type-safe: Full TypeScript support with auto-generated type definitions
• Drop-in: API compatible with popular fuzzy search libraries

Playground

Try rapid-fuzzy in the browser — no installation required: Open Playground

Quick Start

import { search } from 'rapid-fuzzy';

const results = search('typscript', ['TypeScript', 'JavaScript', 'Python']);
// → [{ item: 'TypeScript', score: 0.85, index: 0 }, ...]

For repeated searches, use FuzzyIndex for up to 165x faster lookups:

import { FuzzyIndex } from 'rapid-fuzzy';

const index = new FuzzyIndex(['TypeScript', 'JavaScript', 'Python', ...]);
index.search('typscript'); // sub-millisecond with incremental cache

Installation

npm install rapid-fuzzy
# or
pnpm add rapid-fuzzy

Runtime-specific notes

• Node.js (>=20): Uses native bindings via napi-rs for best performance.
• Browser / Deno / Bun: Falls back to a WASM build automatically. The WASM binary is 607 KB raw (200 KB gzipped).

Browser WASM requirement: The WASM build uses SharedArrayBuffer for threading, which requires the following HTTP headers on your page:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Without these headers, you will see SharedArrayBuffer is not defined. See MDN: SharedArrayBuffer for details.

API

Fuzzy Search

import { search, closest } from 'rapid-fuzzy';

// Find matches sorted by relevance (scores normalized to 0.0-1.0)
const results = search('typscript', [
  'TypeScript',
  'JavaScript',
  'Python',
  'TypeSpec',
]);
// → [{ 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 });

// 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

String Distance

import { levenshtein, jaroWinkler, sorensenDice } from 'rapid-fuzzy';

levenshtein('kitten', 'sitting');     // 3
jaroWinkler('MARTHA', 'MARHTA');      // 0.961
sorensenDice('night', 'nacht');       // 0.25

Query Syntax

Queries support extended syntax powered by the nucleo pattern parser:

Diacritics are handled automatically — cafe matches café, uber matches über, and naive matches naïve with no configuration needed.

Note: These patterns apply to all search functions: search(), closest(), FuzzyIndex.search(), FuzzyObjectIndex.search(), and searchObjects(). They do not apply to distance functions (levenshtein, jaro, etc.).

Object Search

Search across object properties with weighted keys — a drop-in replacement for fuse.js's keys option:

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:

import { FuzzyIndex, FuzzyObjectIndex } from 'rapid-fuzzy';

// String search index — up to 165x 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:

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 }, ...]

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

import { levenshteinBatch, levenshteinMany } from 'rapid-fuzzy';

// Compute distances for multiple pairs at once
levenshteinBatch([
  ['kitten', 'sitting'],
  ['hello', 'help'],
  ['foo', 'bar'],
]);
// → [3, 2, 3]

// Compare one string against many candidates
levenshteinMany('kitten', ['sitting', 'kittens', 'kitchen']);
// → [3, 1, 2]

Choosing an Algorithm

Return types:

• levenshtein, damerauLevenshtein → integer (edit count)
• jaro, jaroWinkler, sorensenDice, normalizedLevenshtein → float between 0.0 (no match) and 1.0 (identical)
• tokenSortRatio, tokenSetRatio, partialRatio, weightedRatio → float between 0.0 and 1.0
• search → array of { item, score, index, positions } sorted by relevance (score: 0.0–1.0)

Benchmarks

Measured on Apple M-series with Node.js v22 using Vitest bench. Each benchmark processes 6 realistic string pairs of varying length and similarity.

Distance Functions

Note: For single-pair Levenshtein, fastest-levenshtein is ~1.4x faster due to its optimized pure-JS implementation that avoids FFI overhead. rapid-fuzzy is 2.5x faster than leven, and provides broader algorithm coverage plus batch / search scenarios.

Search Performance

Both rapid-fuzzy columns below show the same library: standalone search() vs FuzzyIndex (indexed mode for repeated searches).

Closest Match (Levenshtein-based)

In indexed mode (FuzzyIndex), rapid-fuzzy is up to 224x faster than fastest-levenshtein for closest-match lookups.

Key takeaways

• vs fuse.js: FuzzyIndex is 218x–7,572x faster depending on dataset size. Even standalone search() is 19–46x faster.
• Indexed mode: FuzzyIndex keeps data on the Rust side with incremental caching — 165x faster than standalone search() on large datasets, delivering sub-millisecond autocomplete.
• vs fuzzysort / uFuzzy: FuzzyIndex outperforms both on 1K+ datasets (up to 4.9x vs fuzzysort, 21x vs uFuzzy).

Why rapid-fuzzy?

Migration Guides

Switching from another library? These guides provide API mapping tables, code examples, and performance comparisons:

• From string-similarity — Same Dice coefficient algorithm, now maintained and faster
• From fuse.js — Up to 7,000x faster fuzzy search with FuzzyIndex
• From leven / fastest-levenshtein — Multi-algorithm upgrade with batch APIs
• From fuzzysort — Richer matching with query syntax and 9 distance algorithms
• From uFuzzy — Weighted object search, batch APIs, and persistent indexes

License

MIT