FuzzyIndex

A persistent fuzzy search index backed by Rust-side data.

Holds items in memory on the Rust side, avoiding repeated FFI overhead for applications that search the same dataset multiple times. Pre-computes the search representation of each item (a character mask, plus the UTF-32 text of non-ASCII items), eliminating per-search string conversion overhead. Memory is freed when the JavaScript garbage collector collects the instance or when destroy() is called explicitly.

Constructors

Constructor

new FuzzyIndex(items): FuzzyIndex

Create a new FuzzyIndex from an array of strings.

Parameters

Parameter	Type
items	readonly string[]

Returns

FuzzyIndex

Accessors

size

Get Signature

get size(): number

Return the number of items in the index.

Returns

number

Methods

add()

add(item): void

Add a single item to the index.

Parameters

Parameter	Type
item	string

Returns

void

---

addMany()

addMany(items): void

Add multiple items to the index at once.

Parameters

Parameter	Type
items	readonly string[]

Returns

void

---

closest()

closest(query, minScore?): string | null

Find the closest matching string in the index.

Returns the best match, or null if no match is found: the index’s copy of the item, converted to UTF-8 like SearchResult.item. If minScore is provided, returns null when the best match scores below the threshold. A NaN minScore throws an InvalidArg error.

Parameters

Parameter	Type
query	string
minScore?	number | null

Returns

string | null

---

destroy()

destroy(): void

Free the internal data. After calling this, the index is empty.

The index stays usable: it behaves as an empty index (searches return no results) and add() / addMany() work as before.

Returns

void

---

remove()

remove(index): boolean

Remove the item at the given index.

Uses swap-remove for O(1) performance: the last item moves into the freed slot. Returns false, removing nothing, if index is out of range (negative, or not less than size). Throws a TypeError if index is not a number and a RangeError if it is not an integer (NaN, ±Infinity or a fraction), like FuzzyObjectIndex.remove().

Parameters

Parameter	Type
index	number

Returns

boolean

---

search()

search(query, options?): SearchResult[]

Search the index for items matching the query.

Returns matches sorted by score (best match first). Scores are normalized to a 0.0-1.0 range where 1.0 is a perfect match.

Results are identical to search(query, items, options) over the same items, including the query syntax and whitespace rules.

The second argument accepts either a number (maxResults shorthand) or a SearchOptions object. maxResults must be a non-negative integer or Infinity.

Parameters

Parameter	Type
query	string
options?	number | SearchOptions | null

Returns

SearchResult[]

---

searchIndices()

searchIndices(query, options?): IndexSearchResult[]

Search the index, returning only indices and scores (no item strings).

This is more efficient than search() when you maintain your own data array and only need the index to look up the original item. Avoids String cloning overhead for each result.

The second argument accepts either a number (maxResults shorthand) or a SearchOptions object. maxResults must be a non-negative integer or Infinity.

Parameters

Parameter	Type
query	string
options?	number | SearchOptions | null

Returns

IndexSearchResult[]

---

serialize()

serialize(): Uint8Array

Serialize the index to a compact binary format.

The returned Buffer can be written to disk, stored in IndexedDB, or transferred over the network. Use FuzzyIndex.deserialize() to reconstruct the index.

The format stores the item strings (UTF-8, each with a 4-byte length) after a small header, not the precomputed search data: deserialize() recomputes it, so loading takes about as long as building the index from an array. The format is versioned; data written by a different format version is rejected.

Returns

Uint8Array

---

deserialize()

static deserialize(data): FuzzyIndex

Reconstruct a FuzzyIndex from a previously serialized Buffer, or any other Uint8Array holding the same bytes (such as the output of the browser build’s serialize()).

Pre-computes the search representation of the stored items, so the returned index is immediately ready for searching.

Parameters

Parameter	Type
data	Uint8Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike>

Returns

FuzzyIndex

---

fromAsync()

static fromAsync(items): Promise<FuzzyIndex>

Construct a FuzzyIndex on the libuv thread pool, returning a Promise.

For large datasets this keeps the JavaScript event loop unblocked during index construction. The synchronous constructor is fine for small datasets.

Invalid input (such as an array containing a non-string) rejects the returned Promise instead of throwing synchronously.

Parameters

Parameter	Type
items	readonly string[]

Returns

Promise<FuzzyIndex>