Fuse.js

https://www.fusejs.io/
Admin
Fuse.js is a powerful, lightweight, zero-dependency fuzzy-search library for client-side fuzzy...
Tokens:13,922
Snippets:168
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Fuse.js

Source: https://www.fusejs.io/getting-started.html

Install the package using your preferred JavaScript package manager.

```sh
npm install fuse.js
```

```sh
pnpm add fuse.js
```

```sh
yarn add fuse.js
```

```sh
bun add fuse.js
```

--------------------------------

### Virtualized Rendering with react-window

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

Install and use react-window to render only visible search results for large datasets.

```bash
npm install react-window
```

```jsx
import { FixedSizeList } from 'react-window'

function SearchResults({ results }) {
  // Only the visible rows are rendered — the rest are virtualized
  const Row = ({ index, style }) => (
    <div style={style}>
      {results[index].item.title}
    </div>
  )

  return (
    <FixedSizeList
      height={400}
      itemCount={results.length}
      itemSize={40}
      width="100%"
    >
      {Row}
    </FixedSizeList>
  )
}
```

--------------------------------

### Install Fuse.js via npm

Source: https://www.fusejs.io/

Command to install the library into a project using the npm package manager.

```bash
npm install fuse.js
```

--------------------------------

### Quick Start with FuseWorker

Source: https://www.fusejs.io/web-workers.html

Initialize a FuseWorker instance and perform an asynchronous search.

```javascript
import { FuseWorker } from 'fuse.js/worker'

const fuse = new FuseWorker(docs, {
  keys: ['title', 'author', 'description'],
  threshold: 0.4,
  includeScore: true
})

const results = await fuse.search('javascript')

// Clean up when done
fuse.terminate()
```

--------------------------------

### Cross-Field Token Matching

Source: https://www.fusejs.io/token-search.html

Example demonstrating that 'all' matching mode evaluates across all fields and array elements.

```javascript
const products = [
  { title: 'Red', description: 'cotton shirt' }, // "red" + "shirt" in different fields
  { title: 'Red dress', description: 'silk' }
]
```

--------------------------------

### Over-engineered semantic search example

Source: https://www.fusejs.io/articles/vs-semantic-search.html

An example of an inefficient approach using server-side semantic search for a small dataset.

```javascript
// Over-engineered: calling an API to search 200 items
const response = await fetch('/api/search', {
  method: 'POST',
  body: JSON.stringify({ query: userInput })
})
// Server: embeds query → queries Pinecone → returns results
// Total time: 300ms, cost: ~$0.001 per query
```

--------------------------------

### Initial State Vector

Source: https://www.fusejs.io/articles/how-fuzzy-search-works.html

The starting state vector R initialized to all zeros before processing the text.

```text
     t  e  s  t
R =  0  0  0  0
```

--------------------------------

### Strict Validation Errors

Source: https://www.fusejs.io/extended-search.html

Examples of invalid queries that will throw errors during execution.

```javascript
fuse.search({ title: { $startWith: 'old' } }) // throws: Unknown query operator '$startWith'
fuse.search({ title: { $startsWith: '' } }) // throws: Empty value for operator '$startsWith' on key 'title'
```

--------------------------------

### Negating Operators with $not

Source: https://www.fusejs.io/extended-search.html

Examples of using the $not operator to negate specific search conditions.

```javascript
fuse.search({ title: { $not: { $contains: 'draft' } } }) // === '!draft'
fuse.search({ title: { $not: { $startsWith: 'old' } } }) // === '!^old'
fuse.search({ title: { $not: { $endsWith: '.go' } } }) // === '!.go$'
```

--------------------------------

### Initialize and search with Fuse Cloud

Source: https://www.fusejs.io/cloud.html

Demonstrates how to instantiate the FuseCloud client using a public key and perform a search query.

```javascript
import { FuseCloud } from "@fusejs/cloud"

const client = new FuseCloud({
  publicKey: "pk_abc123",
  index: "products"
})

const { results } = await client.search("iphone")
// → [{ id: "1", score: 0.02, item: { title: "iPhone 16 Pro", ... } }]
```

--------------------------------

### Import Different Build Variants

Source: https://www.fusejs.io/getting-started.html

Select between full, basic, or minified builds based on your feature requirements.

```js
// Full build (default)
import Fuse from 'fuse.js'

// Basic build
import Fuse from 'fuse.js/basic'

// Minified variants
import Fuse from 'fuse.js/min'
import Fuse from 'fuse.js/min-basic'
```

--------------------------------

### Run Benchmark with Node.js

Source: https://www.fusejs.io/performance.html

Execute the benchmark script using the Node.js runtime.

```shell
node --input-type=module bench.mjs
```

--------------------------------

### Perform a Basic Search

Source: https://www.fusejs.io/getting-started.html

Initialize Fuse with a data array and search keys, then execute a search query.

```js
import Fuse from 'fuse.js'

const books = [
  { title: "Old Man's War", author: 'John Scalzi' },
  { title: 'The Lock Artist', author: 'Steve Hamilton' }
]

const fuse = new Fuse(books, {
  keys: ['title', 'author']
})

const results = fuse.search('jon')
// [{ item: { title: "Old Man's War", author: "John Scalzi" }, refIndex: 0 }]
```

