Fuzzy

@polgubau/fuzzy is an optimized fuzzy finder library designed with TypeScript from the roots. You just need to type one command and call one function to get a fuzzy finder for your project.

What and why

Filters in JavaScript are often slow and cumbersome. The native Array.prototype.filter method is not optimized for performance, especially when dealing with large datasets. This library provides a simple and efficient way to perform fuzzy searches on arrays of strings.

It allows you to create a fuzzy search function that can be reused across your application, making it easy to filter lists based on user input.

What this is NOT ⚠️

A catch-all library that solves every problem.
A replacement for Lodash or Underscore.
A package that will unnecessarily inflate your bundle size.

What this IS ✅

A collection of small, focused utility functions.
Modular, tree-shakable and lightweight both for CJS and ESM.
Designed to be simple, efficient, and easy to use.
Fully typed, with TypeScript definitions included.

Installation

Install the library using your package manager of choice:

pnpm add @polgubau/fuzzy

Usage

import fuzzy from '@polgubau/fuzzy';

const list = ["volvo", "seat", "mercedes", "audi", "bmw"];
const queryText = "volv"; // The search term
const fuzzySearch = fuzzy(list);

// Run this whenever the search term changes
const fuzzedList = fuzzySearch(queryText);
console.log(fuzzedList);

Framework adapters

The library core is available as a standalone package, but we also provide adapters for popular frameworks like React and Vue.

Notice how the core import is @polgubau/fuzzy, while the React and Vue adapters are imported from @polgubau/fuzzy/react and @polgubau/fuzzy/vue respectively.

Using this import will allow you to use the library in a framework-agnostic way, while the framework-specific imports will provide additional functionality tailored to that framework. So you don’t import vue or react bundles if you don’t need them.

Using React?

To simplify the integration of fuzzy search into your React applications, we provide a custom hook called useFuzzy.

import { useFuzzy, Highlight } from '@polgubau/fuzzy/react' // Note: now importing from /react

const filteredList = useFuzzy({
  list: ["volvo", "seat", "mercedes", "audi", "bmw"],
  query: "volv"
})

filteredList.map(({ item, matches: [range] }) => (
  <div key={item}>
    <Highlight text={item} ranges={range} />
  </div>
))

Using Vue?

The same approach is available for Vue applications. We provide a composable called useFuzzy to simplify the integration of fuzzy search into your Vue applications.

<template>
  <div>
    <input v-model="query" placeholder="Search..." />
    <ul>
      <li v-for="(result, index) in fuzzySearch.results" :key="index">
        {{ result }}
      </li>
    </ul>
  </div>
</template>
 
<script lang="ts">
import { ref } from "vue";
import { useFuzzy } from "@polgubau/fuzzy/vue";
 
export default {
  setup() {
    // Lista de strings para la búsqueda
    const items = ref<string[]>(["Apple", "Banana", "Cherry", "Grape", "Pineapple"]);
    const query = ref("");
 
    // Using the composable
    const fuzzySearch = useFuzzy({ list: items, query });
 
    return {
      query,
      fuzzySearch,
    };
  },
};
</script>

Documentation

The documentation page is available at fuzzy.polgubau.com.

The documentation is built using Fumadocs with some customizations.

I18n support

The documentation is available in multiple languages. You can switch between them using the language selector in the top right corner of the page. Currently, the following languages are supported:

Language	Supported
English	✅
Spanish	✅
Catalan	✅
German	✅

🛠 Development

Building the project

The easiest way to work with the project monorepo is to run

pnpm dev

in the root directory. This will start a watch build for the package and start a local server to preview the documentation page.

Running tests

The tests are written in TypeScript and use Vitest as the testing framework. Run the command inside the packages/fuzzy directory to run the tests.

pnpm test

Author and license

Made with ❤️ by Pol Gubau Amores

This project is based on microfuzz, which was created by @Nozbe, some improvements were made to the original code, and it was rewritten in TypeScript.

See all contributors.

This project is available under the MIT license. See the LICENSE file for more info.