# @art-suite/art-fuzzy-search

> Easy, fast, fuzzy text search.

Latest version **0.1.6** (published 2025-11-07) · ISC license · 0 weekly downloads

## Install

```sh
npm install @art-suite/art-fuzzy-search
pnpm add @art-suite/art-fuzzy-search
yarn add @art-suite/art-fuzzy-search
bun add @art-suite/art-fuzzy-search
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.6 |
| Published | 2025-11-07 |
| First published | 2021-09-24 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 15.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Shane Brinkman-Davis Delamore |
| Maintainers | shanebdavis |

## Links

- npm: https://www.npmjs.com/package/@art-suite/art-fuzzy-search
- Repository: https://github.com/art-suite/art-suite-foundations
- Issues: https://github.com/art-suite/art-suite-foundations/issues
- npm.io page: https://npm.io/package/@art-suite/art-fuzzy-search

## Dependencies (2)

- [stable](https://npm.io/package/stable.md) ^0.1.8
- [art-standard-lib](https://npm.io/package/art-standard-lib.md) ^1.74.4

## Recent versions

- 0.1.6 (latest) — 2025-11-07
- 0.1.5 — 2021-10-13
- 0.1.4 — 2021-10-13
- 0.1.3 — 2021-10-13
- 0.1.2 — 2021-09-27
- 0.1.1 — 2021-09-24
- 0.1.0 — 2021-09-24

## README

# ArtFuzzySearch

Easy, fast, fuzzy text search.

The primary use-case for ArtFuzzySearch is to quickly filter a list of items as you type, and to do it in flexible way so you catch odd spellings and type-os and other inconsistencies. The key to success is speed and, together with a good UX, interactively showing the results as the user types and edits their search string.

> It works similar to VSCode and SublimeText's file-search. The order of the letters matter, but there can be missing letters or skipped letters.


# Example

Basic example:

```javascript
let {fuzzySearch} = require("@art-suite/art-fuzzy-search");

let result = fuzzySearch(
  "sord",     // searchString
  [           // searchData
    "Sally Ford",
    "John Goodall",
    "Swordmaster Smith"
  ]
)

/*
result: [     // filtered and sorted searchData
  "Swordmaster Smith",
  "Sally Ford"
];
*/

```

More complex example:

```javascript
let {fuzzySearch} = require("@art-suite/art-fuzzy-search");

let result = fuzzySearch(
  "fz",       // searchString
  [           // searchData
    ["I love food"],
    "fz - just a string is OK too",
    ["I find pizza appealing", 123, true],
    ["I fuzzbuzz", "any extra data", "is returned unchanged"]
  ]
)

/*
result: [     // filtered and sorted searchData
  "fz - just a string is OK too",
  ["I fuzzbuzz", "any extra data", "is returned unchanged"],
  ["I find pizza appealing", 123, true]
];
*/

```

# API

```javascript
let {fuzzySearch} = require("@art-suite/art-fuzzy-search");

fuzzySearch(searchString, searchData) => filteredAndSortedSearchData
```

- **IN**: `(searchString, searchData)`

  - searchString: an String to search for
  - searchData: `[searchDataRecord, ...]` (an Array of searchDataRecords)

- **OUT**: searchData, filtered and sorted by best-matches

- **searchDataRecord**: `[searchInString, arbitraryData...]`
  - searchDataRecords can be just a searchInString or an array
  - only the first element is used by fuzzySearch
  - searchInString: arbitrary String which is tested to see if it matches the provided searchString; the quality of the match is also considered and used for the final sort of the returned searchData
  - arbitraryData: if searchInString matches, the entire searchDataRecord will be returned, untouched - including any arbitrary data included after searchInString. Use these additional slots to pass through any additional data you need. e.g. a JSON object of the record or just the record's ID.

Note that fuzzySearch is very forgiving. The only requirement for a match is that the characters of the searchString exist in the searchInString (case insensitively), in the same order, but possibly with any number of characters in between:

> Example: If searchString == 'dog', then the string "I did a lot of great work." *will match*: "I **D**id a l**O**t of **G**reat work."

The key is the results will be sorted based on the quality of the match - best match first. The main sorting criterias is the length of the match. Sorter matches are preferred. For more details, see the [Algorithm Notes](#algorithm-notes) below.

# Algorithm Notes

Basic algorithm:

1. Filter out all search-texts that don't match:
    - all letters from the search string must be present and in the same order in the search text
    - However, they don't have to match case and they can optionally match search-text with extra characters in between. e.g. "fz" will match "Fun zoo" since "f" and "z" are in order even though "un " is in between.
2. Sort the results by result-quality which is determined by
    - length of match; shorter is preferred
    - case sensitive matches are preferred
    - matches closer to the beginning of the search-text are preferred

---
_Source: https://npm.io/package/@art-suite/art-fuzzy-search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._