Fuse.js

Fuse.js is a lightweight, zero-dependency fuzzy-search library compatible with browsers, Node.js, and Deno. Key capabilities include:

• Fuzzy search: Typo-tolerant matching using the Bitap algorithm.
• Token search: Multi-word query splitting with term-based fuzzy matching and IDF ranking.
• Extended search: Support for operators like exact, prefix, suffix, inverse, and include matching.
• Logical search: Structured queries using $and and $or expressions.
• Weighted keys: Ability to boost specific fields (e.g., prioritizing title over description).
• Nested search: Accessing data via dot notation, array notation, or a custom getFn.
• Two builds: Available in a full version (~8.6 kB gzip) or a basic version (~6.8 kB gzip).

You can fine-tune how strictly Fuse.js matches patterns using three primary interacting options:

• threshold: The cutoff for the fuzziness score. 0.0 requires a perfect match; 1.0 matches anything. (Default: 0.6)
• location: The expected starting position of the pattern in the text. (Default: 0)
• distance: How far from location a match can be before being penalized. The effective search window is threshold × distance.

Important Note on Long Text: With default settings (threshold: 0.6, distance: 100), Fuse.js effectively only searches the first ~60 characters of a field. If your data contains long text fields, you should either increase distance or set ignoreLocation: true.

// Example: Searching long text by ignoring location
const fuse = new Fuse(data, {
  threshold: 0.6,
  ignoreLocation: true
});

The final relevance score (from 0 to 1) is a combination of the fuzziness score, the key weight, and the field-length norm (shorter fields rank higher). To see these scores, you must set includeScore: true in your configuration.

You can adjust how the field-length norm affects the score using:

• ignoreFieldNorm: When true, field length has no effect on scoring. (Default: false)
• fieldNormWeight: Adjusts the strength of the field-length norm. 0 ignores it, 0.5 reduces it, and 2.0 amplifies it. (Default: 1)

Fuse.js implements fuzzy search using the Bitap algorithm. Instead of a single state vector for exact matching, it maintains multiple state vectors representing different error levels:

• R0: Zero errors (exact match).
• R1: One error allowed.
• R2: Two errors allowed, and so on.

When a character mismatch occurs, the match 'dies' in the current error level but is 'carried over' to the next level (e.g., from R0 to R1), counting the mismatch as an error. This allows the engine to handle:

• Substitutions: Replacing a character.
• Deletions: Missing a character from the pattern.
• Insertions: An extra character in the text.

The algorithm continues adding error levels until the resulting score exceeds the configured threshold.

For advanced AI applications, use a layered approach:

1. Fuse.js for the fast, interactive 'search-as-you-type' layer (finding known pages, titles, or products).
2. Semantic Search for the natural language layer (answering complex questions or finding conceptually similar content).

Example Pattern (Documentation Site):

• Use Fuse.js to instantly filter documentation titles and headings as the user types.
• Use Semantic Search (Embeddings + Vector DB) when the user asks a specific question to retrieve relevant context for an LLM.

Example Pattern (E-commerce):

• Use Fuse.js for the product search bar (typo-tolerant filtering).
• Use Semantic Search for "Find similar products" recommendations or natural language queries like "warm jacket under $100".

Enable precise control over matches by setting useExtendedSearch: true. This allows you to use special characters in your query strings to perform exact matches, prefix searches, or exclusions.

const fuse = new Fuse(list, {
  useExtendedSearch: true,
  keys: ['title']
})

fuse.search('=exact match') // exact match
fuse.search('^prefix')     // starts with
fuse.search('!term')       // does not include

Choosing between the standard Fuse class and FuseWorker depends on your dataset size and UI requirements:

• Use Fuse (Standard) if:
  • Your dataset is small (< 5K items).
  • You need features unsupported by FuseWorker (e.g., sortFn, getFn, useTokenSearch, or remove()).
  • You are running in a Node.js environment.
• Use FuseWorker if:
  • Your dataset is large (10K+ items).
  • You need to maintain a responsive UI (no frame drops) during search-as-you-type.
  • You are targeting mobile devices with slower CPUs.

Performance Note: For datasets between 5K and 10K items, both are viable; test with your specific data.

Fuse Cloud is a hosted search service that follows a three-step workflow:

1. Upload your data: Push a JSON array (the same format used with local Fuse.js) to the service.
2. Get a search API: Fuse Cloud indexes your data and provides you with a publicKey.
3. Search from the client: Call the API directly from your frontend using the @fusejs/cloud client. No custom backend is required.

Fuse.js uses a fuzziness score to rank results, where:

• 0 is a perfect match (zero edit distance).
• 1 is a complete mismatch.

The final score is calculated by combining the edit distance with other factors like key weight and field-length normalization.

You can control how strict or loose the search is using the threshold option. The threshold acts as a cutoff: any result with a score higher than the threshold is excluded from the results.

• Lower threshold: More strict (requires closer matches, fewer errors allowed).
• Higher threshold: More loose (allows more typos and approximate matches).

The default threshold is 0.6.