--------------------------------

### Initialize Fuse.js and perform a search

Source: https://www.fusejs.io/demo.html

Configures a new Fuse instance with specific search options and executes an initial search query.

```javascript
const fuse = new Fuse(books, { includeScore: true, includeMatches: true, keys: ['title', 'author.firstName', 'author.lastName'] }) fuse.search('')
```

--------------------------------

### Perform a basic fuzzy search with Fuse.js

Source: https://www.fusejs.io/

Initializes a Fuse instance with a dataset and search keys, then executes search queries.

```javascript
import Fuse from 'fuse.js'

const books = [
  { title: "Old Man's War", author: 'John Scalzi' },
  { title: 'The Lock Artist', author: 'Steve Hamilton' },
  { title: 'JavaScript Patterns', author: 'Stoyan Stefanov' }
]

const fuse = new Fuse(books, {
  keys: ['title', 'author'],
  includeScore: true
})

fuse.search('jon')
// [{ item: { title: "Old Man's War", author: "John Scalzi" }, refIndex: 0, score: 0.25 }]

fuse.search('patterns')
// [{ item: { title: "JavaScript Patterns", ... }, refIndex: 2, score: 0.0 }]
```

--------------------------------

### Using Object Syntax for Queries

Source: https://www.fusejs.io/extended-search.html

Shows how to use structural object queries instead of string-based operators.

```javascript
const fuse = new Fuse(books, { keys: ['title', 'author'] })

fuse.search({ title: { $startsWith: 'old' } })
```

--------------------------------

### Basic Token Search Configuration

Source: https://www.fusejs.io/token-search.html

Enables token search with the 'all' match requirement, ensuring all query tokens must be present in the result.

```javascript
new Fuse(products, {
  useTokenSearch: true,
  tokenMatch: 'all',
  keys: ['title', 'description']
})
  .search('red shirt')
  .map((r) => r.item)
```

--------------------------------

### Configure Token Matching Mode

Source: https://www.fusejs.io/token-search.html

Toggle between 'any' (OR) and 'all' (AND) matching logic for multi-word queries.

```javascript
const list = ['red shirt', 'red hat', 'blue shirt']

new Fuse(list, { useTokenSearch: true })
  .search('red shirt')
  .map((r) => r.item)
// 'any' (default): ['red shirt', 'red hat', 'blue shirt']  ← matches either word

new Fuse(list, { useTokenSearch: true, tokenMatch: 'all' })
  .search('red shirt')
  .map((r) => r.item)
// 'all': ['red shirt']                                     ← matches both words
```

--------------------------------

### Implement client-side search with Fuse.js

Source: https://www.fusejs.io/articles/vs-semantic-search.html

Initializes a Fuse instance with a dataset and search configuration to enable typo-tolerant, in-browser searching.

```javascript
import Fuse from 'fuse.js'

const products = [
  { name: 'MacBook Pro 16"', sku: 'MBP16', category: 'Laptops' },
  { name: 'Magic Keyboard', sku: 'MK', category: 'Accessories' },
  { name: 'Mac Mini M4', sku: 'MM4', category: 'Desktops' },
  // ... hundreds or thousands of items
]

const fuse = new Fuse(products, {
  keys: ['name', 'sku', 'category'],
  threshold: 0.4
})

// Typo-tolerant, instant, runs in the browser
fuse.search('mackbook')
// [{ item: { name: 'MacBook Pro 16"', ... }, ... }]
```

--------------------------------

### Configure worker script path with static URL

Source: https://www.fusejs.io/web-workers.html

Use this approach if the import method fails by manually hosting the worker script file.

```javascript
const fuse = new FuseWorker(docs, options, {
  workerUrl: '/static/fuse.worker.mjs'
})
```

--------------------------------

### Bitap Search Trace for 'test' in 'xtest'

Source: https://www.fusejs.io/articles/how-fuzzy-search-works.html

Step-by-step trace of the state vector R as the algorithm processes each character in the string 'xtest'.

```text
                 t  e  s  t
Start:      R =  0  0  0  0

Read 'x':   R =  0  0  0  0   ← 'x' isn't in the pattern, seed killed
Read 't':   R =  1  0  0  0   ← 't' matches position 0, partial match starts
Read 'e':   R =  0  1  0  0   ← 'e' matches position 1, match continues
Read 's':   R =  0  0  1  0   ← 's' matches position 2, still going
Read 't':   R =  1  0  0  1   ← 't' matches position 3 → full match!
                                  (also starts a new match at position 0)
```

--------------------------------

### new FuseWorker(docs, options?, workerOptions?)

Source: https://www.fusejs.io/web-workers.html

Initializes a new FuseWorker instance to handle parallelized searching.

```APIDOC
## Constructor: new FuseWorker(docs, options?, workerOptions?)

### Description
Creates a new instance of FuseWorker. The dataset is sharded across multiple workers for parallel processing.

### Parameters
- **docs** (Array) - Required - The array of documents to search.
- **options** (Object) - Optional - Standard Fuse.js configuration options (e.g., keys, threshold, includeScore).
- **workerOptions** (Object) - Optional - Configuration for worker behavior:
  - **numWorkers** (number) - Number of parallel workers (default: navigator.hardwareConcurrency, max 8).
  - **workerUrl** (string | URL) - Custom path to the worker script.
```

