Fuse.js

Fuse.js is a lightweight, zero-runtime-dependency fuzzy-search library written in TypeScript. It implements the Bitap approximate string-matching algorithm so searches tolerate typos and partial matches without a dedicated search backend, making it a natural fit for filtering small-to-medium datasets entirely on the client.

Beyond basic fuzzy matching, Fuse.js supports weighted multi-field keys, an extended-search syntax with exact/prefix/suffix operators, logical $and/$or query composition, match-index highlighting, and an opt-in token-search mode with BM25-style relevance ranking for multi-word queries. A companion FuseWorker build offloads indexing and search to Web Workers for large datasets without blocking the UI thread.

What You Get

• Core Fuse class implementing Bitap fuzzy matching with configurable threshold, distance, and location tuning
• Weighted multi-key search so fields like title can outrank fields like description in relevance scoring
• Extended search syntax (=, ^, !, etc.) and logical $and/$or query composition for precise filtering
• Token search mode with per-word typo tolerance and BM25-style IDF ranking for multi-word queries
• FuseWorker build that shards documents across Web Workers for parallel search on large datasets
• Match-index highlighting output (includeMatches) for building highlighted search-result UIs
• Dual ESM/CJS builds plus a smaller “basic” build (fuzzy search only) for bundle-size-sensitive apps

Common Use Cases

• Client-side search-as-you-type over a product catalog, docs site, or command palette without a backend search index
• Fuzzy filtering of autocomplete/typeahead suggestions that tolerate user typos
• Ranking and highlighting matches across multiple weighted fields (e.g. title vs. body) in a search results list
• Offloading fuzzy search for large in-memory datasets to a Web Worker so the main thread stays responsive

Under The Hood

Architecture — The public entry point (src/entry.ts) wires up the Fuse class (src/core/index.ts) with pluggable search strategies registered through a strategy-pattern dispatcher (src/core/register.ts): BitapSearch is always available as the default, while ExtendedSearch (src/search/extended) and TokenSearch (src/search/token) are conditionally registered behind build-time env flags (EXTENDED_SEARCH_ENABLED, TOKEN_SEARCH_ENABLED), which is how the same source tree produces the smaller “basic” build alongside the “full” build. The Fuse instance builds a FuseIndex (src/tools/FuseIndex.ts) from the input documents plus a KeyStore for weighted search keys; queries are parsed into an AST by src/core/queryParser.ts (supporting $and/$or composition), scored per field via computeScore.ts for Bitap matches or an inverted index (src/search/token/InvertedIndex.ts) for BM25-style token scoring, and the top-N results are kept efficiently with a MaxHeap (src/tools/MaxHeap.ts) rather than sorting the full result set. src/workers/FuseWorker.ts wraps the same core to shard documents across Web Workers for parallel search.

Tech Stack — Written in TypeScript (40% of the codebase) with the remainder in JavaScript, bundled by tsdown (an esbuild-based bundler, per tsdown.config.ts) into dual ESM/CJS outputs (dist/fuse.mjs, dist/fuse.cjs) plus separate minified “basic” builds. The package ships with zero runtime dependencies — everything in package.json (vitest, eslint 9 + typescript-eslint, prettier, vitepress, husky, commitlint, standard-version) is a devDependency for testing, linting, docs, and release automation. Type-checking runs via tsc against src/tsconfig.json.

Code Quality — The test/ directory holds 20+ spec files covering fuzzy search, extended search, logical search, and token search (further split into scenario, tokenizer, and AND-logic suites), plus dedicated tests for Web Worker behavior, cache invalidation, CJS interop, and even the public TypeScript type surface (package-types.test.ts, typings.test.ts). Snapshot tests under test/__snapshots__/ pin exact result sets for regression safety, run via vitest. Error handling is centralized in src/core/errorMessages.ts as named constants rather than inline strings, and invalid option combinations (e.g. calling Fuse.match() with useTokenSearch) throw explicit, documented errors instead of failing silently.

API Design — Getting started requires only new Fuse(docs, { keys }) followed by .search(query), with sensible defaults in src/core/config.ts covering everything else. Advanced capabilities (weighted keys, extended-search operators, logical queries, token search, Web Worker offloading) are opt-in through boolean options rather than separate APIs, so the mental model stays consistent as usage scales up. Full TypeScript types are re-exported from entry.ts for options, results, and match objects, and the dedicated docs site (fusejs.io, built from the docs/ folder) supplements the README with interactive demos and a complete API reference.