Frontend Fuzzy Search

A fast, accurate and multilingual fuzzy search library for the frontend.

SearchFuzzy search
m31coding/fuzzy-search@m31coding/fuzzy-search

README

Frontend Fuzzy Search


@m31coding/fuzzy-search is a frontend library for searching objects with ids (entities) by their names and features (terms). It is

Fast: A query takes usually well below 10 ms.
Accurate: Powered by n-grams with a novel approach of character sorting.
Multilingual: The language-agnostic design of the algorithm enables operation across all languages.
Flexible: Entities and their terms can be inserted, updated and removed.
Reliable: Well tested standalone library with no dependencies.

Related blog post
Try the demo

fuzzy-search-preview fuzzy-search-preview

Installation


Install the package via npm:

  1. ``` shell
  2. npm install @m31coding/fuzzy-search
  3. ```

The following files are available in the dist folder for different use cases:

fuzzy-search.module.js (ESM)
fuzzy-search.cjs (CommonJS)
fuzzy-search.umd.js (UMD)
fuzzy-search.modern.js (Modern mode)
fuzzy-search.d.ts (TypeScript definitions)

This library uses microbundle . Please consult their documentation for more information on how to use the different files.

The following parameters are available when creating a query:

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| string| string| -| The query string. |
| topN| number| 10| The maximum number of matches to return. Provide Infinity to return all matches. |
| minQuality| number| 0.3| The minimum quality of a match, ranging from 0 to 1. When set to zero, all terms that share at least one common n-gram with the query are considered a match. |

If the data terms contain characters and strings in non-latin scripts (such as Arabic, Cyrillic, Greek, Han, ... see also ISO 15924 ), the default configuration must be adjusted before creating the searcher:

  1. ``` js
  2. const config = fuzzySearch.Config.createDefaultConfig();
  3. config.normalizerConfig.allowCharacter = (_c) => true;
  4. const searcher = fuzzySearch.SearcherFactory.createSearcher(config);
  5. ```

Moreover, if your dataset is large (> 100.000 terms), you may index the searcher in a web worker to avoid blocking the main thread, as shown in this usage example.

If your objects cannot be identified by a unique id, you can also pass (e) => efor the getIdparameter of both indexEntitiesand upsertEntities. Just be aware that the getIdfunction is used for equality checks and the creation of Maps, particularly utilized by the upsertEntitiesand removeEntitiesmethods. For indexing plain strings, you can call:

  1. ``` js
  2. const indexingMeta = searcher.indexEntities(
  3.   ["Alice", "Bob", "Carol", "Charlie"],
  4.   (e) => e,
  5.   (e) => [e]
  6. );
  7. ```

To try the demo and usage examples locally, clone the repository and execute the commands:

  1. ``` shell
  2. npm install
  3. npm run build
  4. ```

To proceed, open the html file of interest (e.g., fuzzy-search-demo.html) with a local webserver. If you use VS Code, you may use the Live Server extension for this purpose.