--------------------------------

### Enabling String Operators in Basic Build

Source: https://www.fusejs.io/extended-search.html

Shows how to register the ExtendedSearch plugin when using the basic build of Fuse.js.

```javascript
import Fuse from 'fuse.js/basic'
import { ExtendedSearch } from 'fuse.js'

Fuse.use(ExtendedSearch) // enables the string operators only
```

--------------------------------

### Implement a basic search component in React

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

A functional component using useMemo to initialize Fuse.js and useState to manage the search query.

```jsx
import { useMemo, useState } from 'react'
import Fuse from 'fuse.js'

const books = [
  { title: 'The Great Gatsby', author: 'F. Scott Fitzgerald' },
  { title: 'To Kill a Mockingbird', author: 'Harper Lee' },
  { title: 'One Hundred Years of Solitude', author: 'Gabriel Garcia Marquez' },
  { title: 'The Catcher in the Rye', author: 'J.D. Salinger' },
  { title: 'Brave New World', author: 'Aldous Huxley' },
]

function BookSearch() {
  const [query, setQuery] = useState('')

  // Create the Fuse instance once — the index is built at construction time
  const fuse = useMemo(() => {
    return new Fuse(books, {
      keys: ['title', 'author'], // fields to search
      threshold: 0.4,            // 0 = exact, 1 = match anything
    })
  }, [])

  const results = query ? fuse.search(query) : []

  // Show search results when there's a query, full list otherwise
  const displayItems = results.length > 0
    ? results.map(({ item }) => item)
    : books

  return (
    <div>
      <input
        type="text"
        placeholder="Search books..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <ul>
        {displayItems.map((book) => (
          <li key={book.title}>
            {book.title} — {book.author}
          </li>
        ))}
      </ul>
    </div>
  )
}
```

--------------------------------

### Register Features in Basic Build

Source: https://www.fusejs.io/getting-started.html

Manually register additional search features when using the basic build.

```js
import Fuse from 'fuse.js/basic'
import { ExtendedSearch } from 'fuse.js'

Fuse.use(ExtendedSearch)
```

--------------------------------

### Pre-build Fuse.js Index

Source: https://www.fusejs.io/performance.html

Use this approach to improve performance when indexing large datasets on page load.

```javascript
const index = Fuse.createIndex(keys, list)
const fuse = new Fuse(list, options, index)
```

--------------------------------

### Enable Token Search

Source: https://www.fusejs.io/token-search.html

Initialize Fuse with the useTokenSearch option set to true to enable multi-word query support.

```javascript
const fuse = new Fuse(docs, {
  useTokenSearch: true,
  keys: ['title', 'author', 'description']
})

fuse.search('javascrpt paterns')
// → [{ item: { title: 'JavaScript Patterns', ... }, score: 0.12 }]
```

--------------------------------

### Import Fuse.js

Source: https://www.fusejs.io/getting-started.html

Import the library using ESM or CommonJS syntax.

```js
import Fuse from 'fuse.js'
```

```js
const Fuse = require('fuse.js')
```

--------------------------------

### Dynamic Collection Updates

Source: https://www.fusejs.io/token-search.html

Demonstrates how to add or remove documents while maintaining the inverted index for token search.

```javascript
const fuse = new Fuse(docs, { useTokenSearch: true, keys: ['title'] })

// Adding a document updates the inverted index
fuse.add({ title: 'New Book' })

// Removing documents also updates the index
fuse.remove((doc) => doc.title === 'Old Book')
```

--------------------------------

### Import Fuse.js for Deno

Source: https://www.fusejs.io/getting-started.html

Use the Deno-specific import path with type definitions.

```typescript
// @deno-types="https://deno.land/x/fuse@v7.5.0/dist/fuse.d.ts"
import Fuse from 'https://deno.land/x/fuse@v7.5.0/dist/fuse.min.mjs'
```

--------------------------------

### Hybrid search implementation for documentation

Source: https://www.fusejs.io/articles/vs-semantic-search.html

Demonstrates combining Fuse.js for instant UI filtering and semantic search for answering natural language questions.

```javascript
import Fuse from 'fuse.js'

// Layer 1: Instant search-as-you-type for known pages
const fuse = new Fuse(docs, {
  keys: ['title', 'headings', 'slug'],
  threshold: 0.3
})

function handleSearchInput(query) {
  // Fast fuzzy search — instant results as the user types
  return fuse.search(query).slice(0, 5)
}

// Layer 2: Semantic search when the user asks a question
async function handleQuestion(question) {
  const embedding = await embed(question)
  const chunks = await vectorDB.query({ vector: embedding, topK: 10 })
  return await llm.answer(question, chunks)
}
```

--------------------------------

### search(query, options?)

Source: https://www.fusejs.io/web-workers.html

Performs a search across all worker shards.

