Class: QuickScore

QuickScore(itemsopt, optionsopt)

A class for scoring and sorting a list of items against a query string. Each item receives a floating point score between 0 and 1.

Constructor

new QuickScore(itemsopt, optionsopt)

Parameters:
Name Type Attributes Description
items Array.<(string|object)> <optional>

The list of items to score. If the list is not a flat array of strings, a keys array must be supplied via the second parameter. QuickScore makes a shallow copy of the items array, so changes to it won't have any affect, but changes to the objects referenced by the array need to be passed to the instance by a call to its setItems() method.
options Array.<ItemKey> | Options <optional>

If the items parameter is an array of flat strings, the options parameter can be left out. If it is a list of objects containing keys that should be scored, the options parameter must either be an array of key names or an object containing a keys property.

Properties
Name Type Attributes Default Description
keys Array.<ItemKey> <optional>

In the simplest case, an array of key names to score on the objects in the items array.

The key names can point to a nested key by passing either a dot-delimited string or an array of sub-keys that specify the path to the value. So a key name of "foo.bar" would evaluate to "baz" given an object like { foo: { bar: "baz" } }. Alternatively, that path could be passed as an array, like ["foo", "bar"]. In either case, if this sub-key's match produces the highest score for an item in the search results, its scoreKey name will be "foo.bar".

If your items have keys that contain periods, e.g., "first.name", but you don't want these names to be treated as paths to nested keys, simply wrap the name in an array, like { keys: ["ssn", ["first.name"], ["last.name"]] }.

Instead of a string or string array, an item in keys can also be passed as a {name, scorer} object, which lets you specify a different scoring function for each key. The scoring function should behave as described next.
sortKey string <optional>
 options.keys[0]

An optional key name that will be used to sort items with identical scores. Defaults to the name of the first item in the keys parameter. If sortKey points to a nested key, use a dot-delimited string instead of an array to specify the path.
minimumScore number <optional>
 0

An optional value that specifies the minimum score an item must have to appear in the results returned from search(). Defaults to 0, so items that don't match the full query will not be returned. This value is ignored if the query is empty or undefined, in which case all items are returned, sorted alphabetically and case-insensitively on the sortKey, if any.
transformString TransformStringFunction <optional>

An optional function that takes a string parameter and returns a transformed version of that string. This function will be called on each of the searchable keys in the items array as well as on the query parameter to the search() method. The default function calls toLocaleLowerCase() on each string, for a case-insensitive search. The result of this function is cached for each searchable key on each item.

You can pass a function here to do other kinds of preprocessing, such as removing diacritics from all the strings or converting Chinese characters to pinyin. For example, you could use the latinize npm package to convert characters with diacritics to the base character so that your users can type an unaccented character in the query while still matching items that have accents or diacritics. Pass in an options object like this to use a custom transformString() function: { transformString: s => latinize(s.toLocaleLowerCase()) }
scorer ScorerFunction <optional>

An optional function that takes string and query parameters and returns a floating point number between 0 and 1 that represents how well the query matches the string. It defaults to the quickScore() function in this library.

If the function gets a third matches parameter, it should fill the passed-in array with indexes corresponding to where the query matches the string, as described in the search() method.
config Config <optional>

An optional object that is passed to the scorer function to further customize its behavior. If the scorer function has a createConfig() method on it, the QuickScore instance will call that with the config value and store the result. This can be used to extend the config parameter with default values.
Source:

Classes

QuickScore

Members

(readonly) items :Array.<object>

The array of items to search, which should only be modified via the setItems() method.

Type:
  • Array.<object>
Source:

(readonly) keys :Array.<ItemKey>

The keys to search on each item, which should only be modified via the setItems() method.

Type:
Source:

Methods

Scores the instance's items against the query and sorts them from highest to lowest.

Parameters:
Name Type Description
query string

The string to score each item against. The instance's transformString() function is called on this string before it's matched against each item.
Source:
Returns:

When the instance's items are flat strings, an array of ScoredString objects containing the following properties is returned:

  • item: the string that was scored
  • score: the floating point score of the string for the current query
  • matches: an array of arrays that specify the character ranges where the query matched the string

When the items are objects, an array of ScoredObject results is returned:

  • item: the object that was scored
  • score: the highest score from among the individual key scores
  • scoreKey: the name of the key with the highest score, which will be an empty string if they're all zero
  • scoreValue: the value of the key with the highest score, which makes it easier to access if it's a nested string
  • scores: a hash of the individual scores for each key
  • matches: a hash of arrays that specify the character ranges of the query match for each key

The results array is sorted high to low on each item's score. Items with identical scores are sorted alphabetically and case-insensitively on the sortKey option. Items with scores that are <= the minimumScore option (defaults to 0) are not returned, unless the query is falsy, in which case all of the items are returned, sorted alphabetically.

The start and end indices in each RangeTuple in the matches array can be used as parameters to the substring() method to extract the characters from each string that match the query. This can then be used to format the matching characters with a different color or style.

Each ScoredObject item also has a _ property, which caches transformed versions of the item's strings, and might contain additional internal metadata in the future. It can be ignored.

Type
Array.<(ScoredString|ScoredObject)>

setItems(items)

Sets the items array and caches a transformed copy of all the item strings specified by the keys parameter to the constructor, using the transformString option (which defaults to toLocaleLowerCase()).

Parameters:
Name Type Description
items Array.<(string|object)>

List of items to score.
Source:

setKeys(keys, sortKeyopt)

Sets the keys configuration. setItems() must be called after changing the keys so that the items' transformed strings get cached.

Parameters:
Name Type Attributes Default Description
keys Array.<ItemKey>

List of keys to score, as either strings or {name, scorer} objects.
sortKey string <optional>
 keys[0]

Name of key on which to sort identically scored items. Defaults to the first keys item.
Source: