Flourish search

Search for matching strings in arrays of data.

How to install

npm install -s @flourish/search

Then import it with:

import createSearch from "@flourish/search";

Usage

Create a new search function by calling createSearch with an array of items and an optional accessor function:

let search = createSearch(array, accessorFunction);

The accessorFunction instructs the createFunction on how to create a one-to-one mapping from each element of array to a string or array of strings that can be searched over. The default value of accessorFunction is x => x. (If the value returned when calling the accessorFunction is an array it will be sliced).

search(value)

Filter array based on whether it's accessor-mapped values match the search string. For the default accessor this just means return all values of array that match (see below) value.

Types of matching

Matching is, by default, case-insensitive but this can be changed throught the normalizer method. The match can be searched for "anywhere" (the default) in the mapped string, at the "start" of that string or it can be a "whole"-string match.

search.normalizer([value])

If value is undefined then this function returns the current normalizer function (by default x => x). Otherwise, the normalizer function is set to value. The normalizer function determines how mapped items and search terms should be manipulated before being compared. For example, you can do case-insensitive searching by passing in the function x => x.toLowercase.

When value is defined the search function is returned to allow for method chaining.

search.mode([value])

If value is undefined then this function returns a string describing the search mode being used. The three options are:

• "anywhere": search for the specified string anywhere in the mapped string;
• "start": search for the specified string at the start of the mapped string;
• "whole": search for the exact specified string (after case (in)sensitivity has been accounted for).

The default mode is "anywhere".

If value is defined and is one of these three specified strings then the mode is set to that value. If value is any other value (excluding undefined) then an error is thrown.

When value is defined the search function is returned to allow for method chaining.

search.arrayMode([value])

If value is undefined then this function returns a string describing the array mode being used. The two options are:

• "some": only one string in an array of mapped strings needs to match the search string for a match;
• "every": every string in an array of mapped strings needs to match the search string for a match;

The default mode is "some".

If value is defined and is one of the two specified strings then the mode is set to that value. If value is any other value (excluding undefined) then an error is thrown.

When value is defined the search function is returned to allow for method chaining.