```APIDOC
## Method: search(query, options?)

### Description
Executes a search query across all worker threads simultaneously and merges the results.

### Parameters
- **query** (string | Object) - Required - The search query string or expression object.
- **options** (Object) - Optional - Search options such as `limit`.

### Response
- **Returns** (Promise<FuseResult[]>) - A promise that resolves to an array of search results.
```

--------------------------------

### Deep Composition with Logical Queries

Source: https://www.fusejs.io/extended-search.html

Shows how to nest object queries within logical operators for complex search requirements.

```javascript
fuse.search({
  $and: [
    { category: { $eq: 'fiction' } },
    {
      $or: [
        { title: { $startsWith: 'old' } },
        { author: { $contains: 'scalzi' } }
      ]
    }
  ]
})
```

--------------------------------

### Compare search logic between Fuse.js and Vector DB

Source: https://www.fusejs.io/articles/vs-semantic-search.html

Illustrates the fundamental difference in how Fuse.js handles character similarity versus how vector databases process semantic embeddings.

```text
User types: "recpie"

Fuse.js:   "recpie" ≈ "recipe"         (character similarity)
Vector DB: "recpie" → [0.12, -0.84, …] (semantic embedding)
```

--------------------------------

### Memoize the Fuse Index

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

Pre-build and cache the Fuse index using useMemo to improve performance when data changes frequently.

```jsx
import { useMemo } from 'react'
import Fuse from 'fuse.js'

function useSearch(items, keys, query) {
  const fuse = useMemo(() => {
    // Pre-build the index so Fuse doesn't rebuild it on every new instance
    const index = Fuse.createIndex(keys, items)
    // pass pre-built index
    return new Fuse(items, { keys, threshold: 0.4 }, index)
  }, [items, keys])

  return query ? fuse.search(query) : []
}
```

--------------------------------

### Perform an AND logical search

Source: https://www.fusejs.io/logical-search.html

Matches documents that satisfy all provided clauses using short-circuit evaluation.

```javascript
const result = fuse.search({
  $and: [{ author: 'abc' }, { title: 'xyz' }]
})
```

--------------------------------

### Basic Fuzzy Search Implementation

Source: https://www.fusejs.io/fuzzy-search.html

Initializes a Fuse instance with a list of strings and enables score inclusion to evaluate match quality.

```javascript
const fuse = new Fuse(['apple', 'banana', 'orange'], {
  includeScore: true
})

fuse.search('aple')
// [{ item: 'apple', refIndex: 0, score: 0.25 }]
```

--------------------------------

### Load Fuse.js via CDN

Source: https://www.fusejs.io/getting-started.html

Include Fuse.js in your HTML using a script tag or as an ES module.

```html
<script src="https://cdn.jsdelivr.net/npm/fuse.js@7.5.0"></script>
```

```html
<script type="module">
  import Fuse from 'https://cdn.jsdelivr.net/npm/fuse.js@7.5.0/dist/fuse.mjs'
</script>
```

--------------------------------

### Adding Documents

Source: https://www.fusejs.io/web-workers.html

Add a new document to the worker shards using round-robin distribution.

```javascript
await fuse.add({ title: 'New Item', author: 'Jane' })
```

--------------------------------

### Implement a Complete Fuzzy Search Component

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

A comprehensive search component featuring debouncing, match highlighting, and result limiting.

```jsx
import { useEffect, useMemo, useState } from 'react'
import Fuse from 'fuse.js'

function useDebounce(value, delay) {
  const [debounced, setDebounced] = useState(value)
  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay)
    return () => clearTimeout(timer)
  }, [value, delay])
  return debounced
}

function highlightMatches(text, regions = []) {
  if (!regions.length) return text
  const chunks = []
  let lastIndex = 0
  for (const [start, end] of regions) {
    if (start > lastIndex) chunks.push(text.slice(lastIndex, start))
    chunks.push(<mark key={start}>{text.slice(start, end + 1)}</mark>)
    lastIndex = end + 1
  }
  if (lastIndex < text.length) chunks.push(text.slice(lastIndex))
  return chunks
}

function FuzzySearch({ items, keys, itemKey, placeholder = 'Search...' }) {
  const [query, setQuery] = useState('')
  const debouncedQuery = useDebounce(query, 200)

  // Recreate Fuse only when items or keys change
  const fuse = useMemo(
    () => new Fuse(items, { keys, includeMatches: true, threshold: 0.4 }),
    [items, keys]
  )

  // Cap results to keep rendering fast
  const results = debouncedQuery
    ? fuse.search(debouncedQuery, { limit: 50 })
    : []

  return (
    <div>
      <input
        type="text"
        placeholder={placeholder}
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <ul>
        {results.length > 0
          ? results.map(({ item, matches }) => (
              <li key={item[itemKey]}>
                {keys.map((key) => {
                  const match = matches?.find((m) => m.key === key)
                  return (
                    <span key={key}>
                      {highlightMatches(item[key], match?.indices)}{' '}
                    </span>
                  )
                })}
              </li>
            ))
          : items.slice(0, 50).map((item) => (
              <li key={item[itemKey]}>
                {keys.map((key) => (
                  <span key={key}>{item[key]} </span>
                ))}
              </li>
            ))}
      </ul>
    </div>
  )
}
```

