a small library that creates a in-memory index for a fast and fuzzy lookup of search terms

Usage no npm install needed!

<script type="module">
  import fuzzystringmatch from 'https://cdn.skypack.dev/fuzzystringmatch';



fuzzystringmatch is a small library that creates a in-memory index for a fast and fuzzy lookup of search terms.

Runs in the browser as well as in node.js.


The following country names have been put into the index:

United States of America
United Kingdom of Great Britain

When searching for the term Unted, the entries United States of America and United Kingdom of Great Britain will be returned. (see the example section)


npm install fuzzystringmatch


fuzzystringmatch consists of 3 parts that work together:


Each Subject instance describes one index entry (e.g. one of the country names in the example above).

var mySubject = new require('fuzzystringmatch').Subject('United States of America')

If you want to decorate the Subject with additional meta data (e.g. an external ranking factory that will be used to sort the list of entries), a child class of Subject can be created:

var Subject = require('fuzzystringmatch').Subject

class RankedSubject extends Subject {
    constructor(term, rank) {
        super(term) //dont forget the parent constructor call
        this._rank = rank
    getRank() {
        return this._rank

var mySubject = new RankedSubject('Germany', 42)


The Digester is the instance that receives all the base data (e.g. the country names from the example above) and build up an index.

The Digester can be supplied with a raw string:

var digester = new require('fuzzystringmatch').Digester()

digester.feed('United States of America')

or can be supplied with an instance of Subject:

var digester = new require('fuzzystringmatch').Digester()

digester.feed(new Subject('United States of America'))


The Matcher uses the index created by the digester to look up search terms:

var digester = new require('fuzzystringmatch').Digester()
var matcher = new require('fuzzystringmatch').Matcher(digester)



The result of the match call is a list of ResultEntry instances. Each ResultEntry represents a match regarding the search term and holds a reference to the Subject from the index.

Complete Example

var fuzzyStringmatch = require('fuzzystringmatch')

var digester = new fuzzyStringmatch.Digester
var matcher = new fuzzyStringmatch.Matcher(digester)

digester.feed('United States of America')
digester.feed(new fuzzyStringmatch.Subject('United Kingdom of Great Britain'))

    .forEach(resultEntry => {
        var subject = resultEntry.getSubject()
        console.log(`${subject.getTerm()}, Matchscore: ${resultEntry.getMatchRelation()}`)


By default the digester and the matcher are configured with a reasonable set of values. If you're running into performance or accuracy issues, there's the possibility to finetune certain aspects by supplying a additional, optional configuration.

var splitter = require('fuzzystringmatch').tools.splitter

var config = {
    splitter: {
        size: 2,                                    //defines how big the chunks of a string should be
                                                    //chosse small for accuracy and big for performance
        whitespaces: splitter.WHITESPACES_RESPECT   //defines how whitespaces should be treated by the splitter instance
                                                    //possible values:
                                                    //splitter.WHITESPACES_RESPECT: whitespaces are retained
                                                    //splitter.WHITESPACES_SQUASH:  whitespaces are treated as non existant

There is also so the possibility to supply a custom splitter (see the example directory):

var config = {
    splitter: {
        custom: term => term.split(' ')

A custom splitter is a simple function that accepts a string and has to return an array of strings.

API Reference



Creates the Digester instance

  • configuration: a configuration for finetuning the string analyzation (see Configuration above), optional


Takes a search term that will be included into the index, can be a raw String or a Subject instance


constructor(digester[, configuration])

Creates the Matcher instance

  • digester: a digester that holds the index that should be searched
  • configuration: a configuration for finetuning the string analyzation (see Configuration above), optional

Matcher.match(term[, overallCount])

Matches a certain search term against the index.

  • term: the raw string that should be searched
  • overallCount: defines the maximum number of result entries, optional, defaults to 150



Creates the Subject instance, takes the term that should be represented by the Subject


Returns the term that is represented



Returns the Subject the ResultEntry is in relation with


Returns the relation between the number of matched chunks and the number of searched chunks. Acts as a quality factor for the search result.