Registry / data / fast-fuzzy

fast-fuzzy

JSON →
library1.12.0jsnpmunverified

fast-fuzzy is a compact and high-performance JavaScript utility for fuzzy string matching, currently at version 1.12.0. It implements a modified Levenshtein distance algorithm, specifically Damerau-Levenshtein distance, which is more forgiving of transpositions. The library preprocesses inputs through UTF-8 normalization, optional lowercasing, symbol stripping, and whitespace normalization to ensure robust matching. It scores matches between 0 and 1, returning results sorted by score, then by match earliness, and finally by length proximity to the search term. For efficiency, especially when searching the same set of candidates repeatedly, it internally uses a trie data structure to cache work and prune non-matching subtrees, significantly outperforming brute-force approaches. While it offers a simple `search` function for one-off queries, the `Searcher` class is recommended for persistent collections due to its trie caching. The project appears to have a steady, though not strictly scheduled, release cadence, with ongoing maintenance.

npm install fast-fuzzy
INSTALL
IMPORT
SIG · FAST-FUZZY
F
fast-fuzzy
datajavascriptv1.12.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

search
✓ import { search } from 'fast-fuzzy'
✗ const search = require('fast-fuzzy').search
Use named import for `search` function; prefer `Searcher` for repeated searches.
Searcher
✓ import { Searcher } from 'fast-fuzzy'
✗ const { Searcher } = require('fast-fuzzy')
Instantiate `Searcher` for efficient searches against static candidate sets.
fuzzy
✓ import { fuzzy } from 'fast-fuzzy'
✗ import fuzzy from 'fast-fuzzy'
`fuzzy` is a named export for the core ranking algorithm, not the default export.

Demonstrates initializing a `Searcher` with complex objects and a `keySelector`, performing a fuzzy search, and dynamically adding new candidates, with results filtered by a threshold.

import { Searcher } from 'fast-fuzzy'; interface Product { id: string; name: string; description: string; tags: string[]; } const products: Product[] = [ { id: '1', name: 'Apple MacBook Pro', description: 'High-performance laptop', tags: ['laptop', 'apple'] }, { id: '2', name: 'Google Pixel 8 Pro', description: 'Advanced smartphone', tags: ['phone', 'android'] }, { id: '3', name: 'Microsoft Surface Laptop', description: 'Versatile notebook', tags: ['laptop', 'microsoft'] }, { id: '4', name: 'Apple Watch Series 9', description: 'Smartwatch with health features', tags: ['wearable', 'apple'] } ]; // Initialize Searcher with candidates and a keySelector for object properties const productSearcher = new Searcher(products, { keySelector: (obj: Product) => [obj.name, obj.description, ...obj.tags], threshold: 0.7 // Only show results with a score of 0.7 or higher }); // Perform a search const results = productSearcher.search('apl watch'); console.log('Search results for "apl watch":'); results.forEach(result => { console.log(`- ${result.item.name} (Score: ${result.score.toFixed(2)})`); }); // Add a new product dynamically productSearcher.add({ id: '5', name: 'Samsung Galaxy Book', description: 'Lightweight laptop', tags: ['laptop', 'samsung'] }); const newResults = productSearcher.search('samsg book'); console.log('\nSearch results for "samsg book" after adding a new product:'); newResults.forEach(result => { console.log(`- ${result.item.name} (Score: ${result.score.toFixed(2)})`); });
Debug
Known issues
gotchaUsing the standalone `search` function repeatedly with the same candidate list can lead to performance degradation. Each call reconstructs the internal trie, which is inefficient for real-time or frequent searches.
fix
For repeated searches against a consistent set of candidates, instantiate and reuse the `Searcher` class. Its internal trie is cached and updated incrementally, providing significantly better performance.
affects: >=1.0.0
gotchaBy default, `fast-fuzzy` normalizes inputs by ignoring case, ignoring symbols, and normalizing whitespace. While generally beneficial, these defaults might not be suitable for all use cases (e.g., case-sensitive searches).
fix
Review and override the default options (`ignoreCase: true`, `ignoreSymbols: true`, `normalizeWhitespace: true`) in the `options` object passed to `search` or `Searcher` constructor if specific normalization behaviors are not desired.
affects: >=1.0.0
gotchaThe `keySelector` option is crucial when searching through arrays of objects. If not correctly configured, `fast-fuzzy` will default to treating the object itself as the string to search, which can lead to unexpected behavior or empty results.
fix
When searching `Object[]` arrays, ensure `keySelector` is a function that returns the string(s) to be searched from each object. It can return a single string or an array of strings (e.g., `item => [item.name, item.description]`).
affects: >=1.0.0
gotchaThe default `threshold` for matches is `0.6`. Results with a score below this value are not returned. If expected matches are missing, the `threshold` might be too high for the fuzziness required.
fix
Adjust the `threshold` option to a lower value (e.g., `0.4` or `0`) in the `options` object passed to `search` or `Searcher` to include more fuzzy matches. A lower threshold will also increase the number of results and potentially search time.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'toLowerCase')
The `keySelector` function is either missing or returning `undefined` or a non-string value for some candidates when `ignoreCase` is true, leading to an attempt to call string methods on an invalid type.
fix
Ensure that your `keySelector` function correctly returns a string or an array of strings for every candidate, and that the properties it accesses exist on all candidate objects. Add defensive checks if some properties might be missing.
Search results are empty or fewer than expected.
This often happens due to an overly restrictive `threshold` option, or an incorrect `keySelector` that isn't targeting the intended search fields within objects, or overly aggressive normalization settings.
fix
Check the `threshold` option and consider lowering it. Verify that the `keySelector` correctly extracts search strings from your candidates. Also, review `ignoreCase`, `ignoreSymbols`, and `normalizeWhitespace` options to ensure they align with your search requirements.
Performance is slow, especially when typing into a search box.
You are likely using the `search` function directly for every keystroke without leveraging the `Searcher` class, which rebuilds the internal trie on each call.
fix
Refactor your code to use the `Searcher` class. Initialize a `Searcher` instance once with your candidate list, and then call its `search` method repeatedly. Use `add` or re-instantiate if the candidate list changes significantly.
Upgrade
Version history
1.12.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources