maz-smart-search

Smart-Search

Smart-Search is a JavaScript library that perform fuzzy-search through a list of entries.

Install

Yarn

yarn add maz-smart-search

Npm

npm install maz-smart-search --save

CDN

<script src="https://unpkg.com/vue-mazel-ui/dist/smart-search.js"></script>

Usage

var results = smartSearch(entries, patterns, fields, options);

Parameters

• entries Array<Object>

  List of objects where the search will perform. (see details)

• patterns Array<String>

  List of patterns that will be searched in the entries. (see details)

• fields Array<String>

  List of entries's properties where all the patterns will be searched. (see details)

• options Object

  Optional properties. (see details)

Return Array<Object>

The return is an array of objects containing the entries that have matched. (see details)

Example

var entries = [
  { id:0, name:'Robin David',     email:'[e-mail]' },
  { id:1, name:'Loris Francois',  email:'[e-mail]' },
  { id:2, name:'Armand Roy',      email:'[e-mail]' },
  { id:3, name:'Mathias Meunier', email:'[e-mail]' },
  { id:4, name:'Ruben Bernard',   email:'[e-mail]' },
];
 
var patterns = ['gmail', 'oi'];
var fields = { name: true, email: true };
 
var results = smartSearch(entries, patterns, fields);
 
results.forEach( function (result) {
  console.log(result.entry);
});

will display :

  { id: 1, name: 'Loris Francois', email: '[e-mail]' }
  { id: 0, name: 'Robin David', email: '[e-mail]' }

Details

Parameters

entries Array<Object>

List of objects where the search is performed.

Example:

var entries = [
  { id:0, name:'Robin David',     email:'[e-mail]' },
  { id:1, name:'Loris Francois',  email:'[e-mail]' },
  { id:2, name:'Armand Roy',      email:'[e-mail]' },
  { id:3, name:'Mathias Meunier', email:'[e-mail]' },
  { id:4, name:'Ruben Bernard',   email:'[e-mail]' },
];

patterns Array<String>

List of patterns that are searched in the entries.

Each pattern is searched accross the specified properties (fields) of every entry.

A pattern match a string if all the letters that it is constituted appears, in the same order, in the string. The relevance of the matching is computed from the minimum number of letters that have be inserted into the pattern in such a way it matches the string.

Example:

  the pattern 'oi'
    - match with 0 insertions in 'Loris Francois'
    - match with 1 insertions in 'Robin David'

The optional parameter 'maxInsertions' limit the number of insertions authorised.

fields Array<String>

List of objects's properties where the patterns are searched.

The property's value should be a String. If not, the property is ignored.

Nested properties could be specified with a dot character.

Example:

var entries = [
  {
    id:0,
    name:{ first:{ 'Robin' }, last:{ 'David' } },
    email:'[e-mail]'
  },
  {...}
];
var results = smartSearch(entries, patterns, { name: { last: true }, email: true });

options Object

An optional fourth parameter allow user to customize search behavior.

The options available are :

• caseSensitive Boolean (default:false)

  Indicates whether matching should be case sensitive.

• fieldMatching Boolean (default:false)

  By default an entry match if all patterns match through the entire entry.

  With fieldMatching = true, an entry match if all patterns match in at least one field.

• maxInsertions Integer (default:-1)

Indicate the maximum of insertions authorisedduring pattern matching.

maxInsertions = -1 means no limit.

Example:

var options = {
  maxInsertions: 3;
};
var results = smartSearch(entries, patterns, fields, options);

Return Array<Object>

The return value is an array of objects containing the entries that have matched all the patterns.

The properties of each returned object are the following:

• entry : original entry from the entries array.
• info : informations about the matching.
• score : relevance score.

Example:

[
  {
    entry:{id:1, name:'Loris Francois', email:'[e-mail]'},
    info:[
    {
      field:'name',
      patterns:[
      {value:'oi', insertions:0, matchIndexes:[11,12]},
      ]
    },
    {
      field:'email',
      patterns:[
      {value:'gmail', insertions:0, matchIndexes:[15,16,17,18,19]},
      {value:'oi', insertions:0, matchIndexes:[11,12]},
      ]
    },
    ],
    score:0.011
  },
  {
    entry:{id:0, name:'Robin David', email:'[e-mail]'},
    info:[
    {
      field:'name',
      patterns:[
      {value:'oi', insertions:1, matchIndexes:[1,3]},
      ]
    },
    {
      field:'email',
      patterns:[
      {value:'gmail', insertions:0, matchIndexes:[12,13,14,15,16]},
      {value:'oi', insertions:1, matchIndexes:[1,3]},
      ]
    },
    ],
    score:1.001
  }
]

---

License

MIT