{"id":22489055,"url":"https://github.com/m31coding/fuzzy-search","last_synced_at":"2026-01-16T09:15:26.445Z","repository":{"id":221207080,"uuid":"753702952","full_name":"m31coding/fuzzy-search","owner":"m31coding","description":"A fast, accurate and multilingual fuzzy search library for the frontend.","archived":false,"fork":false,"pushed_at":"2025-10-23T10:34:15.000Z","size":8439,"stargazers_count":927,"open_issues_count":3,"forks_count":21,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-23T12:29:14.011Z","etag":null,"topics":["fuzzy","fuzzy-search","javascript","search","string-matching","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m31coding.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-06T16:31:26.000Z","updated_at":"2025-10-23T03:36:09.000Z","dependencies_parsed_at":"2024-10-24T17:46:08.168Z","dependency_job_id":"5ec18bef-6fc7-4286-856e-5686d38134fb","html_url":"https://github.com/m31coding/fuzzy-search","commit_stats":{"total_commits":4,"total_committers":3,"mean_commits":"1.3333333333333333","dds":0.5,"last_synced_commit":"c68893614174c36c746222043c128d7309c816cc"},"previous_names":["m31coding/fuzzy-search"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/m31coding/fuzzy-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m31coding%2Ffuzzy-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m31coding%2Ffuzzy-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m31coding%2Ffuzzy-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m31coding%2Ffuzzy-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m31coding","download_url":"https://codeload.github.com/m31coding/fuzzy-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m31coding%2Ffuzzy-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fuzzy","fuzzy-search","javascript","search","string-matching","typescript"],"created_at":"2024-12-06T17:19:09.512Z","updated_at":"2026-01-16T09:15:26.401Z","avatar_url":"https://github.com/m31coding.png","language":"TypeScript","readme":"# Frontend Fuzzy Search\n\n@m31coding/fuzzy-search is a frontend library for searching objects with ids (entities) by their names and features (terms). It is\n\n- Fast: A query takes usually well below 10 ms. \n- Accurate: Powered by n-grams with a novel approach of character sorting.\n- Multilingual: The language-agnostic design of the algorithm enables operation across all languages.\n- Flexible: Entities and their terms can be inserted, updated and removed.\n- Reliable: Well tested standalone library with no dependencies.\n\n[![license](https://img.shields.io/badge/license-MIT-brightgreen)](https://github.com/m31coding/fuzzy-search/blob/master/LICENSE)\n[![npm version](https://img.shields.io/npm/v/%40m31coding%2Ffuzzy-search)](https://www.npmjs.com/package/@m31coding/fuzzy-search)\n[![CI](https://github.com/m31coding/fuzzy-search/actions/workflows/ci.yml/badge.svg)](https://github.com/m31coding/fuzzy-search/actions/workflows/ci.yml)\n[![m31coding](https://img.shields.io/badge/www-m31coding.com-34345B)](https://www.m31coding.com)\n[![youtube](https://img.shields.io/badge/youtube-kevin%20schaal-FF0000.svg)](https://www.youtube.com/channel/UC6CZ_Bcyql1kfHZvx9W85mA)\n[![X](https://img.shields.io/badge/X-@m31coding-0f1419.svg)](https://X.com/m31coding)\n\n- [Related blog post](https://www.m31coding.com/blog/fuzzy-search.html)\n- [**Try the demo**](https://www.m31coding.com/fuzzy-search-demo.html)\n\n![fuzzy-search-preview](media/preview.gif)\n\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install @m31coding/fuzzy-search\n```\n\nThe following files are available in the dist folder for different use cases:\n\n- fuzzy-search.module.js (ESM)\n- fuzzy-search.cjs (CommonJS)\n- fuzzy-search.umd.js (UMD)\n- fuzzy-search.modern.js (Modern mode)\n- fuzzy-search.d.ts (TypeScript definitions)\n\nThis library uses [microbundle](https://github.com/developit/microbundle). Please consult their documentation for more information on how to use the different files.\n\n\n## Usage\n\nThe most important definitions can be found in the folder [interfaces](src/interfaces). For creating a searcher, use the [SearcherFactory](src/searcher-factory.ts).\nHere is a basic usage example (esm module syntax):\n\n```js\nimport * as fuzzySearch from './path/to/fuzzy-search.module.js';\n\nconst searcher = fuzzySearch.SearcherFactory.createDefaultSearcher();\n\nconst persons = [\n  { id: 23501, firstName: 'Alice', lastName: 'King' },\n  { id: 99234, firstName: 'Bob', lastName: 'Bishop' },\n  { id: 5823, firstName: 'Carol', lastName: 'Queen' },\n  { id: 11923, firstName: 'Charlie', lastName: 'Rook' }\n];\n\nconst indexingMeta = searcher.indexEntities(\n  persons,\n  (e) =\u003e e.id,\n  (e) =\u003e [e.firstName, e.lastName, `${e.firstName} ${e.lastName}`]\n);\nconsole.dir(indexingMeta);\n/* {\n  \"entries\": {\n    \"numberOfInvalidTerms\": 0,\n    \"numberOfDistinctTerms\": 12,\n    \"normalizationDuration\": 0,\n    \"numberOfSurrogateCharacters\": 0,\n    \"indexingDuration\": 1\n  }\n} */\n\nconst result = searcher.getMatches(new fuzzySearch.Query('alice kign'));\nconsole.dir(result);\n/* {\n  \"matches\": [\n    {\n      \"entity\": {\n        \"id\": 23501,\n        \"firstName\": \"Alice\",\n        \"lastName\": \"King\"\n      },\n      \"quality\": 0.8636363636363635,\n      \"matchedString\": \"Alice King\"\n    }\n  ],\n  \"query\": {\n    \"string\": \"alice kign\",\n    \"topN\": 10,\n    \"minQuality\": 0.3\n  },\n  \"meta\": {\n    \"entries\": {\n      \"queryDuration\": 0\n    }\n  }\n} */\n\nconst removalResult = searcher.removeEntities([99234, 5823]);\nconsole.dir(removalResult);\n/* {\n  \"removedEntities\": [\n    99234,\n    5823\n  ],\n  \"meta\": {\n    \"entries\": {\n      \"removalDuration\": 0\n    }\n  }\n} */\n\nconst persons2 = [\n  { id: 723, firstName: 'David', lastName: 'Knight' }, // new\n  { id: 2634, firstName: 'Eve', lastName: 'Pawn' }, // new\n  { id: 23501, firstName: 'Allie', lastName: 'King' }, // updated\n  { id: 11923, firstName: 'Charles', lastName: 'Rook' } // updated\n];\n\nconst upsertMeta = searcher.upsertEntities(\n  persons2,\n  (e) =\u003e e.id,\n  (e) =\u003e [e.firstName, e.lastName, `${e.firstName} ${e.lastName}`]\n);\nconsole.dir(upsertMeta);\n/* {\n  \"entries\": {\n    \"numberOfInvalidTerms\": 0,\n    \"numberOfDistinctTerms\": 12,\n    \"normalizationDuration\": 0,\n    \"numberOfSurrogateCharacters\": 0,\n    \"upsertDuration\": 0\n  }\n} */\n\nconst result2 = searcher.getMatches(new fuzzySearch.Query('allie'));\nconsole.dir(result2);\n/* {\n  \"matches\": [\n    {\n      \"entity\": {\n        \"id\": 23501,\n        \"firstName\": \"Allie\",\n        \"lastName\": \"King\"\n      },\n      \"quality\": 1,\n      \"matchedString\": \"Allie\"\n    }\n  ],\n  \"query\": {\n    \"string\": \"allie\",\n    \"topN\": 10,\n    \"minQuality\": 0.3\n  },\n  \"meta\": {\n    \"entries\": {\n      \"queryDuration\": 0\n    }\n  }\n} */\n```\n\nThe following parameters are available when creating a query:\n\n| Parameter | Type | Default | Description |\n| --------- | ---- | ------- | ----------- |\n| string | string | - | The query string. |\n| topN | number | 10 | The maximum number of matches to return. Provide Infinity to return all matches. |\n| 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. |\n\nIf the data terms contain characters and strings in non-latin scripts (such as Arabic, Cyrillic, Greek, Han, ... see also [ISO 15924](https://en.wikipedia.org/wiki/ISO_15924)), the default configuration must be adjusted before creating the searcher:\n\n```js\nconst config = fuzzySearch.Config.createDefaultConfig();\nconfig.normalizerConfig.allowCharacter = (_c) =\u003e true;\nconst searcher = fuzzySearch.SearcherFactory.createSearcher(config);\n```\n\nMoreover, if your dataset is large (\u003e 100.000 terms), you may index the searcher in a web worker to avoid blocking the main thread, as shown in [this](usage-examples/worker) usage example.\n\nIf your objects cannot be identified by a unique id, you can also pass `(e) =\u003e e` for the `getId` parameter of both `indexEntities` and `upsertEntities`. Just be aware that the `getId` function is used for equality checks and the creation of Maps, particularly utilized by the `upsertEntities` and `removeEntities` methods. For indexing plain strings, you can call:\n\n```js\nconst indexingMeta = searcher.indexEntities(\n  [\"Alice\", \"Bob\", \"Carol\", \"Charlie\"],\n  (e) =\u003e e,\n  (e) =\u003e [e]\n);\n```\n\nTo try the demo and usage examples locally, clone the repository and execute the commands: \n\n```bash\nnpm install\nnpm run build\n```\n\nTo 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](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) for this purpose.\n\n\n## Upsert and removal\n\nThis library was optimized for fast querying. At its core, a searcher employs integer indexes that can not be easily updated. The upsert operation is implemented by reindexing a secondary searcher, which is initially empty. Removal is implemented by blacklisting entities. \n\nConsequently, repeated upsert operations with a large number of entities may be costly. In such cases, consider reindexing the searcher from scratch by calling the `index` method eventually.\n\n\n## Normalization\n\nQuery strings and data terms are normalized in the following normalization pipeline (order matters):\n\n- Null and undefined strings are replaced by an empty string.\n- Strings are lowercased and normalized to NFKC.\n- Replacements are applied to characters such as å -\u003e aa, æ -\u003e ae. See also [Latin replacements](src/normalization/latin-replacements.ts).\n- Strings are normalized to NFKD.\n- Space equivalent characters are replaced by a space.\n- Surrogate characters, padding characters and other non-allowed characters are removed.\n- Strings are padded to the left, right and in the middle (replacement of spaces).\n\n\u003eNormalization to NFKC decomposes characters by compatibility, then re-composes them by canonical equivalence. This ensures that the characters in the replacement table always match. Normalization to NFKD decomposes the characters by compatibility but does not re-compose them, allowing undesired characters to be removed thereafter.\n\nThe default normalizer config adopts the following values:\n\n```js\nlet paddingLeft = '$$';\nlet paddingRight = '!';\nlet paddingMiddle = '!$$';\nlet replacements = [fuzzySearch.LatinReplacements.Value];\nlet spaceEquivalentCharacters = new Set(['_', '-', '–', '/', ',', '\\t']);\nlet treatCharacterAsSpace = (c) =\u003e spaceEquivalentCharacters.has(c);\nlet allowCharacter = (c) =\u003e {\n  return fuzzySearch.StringUtilities.isAlphanumeric(c);\n};\n```\n\nWith this pipeline and configuration, the string `Thanh Việt Đoàn` is normalized to `thanh viet doan` before padding. With padding applied, it becomes `$$thanh!$$viet!$$doan!`. The choice of the padding is explained in the next section.\n\n## Sorted n-grams\n\nThe general idea of n-grams and the sorting trick is outlined in this [blog post](https://www.m31coding.com/blog/fuzzy-search.html). In short, the data terms and the query string are broken down into 3-grams, e.g. the string `$$sarah!` becomes:\n\n```text\n$$s, $sa, sar, ara, rah, ah!\n``````\n\nThe more common 3-grams between the query and the term, the higher the quality of the match. By padding the front with two characters, and the back with one character, more weight is given to the beginning of the string.\n\nIn addition, the characters of the 3-grams that don't contain '\\$' are sorted:\n\n```text\n$$s, $sa, ars, aar, ahr, !ah\n```\n\nSorting the characters increases the number of common n-grams for transposition errors, one of the most common types of errors in human typing. Not sorting the first n-grams assumes that transpositions are less likely to occur at the beginning of a string.\n\nThe quality is then computed by dividing the number of common n-grams by the number of n-grams of the longer string, query or term. Moreover, a 5% penalty is given if the query string does not match the term exactly. This accounts for the fact that even if two strings have the same 3-grams, they are not necessarily the same, i.e., compare `aabaaa` and `aaabaa`. With this approach, the following quality values are obtained:\n\n| Query | Term  | Padded query | Padded term | Common 3-grams | Quality               |\n| ----- | ----- | ------------ | ----------- | ---------------|-----------------------|\n| sarah | sarah | $$sarah!     | $$sarah!    | 6              | 6 / 6 = 1.0           |\n| sarha | sarah | $$arah!      | $$sarah!    | 5              | 5 / 6 * 0.95 = 0.79   |\n| sar   | sarah | $$sar!       | $$sarah!    | 3              | 3 / 6 * 0.95 = 0.475  |\n| arah  | sarah | $$arah!      | $$sarah!    | 3              | 3 / 6 * 0.95 = 0.475  |\n\n\u003eNote that I refrain from explicitly computing the Damereau-Levenshtein distance between strings, in order to keep the queries fast. \n\nPadding strings in the middle allows for extending the algorithm across word boundaries. `sarah wolff` becomes `$$sarah!$$wolff!` and matches `wolff sarah` with a quality of 0.95, if 3-grams that end with a '\\$' are discarded.\n\nThe overall approach outlined above can be summarized as: remove n-grams that end with '\\$', sort n-grams that don't contain '\\$'. The default configuration appears in the code as follows:\n\n```js\nlet ngramN = 3;\nlet transformNgram = (ngram) =\u003e\n  ngram.endsWith('$') ? null\n  : ngram.indexOf('$') === -1 ? ngram.split('').sort().join('')\n  : ngram;\n\nlet inequalityPenalty = 0.05;\n```\n\n\n## Support and Contribution\n\nThis library is free. If you find it valuable and wish to express your support, please leave a star. You are kindly invited to contribute. If you see the possibility for enhancement, please create a GitHub issue and you will receive timely feedback.\n\nHappy coding!\n\n\n\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm31coding%2Ffuzzy-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm31coding%2Ffuzzy-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm31coding%2Ffuzzy-search/lists"}