```jsx
<FuzzySearch
  items={products}
  keys={['name', 'description']}
  itemKey="id"
  placeholder="Search products..."
/>
```

--------------------------------

### Bitmask Representation for Pattern 'test'

Source: https://www.fusejs.io/articles/how-fuzzy-search-works.html

Visual representation of the bitmask creation for the pattern 'test', where each character maps to a bit position.

```text
         t  e  s  t
mask[t]  1  0  0  1
mask[e]  0  1  0  0
mask[s]  0  0  1  0
```

--------------------------------

### Benchmark Fuse.js Performance

Source: https://www.fusejs.io/performance.html

A script to measure indexing and search performance with custom datasets and configurations.

```javascript
import Fuse from 'fuse.js'

// -- Configure to match your use case --
const LIST_SIZE = 10_000
const KEYS = ['title', 'description', 'category', 'tags']
const QUERY = 'javascript'
const OPTIONS = { keys: KEYS, threshold: 0.4 }
const SEARCH_RUNS = 100

// -- Generate sample data --
const words = ['alpha', 'bravo', 'charlie', 'delta', 'echo', 'foxtrot',
  'golf', 'hotel', 'india', 'juliet', 'kilo', 'lima', 'mike', 'november',
  'oscar', 'papa', 'quebec', 'romeo', 'sierra', 'tango', 'uniform',
  'victor', 'whiskey', 'xray', 'yankee', 'zulu', 'javascript', 'typescript',
  'python', 'rust', 'golang', 'swift', 'kotlin', 'scala', 'elixir']

function randomSentence(len) {
  return Array.from({ length: len }, () =>
    words[Math.floor(Math.random() * words.length)]
  ).join(' ')
}

const list = Array.from({ length: LIST_SIZE }, () => ({
  title: randomSentence(4),
  description: randomSentence(12),
  category: randomSentence(2),
  tags: randomSentence(6)
}))

// -- Benchmark indexing --
const indexStart = performance.now()
const fuse = new Fuse(list, OPTIONS)
const indexTime = performance.now() - indexStart

// -- Benchmark search (average over multiple runs) --
const searchStart = performance.now()
for (let i = 0; i < SEARCH_RUNS; i++) {
  fuse.search(QUERY)
}
const searchTime = (performance.now() - searchStart) / SEARCH_RUNS

// -- Results --
console.log(`List size:    ${LIST_SIZE.toLocaleString()} items`)
console.log(`Keys:         ${KEYS.join(', ')}`)
console.log(`Index time:   ${indexTime.toFixed(2)}ms`)
console.log(`Search time:  ${searchTime.toFixed(2)}ms (avg over ${SEARCH_RUNS} runs)`)
console.log(`Results:      ${fuse.search(QUERY).length} matches`)
```

--------------------------------

### Combining Multiple Operators

Source: https://www.fusejs.io/extended-search.html

Demonstrates how to use AND, OR, and multiple operators within a single field query.

```javascript
// starts with "old" AND ends with "war"
fuse.search({ title: { $startsWith: 'old', $endsWith: 'war' } })

// starts with "old" OR ends with "war"   (=== string:  '^old | war$')
fuse.search({ title: { $or: [{ $startsWith: 'old' }, { $endsWith: 'war' }] } })

// fuzzy "old" AND fuzzy "war"   (=== string:  'old war')
fuse.search({ title: { $and: [{ $fuzzy: 'old' }, { $fuzzy: 'war' }] } })
```

--------------------------------

### FuseWorker Constructor

Source: https://www.fusejs.io/web-workers.html

Instantiate the worker with documents and configuration options.

```javascript
const fuse = new FuseWorker(docs, options?, workerOptions?)
```

--------------------------------

### Execute complex extended search queries

Source: https://www.fusejs.io/extended-search.html

Demonstrates combining logical operators and positional matching with extended search enabled.

```javascript
const books = [
  { title: "Old Man's War", author: 'John Scalzi' },
  { title: 'The Lock Artist', author: 'Steve Hamilton' },
  { title: 'Artist for Life', author: 'Michelangelo' }
]

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

// Starts with "Old" AND fuzzy match "war"
fuse.search('^Old war')

// Does NOT include "Artist" AND starts with "Old"
fuse.search('!Artist ^Old')

// Ends with "Artist" OR includes "War"
fuse.search("Artist$ | 'War")
```

--------------------------------

### Perform exact and prefix searches

Source: https://www.fusejs.io/extended-search.html

Use double quotes for exact phrase matching and the caret symbol for prefix matching.

```javascript
fuse.search('="scheme language"') // exact match for "scheme language"
fuse.search("'^hello world") // include-match for "hello world"
```

--------------------------------

### Combining Extended Search with Logical Queries

Source: https://www.fusejs.io/extended-search.html

Demonstrates using string-based extended search operators within a logical $and query.

```javascript
fuse.search({
  $and: [
    { title: '^Old' }, // title starts with "Old"
    { author: "'Scalzi" } // author includes "Scalzi"
  ]
})
```

--------------------------------

### Fuzzy Search Configuration Options

