https://github.com/louismazel/maz-smart-search
Smart-Search is a JavaScript library that perform fuzzy-search through a list of entries.
https://github.com/louismazel/maz-smart-search
Last synced: 6 months ago
JSON representation
Smart-Search is a JavaScript library that perform fuzzy-search through a list of entries.
- Host: GitHub
- URL: https://github.com/louismazel/maz-smart-search
- Owner: LouisMazel
- License: mit
- Created: 2019-12-20T12:39:26.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T02:21:55.000Z (over 3 years ago)
- Last Synced: 2025-05-31T13:13:14.170Z (about 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 326 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Smart-Search
> Smart-Search is a JavaScript library that perform fuzzy-search through a list of entries.
## Install
### Yarn
```bash
yarn add maz-smart-search
```
### Npm
```bash
npm install maz-smart-search --save
```
### CDN
```javascript
```
## Usage
```javascript
var results = smartSearch(entries, patterns, fields, options);
```
### Parameters
- **entries** `Array`
List of objects where the search will perform. ([see details](#entries))
- **patterns** `Array`
List of patterns that will be searched in the **_entries_**. ([see details](#patterns))
- **fields** `Array`
List of **_entries_**'s properties where all the **_patterns_** will be searched. ([see details](#fields))
- **options** `Object`
Optional properties. ([see details](#options))
### Return `Array`
The return is an array of objects containing the **_entries_** that have matched. ([see details](#Return))
## Example
```javascript
var entries = [
{ id:0, name:'Robin David', email:'robin.david@gmail.com' },
{ id:1, name:'Loris Francois', email:'loris.francois@gmail.com' },
{ id:2, name:'Armand Roy', email:'armand.roy@live.com' },
{ id:3, name:'Mathias Meunier', email:'mathias.meunier@gmail.com' },
{ id:4, name:'Ruben Bernard', email:'ruben.bernard@yahoo.com' },
];
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: 'loris.francois@gmail.com' }
{ id: 0, name: 'Robin David', email: 'robin.david@gmail.com' }
## Details
### Parameters
#### entries `Array`
List of objects where the search is performed.
> Example:
```javascript
var entries = [
{ id:0, name:'Robin David', email:'robin.david@gmail.com' },
{ id:1, name:'Loris Francois', email:'loris.francois@gmail.com' },
{ id:2, name:'Armand Roy', email:'armand.roy@live.com' },
{ id:3, name:'Mathias Meunier', email:'mathias.meunier@gmail.com' },
{ id:4, name:'Ruben Bernard', email:'ruben.bernard@yahoo.com' },
];
```
#### patterns `Array`
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`
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:
```javascript
var entries = [
{
id:0,
name:{ first:{ 'Robin' }, last:{ 'David' } },
email:'robin.david@gmail.com'
},
{...}
];
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:
```javascript
var options = {
maxInsertions: 3;
};
var results = smartSearch(entries, patterns, fields, options);
```
#### Return `Array`
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:
```javascript
[
{
entry:{id:1, name:'Loris Francois', email:'loris.francois@gmail.com'},
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:'robin.david@gmail.com'},
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](./LICENCE)