simple-fuzzy

Hi, Sounak this side 👋

I’m a software engineer passionate about building fast, efficient, and developer-friendly tools.
This package is part of my journey to create simple yet powerful solutions for everyday dev problems. 🚀

visit my website

If you wanna support me 👇

Why Another Fuzzy Search Library? 🤔

If you've ever used Fuse.js, you know it's an amazing, feature-packed fuzzy search library.
It’s powerful, flexible, and works great for large-scale search scenarios.

So why create simple-fuzzy?

Because sometimes you don’t need all that.
In many client-side applications — autocomplete dropdowns, quick search bars, small admin tables — you just want instant results without pulling in a 20KB+ dependency or tweaking dozens of options.

simple-fuzzy is:

• Ultra-lightweight — zero dependencies, tiny footprint.
• Faster for small datasets — optimized for lists under ~1,000 items.
• Dead-simple API — one function, one purpose, no steep learning curve.
• Full TypeScript support — key autocompletion, type safety, and great IntelliSense in VS Code.

If you want a blazing-fast, minimalist fuzzy search that just works out of the box,
simple-fuzzy is the tool for you. 🚀

simple-fuzzy

An extremely fast, lightweight fuzzy search library optimized for small datasets (under 1,000 items).

simple-fuzzy is designed for client-side applications that need blazing-fast fuzzy matching with minimal overhead.
Unlike heavy alternatives, it focuses on one highly-optimized algorithm to deliver instant results for autocomplete, command palettes, and quick-find features.

Comparison with fuse.js 👍

import Fuse from "fuse.js";
import { createFuzzySearch } from "simple-fuzzy";

const data = Array.from({ length: 1000 }, (_, i) => `item-${i}`);
const fuse = new Fuse(data);
const simpleSearch = createFuzzySearch(data);

console.time("fuse");
fuse.search("item-99");
console.timeEnd("fuse");

console.time("simple-fuzzy");
simpleSearch("item-99");
console.timeEnd("simple-fuzzy");

Output 🎉🎉🎉

fuse: 1.5ms
simple-fuzzy: 0.2ms

🚀 Key Features

• ⚡️ Blazing Fast: Minimalist, opinionated algorithm for maximum speed.
• 🧩 Lightweight: Zero dependencies, tiny footprint.
• 🛠️ Full TypeScript Support: Autocompletion + IntelliSense for object keys.
• 🎯 Optimized for Small Datasets: Best for lists up to ~1,000 items.
• 🔍 Configurable Match Tightness: Adjustable threshold (1–10) for loose or strict searches.

📦 Installation

npm install simple-fuzzy
# or
yarn add simple-fuzzy

✍️ Usage

1️⃣ Searching a simple array of strings

import { createFuzzySearch } from "simple-fuzzy";

const fruits = ["apple", "banana", "orange", "grape", "cherry"];

// Create search function
const searchFruits = createFuzzySearch(fruits, { threshold: 5 });

// Search
console.log(searchFruits("aple"));
// Output: ["apple"]

2️⃣ Searching an array of objects (single key)

import { createFuzzySearch } from "simple-fuzzy";

interface Book {
  title: string;
  author: string;
}

const books: Book[] = [
  { title: "The Lord of the Rings", author: "J.R.R. Tolkien" },
  { title: "The Hobbit", author: "J.R.R. Tolkien" },
  { title: "Pride and Prejudice", author: "Jane Austen" },
];

// Search only in the `title` field
const searchBooks = createFuzzySearch(books, { key: "title", threshold: 7 });

console.log(searchBooks("hobit"));
// Output: [{ title: "The Hobbit", author: "J.R.R. Tolkien" }]

3️⃣ Searching multiple keys in objects

import { createFuzzySearch } from "simple-fuzzy";

interface User {
  name: string;
  email: string;
}

const users: User[] = [
  { name: "Alice Johnson", email: "[e-mail]" },
  { name: "Bob Smith", email: "[e-mail]" },
  { name: "Charlie Brown", email: "[e-mail]" },
];

// Search in both `name` and `email`
const searchUsers = createFuzzySearch(users, {
  key: ["name", "email"],
  threshold: 4,
});

console.log(searchUsers("alice"));
// Output: [{ name: "Alice Johnson", email: "[e-mail]" }]

📖 API Reference

createFuzzySearch<T>(data: T[], options?: FuzzySearchOptions<T>)

Parameters:

Name	Type	Default	Description
data	T[]	—	Array of strings or objects to search.
options.key	keyof T | (keyof T)[]	—	Key(s) to search in if data contains objects.
options.threshold	number (1–10)	5	Match tightness — 1 = loose, 10 = strict.

Returns:
A function (query: string) => T[] that returns sorted results from best to worst match.

🧪 Example Test Cases

import { createFuzzySearch } from "simple-fuzzy";

// Array of strings - loose match
const fruits = ["apple", "pineapple", "grape", "appletini", "banana", "mango"];
const searchLoose = createFuzzySearch(fruits, { threshold: 2 });
console.log(searchLoose("aple"));
// ["apple", "pineapple", "appletini"]

// Array of strings - tight match
const searchTight = createFuzzySearch(fruits, { threshold: 9 });
console.log(searchTight("aple"));
// ["apple"]

// Array of objects - single key
const users = [
  { name: "Alice Johnson", email: "[e-mail]" },
  { name: "Bob Smith", email: "[e-mail]" },
];
const searchByName = createFuzzySearch(users, { key: "name", threshold: 5 });
console.log(searchByName("alice"));
// [{ name: "Alice Johnson", email: "[e-mail]" }]

// Multiple keys
const searchByNameOrEmail = createFuzzySearch(users, {
  key: ["name", "email"],
  threshold: 4,
});
console.log(searchByNameOrEmail("bob"));
// [{ name: "Bob Smith", email: "[e-mail]" }]

// Case-insensitive
console.log(searchByName("ALICE"));
// [{ name: "Alice Johnson", email: "[e-mail]" }]

// Empty query returns empty array
console.log(searchByName(""));
// []

📜 License

MIT © 2025 — Maintained by Sounak Das