subsequence-search

Search for a given subsequence in a list of strings and transform the resulting list as required.

It behaves a lot like the sublime text fuzzy search.

The resulting list can be transformed using chainable transforms.

Demo it here.

###Installation

npm install subsequence-search --save

###Usage

#####Node

Go ahead and require('subsequence-search) in node after installation.

#####Browser

After installation, serve:

• subsequence-search.js or
• subsequence-search.min.js

out of node_modules/subsequence-search/build/

In your browser code, go ahead and require('subsequence-search) to use it.

###API

####search(dataList, searchString, transforms)

• dataList is an array of strings that you want to match against
• searchString is the string you want to match against the dataList
• transforms is an object containing transform functions (transforms are explained later)
  • transform functions are applied in order to the data list got after matching searchString and dataList.

E.g.,

var subsearch = require('subsequence-search');
var data = ['there is some fog', 'have an apple', 'omg! potato?', 'foxes are kinda cool!'];
console.log(subsearch.search(data, 'fo', {
  rank: subsearch.transforms.rank,
  highlight: subsearch.transforms.highlight('highlightClass')
}));
//output
//["<span class="highlightClass">f</span><span class="highlightClass">o</span>xes are kinda cool!", "there is some <span class="highlightClass">f</span><span class="highlightClass">o</span>g"]

####transforms

The transforms object can hold multiple transform functions.

A transform is a function that accepts an Array and returns a transformed Array.

The Array received by a transform function is of the form of an Array returned by String.prototype.match.

For example:

var subsearch = require('subsequence-search');
//lets say you have the following data
var data = ['there is some fog', 'have an apple', 'omg! potato?', 'foxes are kinda cool!'];
//and you do
subsearch.search(data, 'fo', {
  myTransform: function(list){
    console.log(list);
    return list;
  }
});
//then you get an array containing to arrays printed in your console
//see the image below

As you can see in the image, each item is the same as what you get when you do

'some string'.match(/^(s)(.*?)(e)(.*)$/);

i.e., a String.prototype.match with some capturing groups.

You can chain as many transform functions as you want by passing them in the transforms object to the search call.

The only thing to keep in mind is that they are applied in order.

Keeping that in mind, you can do what you wish in those transform functions to get the data in a format that is useful for your application.

subsequence-search ships with three transform functions for your convenience. They are:

• rank : returns a re-ordered Array that has the most relevant results higher in the list
• highlight: accepts a css class and transforms the result set to encapsulate the matching letters in a span with the given css class
  • it returns an array of strings
• noHighlight: returns back an array of plaintext matches

These are available on the transforms property on the object you get when you do require('subsequence-search') i.e.,

var subsearch = require('subsequence-search');
//built in transforms:
//subsearch.transforms.rank
//subsearch.transforms.highlight(classname)
//subsearch.transforms.noHighlight
var data = ['there is some fog', 'have an apple', 'omg! potato?', 'foxes are kinda cool!'];
console.log(subsearch.search(data, 'fo', {
  rank: subsearch.transforms.rank,
  highlight: subsearch.transforms.highlight('highlightClass')
}));
//output
//["<span class="highlightClass">f</span><span class="highlightClass">o</span>xes are kinda cool!", "there is some <span class="highlightClass">f</span><span class="highlightClass">o</span>g"]

###Compatibility subsequence-search is compatible with browsers that are ES5 compliant.

It uses map, reduce, filter, etc heavily so if you need to use subsequence-search on older browsers, use a shim.

###Changelog

• 0.1.4
  • Subsequence is now searched for, non-greedily from the beginning of input string
• 0.1.3
  • Change the order in which inputs are validated in index.js
  • Added some more comments
• 0.1.2
  • Fixed package.json (missing git repo)
• 0.1.1
  • Fixed documentation (added demo)
• 0.1.0
  • added chainable transforms
  • added test suite