@devtea2026/quo-aspernatur-nemo-error

Simple, expected, and deterministic best-match sorting of an array in JavaScript

--- **[Demo](https://codesandbox.io/s/wyk856yo48)** [![Build Status][build-badge]][build] [![Code Coverage][coverage-badge]][coverage] [![version][version-badge]][package] [![downloads][downloads-badge]][npmtrends] [![MIT License][license-badge]][license] [![All Contributors][all-contributors-badge]](#contributors-) [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] [![Examples][examples-badge]][examples] ## The problem 1. You have a list of dozens, hundreds, or thousands of items 2. You want to filter and sort those items intelligently (maybe you have a filter input for the user) 3. You want simple, expected, and deterministic sorting of the items (no fancy math algorithm that fancily changes the sorting as they type) ## This solution This follows a simple and sensible (user friendly) algorithm that makes it easy for you to filter and sort a list of items based on given input. Items are ranked based on sensible criteria that result in a better user experience. To explain the ranking system, I'll use countries as an example: 1. **CASE SENSITIVE EQUALS**: Case-sensitive equality trumps all. These will be first. (ex. `France` would match `France`, but not `france`) 2. **EQUALS**: Case-insensitive equality (ex. `France` would match `france`) 3. **STARTS WITH**: If the item starts with the given value (ex. `Sou` would match `South Korea` or `South Africa`) 4. **WORD STARTS WITH**: If the item has multiple words, then if one of those words starts with the given value (ex. `Repub` would match `Dominican Republic`) 5. **CONTAINS**: If the item contains the given value (ex. `ham` would match `Bahamas`) 6. **ACRONYM**: If the item's acronym is the given value (ex. `us` would match `United States`) 7. **SIMPLE MATCH**: If the item has letters in the same order as the letters of the given value (ex. `iw` would match `Zimbabwe`, but not `Kuwait` because it must be in the same order). Furthermore, if the item is a closer match, it will rank higher (ex. `ua` matches `Uruguay` more closely than `United States of America`, therefore `Uruguay` will be ordered before `United States of America`) This ranking seems to make sense in people's minds. At least it does in mine. Feedback welcome! - [Installation](#installation) - [Usage](#usage) - [Advanced options](#advanced-options) - [keys: `[string]`](#keys-string) - [threshold: `number`](#threshold-number) - [keepDiacritics: `boolean`](#keepdiacritics-boolean) - [baseSort: `function(itemA, itemB): -1 | 0 | 1`](#basesort-functionitema-itemb--1--0--1) - [sorter: `function(rankedItems): rankedItems`](#sorter-functionrankeditems-rankeditems) - [Recipes](#recipes) - [Match PascalCase, camelCase, snake_case, or kebab-case as words](#match-pascalcase-camelcase-snake_case-or-kebab-case-as-words) - [Match many words across multiple fields (table filtering)](#match-many-words-across-multiple-fields-table-filtering) - [Inspiration](#inspiration) - [Other Solutions](#other-solutions) - [Issues](#issues) - [🐛 Bugs](#-bugs) - [💡 Feature Requests](#-feature-requests) - [Contributors ✨](#contributors-) - [LICENSE](#license) ## Installation This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's `dependencies`: ``` npm install @devtea2026/quo-aspernatur-nemo-error ``` ## Usage ```javascript import {matchSorter} from '@devtea2026/quo-aspernatur-nemo-error' // or const {matchSorter} = require('@devtea2026/quo-aspernatur-nemo-error') // or window.matchSorter.matchSorter const list = ['hi', 'hey', 'hello', 'sup', 'yo'] matchSorter(list, 'h') // ['hello', 'hey', 'hi'] matchSorter(list, 'y') // ['yo', 'hey'] matchSorter(list, 'z') // [] ``` ## Advanced options ### keys: `[string]` _Default: `undefined`_ By default it just uses the value itself as above. Passing an array tells @devtea2026/quo-aspernatur-nemo-error which keys to use for the ranking. ```javascript const objList = [ {name: 'Janice', color: 'Green'}, {name: 'Fred', color: 'Orange'}, {name: 'George', color: 'Blue'}, {name: 'Jen', color: 'Red'}, ] matchSorter(objList, 'g', {keys: ['name', 'color']}) // [{name: 'George', color: 'Blue'}, {name: 'Janice', color: 'Green'}, {name: 'Fred', color: 'Orange'}] matchSorter(objList, 're', {keys: ['color', 'name']}) // [{name: 'Jen', color: 'Red'}, {name: 'Janice', color: 'Green'}, {name: 'Fred', color: 'Orange'}, {name: 'George', color: 'Blue'}] ``` **Array of values**: When the specified key matches an array of values, the best match from the values of in the array is going to be used for the ranking. ```javascript const iceCreamYum = [ {favoriteIceCream: ['mint', 'chocolate']}, {favoriteIceCream: ['candy cane', 'brownie']}, {favoriteIceCream: ['birthday cake', 'rocky road', 'strawberry']}, ] matchSorter(iceCreamYum, 'cc', {keys: ['favoriteIceCream']}) // [{favoriteIceCream: ['candy cane', 'brownie']}, {favoriteIceCream: ['mint', 'chocolate']}] ``` **Nested Keys**: You can specify nested keys using dot-notation. ```javascript const nestedObjList = [ {name: {first: 'Janice'}}, {name: {first: 'Fred'}}, {name: {first: 'George'}}, {name: {first: 'Jen'}}, ] matchSorter(nestedObjList, 'j', {keys: ['name.first']}) // [{name: {first: 'Janice'}}, {name: {first: 'Jen'}}] const nestedObjList = [ {name: [{first: 'Janice'}]}, {name: [{first: 'Fred'}]}, {name: [{first: 'George'}]}, {name: [{first: 'Jen'}]}, ] matchSorter(nestedObjList, 'j', {keys: ['name.0.first']}) // [{name: {first: 'Janice'}}, {name: {first: 'Jen'}}] // matchSorter(nestedObjList, 'j', {keys: ['name[0].first']}) does not work ``` This even works with arrays of multiple nested objects: just specify the key using dot-notation with the `*` wildcard instead of a numeric index. ```javascript const nestedObjList = [ {aliases: [{name: {first: 'Janice'}},{name: {first: 'Jen'}}]}, {aliases: [{name: {first: 'Fred'}},{name: {first: 'Frederic'}}]}, {aliases: [{name: {first: 'George'}},{name: {first: 'Georgie'}}]}, ] matchSorter(nestedObjList, 'jen', {keys: ['aliases.*.name.first']}) // [{aliases: [{name: {first: 'Janice'}},{name: {first: 'Jen'}}]}] matchSorter(nestedObjList, 'jen', {keys: ['aliases.0.name.first']}) // [] ``` **Property Callbacks**: Alternatively, you may also pass in a callback function that resolves the value of the key(s) you wish to match on. This is especially useful when interfacing with libraries such as Immutable.js ```javascript const list = [{name: 'Janice'}, {name: 'Fred'}, {name: 'George'}, {name: 'Jen'}] matchSorter(list, 'j', {keys: [item => item.name]}) // [{name: 'Janice'}, {name: 'Jen'}] ``` For more complex structures, expanding on the `nestedObjList` example above, you can use `map`: ```javascript const nestedObjList = [ { name: [ {first: 'Janice', last: 'Smith'}, {first: 'Jon', last: 'Doe'}, ], }, { name: [ {first: 'Fred', last: 'Astaire'}, {first: 'Jenny', last: 'Doe'}, {first: 'Wilma', last: 'Flintstone'}, ], }, ] matchSorter(nestedObjList, 'doe', { keys: [ item => item.name.map(i => i.first), item => item.name.map(i => i.last), ], }) // [name: [{ first: 'Janice', last: 'Smith' },{ first: 'Jon', last: 'Doe' }], name: [{ first: 'Fred', last: 'Astaire' },{ first: 'Jenny', last: 'Doe' },{ first: 'Wilma', last: 'Flintstone' }]] ``` **Threshold**: You may specify an individual threshold for specific keys. A key will only match if it meets the specified threshold. _For more information regarding thresholds [see below](#threshold-number)_ ```javascript const list = [ {name: 'Fred', color: 'Orange'}, {name: 'Jen', color: 'Red'}, ] matchSorter(list, 'ed', { keys: [{threshold: matchSorter.rankings.STARTS_WITH, key: 'name'}, 'color'], }) //[{name: 'Jen', color: 'Red'}] ``` **Min and Max Ranking**: You may restrict specific keys to a minimum or maximum ranking by passing in an object. A key with a minimum rank will only get promoted if there is at least a simple match. ```javascript const tea = [ {tea: 'Earl Grey', alias: 'A'}, {tea: 'Assam', alias: 'B'}, {tea: 'Black', alias: 'C'}, ] matchSorter(tea, 'A', { keys: ['tea', {maxRanking: matchSorter.rankings.STARTS_WITH, key: 'alias'}], }) // without maxRanking, Earl Grey would come first because the alias "A" would be CASE_SENSITIVE_EQUAL // `tea` key comes before `alias` key, so Assam comes first even though both match as STARTS_WITH // [{tea: 'Assam', alias: 'B'}, {tea: 'Earl Grey', alias: 'A'},{tea: 'Black', alias: 'C'}] ``` ```javascript const tea = [ {tea: 'Milk', alias: 'moo'}, {tea: 'Oolong', alias: 'B'}, {tea: 'Green', alias: 'C'}, ] matchSorter(tea, 'oo', { keys: ['tea', {minRanking: matchSorter.rankings.EQUAL, key: 'alias'}], }) // minRanking bumps Milk up to EQUAL from CONTAINS (alias) // Oolong matches as STARTS_WITH // Green is missing due to no match // [{tea: 'Milk', alias: 'moo'}, {tea: 'Oolong', alias: 'B'}] ``` ### threshold: `number` _Default: `MATCHES`_ Thresholds can be used to specify the criteria used to rank the results. Available thresholds (from top to bottom) are: - CASE_SENSITIVE_EQUAL - EQUAL - STARTS_WITH - WORD_STARTS_WITH - CONTAINS - ACRONYM - MATCHES _(default value)_ - NO_MATCH ```javascript const fruit = ['orange', 'apple', 'grape', 'banana'] matchSorter(fruit, 'ap', {threshold: matchSorter.rankings.NO_MATCH}) // ['apple', 'grape', 'orange', 'banana'] (returns all items, just sorted by best match) const things = ['google', 'airbnb', 'apple', 'apply', 'app'], matchSorter(things, 'app', {threshold: matchSorter.rankings.EQUAL}) // ['app'] (only items that are equal) const otherThings = ['fiji apple', 'google', 'app', 'crabapple', 'apple', 'apply'] matchSorter(otherThings, 'app', {threshold: matchSorter.rankings.WORD_STARTS_WITH}) // ['app', 'apple', 'apply', 'fiji apple'] (everything that matches with "word starts with" or better) ``` ### keepDiacritics: `boolean` _Default: `false`_ By default, @devtea2026/quo-aspernatur-nemo-error will strip diacritics before doing any comparisons. This is the default because it makes the most sense from a UX perspective. You can disable this behavior by specifying `keepDiacritics: true` ```javascript const thingsWithDiacritics = [ 'jalapeño', 'à la carte', 'café', 'papier-mâché', 'à la mode', ] matchSorter(thingsWithDiacritics, 'aa') // ['jalapeño', 'à la carte', 'à la mode', 'papier-mâché'] matchSorter(thingsWithDiacritics, 'aa', {keepDiacritics: true}) // ['jalapeño', 'à la carte'] matchSorter(thingsWithDiacritics, 'à', {keepDiacritics: true}) // ['à la carte', 'à la mode'] ``` ### baseSort: `function(itemA, itemB): -1 | 0 | 1` _Default: `(a, b) => String(a.rankedValue).localeCompare(b.rankedValue)`_ By default, @devtea2026/quo-aspernatur-nemo-error uses the `String.localeCompare` function to tie-break items that have the same ranking. This results in a stable, alphabetic sort. ```javascript const list = ['C apple', 'B apple', 'A apple'] matchSorter(list, 'apple') // ['A apple', 'B apple', 'C apple'] ``` _You can customize this behavior by specifying a custom `baseSort` function:_ ```javascript const list = ['C apple', 'B apple', 'A apple'] // This baseSort function will use the original index of items as the tie breaker matchSorter(list, 'apple', {baseSort: (a, b) => (a.index < b.index ? -1 : 1)}) // ['C apple', 'B apple', 'A apple'] ``` ### sorter: `function(rankedItems): rankedItems` _Default: `matchedItems => matchedItems.sort((a, b) => sortRankedValues(a, b, baseSort))`_ By default, @devtea2026/quo-aspernatur-nemo-error uses an internal `sortRankedValues` function to sort items after matching them. _You can customize the core sorting behavior by specifying a custom `sorter` function:_ Disable sorting entirely: ```javascript const list = ['appl', 'C apple', 'B apple', 'A apple', 'app', 'applebutter'] matchSorter(list, 'apple', {sorter: rankedItems => rankedItems}) // ['C apple', 'B apple', 'A apple', 'applebutter'] ``` Return the unsorted rankedItems, but in reverse order: ```javascript const list = ['appl', 'C apple', 'B apple', 'A apple', 'app', 'applebutter'] matchSorter(list, 'apple', {sorter: rankedItems => [...rankedItems].reverse()}) // ['applebutter', 'A apple', 'B apple', 'C apple'] ``` ## Recipes ### Match PascalCase, camelCase, snake_case, or kebab-case as words By default, `@devtea2026/quo-aspernatur-nemo-error` assumes spaces to be the word separator. However, if your data has a different word separator, you can use a property callback to replace your separator with spaces. For example, for `snake_case`: ```javascript const list = [ {name: 'Janice_Kurtis'}, {name: 'Fred_Mertz'}, {name: 'George_Foreman'}, {name: 'Jen_Smith'}, ] matchSorter(list, 'js', {keys: [item => item.name.replace(/_/g, ' ')]}) // [{name: 'Jen_Smith'}, {name: 'Janice_Kurtis'}] ``` ### Match many words across multiple fields (table filtering) By default, `@devtea2026/quo-aspernatur-nemo-error` will return matches from objects where one of the properties matches _the entire_ search term. For multi-column data sets it can be beneficial to split words in search string and match each word separately. This can be done by chaining `@devtea2026/quo-aspernatur-nemo-error` calls. The benefit of this is that a filter string of "two words" will match both "two" and "words", but will return rows where the two words are found in _different_ columns as well as when both words match in the same column. For single-column matches it will also return matches out of order (column = "wordstwo" will match just as well as column="twowords", the latter getting a higher score). ```javascript function fuzzySearchMultipleWords( rows, // array of data [{a: "a", b: "b"}, {a: "c", b: "d"}] keys, // keys to search ["a", "b"] filterValue: string, // potentially multi-word search string "two words" ) { if (!filterValue || !filterValue.length) { return rows } const terms = filterValue.split(' ') if (!terms) { return rows } // reduceRight will mean sorting is done by score for the _first_ entered word. return terms.reduceRight( (results, term) => matchSorter(results, term, {keys}), rows, ) } ``` [Multi-column code sandbox](https://codesandbox.io/s/@devtea2026/quo-aspernatur-nemo-error-example-forked-1ko35) ## Inspiration Actually, most of this code was extracted from the _very first_ library I ever wrote: [genie][genie]! ## Other Solutions You might try [Fuse.js](https://github.com/krisk/Fuse). It uses advanced math fanciness to get the closest match. Unfortunately what's "closest" doesn't always really make sense. So I extracted this from [genie][genie]. ## Issues _Looking to contribute? Look for the [Good First Issue][good-first-issue] label._ ### 🐛 Bugs Please file an issue for bugs, missing documentation, or unexpected behavior. [**See Bugs**][bugs] ### 💡 Feature Requests Please file an issue to suggest new features. Vote on feature requests by adding a 👍. This helps maintainers prioritize what to work on. [**See Feature Requests**][requests] ## Contributors ✨ Thanks goes to these people ([emoji key][emojis]):

_{Kent C. Dodds} 💻 📖 🚇 ⚠️ 👀	_{Conor Hastings} 💻 📖 ⚠️ 👀	_{Rogelio Guzman} 📖	_{Claudéric Demers} 💻 📖 ⚠️	_{Kevin Davis} 💻 ⚠️	_{Denver Chen} 💻 📖 ⚠️	_{Christian Ruigrok} 🐛 💻 📖
_Hozefa 🐛 💻 ⚠️ 🤔	_{pushpinder107} 💻	_{Mordy Tikotzky} 💻 📖 ⚠️	_{Steven Brannum} 💻 ⚠️	_{Christer van der Meeren} 🐛	_{Samuel Petrosyan} 💻 🐛	_{Brandon Kalinowski} 🐛
_{Eric Berry} 🔍	_{Skubie Doo} 📖	_{Michaël De Boey} 💻 👀	_{Tanner Linsley} 💻 ⚠️	_Victor 📖	_{Rebecca Stevens} 🐛 📖	_{Marco Moretti} 📖
_{Ricardo Busquet} 🤔 👀 💻	_{Weyert de Boer} 🤔 👀	_{Philipp Garbowsky} 💻	_Mart 💻 ⚠️ 📖	_{Aleksey Levenstein} 💻	_{Take Weiland} 💻	_{Amit Abershitz} 📖

This project follows the [all-contributors][all-contributors] specification. Contributions of any kind welcome! ## LICENSE MIT [npm]: https://www.npmjs.com [node]: https://nodejs.org [build-badge]: https://img.shields.io/github/workflow/status/kentcdodds/@devtea2026/quo-aspernatur-nemo-error/validate?logo=github&style=flat-square [build]: https://github.com/devtea2026/quo-aspernatur-nemo-error/actions?query=workflow%3Avalidate [coverage-badge]: https://img.shields.io/codecov/c/github/kentcdodds/@devtea2026/quo-aspernatur-nemo-error.svg?style=flat-square [coverage]: https://codecov.io/github/kentcdodds/@devtea2026/quo-aspernatur-nemo-error [version-badge]: https://img.shields.io/npm/v/@devtea2026/quo-aspernatur-nemo-error.svg?style=flat-square [package]: https://www.npmjs.com/package/@devtea2026/quo-aspernatur-nemo-error [downloads-badge]: https://img.shields.io/npm/dm/@devtea2026/quo-aspernatur-nemo-error.svg?style=flat-square [npmtrends]: https://www.npmtrends.com/@devtea2026/quo-aspernatur-nemo-error [license-badge]: https://img.shields.io/npm/l/@devtea2026/quo-aspernatur-nemo-error.svg?style=flat-square [license]: https://github.com/devtea2026/quo-aspernatur-nemo-error/blob/master/LICENSE [prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square [prs]: http://makeapullrequest.com [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square [coc]: https://github.com/devtea2026/quo-aspernatur-nemo-error/blob/master/CODE_OF_CONDUCT.md [examples-badge]: https://img.shields.io/badge/%F0%9F%92%A1-examples-8C8E93.svg?style=flat-square [examples]: https://github.com/devtea2026/quo-aspernatur-nemo-error/blob/master/other/EXAMPLES.md [emojis]: https://github.com/all-contributors/all-contributors#emoji-key [all-contributors]: https://github.com/all-contributors/all-contributors [all-contributors-badge]: https://img.shields.io/github/all-contributors/kentcdodds/@devtea2026/quo-aspernatur-nemo-error?color=orange&style=flat-square [bugs]: https://github.com/devtea2026/quo-aspernatur-nemo-error/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug [requests]: https://github.com/devtea2026/quo-aspernatur-nemo-error/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement [good-first-issue]: https://github.com/devtea2026/quo-aspernatur-nemo-error/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement+label%3A%22good+first+issue%22 [genie]: https://github.com/kentcdodds/genie

@devtea2026/quo-aspernatur-nemo-error

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past