Source: https://www.fusejs.io/fuzzy-search.html

Configuration options to control matching behavior and scoring.

```APIDOC
## Configuration Options

### Fuzziness Control
- **threshold** (number) - Optional - The cutoff for the fuzziness score (0.0 to 1.0). Default: 0.6.
- **location** (number) - Optional - The expected position of the pattern in the text. Default: 0.
- **distance** (number) - Optional - Determines how far from the location a match can be before being penalized. Default: 100.
- **ignoreLocation** (boolean) - Optional - When true, disables location-based scoring. Default: false.

### Matching Options
- **isCaseSensitive** (boolean) - Optional - When true, comparisons are case-sensitive. Default: false.
- **ignoreDiacritics** (boolean) - Optional - When true, comparisons ignore diacritics. Default: false.
- **findAllMatches** (boolean) - Optional - When true, continues searching to the end of the text. Default: false.
- **minMatchCharLength** (number) - Optional - Minimum length of a match to be returned. Default: 1.

### Scoring Options
- **includeScore** (boolean) - Optional - When true, includes the match score in the results. Default: false.
- **ignoreFieldNorm** (boolean) - Optional - When true, field length has no effect on scoring. Default: false.
- **fieldNormWeight** (number) - Optional - Adjusts the strength of the field-length norm. Default: 1.
```

--------------------------------

### Simple client-side search with Fuse.js

Source: https://www.fusejs.io/articles/vs-semantic-search.html

An efficient approach for searching small datasets directly in the browser.

```javascript
// Simple: search 200 items in the browser in <1ms
const fuse = new Fuse(items, { keys: ['name', 'description'] })
const results = fuse.search(userInput)
```

--------------------------------

### Configure worker script path with import

Source: https://www.fusejs.io/web-workers.html

Use this approach when bundlers fail to resolve the worker script path automatically.

```javascript
import workerUrl from 'fuse.js/worker-script'

const fuse = new FuseWorker(docs, options, { workerUrl })
```

--------------------------------

### add(doc)

Source: https://www.fusejs.io/web-workers.html

Adds a document to the worker shards.

```APIDOC
## Method: add(doc)

### Description
Adds a single document to one of the worker shards using round-robin distribution.

### Parameters
- **doc** (Object) - Required - The document to add to the collection.
```

--------------------------------

### setCollection(docs)

Source: https://www.fusejs.io/web-workers.html

Replaces the entire dataset across all workers.

```APIDOC
## Method: setCollection(docs)

### Description
Replaces the entire dataset, redistributes it across workers, and rebuilds the indexes.

### Parameters
- **docs** (Array) - Required - The new array of documents.
```

--------------------------------

### Perform an OR logical search

Source: https://www.fusejs.io/logical-search.html

Matches documents that satisfy any of the provided clauses using short-circuit evaluation.

```javascript
const result = fuse.search({
  $or: [{ author: 'abc' }, { author: 'def' }]
})
```

--------------------------------

### Bitap Error Level State Visualization

Source: https://www.fusejs.io/articles/how-fuzzy-search-works.html

A visual representation of how the Bitap algorithm tracks errors across multiple state vectors when searching for 'test' in 'tset'.

```text
                   t  e  s  t
R0 (0 errors):     1  0  0  0   ← 't' matches, but 's' ≠ 'e' — exact match dies
R1 (1 error):      1  1  0  0   ← the mismatch continues here as 1 error
R2 (2 errors):     1  1  1  1   ← another mismatch, 2 errors — still matches!
```

--------------------------------

### Updating Collection

Source: https://www.fusejs.io/web-workers.html

Replace the entire dataset and rebuild indexes across workers.

```javascript
await fuse.setCollection(newDocs)
```

--------------------------------

### Initial State Vector Representation

Source: https://www.fusejs.io/articles/how-fuzzy-search-works.html

Representation of the initial state vector R.

```text
R0000
```

--------------------------------

### Combine Search Operators

Source: https://www.fusejs.io/extended-search.html

Use whitespace for AND logic and pipe characters for OR logic to create complex search queries.

```javascript
// Items that include "Man" AND "Old", OR end with "Artist"
fuse.search("'Man 'Old | Artist$")
```

--------------------------------

### Perform semantic search with embeddings

Source: https://www.fusejs.io/articles/vs-semantic-search.html

Demonstrates the conceptual workflow for semantic search using an embedding model and a vector database query.

```javascript
// Pseudocode — requires an embedding model + vector database
const embedding = await openai.embeddings.create({
  model: 'text-embedding-3-small',
  input: 'lightweight search library'
})

const results = await vectorDB.query({
  vector: embedding.data[0].embedding,
  topK: 5
})
```

--------------------------------

### fuse.search(query)

Source: https://www.fusejs.io/extended-search.html

Performs a search using extended search operators or object syntax. Object syntax allows for structured queries using $prefixed operators.

