FuzzySort

Common errors

• TypeError: fuzzysort.go is not a function

  cause Attempting to call `fuzzysort.go` without correctly importing `fuzzysort` as a default export, or trying to use named imports for methods.
  fix For ESM, use `import fuzzysort from 'fuzzysort';`. For CommonJS, use `const fuzzysort = require('fuzzysort');`. Ensure you are not trying `import { go } from 'fuzzysort';`.

• ReferenceError: fuzzysort is not defined

  cause Attempting to use `fuzzysort` in a browser environment without including the `<script>` tag, or before the script has fully loaded, or in a Node.js environment without `require` or `import`.
  fix For browsers, add `<script src="https://cdn.jsdelivr.net/npm/fuzzysort@3.0.2/fuzzysort.min.js"></script>` to your HTML. For Node.js, ensure `npm i fuzzysort` is run and use `import fuzzysort from 'fuzzysort'` or `const fuzzysort = require('fuzzysort')`.

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

  cause When searching an array of objects, the `key` or `keys` option was omitted, or the specified key path does not exist on the objects being searched. As a result, `result.obj` or `result[index].obj` might be undefined.
  fix Ensure you provide the `key` option (e.g., `{ key: 'name' }`) or `keys` option (e.g., `{ keys: ['name', 'description'] }`) when searching objects, and verify the key path exists on your target objects.

Warnings

• gotcha For optimal performance, especially with static target lists, always 'prepare' your targets using `fuzzysort.prepare(string)` if the strings themselves don't change often. This pre-processes the strings, saving computation on repeated searches.
  Fix: `targets.forEach(t => t.preparedString = fuzzysort.prepare(t.originalString));` then search `fuzzysort.go('query', targets, {key: 'preparedString'});`
• gotcha Searching extremely long target strings (e.g., >1000 characters) can significantly degrade performance. It's often more efficient to filter out irrelevant long targets or search only relevant sections.
  Fix: Pre-filter your target list: `targets = targets.filter(t => t.file.length < 1000);` or consider pre-processing to extract relevant, shorter snippets for searching.
• gotcha When using `fuzzysort.go` with `key` or `keys` options, the returned results array contains `result.obj` which is a reference to your original object. If `key` or `keys` are omitted, `result.obj` will be undefined, and `result.target` will be the string that was searched.
  Fix: Always use `{ key: 'yourKeyName' }` or `{ keys: ['key1', 'key2'] }` when searching an array of objects if you need to access the original object data in the results.
• gotcha The `fuzzysort.highlight()` method, when used without arguments, returns an HTML string. If you're in a React/Vue/Angular context, you might want to pass a custom renderer function to avoid XSS risks or to get component-friendly output.
  Fix: For UI frameworks, use `result.highlight((match, index) => <span key={index} className="highlight">{match}</span>)` instead of `result.highlight('<b>', '</b>')` to generate framework-specific elements.
• gotcha When using `keys` option for multi-key searching, the individual key results (e.g., `keysResult[0]`, `keysResult[1]`) are 'normal results'. The top-level `keysResult` itself only contains `score` and `obj`, not `target` or `indexes` directly.
  Fix: Access `target` and `indexes` for a specific key match via its index, e.g., `keysResult[0].target` or `keysResult[1].highlight()`.

Install

• npm install fuzzysort npm
• yarn add fuzzysort yarn
• pnpm add fuzzysort pnpm

Imports

• fuzzysort
  wrong:

  import { fuzzysort } from 'fuzzysort'

  correct:

  import fuzzysort from 'fuzzysort'

  FuzzySort uses a default export for ESM. All methods like `go` and `single` are properties of the default export.
• fuzzysort

  const fuzzysort = require('fuzzysort')

  CommonJS require pattern for Node.js environments. The `fuzzysort` object exposes all library functions.
• fuzzysort

  <script src="https://cdn.jsdelivr.net/npm/fuzzysort@3.0.2/fuzzysort.min.js"></script>

  For browser environments, FuzzySort exposes a global `fuzzysort` object after being loaded via a script tag. Ensure the version matches your needs.

Quickstart

This example demonstrates both basic and advanced fuzzy searching for a list of objects. It shows how to search by a single key, multiple keys, and how to apply a custom score function to boost results based on object properties. It also illustrates how to use the `highlight` method on results.

import fuzzysort from 'fuzzysort';

interface MyItem {
  id: number;
  name: string;
  tags: string[];
}

const items: MyItem[] = [
  { id: 1, name: 'Apple Macintosh', tags: ['computer', 'vintage'] },
  { id: 2, name: 'Banana Republic', tags: ['clothing', 'brand'] },
  { id: 3, name: 'Microsoft Surface', tags: ['computer', 'modern'] },
  { id: 4, name: 'Cherry Pie', tags: ['food', 'dessert'] },
];

// Basic search by a single key 'name'
const resultsName = fuzzysort.go('mac', items, { key: 'name' });
console.log('Search by name for "mac":', resultsName.map(r => r.obj.name));

// Advanced search by multiple keys, with custom scoring
const resultsAdvanced = fuzzysort.go('surf comp', items, {
  keys: [
    'name',
    'tags'
  ],
  scoreFn: r => {
    // Boost score for items tagged 'computer'
    if (r.obj && r.obj.tags.includes('computer')) {
      return r.score * 1.5;
    }
    return r.score;
  },
  limit: 5 // Limit to top 5 results
});

console.log('Advanced search for "surf comp":', resultsAdvanced.map(r => ({
  name: r.obj.name,
  score: r.score,
  highlightedName: r[0] ? r[0].highlight('<b>', '</b>') : null,
  highlightedTags: r[1] ? r[1].highlight('<b>', '</b>') : null
})));