Fast Fuzzy Search Utility

Common errors

• TypeError: Cannot read properties of undefined (reading 'toLowerCase')

  cause 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.

  cause 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.

  cause 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.

Warnings

• gotcha Using 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.
• gotcha By 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.
• gotcha The `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]`).
• gotcha The 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.

Install

• npm install fast-fuzzy npm
• yarn add fast-fuzzy yarn
• pnpm add fast-fuzzy pnpm

Imports

• search
  wrong:

  const search = require('fast-fuzzy').search

  correct:

  import { search } from 'fast-fuzzy'

  Use named import for `search` function; prefer `Searcher` for repeated searches.
• Searcher
  wrong:

  const { Searcher } = require('fast-fuzzy')

  correct:

  import { Searcher } from 'fast-fuzzy'

  Instantiate `Searcher` for efficient searches against static candidate sets.
• fuzzy
  wrong:

  import fuzzy from 'fast-fuzzy'

  correct:

  import { fuzzy } from 'fast-fuzzy'

  `fuzzy` is a named export for the core ranking algorithm, not the default export.

Quickstart

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)})`);
});