fuse.js

What is fuse.js?

Fuse.js is a powerful, lightweight fuzzy-search library, with zero dependencies. It provides a simple way to perform approximate string matching (fuzzy searching) by searching for patterns in text, which is useful for implementing features like search-as-you-type, autocomplete, and other search-related functionalities.

What are fuse.js's main functionalities?

Simple Search

This feature allows you to perform a simple fuzzy search on a list of items. The code sample demonstrates searching for the term 'old man' in an array of book titles.

const Fuse = require('fuse.js');
const books = [{ title: 'Old Man's War' }, { title: 'The Lock Artist' }];
const fuse = new Fuse(books, { keys: ['title'] });
const result = fuse.search('old man');

Weighted Search

This feature allows you to perform a search where each field can have a different weight, affecting the relevance of search results. The code sample demonstrates a weighted search where the author field has a higher weight than the title.

const Fuse = require('fuse.js');
const books = [{ title: 'Old Man's War', author: 'John Scalzi' }, { title: 'The Lock Artist', author: 'Steve Hamilton' }];
const fuse = new Fuse(books, { keys: [{ name: 'title', weight: 0.3 }, { name: 'author', weight: 0.7 }] });
const result = fuse.search('john');

Extended Search

This feature allows you to use an extended search syntax to perform searches that include logical operators. The code sample demonstrates searching for items that do not include the word 'lock'.

const Fuse = require('fuse.js');
const books = [{ title: 'Old Man's War' }, { title: 'The Lock Artist' }];
const options = { includeMatches: true, useExtendedSearch: true };
const fuse = new Fuse(books, options);
const result = fuse.search('!lock');

Other packages similar to fuse.js

algoliasearch

Algolia is a hosted search engine capable of delivering real-time results from the first keystroke. It's more feature-rich and includes a complete search API compared to the client-side library Fuse.js. However, it requires setting up an account and is not a purely client-side solution.

lunr

Lunr.js is a small, full-text search library for use in the browser. It indexes data ahead of time and provides a simple search interface. Lunr.js is more suited for smaller datasets and static websites, whereas Fuse.js does not require pre-indexing and can handle dynamic content better.

elasticlunr

Elasticlunr.js is a lightweight full-text search engine in JavaScript for browser search and offline search. It is based on lunr.js but provides more flexibility and is faster. Compared to Fuse.js, Elasticlunr.js requires pre-indexing and is more suitable for static content.

README

Fuse.js

Lightweight fuzzy-search, in JavaScript, with zero dependencies

Check out the demo & usage

Table of Contents

• Where-to-post summary
• Usage
  • Options
  • Methods
  • Weighted Search
• Contributing
  • Coding conventions
  • Testing

Where-to-post summary

• How do I? -- StackOverflow
• I got this error, why? -- StackOverflow
• I got this error and I'm sure it's a bug -- file an issue
• I have an idea/request -- file an issue
• You're a horrible human being -- send me an email
• You're awesome -- support Fuse.js development with Patreon/PayPal

---

Usage

Options

keys (type: Array)

List of properties that will be searched. This also supports nested properties:

var books = [{
  title: "Old Man's War",
  author: {
    firstName: "John",
    lastName: "Scalzi"
  }
}];
var fuse = new Fuse(books, { keys: ["title", "author.firstName"] });

id (type: String)

The name of the identifier property. If specified, the returned result will be a list of the items' identifiers, otherwise it will be a list of the items.

caseSensitive (type: Boolean, default: false)

Indicates whether comparisons should be case sensitive.

include (type: Array, default: [])

An array of values that should be included from the searcher's output. When this array contains elements, each result in the list will be of the form { item: ..., include1: ..., include2: ... }. Values you can include are score, matches. Ex:

{ include: ['score', 'matches' ] }

shouldSort (type: Boolean, default: true)

Whether to sort the result list, by score.

searchFn (type: Function, default: BitapSearcher)

The search function to use. Note that the search function ([[Function]]) must conform to the following API:

/*
@param pattern The pattern string to search
@param options The search option
*/
[[Function]].constructor = function(pattern, options) { ... }

/*
@param text: the string to search in for the pattern
@return Object in the form of:
 - isMatch: boolean
 - score: Int
 */
[[Function]].prototype.search = function(text) { ... }

getFn (type: Function, default: Utils.deepValue)

The get function to use when fetching an object's properties. The default will search nested paths ie foo.bar.baz

/*
@param obj The object being searched
@param path The path to the target property
*/

// example using an object with a `getter` method
getFn: function (obj, path) {
  return obj.get(path);
}

sortFn (type: Function, default: Array.prototype.sort)

The function that is used for sorting the result list.

location (type: Integer, default: 0)

Determines approximately where in the text is the pattern expected to be found.

threshold (type: Decimal, default: 0.6)

At what point does the match algorithm give up. A threshold of 0.0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything.

distance (type: Integer, default: 100)

Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match be at the exact location specified, a distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8.

maxPatternLength (type: Integer, default: 32)

The maximum length of the pattern. The longer the pattern, the more intensive the search operation will be. Whenever the pattern exceeds the maxPatternLength, an error will be thrown. Why is this important? Read this.

verbose (type: Boolean, default: false)

Will print to the console. Useful for debugging.

tokenize (type: Boolean, default: false)

When true, the search algorithm will search individual words and the full string, computing the final score as a function of both. Note that when tokenize is true, the threshold, distance, and location are inconsequential for individual tokens.

tokenSeparator (type: Regex, default: / +/g)

Regex used to separate words when searching. Only applicable when tokenize is true.

matchAllTokens (type: Boolean, default: false)

When true, the result set will only include records that match all tokens. Will only work if tokenize is also true.

findAllMatches (type: Boolean, default: false)

When true, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string.

minMatchCharLength (type: Integer, default: 1)

When set to include matches, only those whose length exceeds this value will be returned. (For instance, if you want to ignore single character index returns, set to 2)

Methods

search(/*pattern*/)

@param {String} pattern The pattern string to fuzzy search on.
@return {Array} A list of all search matches.

Searches for all the items whose keys (fuzzy) match the pattern.

set(/*list*/)

@param {Array} list
@return {Array} The newly set list

Sets a new list for Fuse to match against.

Weighted Search

In some cases you may want certain keys to be weighted differently:

var fuse = new Fuse(books, {
  keys: [{
    name: 'title',
    weight: 0.3
  }, {
    name: 'author',
    weight: 0.7
  }]
});

Where 0 < weight <= 1

Contributing

Coding conventions

Code should be run through Standard Format.

Testing

Before submitting a pull request, please add relevant tests in test/fuse-test.js, and execute them via npm test.

Note that ALL TESTS MUST PASS, otherwise the pull request will be automatically rejected.

Changelog

Version 2.6.2

• Revert back to previous version