Skip to content
MMMikeMPublic

About

Fast fuzzy matching. Zero dependencies, ~8.5 kB, tiers + ranges on every match.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Ekrina

Lazy where it counts.

npm license

CI Node 18+ Deno Bun

minzipped size coverage 100% OpenSSF Scorecard OpenSSF Best Practices

A fuzzy matcher usually hands back a number. Ranking on it is guesswork, highlighting means re-running the match yourself, and one transposed character makes the whole thing return nothing at all.

Ekrina tells you how every result matched: a tier such as prefix, fuzzy or corrected, the ranges to highlight in your own string, and a score you can filter on. It corrects up to two mistakes per query and says when it did, but only guesses when the query as typed comes up short, and it returns nothing for nonsense. It does only the work each query needs, has no dependencies, and runs on anything with ES2022.

To see it first, search the emoji on the docs site's home page, which runs this library in your browser.

npm install ekrina

From zero to a search

1. Build a searcher once, and call it with each query.

import { createSearcher } from "ekrina";

const commands = [
	{ id: "file.open", title: "Open File…" },
	{ id: "file.openRecent", title: "Open Recent" },
	{ id: "settings.open", title: "Preferences: Open User Settings" },
];

const search = createSearcher(commands, (command) => command.title);

2. Read how each result matched. Lower scores are better, and results come back best first.

search("settings");
// [{
//   item: { id: "settings.open", title: "Preferences: Open User Settings" },
//   score: 1,
//   tier: "boundary",
//   ranges: [[23, 30]],
//   text: "Preferences: Open User Settings",
// }]

ranges index text, the string your function returned, so highlighting is slicing it, escaped if it goes into HTML (highlighting).

3. Say when it corrected a typo.

const [top] = search("recnet");
// top: { item: { id: "file.openRecent", … }, score: 3.1, tier: "corrected", corrected: "recent", ranges: [[5, 10]], text: "Open Recent" }

if (top?.tier === "corrected") {
	showNotice(`Showing results for ${top.corrected}`);
}

A correction always comes after every match of the query as typed, and search("qxzwkv") returns [].

How it compares

Each library at its best-scoring configuration, on 10,000 real Wikidata names under their native spellings:

Library MRR ms Gzip kB Junk Typos Tiers Ranges Deps
Ekrina 0.91 0.32 8.6 0% ≤ 2 edits yes yes 0
fast-fuzzy 0.81 4.41 11.1 24% any no partial 1
Fuse.js (tuned) 0.76 10.92 9.6 47% any no opt-in 0
uFuzzy (all opts) 0.66 0.63 4.3 0% ≤ 1 edit no yes 0
fuzzysort 0.46 0.24 3.7 7% none no yes 0
@nozbe/microfuzz 0.41 1.33 1.7 7% none no yes 0
match-sorter 0.39 2.11 3.6 7% none yes no 2
fuzzy 0.30 1.50 0.8 7% none no partial 0

MRR is mean reciprocal rank over families of real-world mistakes, where 1 means the right item always comes first, and Junk is the share of queries with no right answer that a library answers anyway. The comparison has the method and what to pick, including where another library wins, and the benchmarks have every family.

Docs

The name

Ancient Greek ἔκρινα, eh-KREE-na, "I sifted, I judged", is the aorist of κρίνω, the root of criterion and critic, and cognate with the Latin cernere behind discern. It sifts a list and judges each candidate against a criterion.

Security

Ekrina has no runtime dependencies and no install scripts, its tests cover every line and branch, and each release is built in CI with npm provenance and goes live only after a maintainer approves it. Reporting a vulnerability, verifying a release and the limits on hostile input are in SECURITY.md.

Contributing

Bug reports and feature requests go in GitHub issues, and CONTRIBUTING.md covers changing the code.

License

MIT

About

Fast fuzzy matching. Zero dependencies, ~8.5 kB, tiers + ranges on every match.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages