1 | # [fuzzysort](https://raw.github.com/farzher/fuzzysort/master/fuzzysort.js)
|
2 |
|
3 | Fast SublimeText-like fuzzy search for JavaScript.
|
4 |
|
5 | Sublime's fuzzy search is... sublime. I wish everything used it. So here's an open source js version.
|
6 |
|
7 |
|
8 |
|
9 | ## [Demo](https://rawgit.com/farzher/fuzzysort/master/test.html)
|
10 |
|
11 | https://rawgit.com/farzher/fuzzysort/master/test.html
|
12 |
|
13 | ![](http://i.imgur.com/1M6ZrgS.gif)
|
14 |
|
15 |
|
16 | ![](http://i.imgur.com/kdZxnJ0.png)
|
17 |
|
18 | ![](http://i.imgur.com/4kKfMK4.png)
|
19 |
|
20 | ![](http://i.imgur.com/K8KMgcn.png)
|
21 |
|
22 | ![](http://i.imgur.com/PFIp7WR.png)
|
23 |
|
24 |
|
25 |
|
26 | ## Installation Node
|
27 |
|
28 | ```sh
|
29 | npm i fuzzysort
|
30 | node
|
31 | > require('fuzzysort').single('t', 'test')
|
32 | { score: -3, indexes: [0], target: 'test' }
|
33 | ```
|
34 |
|
35 |
|
36 | ## Installation Browser
|
37 |
|
38 | ```html
|
39 | <script src="https://rawgit.com/farzher/fuzzysort/master/fuzzysort.js"></script>
|
40 | <script> console.log(fuzzysort.single('t', 'test')) </script>
|
41 | ```
|
42 |
|
43 |
|
44 |
|
45 |
|
46 | ## Usage
|
47 |
|
48 | ### `fuzzysort.single(search, target)`
|
49 |
|
50 | ```js
|
51 | var result = fuzzysort.single('query', 'some string that contains my query.')
|
52 | result.score // -59
|
53 | result.indexes // [29, 30, 31, 32, 33]
|
54 | result.target // some string that contains my query.
|
55 | fuzzysort.highlight(result, '<b>', '</b>') // some string that contains my <b>query</b>.
|
56 |
|
57 | fuzzysort.single('query', 'irrelevant string') // null
|
58 |
|
59 | // exact match returns a score of 0. lower is worse
|
60 | fuzzysort.single('query', 'query').score // 0
|
61 | ```
|
62 |
|
63 |
|
64 | ### `fuzzysort.go(search, targets, options=null)`
|
65 |
|
66 | ```js
|
67 | fuzzysort.go('mr', ['Monitor.cpp', 'MeshRenderer.cpp'])
|
68 | // [{score: -18, target: "MeshRenderer.cpp"}, {score: -6009, target: "Monitor.cpp"}]
|
69 |
|
70 | // When using `key`, the results will have an extra property, `obj`, which referencese the original obj
|
71 | fuzzysort.go('mr', [{file:'Monitor.cpp'}, {file:'MeshRenderer.cpp'}], {key: 'file'})
|
72 | // [{score: -18, target: "MeshRenderer.cpp", obj}, {score: -6009, target: "Monitor.cpp", obj}]
|
73 | ```
|
74 |
|
75 | ### `fuzzysort.goAsync(search, targets, options=null)`
|
76 |
|
77 | ```js
|
78 | let promise = fuzzysort.goAsync('mr', ['Monitor.cpp', 'MeshRenderer.cpp'])
|
79 | promise.then(results => console.log(results))
|
80 | if(invalidated) promise.cancel()
|
81 | ```
|
82 |
|
83 | ##### Options
|
84 |
|
85 | ```js
|
86 | fuzzysort.go(search, targets, {
|
87 | threshold: -Infinity, // Don't return matches worse than this (faster)
|
88 | limit: Infinity, // Don't return more results than this (faster)
|
89 |
|
90 | key: null, // For when targets are objects (see its example usage)
|
91 | keys: null, // For when targets are objects (see its example usage)
|
92 | scoreFn: null, // For use with `keys` (see its example usage)
|
93 | })
|
94 | ```
|
95 |
|
96 | #### `fuzzysort.highlight(result, highlightOpen='<b>', highlightClose='</b>')`
|
97 |
|
98 | ```js
|
99 | fuzzysort.highlight(fuzzysort.single('tt', 'test'), '*', '*') // *t*es*t*
|
100 | ```
|
101 |
|
102 |
|
103 |
|
104 | ## How To Go Fast
|
105 |
|
106 | You can help the algorithm go fast by providing prepared targets instead of raw strings. Preparing strings is slow, do this ahead of time and only prepare each target once.
|
107 |
|
108 | ```js
|
109 | myObj.titlePrepared = fuzzysort.prepare(myObj.title)
|
110 | fuzzysort.single('gotta', myObj.titlePrepared)
|
111 | fuzzysort.single('go', myObj.titlePrepared)
|
112 | fuzzysort.single('fast', myObj.titlePrepared)
|
113 | ```
|
114 |
|
115 |
|
116 | ### Advanced Usage
|
117 |
|
118 | Search a list of objects, by multiple fields, with custom weights.
|
119 |
|
120 | ```js
|
121 | let objects = [{title:'Favorite Color', desc:'Chrome'}, {title:'Google Chrome', desc:'Launch Chrome'}]
|
122 | let results = fuzzysort.go('chr', objects, {
|
123 | keys: ['title', 'desc'],
|
124 | // Create a custom combined score to sort by. -100 to the desc score makes it a worse match
|
125 | scoreFn(a) => Math.max(a[0]?a[0].score:-1000, a[1]?a[1].score-100:-1000)
|
126 | })
|
127 |
|
128 | var bestResult = results[0]
|
129 | // When using multiple `keys`, results are different. They're indexable to get each normal result
|
130 | fuzzysort.highlight(bestResult[0]) // 'Google <b>Chr</b>ome'
|
131 | fuzzysort.highlight(bestResult[1]) // 'Launch <b>Chr</b>ome'
|
132 | bestResult.obj.title // 'Google Chrome'
|
133 | ```
|
134 |
|
135 | Multiple instances, each with different default options.
|
136 |
|
137 | ```js
|
138 | const strictsort = fuzzysort.new({threshold: -999})
|
139 | ```
|
140 |
|
141 |
|
142 | ### Changelog
|
143 |
|
144 | #### v1.0.0
|
145 |
|
146 | - Inverted scores; they're now negative instead of positive, so that higher scores are better
|
147 | - Added ability to search objects by `key`/`keys` with custom weights
|
148 | - Removed the option to automatically highlight and exposed `fuzzysort.highlight`
|
149 | - Removed all options from `fuzzysort` and moved them into `fuzzysort.go` optional params
|
150 |
|
151 | #### v0.x.x
|
152 |
|
153 | - init
|