suggester

Description:

suggester

An autocompetion engine for Dart.
Supports highly configurable partial matching.
Fast and memory efficient.
Suitable for both web and mobile devices.
Test It Live ! #
Play with a Live instance of Suggester.
Test different combinations of data and parameters tofind what suits your application.
Usage #
Import #
import 'package:suggester/suggester.dart';
copied to clipboard
Choose Term Mapping #
Suggester works by tokenising both suggestions and input using a Term Mapping and finding partial matches between them via prefix searching.
For example a TermMapping that groups inputs and suggestions into sequences of letters and numbers:
print(AlphaOrNumeric().map('[email protected]', false, false));
copied to clipboard
{armani, klein, 3, veda, io}
copied to clipboard
TermMapping that groups inputs and suggestions into NGrams of size 3, i.e. Trigrams.
print(Ngrams(3).map('[email protected]', false, false));
copied to clipboard
{arm, rma, man, ani, ni., i.k, .kl, kle, lei, ein, in3, n3@, 3@v, @ve, ved, eda, da., a.i, .io}
copied to clipboard
Construct Suggester and Load Entries #
A small list of entries. Suggester comfortably handles any number.
final entries = [
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]',
'[email protected]'
];
copied to clipboard
Construct 2 example Suggester objects, each using a different Term Mapping.
Load each with the above list of entries.
final suggesterAlphaOrNumeric = Suggester(AlphaOrNumeric())
..addAll(entries);

final suggesterTrigram = Suggester(Ngrams(3))..addAll(entries);

copied to clipboard
Suggest! #
Find all suggestions featuring search term 'wen', note the difference between TermMappings.
print(suggesterAlphaOrNumeric.suggest('wen').map((e) => e.entry.value));

copied to clipboard
([email protected])

copied to clipboard
print(suggesterTrigram.suggest('wen').map((e) => e.entry.value));
copied to clipboard
([email protected], [email protected], [email protected])

copied to clipboard
Mark Suggestion Search Terms #
User feedback is helped by marking a suggestion with the search terms.
Pass 2 custom functions to be applied to marked and unmarked terms.
Terms can be mapped to any type, here it is mapped to html tags but could as well return an iterable of UI elements.
print(suggesterTrigram.suggest('wen').map((e) => e
.mapTermsAndNonTerms((term) => '<mark>$term</mark>', (nonTerm) => nonTerm)
.join()));

copied to clipboard
(Ro<mark>wen</mark>[email protected], banjo.ber<mark>wen</mark>@newell.ca, Curtis_McGlynn@<mark>wen</mark>dell.me)

copied to clipboard
[email protected], [email protected], [email protected]
Expand Search With Edit Distance #
An edit distance may also be specified during search allowing terms to be matched using a Hamming edit distance. This extends the range of a TermMapping. Using the original AlphaOrNumeric example with a maxEditDistance of 1:
print(suggesterAlphaOrNumeric
.suggest('wen', maxEditDistance: 1)
.map((e) => e.entry.value));

copied to clipboard
([email protected], [email protected])
copied to clipboard
... and with a maxEditDistance of 2
for (final suggestion
in suggesterAlphaOrNumeric.suggest('wen', maxEditDistance: 2)) {
print(suggestion.entry.value);
}

copied to clipboard
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]

copied to clipboard
Accept Suggestions #
Once a selection is accepted this can be recorded via the accept method:
final result = suggesterAlphaOrNumeric.suggest('lu');

print(result.map((final suggestion) => suggestion.entry.value));

copied to clipboard
Note ordering of search suggestions.
([email protected], [email protected])

copied to clipboard
Accept last suggestion in ordering:
result.last.entry.accept();

print(result.map((final suggestion) => suggestion.entry.value));

copied to clipboard
Last suggestion now becomes first to reflect prior acceptance.
([email protected], [email protected])

copied to clipboard
By default when a suggestion is accepted it results in a subScore value incrementing but any int value may specified including a timestamp so that last used suggestions are always favoured. For example:
result.last.entry.accept(subScore: DateTime.now().millisecondsSinceEpoch);

print(result.first.entry);

copied to clipboard
{value: [email protected], subScore: 1609579026000}

copied to clipboard
Check Current Entries #
Iterate through all current entries
print(suggesterAlphaOrNumeric.entries);
copied to clipboard
Iterate all entries ordered by subScore.
Note that the last accepted entry is first with timestamp subScore.
print(suggesterAlphaOrNumeric.entriesBySubScore());
copied to clipboard
[{value: [email protected], subScore: 1609569378812},
{value: [email protected], subScore: 1},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
{value: [email protected], subScore: 0},
...]
copied to clipboard
Serialise #
Suggester is serialisable so suggestions and approval history are easily stored and reused.

final json = suggesterAlphaOrNumeric.toJson();

final rehydrated = Suggester.fromJson(AlphaOrNumeric(), json);

if (SuggesterEquality().equals(rehydrated, suggesterAlphaOrNumeric)) {
print('Rehydrated successfully!');
}

copied to clipboard
Rehydrated successfully!

copied to clipboard
Features and bugs #
Please file feature requests and bugs at the issue tracker.