```APIDOC
## fuse.search(query)

### Description
Executes a search against the indexed data. Supports both string-based extended search operators and structured object queries.

### Parameters
- **query** (Object) - Required - The search query object containing keys and operators (e.g., { title: { $startsWith: 'old' } }).

### Supported Operators
- **$fuzzy**: Typo-tolerant (edit-distance) fuzzy match.
- **$eq**: The whole candidate string equals the value.
- **$contains**: Candidate contains the value (substring).
- **$startsWith**: Candidate starts with the value.
- **$endsWith**: Candidate ends with the value.
- **$not**: Negates an operator (only supports $contains, $startsWith, $endsWith).
- **$and**: ANDs multiple clauses.
- **$or**: ORs multiple clauses.

### Example
```javascript
// Structured object query
fuse.search({ title: { $startsWith: 'old' } });

// Logical combination
fuse.search({
  $and: [
    { category: { $eq: 'fiction' } },
    { $or: [{ title: { $startsWith: 'old' } }, { author: { $contains: 'scalzi' } }] }
  ]
});
```
```

--------------------------------

### Combining $not with Other Operators

Source: https://www.fusejs.io/extended-search.html

Shows how $not can be combined with other operators within the same field to create an AND condition.

```javascript
// starts with "old" AND does not contain "draft"
fuse.search({ title: { $startsWith: 'old', $not: { $contains: 'draft' } } })
```

--------------------------------

### Search with dotted keys

Source: https://www.fusejs.io/logical-search.html

Use $path and $val to query keys that contain literal dots.

```javascript
const books = [
  {
    title: "Old Man's War",
    author: { 'first.name': 'John', 'last.name': 'Scalzi' }
  }
]

const fuse = new Fuse(books, {
  keys: ['title', ['author', 'first.name'], ['author', 'last.name']]
})

const result = fuse.search({
  $and: [
    { $path: ['author', 'first.name'], $val: 'jon' },
    { $path: ['author', 'last.name'], $val: 'scazi' }
  ]
})
```

--------------------------------

### Performing Searches

Source: https://www.fusejs.io/web-workers.html

Execute asynchronous searches against the worker threads.

```javascript
const results = await fuse.search('query')
const limited = await fuse.search('query', { limit: 10 })
```

--------------------------------

### Combine logical search with extended search

Source: https://www.fusejs.io/logical-search.html

Enable useExtendedSearch to parse string values as extended search patterns within logical expressions.

```javascript
const fuse = new Fuse(books, {
  useExtendedSearch: true,
  keys: ['title', 'color']
})

const result = fuse.search({
  $and: [
    { title: 'old war' },      // fuzzy match "old war"
    { color: "'blue" },         // exact include "blue"
    {
      $or: [
        { title: '^lock' },     // starts with "lock"
        { title: '!arts' }      // does not contain "arts"
      ]
    }
  ]
})
```

--------------------------------

### Highlight search matches in React

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

Enables includeMatches in Fuse.js and uses a helper function to wrap matched character ranges in <mark> tags.

```jsx
import { useMemo, useState } from 'react'
import Fuse from 'fuse.js'

// Splits text into plain strings and <mark> elements based on match regions
function highlightMatches(text, regions = []) {
  if (!regions.length) return text

  const chunks = []
  let lastIndex = 0

  // Fuse.js returns sorted, non-overlapping [start, end] pairs
  for (const [start, end] of regions) {
    // Add any unmatched text before this region
    if (start > lastIndex) {
      chunks.push(text.slice(lastIndex, start))
    }
    // Wrap the matched range in a <mark> tag
    chunks.push(<mark key={start}>{text.slice(start, end + 1)}</mark>)
    lastIndex = end + 1
  }

  // Add any remaining text after the last match
  if (lastIndex < text.length) {
    chunks.push(text.slice(lastIndex))
  }

  return chunks
}

function BookSearch({ books }) {
  const [query, setQuery] = useState('')

  const fuse = useMemo(() => {
    return new Fuse(books, {
      keys: ['title', 'author'],
      includeMatches: true, // return character-level match positions
      threshold: 0.4,
    })
  }, [books])

  const results = query ? fuse.search(query) : []

  return (
    <div>
      <input
        type="text"
        placeholder="Search books..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <ul>
        {results.map(({ item, matches }) => {
          // Find match data for each field we want to highlight
          const titleMatch = matches?.find((m) => m.key === 'title')
          const authorMatch = matches?.find((m) => m.key === 'author')

          return (
            <li key={item.title}>
              {highlightMatches(item.title, titleMatch?.indices)} —{' '}
              {highlightMatches(item.author, authorMatch?.indices)}
            </li>
          )
        })}
      </ul>
    </div>
  )
}
```

```css
mark {
  background-color: #fef08a;
  padding: 0;
}
```

--------------------------------

### Enable Extended Search

Source: https://www.fusejs.io/extended-search.html

Initialize Fuse with the useExtendedSearch flag to enable support for magic character operators in query strings.

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

--------------------------------

### fuse.search(expression)

Source: https://www.fusejs.io/logical-search.html

Perform a logical search by passing an expression object to the search method.

