Awesome

js-worker-search

🎉 Become a sponsor or ☕ Buy me a coffee

Full text client-side search based on js-search but with added web-worker support for better performance.

Check out the redux-search for an example integration.

Or install it yourself with NPM:

npm install --save js-worker-search

SearchApi Documentation

Forked from JS search, this utility builds a search index and runs actual searches. It auto-detects the capabilities of the current environment (browser or Node) and uses a web-worker based implementation when possible. When no web-worker support is available searching is done on the main (UI) thread.

SearchApi defines the following public methods:

constructor ({ caseSensitive, indexMode, tokenizePattern })

By default, SearchApi builds an index to match all substrings. You can override this behavior by passing an named indexMode parameter. Valid values are INDEX_MODES.ALL_SUBSTRINGS, INDEX_MODES.EXACT_WORDS, and INDEX_MODES.PREFIXES.

Searches are case insensitive by default and split on all whitespace characters. Read below for more information on customizing default options.

indexDocument (uid, text)

Adds or updates a uid in the search index and associates it with the specified text. Note that at this time uids can only be added or updated in the index, not removed.

Parameters:

• uid: Uniquely identifies a searchable object
• text: Searchable text to associate with the uid

search(query)

Searches the current index for the specified query text. Only uids matching all of the words within the text will be accepted. If an empty query string is provided all indexed uids will be returned.

Document searches are case-insensitive (e.g. "search" will match "Search"). Document searches use substring matching (e.g. "na" and "me" will both match "name").

Parameters:

• query: Searchable query text

This method will return an array of uids.

terminate()

If search is running in a web worker, this will terminate the worker to allow for garbage collection.

Example Usage

Use the API like so:

import SearchApi from 'js-worker-search'

const searchApi = new SearchApi()

// Index as many objects as you want.
// Objects are identified by an id (the first parameter).
// Each Object can be indexed multiple times (once per string of related text).
searchApi.indexDocument('foo', 'Text describing an Object identified as "foo"')
searchApi.indexDocument('bar', 'Text describing an Object identified as "bar"')

// Search for matching documents using the `search` method.
// In this case the promise will be resolved with the Array ['foo', 'bar'].
// This is because the word "describing" appears in both indices.
const promise = searchApi.search('describing')

Custom index mode

By default, SearchApi builds an index to match all substrings. You can override this behavior by passing an indexMode parameter to the constructor like so:

import SearchApi, { INDEX_MODES } from 'js-worker-search'

// all-substrings match by default; same as current
// eg "c", "ca", "a", "at", "cat" match "cat"
const searchApi = new SearchApi()

// prefix matching (eg "c", "ca", "cat" match "cat")
const searchApi = new SearchApi({
  indexMode: INDEX_MODES.PREFIXES
})

// exact words matching (eg only "cat" matches "cat")
const searchApi = new SearchApi({
  indexMode: INDEX_MODES.EXACT_WORDS
})

Custom tokenizer patterns

By default, SearchApi breaks text into words (tokenizes) using spaces and newlines as the delimiting character. If you want to provide your own splitting rule, pass a RegExp to the constructor that defines the pattern , like so:

// Custom tokenizer pattern to include all non alphanumerics as delimeters
// ex: searching "Swift" matches "Thomas Swift" and "Thomas (Swift)" but not "swiftly tilting"
const searchApi = new SearchApi({
    indexMode: INDEX_MODES.EXACT_WORDS,
    tokenizePattern: /[^a-z0-9]+/,
})

Case-sensitive searches

The default sanitizer performs a case-insensitive search. If you want to override that behavior and do a case-sensitive search, set the caseSensitive bit to true, like so:

// custom sanitizer for case-sensitive searches
const searchApi = new SearchApi({
  caseSensitive: true
})

Partial matches

By default, the search utility only returns documents containing every search token. It can be configured to return documents containing any search token.

// Change search behavior from AND to OR
const searchApi = new SearchApi({
  matchAnyToken: true
})

Changelog

Changes are tracked in the changelog.

License

js-worker-search is available under the MIT License.