FuzzyObjectIndex

A persistent fuzzy search index for object collections with weighted keys.

Pre-computes key texts and stores them on the Rust side for fast repeated searches. Use this when searching the same collection multiple times.

The type parameters after T only capture the key names passed to the constructor so they can be checked against T; annotate variables as FuzzyObjectIndex<T>.

Example

const index = new FuzzyObjectIndex(users, {
  keys: [{ name: 'name', weight: 2.0 }, 'email'],
});

const results = index.search('john');
// results[0].item → { name: 'John Smith', ... }

index.add({ name: 'New User', email: 'new@example.com' });
index.destroy(); // free Rust-side memory

Type Parameters

Type Parameter	Default type
T	-
S extends string	string
C extends string	string

Constructors

Constructor

new FuzzyObjectIndex<T, S, C>(items, options): FuzzyObjectIndex<T, S, C>

Parameters

Parameter	Type
items	readonly T[]
options	CheckedOptions<T, S, C, unknown>

Returns

FuzzyObjectIndex<T, S, C>

Throws

If items is not an array or options.keys is not a non-empty array of key paths / key configs.

Accessors

size

Get Signature

get size(): number

Number of items in the index.

Returns

number

Methods

add()

add(item): void

Add a single item to the index.

Parameters

Parameter	Type
item	T

Returns

void

---

addMany()

addMany(items): void

Add multiple items at once. If reading a key of any item throws, no item is added.

Parameters

Parameter	Type
items	readonly T[]

Returns

void

---

closest()

closest(query, options?): T | null

Find the closest matching object, or null if no match: the item of the first result of search(query, { maxResults: 1, minScore, scoreMode, matchMode }).

The second argument accepts a number (minScore shorthand) or a KeyClosestOptions object, whose scoreMode defaults to 'weighted' and matchMode to 'perKey'.

Parameters

Parameter	Type
query	string
options?	number | KeyClosestOptions | null

Returns

T | null

Example

index.closest('smith', 0.9); // minScore 0.9
index.closest('smith', { minScore: 0.9, scoreMode: 'matched' });
index.closest('john tokyo', { scoreMode: 'max', matchMode: 'crossKey' });

Throws

If options is neither a number nor an object.

Throws

If scoreMode is not 'weighted', 'matched' or 'max', matchMode is not 'perKey' or 'crossKey', or minScore is not a number or is NaN (a TypeError in the browser build).

---

destroy()

destroy(): void

Remove all items and free their Rust-side memory.

The index stays usable: afterwards it behaves as an empty index, and add() / addMany() work as usual.

Returns

void

---

remove()

remove(index): boolean

Remove the item at the given position (swap-remove semantics: the last item moves into the freed slot, so its index changes).

Returns false when index is out of range.

Parameters

Parameter	Type
index	number

Returns

boolean

Throws

If index is not a number.

Throws

If index is not an integer (e.g. NaN or 1.5).

---

search()

search(query, options?): ObjectSearchResult<T>[]

Search for objects matching the query.

The second argument accepts a number (maxResults shorthand) or an options object, like FuzzyIndex.search().

Parameters

Parameter	Type
query	string
options?	number | ObjectIndexSearchOptions | null

Returns

ObjectSearchResult<T>[]

Throws

If options is neither a number nor an object.

---

serialize()

serialize(): Uint8Array

Serialize the index and its items to a Buffer (NodeBuffer: a Uint8Array in TypeScript programs without the Node.js types).

Items must be JSON-serializable. Pass the result to FuzzyObjectIndex.deserialize() to reconstruct the index.

Returns

Uint8Array

---

deserialize()

static deserialize<T>(data): FuzzyObjectIndex<T>

Reconstruct a FuzzyObjectIndex from data produced by serialize(): a Buffer, any other ArrayBufferView (e.g. Uint8Array) or an ArrayBuffer.

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type
data	ArrayBufferLike | ArrayBufferView<ArrayBufferLike>

Returns

FuzzyObjectIndex<T>

Throws

If data is not binary data.

Throws

If data is malformed (the message starts with "Invalid FuzzyObjectIndex data").