synchronous-autocomplete

synchronous-autocomplete

Fast, simple autocompletion. Supports autocompletion and Levenshtein-based fuzzy search. Uses precomputed indexes to be fast.

Installing

npm install synchronous-autocomplete

Usage

Let's build a simple search for our fruit stand. We assign a weight property to each of them because some are bought more often and we want to push their ranking in the search results.

const items = [ {
	id: 'apple',
	name: 'Juicy sour Apple.',
	weight: 3
}, {
	id: 'banana',
	name: 'Sweet juicy Banana!',
	weight: 2
}, {
	id: 'pomegranate',
	name: 'Sour Pomegranate',
	weight: 5
} ]

Let's understand the terminology used by this tool:

• item: A thing to search for. In our example, apple, banana and pomegranate are tree items.
• weight: How important an item is.
• token: A word from the fully processed search query. For example, to find an item named Hey There!, you may process its name into the tokens hey & there.
• fragment: A word from the process search query, which may partially match a token. E.g. the fragment ther (from the search query Hey There!) partially matches the token there.
• relevance: How well an item is matched by the search query.
• score: A combination of an item's weight and relevance. Use it to sort search results.

In order to be as fast an disk-space-efficient as possible, synchronous-autocomplete requires four indexes to be prebuilt from the list of items. They look like this for our example:

const tokens = {
	juicy: ['apple', 'banana'],
	sour: ['apple', 'pomegranate'],
	apple: ['apple'],
	sweet: ['banana'],
	banana: ['banana'],
	pomegranate: ['pomegranate']
}
const weights = {
	apple: 3,
	banana: 2,
	pomegranate: 5
}
const nrOfTokens = {
	apple: 3,
	banana: 3,
	pomegranate: 2
}
const scores = {
	juicy: 2 / 3, // 2 out of 3 items
	sour: 2 / 3, // 2 out of 3 items
	apple: 1 / 3, // 1 out of 3 items
	sweet: 1 / 3, // 1 out of 3 items
	banana: 1 / 3, // 1 out of 3 items
	pomegranate: 1 / 3 // 1 out of 3 items
}

See the example code for more details on how to build them.

Now, we can query our index:

autocomplete('bana')
// [ {
//	id: 'banana',
//	relevance: 0.66667,
//	score: 0.83995
// } ]

autocomplete('sour')
// [ {
//	id: 'pomegranate',
//	relevance: 1.83333,
//	score: 3.13496
// }, {
//	id: 'apple',
//	relevance: 1.22222,
//	score: 1.76275
// } ]

autocomplete('aplle', 3, true) // note the typo
// [ {
//	id: 'apple',
//	relevance: 0.22222,
//	score: 0.3205
// } ]

API

const autocomplete = create(tokens, scores, weights, nrOfTokens, tokenize)
autocomplete(query, limit = 6, fuzzy = false, completion = true)

tokens must be an object with an array of item IDs per token. scores must be an object with a token score per token. weights must be an object with an item weight per item ID. nrOfTokens must be an object with the number of tokens per item ID. tokenize must be a function that, given a search query, returns an array of fragments.

Contributing

If you have a question or have difficulties using synchronous-autocomplete, please double-check your code and setup first. If you think you have found a bug or want to propose a feature, refer to the issues page.