Node Pizza Maker

# npm

## match-sorter

3.1.1 • Public • Published

# match-sorter

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

Demo

## 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. CASE STARTS WITH: If the item has a defined case (`camelCase`, `PascalCase`, `snake_case` or `kebab-case`), then if one of the parts starts with the given value (ex. `kingdom` would match `unitedKingdom` or `united_kingdom`)
6. CASE ACRONYM If the item's case matches the synonym (ex. `uk` would match `united-kingdom` or `UnitedKingdom`)
7. CONTAINS: If the item contains the given value (ex. `ham` would match `Bahamas`)
8. ACRONYM: If the item's acronym is the given value (ex. `us` would match `United States`)
9. 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!

## Getting Started

### Installation

This module is distributed via npm which is bundled with node and should be installed as one of your project's `dependencies`:

``````npm install --save match-sorter
``````

### keys: `[string]`

Default: `undefined`

By default it just uses the value itself as above. Passing an array tells match-sorter which keys to use for the ranking.

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.

Nested Keys: You can specify nested keys using dot-notation.

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

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

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.

### 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
• STRING_CASE
• STRING_CASE_ACRONYM
• CONTAINS
• ACRONYM
• MATCHES (default value)
• NO_MATCH

### keepDiacritics: `boolean`

Default: `false`

By default, match-sorter 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`

## Using ES6?

In the examples above, we're using CommonJS. If you're using ES6 modules, then you can do:

`import matchSorter, {rankings, caseRankings} from 'match-sorter'`

## Inspiration

Actually, most of this code was extracted from the very first library I ever wrote: genie!

## Other Solutions

You might try Fuse.js. 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.

## Contributors

Thanks goes to these people (emoji key):

 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💻 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

MIT

## Keywords

### Install

`npm i [email protected]`

3.1.1

MIT

186 kB

18