Package Exports

sifter

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (sifter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

sifter.js

Sifter is a CommonJS library for textually searching arrays and hashes of objects by property (or multiple properties). It's designed specifically for autocomplete. The process is three-step: score, filter, sort.

Supports díåcritîçs.
For example, if searching for "montana" and an item in the set has a value of "montaña", it will still be matched.
Smart sorting.
Items are scored intelligently depending on where a match is found in the string (how close to the beginning) and what percentage of the string matches.

Installation

$ npm install sifter # node.js
$ bower install sifter # browser

Usage

var sifter = new Sifter([
    {title: 'Annapurna I', location: 'Nepal', continent: 'Asia'},
    {title: 'Annapurna II', location: 'Nepal', continent: 'Asia'},
    {title: 'Annapurna III', location: 'Nepal', continent: 'Asia'},
    {title: 'Eiger', location: 'Switzerland', continent: 'Europe'},
    {title: 'Everest', location: 'Nepal', continent: 'Asia'},
    {title: 'Gannett', location: 'Wyoming', continent: 'North America'},
    {title: 'Denali', location: 'Alaska', continent: 'North America'}
]);

var result = sifter.search('anna', {
    fields: ['title', 'location', 'continent'],
    sort: 'title',
    direction: 'desc',
    limit: 3
});

Seaching will provide back meta information and an "items" array that contains objects with the index (or key, if searching a hash) and a score that represents how good of a match the item was. Items that did not match will not be returned.

{"score": 0.2878787878787879, "id": 0},
{"score": 0.27777777777777773, "id": 1},
{"score": 0.2692307692307692, "id": 2}

The sorting options are only acknowledged when searching by an empty string. Otherwise, sorting will always be by best-match. The full result comes back in the format of:

{
    "options": {
        "fields": ["title", "location", "continent"],
        "sort": "title",
        "direction": "desc",
        "limit": 3
    },
    "query": "anna",
    "tokens": [{
        "string": "anna",
        "regex": /[aÀÁÂÃÄÅàáâãäå][nÑñ][nÑñ][aÀÁÂÃÄÅàáâãäå]/
    }],
    "total": 3,
    "items": [
        {"score": 0.2878787878787879, "id": 0},
        {"score": 0.27777777777777773, "id": 1},
        {"score": 0.2692307692307692,"id": 2}
    ]
}

API

search(query, options)

Option	Type	Description
"fields"	array	An array of property names to be searched.
"limit"	integer	The maximum number of results to return.
"sort"	string	The name of the property to sort by if no query is given.
"direction"	string	The order in which to sort results ("asc" or "desc").

Contributing

The following dependencies are required to build and test:

$ npm install -g mocha
$ npm install -g uglify-js

First build a copy with make then run the test suite with make test.

When issuing a pull request, please exclude "sifter.js" and "sifter.min.js" in the project root.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.