```APIDOC
## fuse.search(expression)

### Description
Executes a search against the Fuse instance using a structured logical expression object.

### Parameters
- **expression** (Object) - Required - An object containing logical operators ($and, $or) or field-specific queries.

### Examples

#### Logical AND
```js
const result = fuse.search({
  $and: [{ author: 'abc' }, { title: 'xyz' }]
})
```

#### Logical OR
```js
const result = fuse.search({
  $or: [{ author: 'abc' }, { author: 'def' }]
})
```

#### Dotted Keys
```js
const result = fuse.search({
  $and: [
    { $path: ['author', 'first.name'], $val: 'jon' },
    { $path: ['author', 'last.name'], $val: 'scazi' }
  ]
})
```
```

--------------------------------

### Custom Function Tokenizer

Source: https://www.fusejs.io/token-search.html

Uses Intl.Segmenter for locale-aware word segmentation, useful for CJK scripts. The function must be deterministic and return an array of strings.

```javascript
const segmenter = new Intl.Segmenter('zh', { granularity: 'word' })

const fuse = new Fuse(docs, {
  useTokenSearch: true,
  keys: ['text'],
  tokenize: (text) =>
    Array.from(segmenter.segment(text), (s) => s.isWordLike ? s.segment : null)
      .filter(Boolean)
})
```

--------------------------------

### Mix object and string leaf queries

Source: https://www.fusejs.io/logical-search.html

Object queries do not require the useExtendedSearch flag, unlike string-based patterns.

```javascript
fuse.search({
  $or: [
    { title: { $startsWith: 'old' } }, // object leaf — no flag needed
    { title: '^new' }                  // string leaf — needs useExtendedSearch
  ]
})
```

--------------------------------

### terminate()

Source: https://www.fusejs.io/web-workers.html

Terminates all worker threads.

```APIDOC
## Method: terminate()

### Description
Terminates all active worker threads and cleans up resources. This should be called when the worker is no longer needed.
```

--------------------------------

### fuse.search(pattern)

Source: https://www.fusejs.io/fuzzy-search.html

Performs a fuzzy search against the indexed data using the provided pattern.

```APIDOC
## fuse.search(pattern)

### Description
Searches the indexed list for items that match the provided pattern based on the configured fuzzy search options.

### Parameters
- **pattern** (string) - Required - The search string to match against the indexed data.

### Response
- **Array** - An array of objects containing the matched item, its reference index, and the match score (if `includeScore` is enabled).
```

--------------------------------

### Limit search results

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

Reduces the number of returned results to improve rendering performance for large datasets.

```jsx
const results = query ? fuse.search(query, { limit: 20 }) : []
```

--------------------------------

### Custom Regex Tokenizer

Source: https://www.fusejs.io/token-search.html

Overrides the default tokenizer to preserve specific punctuation characters within tokens. The regex must include the global 'g' flag.

```javascript
const fuse = new Fuse(docs, {
  useTokenSearch: true,
  keys: ['text'],
  // keep dots, plusses, and dashes inside tokens
  tokenize: /[\w.+-]+/g
})

fuse.search('node.js') // matches docs containing the literal "node.js"
```

--------------------------------

### IDF Formula

Source: https://www.fusejs.io/token-search.html

The BM25 formula used to calculate IDF weights for terms.

```text
idf = log(1 + (fieldCount - docFreq + 0.5) / (docFreq + 0.5))
```

--------------------------------

### Nest logical operators

Source: https://www.fusejs.io/logical-search.html

Logical operators can be nested to create complex query structures.

```javascript
const result = fuse.search({
  $and: [
    { title: 'old war' },
    {
      $or: [
        { title: '^lock' },
        { title: '!arts' }
      ]
    }
  ]
})
```

--------------------------------

### Terminating Workers

Source: https://www.fusejs.io/web-workers.html

Clean up resources by terminating all active worker threads.

```javascript
fuse.terminate()
```

--------------------------------

### Debounce search input in React

Source: https://www.fusejs.io/articles/using-fuse-with-react.html

Uses a custom hook to delay search execution, preventing redundant processing during rapid keystrokes.

```jsx
import { useEffect, useMemo, useState } from 'react'
import Fuse from 'fuse.js'

// Delays updating the value until the user stops typing
function useDebounce(value, delay) {
  const [debounced, setDebounced] = useState(value)

  useEffect(() => {
    const timer = setTimeout(() => setDebounced(value), delay)
    return () => clearTimeout(timer) // reset timer on each keystroke
  }, [value, delay])

  return debounced
}

function BookSearch({ books }) {
  const [query, setQuery] = useState('')
  const debouncedQuery = useDebounce(query, 200) // wait 200ms after last keystroke

  // Rebuild the Fuse instance when the book list changes
  const fuse = useMemo(() => {
    return new Fuse(books, {
      keys: ['title', 'author'],
      threshold: 0.4,
    })
  }, [books])

  // Search only fires after debounce settles
  const results = debouncedQuery ? fuse.search(debouncedQuery) : []

  const displayItems = results.length > 0
    ? results.map(({ item }) => item)
    : books

  return (
    <div>
      <input
        type="text"
        placeholder="Search books..."
        value={query}
        onChange={(e) => setQuery(e.target.value)}
      />
      <ul>
        {displayItems.map((book) => (
          <li key={book.title}>
            {book.title} — {book.author}
          </li>
        ))}
      </ul>
    </div>
  )
}
```
Tokens:
Raw