fuzzyjs

!NPM
!NPM
!GitHub Workflow Status

fuzzyjs is a fuzzy search algorithm in javascript.

Usage

test

Tests a query against a source using fuzzy matching

``ts
import { test } from "fuzzyjs";

test("ssjs", "Set Syntax: JavaScript");
true;
`

`ts
function test(query: string, source: string, opts?: TestOptions): boolean;

type TestOptions = {
caseSensitive?: boolean; // (default: false)
};
`

match

Matches a query against a source using fuzzy matching, returns information about the result

`ts
import { match } from 'fuzzyjs'

match('ssjav', 'Set Syntax: JavaScript')
{
match: true,
score: 22,
ranges: [
{ start: 0, stop: 1 },
{ start: 4, stop: 5 },
{ start: 12, stop: 15 }
]
}
`

`ts
function match(query: string, source: string, opts?: MatchOptions): MatchResult;

type MatchOptions = {
caseSensitive?: boolean;
strategy?: ScoreStrategy; // (default: defaultStrategy, see below)
withScore?: boolean; // (default: true)
};

type MatchResult = {
match: boolean;
score: number; // only if withScore is true, else undefined
ranges: MatchRange[];
};
`

Utilities

surround

Surround parts of the string that matched with prefix and suffix

`ts
import { match, surround } from "fuzzyjs";

const result = match("ssjav", "Set Syntax: JavaScript");

surround("Set Syntax: JavaScript", {
result,
prefix: "",
suffix: "",
});
("Set Syntax: JavaScript");
`

`ts
function surround(source: string, options: SurroundOptions): string;

type SurroundOptions = {
result: {
ranges: MatchRange[];
};
prefix?: string; // (default: '')
suffix?: string; // (default: '')
};
`

filter

Can be used as a Array.prototype.filter callback.

`ts
import { filter as fuzzy } from "fuzzyjs";

const sources = [
"Set Syntax: JavaScript",
"Set Syntax: CSS",
"Set Syntax: HTML",
];

sources.filter(fuzzy("ssjs", { iterator: (item) => item }));
["Set Syntax: JavaScript"];

const sources = [
{ name: { foo: "Set Syntax: JavaScript" } },
{ name: { foo: "Set Syntax: CSS" } },
{ name: { foo: "Set Syntax: HTML" } },
];

sources.filter(fuzzy("ssjs", { iterator: (source) => source.name.foo }));
[{ name: { foo: "Set Syntax: JavaScript" } }];
`

`ts
function filter(
query: string,
options: FilterOptions
): (source: TItem) => boolean;

type FilterOptions = {
caseSensitive?: boolean;
iterator: (source: TItem) => string;
};
`

sort

Can be used as a Array.prototype.sort callback.
If you have a large array of objects, you might want to pass idAccessor as it creates a memoization table which reduces drastically how many times the fuzzy matching algorithm will be called.

`ts
import { sort as fuzzy } from "fuzzyjs";

const sources = [
"Set Syntax: CSS",
"Set Syntax: HTML",
"Set Syntax: JavaScript",
];

sources.sort(fuzzy("ssjs", { iterator: (item) => item }));
[("Set Syntax: JavaScript", "Set Syntax: CSS", "Set Syntax: HTML")];

const sources = [
{ name: { id: 0, foo: "Set Syntax: CSS" } },
{ name: { id: 1, foo: "Set Syntax: HTML" } },
{ name: { id: 2, foo: "Set Syntax: JavaScript" } },
];

sources.sort(fuzzy("ssjs", { iterator: (source) => source.name.foo }));
[
{ name: { id: 2, foo: "Set Syntax: JavaScript" } },
{ name: { id: 0, foo: "Set Syntax: CSS" } },
{ name: { id: 1, foo: "Set Syntax: HTML" } },
];
`

`ts
function sort(
query: string,
options?: SortOptions
): (leftSource: TItem, rightSource: TItem) => 0 | 1 | -1;

type SortOptions = {
caseSensitive?: boolean;
iterator: (item: TItem) => string;
};
`

Scoring function

A scoring function is a function that given two context, returns a number (either positive or negative) that will be added the the match score.

A leading character is a character that matters more than others.
These are made of capitals and letters following -_ ./\.

`ts
function pushScore(
previousContext: ScoreContext | undefined,
context: ScoreContext
): number;

type ScoreContext = {
currentScore: number; // the current match score
character: string; // the current character
match: boolean; // is the character matching the source string
leading: boolean; // is the character leading
};
``

Link to default strategy: here.

License

fuzzyjs is licensed under MIT License.