Basic Usage
Building an index
Pass your item array and field configuration to createIndex. All items are indexed immediately at construction time.
import { createIndex } from '@vielzeug/scout';
const users = [
{ email: 'ada@example.com', name: 'Ada Lovelace' },
{ email: 'grace@example.com', name: 'Grace Hopper' },
];
const index = createIndex(users, {
fields: ['name', 'email'],
});Searching
Call index.search(query) with any string. Results are sorted by score descending.
const results = index.search('alice');
for (const { item, score, matches } of results) {
console.log(item.name, score);
}An empty query returns all items with score = 1:
index.search(''); // All items, score = 1 eachPer-field weights
Give fields different weights to control score ranking. A match on a high-weight field ranks the item higher than a match on a low-weight field.
const index = createIndex(users, {
fields: [
{ field: 'name', weight: 3 }, // name matches rank 3× higher
{ field: 'department', weight: 1 },
{ field: 'bio', weight: 0.5 },
],
});Non-string fields
Use stringify to convert numeric or boolean fields to searchable text.
const index = createIndex(products, {
fields: [
'title',
{ field: 'price', stringify: (v) => `$${v}` },
{ field: 'inStock', stringify: (v) => (v ? 'available in stock' : 'out of stock') },
],
});Non-Latin scripts (CJK, Thai, ...)
Scout's normalization indexes any script correctly: trigrams are generated per-character, so Chinese, Japanese, Cyrillic, and accented Latin text are all searchable out of the box. What it doesn't do is insert word boundaries for scripts that don't use spaces (Chinese, Japanese, Thai, ...), which affects findMatchRanges() / highlighting and multi-word phrase matching. Pre-segment those fields with segmentWords():
import { createIndex, segmentWords } from '@vielzeug/scout';
const docs = [{ title: '日本語を勉強しています' }, { title: '我喜欢学习中文' }];
const index = createIndex(docs, {
fields: [{ field: 'title', stringify: (v) => segmentWords(String(v)) }],
});
index.search('日本語'); // matches the first documentsegmentWords() uses the runtime's native Intl.Segmenter: no dependency. It's opt-in per field rather than built into the shared normalization because it benchmarks ~15x slower than the default regex path for ordinary whitespace-delimited text.
Limiting results
Pass limit, threshold, and minQueryLength in options to control result count and quality. limit must be a finite non-negative integer, threshold a finite value in 0..1, and minQueryLength a finite positive integer; invalid values throw ScoutConfigError.
// At most 10 results, minimum query-coverage score 0.3
const results = index.search('widget', { limit: 10, threshold: 0.3 });Per-call options override the index-level defaults set in createIndex.
Scores are query coverage: the fraction of the query's trigrams found in a field, scaled by that field's relative weight. 'fin' against 'Finalize Q3 roadmap' scores how much of the query was found (about 0.67), independent of how long the field is; conversely, a long query like 'tomato soup recipe' does not reward a field that merely contains part of it. Each item is also scored against the union of all its fields' text at the smallest field weight, so a cross-field query like 'alice smith' finds { first: 'Alice', last: 'Smith' } as well as one combined Alice Smith field.
Controlling short-query behaviour
Queries shorter than minQueryLength (default 3) fall back to an O(n) substring containment scan. Short-query matches return score = 1.0.
// Use trigram scoring even for 1-char queries (good for small corpora)
const index = createIndex(items, { fields: ['name'], minQueryLength: 1 });
// Force containment scan for all queries up to 8 chars (good for autocomplete on large sets)
const results = index.search('alice', { minQueryLength: 8 });Reactive Search
createSearch() wraps a ScoutIndex in one external store whose snapshot contains query, isSearching, and results. The index stays in your hands for incremental mutations, and one index can back several search stores:
import { createIndex, createSearch } from '@vielzeug/scout';
const index = createIndex(users, { fields: [{ field: 'name', weight: 2 }, 'email'] });
const search = createSearch(index, { debounce: 150 });
search.subscribe(() => {
const { isSearching, results } = search.getSnapshot();
if (isSearching) showLoadingSpinner();
else renderResults(results.map((result) => result.item));
});
input.addEventListener('input', (event) => {
search.setQuery((event.currentTarget as HTMLInputElement).value);
});
index.add(newUser); // the search state re-runs the committed query
search.dispose();Each notification observes a complete committed snapshot. During a debounce window, query contains the latest input, isSearching is true, and results remain the last committed results. Index mutations re-run the last committed query, so new items surface without another setQuery().
using declaration
{
using search = createSearch(index, { debounce: 150 });
// search.dispose() called automatically at scope exit
}Zero debounce for synchronous updates
Pass debounce: 0 for synchronous commits with no searching transition:
const search = createSearch(index, { debounce: 0 });
search.setQuery('alice');
console.log(search.getSnapshot().results); // Already updatedResetting search
search.clear(); // Resets query, results, and isSearching atomicallyComposing with Ripple
A complete SearchState implements Ripple's structural subscribable contract:
import { createRipple } from '@vielzeug/ripple';
const ripple = createRipple();
const state = ripple.fromSubscribable(search, { signal: search.disposalSignal });
const topResult = ripple.computed(() => state.value.results[0]?.item ?? null);Incremental Updates
Use add(), remove(), and reindex() for individual mutations. Use setItems() when a refreshed collection replaces the current corpus; Scout reconciles membership, current field values, and source order in one notification.
const index = createIndex(products, { fields: ['title'] });
// Add a newly created item
const newProduct = { id: 99, title: 'New Widget' };
index.add(newProduct);
// Remove a deleted item (by key; the default key is the reference)
index.remove(products[0]);
// Re-index a mutated item after in-place mutation
products[1].title = 'Updated Title';
index.reindex(products[1]);Without a
key,remove(),reindex(), andsetItems()identify items by reference equality (===): pass retained object references from the current corpus, andsetItems()collapses duplicate references. With akey, any object carrying the same key works: see Immutable data and stable keys.
Immutable data and stable keys
If your pipeline creates fresh objects on every update (framework stores, immutable reducers, mapped projections), pass a key that identifies each item across generations:
const index = createIndex(products, {
fields: ['title'],
key: (product) => product.id,
});
// setItems() with fresh copies of unchanged items: no reindex, no notification.
// Changed keys reindex only their changed fields; missing keys drop out.
index.setItems(await loadProducts()); // [{ id: 7, title: 'New title' }, ...]
// reindex() accepts any fresh object carrying the key:
index.reindex({ id: 7, title: 'Retitled' });
// Or delete by key directly, without fabricating a Product:
index.removeKey(7);Two different objects that share one key — inside a single setItems() call or the initial createIndex() corpus — throw ScoutConfigError. Search results always return the latest object stored for each key.
Replacing a refreshed corpus
const latestProducts = await loadProducts();
index.setItems(latestProducts);setItems() removes keys absent from latestProducts, indexes new keys, reindexes retained keys against their incoming objects, and adopts the incoming order. It notifies subscribe() listeners once, only when index membership, field text, or order changed.
Inspecting the corpus
Use .items to read all currently indexed items in insertion order, or .size for a count:
console.log(index.size); // 42
console.log(index.items); // [{ id: 1, title: ... }, ...]Reacting to mutations directly
createSearch() already keeps results in sync with add()/remove()/reindex()/setItems() internally. toSearchMatcher() also invalidates its query cache after index mutation. If you're building your own reactivity on top of a plain ScoutIndex (no ripple involved), subscribe with subscribe():
const unsubscribe = index.subscribe(() => {
rerenderResultsList();
});
index.add(newProduct); // triggers rerenderResultsList()
unsubscribe(); // when donesubscribe() only fires for mutations that actually change the index: a duplicate add() or a remove() of an unindexed item is a no-op and doesn't notify listeners.
Match Highlighting
Every SearchResult carries matches: per-field literal [start, end) ranges into the original field value. A fuzzy trigram candidate can have matches: [] when no literal query text appears in its field value.
highlightField(): recommended
highlightField(result, field, text) is the shorthand that does the field lookup and fragment split in one step:
import { highlightField } from '@vielzeug/scout';
for (const result of index.search('alice')) {
const parts = highlightField(result, 'name', result.item.name);
// [{ text: 'Alice', highlighted: true }, { text: ' Johnson', highlighted: false }]
renderHighlightedText(parts);
}part.text is unescaped
highlight() / highlightField() return the original, unescaped field text split into fragments: never concatenate part.text into an HTML string for innerHTML. Render each part as text (textContent, a framework's text binding) and wrap highlighted parts in your own element:
function renderHighlightedText(parts: HighlightPart[]): DocumentFragment {
const fragment = document.createDocumentFragment();
for (const part of parts) {
if (part.highlighted) {
const mark = document.createElement('mark');
mark.textContent = part.text; // textContent: never innerHTML
fragment.appendChild(mark);
} else {
fragment.appendChild(document.createTextNode(part.text));
}
}
return fragment;
}findMatchRanges() + highlight(): manual
Use findMatchRanges() when you need to apply match ranges to a different string than the indexed field value: for example a truncated preview or a differently formatted display string:
import { findMatchRanges, highlight } from '@vielzeug/scout';
const [result] = index.search('alice');
const preview = result.item.bio.slice(0, 100);
const ranges = findMatchRanges(preview, 'alice');
const parts = highlight(preview, ranges);Or use highlight() directly when you already have the ranges from result.matches:
const [result] = index.search('alice');
const nameMatch = result.matches.find((m) => m.field === 'name');
const parts = highlight(result.item.name, nameMatch?.ranges ?? []);Searchable Reference Lists
A glossary or compendium mixes entry kinds and needs direct-match ranking above fuzzy hits. Rank with rankEntries, render keyword links with splitPattern, and highlight the typed query with findMatchRanges + highlight.
import { dedupeEntries, escapeRegExp, findMatchRanges, highlight, rankEntries, splitPattern } from '@vielzeug/scout';
const keywordPattern = new RegExp(`(${keywords.map((k) => escapeRegExp(k.name)).join('|')})`, 'g');
const results = rankEntries(entries, query, { fuzzyIds: fuzzyIndexIds });
for (const entry of results) {
for (const segment of splitPattern(entry.text, keywordPattern)) {
if (segment.matched) renderKeywordLink(segment.text);
else for (const part of highlight(segment.text, findMatchRanges(segment.text, query))) renderMark(part);
}
}Dedupe merged catalogs with dedupeEntries before ranking so alias rows do not shadow their originals.
Framework Integration
import { createIndex, createSearch } from '@vielzeug/scout';
import { useEffect, useMemo, useSyncExternalStore } from 'react';
type User = { id: number; name: string; email: string };
function useScoutSearch(items: User[]) {
const search = useMemo(() => {
const index = createIndex(items, { fields: [{ field: 'name', weight: 2 }, 'email'] });
return createSearch(index, { debounce: 150 });
}, [items]);
const snapshot = useSyncExternalStore(search.subscribe, search.getSnapshot, search.getSnapshot);
useEffect(() => () => search.dispose(), [search]);
return { ...snapshot, setQuery: search.setQuery };
}import { createIndex, createSearch } from '@vielzeug/scout';
import { onScopeDispose, shallowRef } from 'vue';
type User = { id: number; name: string; email: string };
function useScoutSearch(items: User[]) {
const index = createIndex(items, { fields: [{ field: 'name', weight: 2 }, 'email'] });
const search = createSearch(index, { debounce: 150 });
const snapshot = shallowRef(search.getSnapshot());
const stop = search.subscribe(() => {
snapshot.value = search.getSnapshot();
});
onScopeDispose(() => {
stop();
search.dispose();
});
return { search, snapshot };
}<script lang="ts">
import { createIndex, createSearch } from '@vielzeug/scout';
import { onDestroy } from 'svelte';
type User = { id: number; name: string; email: string };
export let items: User[];
const index = createIndex(items, { fields: [{ field: 'name', weight: 2 }, 'email'] });
const search = createSearch(index, { debounce: 150 });
let snapshot = search.getSnapshot();
const stop = search.subscribe(() => { snapshot = search.getSnapshot(); });
onDestroy(() => { stop(); search.dispose(); });
</script>
<input value={snapshot.query} on:input={(event) => search.setQuery(event.currentTarget.value)} placeholder="Search…" />
{#each snapshot.results as { item }}
<p>{item.name}</p>
{/each}Working with Other Vielzeug Libraries
With Sourcerer
toSearchMatcher() adapts a ScoutIndex into Sourcerer's local-source filter.
import { createIndex, toSearchMatcher } from '@vielzeug/scout';
import { createLocalSource } from '@vielzeug/sourcerer';
const index = createIndex(users, {
fields: [{ field: 'name', weight: 2 }, 'email'],
});
const source = createLocalSource(users, { filter: toSearchMatcher(index), params: '' });
source.setParams('alice');
console.log(source.state.items);Update the index and source from the same collection change. Use
index.setItems(items)withsource.setItems(items)for replacement collections.
With Vault
toFilterPredicate() returns an (item: T) => boolean snapshot predicate: pass it to vault's query.filter() or plain Array.filter.
import { createIndex, toFilterPredicate } from '@vielzeug/scout';
const index = createIndex(products, { fields: ['title', 'sku'] });
const matching = products.filter(toFilterPredicate(index, 'widget'));
const rows = await db.query('products').filter(toFilterPredicate(index, searchTerm)).toArray();Call toFilterPredicate again whenever the query or corpus changes: the predicate is a snapshot, not reactive.
Best Practices
- Build the index once:
createIndex()runs in O(corpus × field_length). Create it at module level or in an effect, not inside render loops. - Keep the index in sync: call
index.add()/remove()/reindex()when items mutate, orindex.setItems()with the refreshed collection. Stale index entries return wrong scores. - Set a
keyfor immutable data: when updates create fresh objects,key: (item) => item.idletssetItems()skip unchanged items andremoveKey()delete by id. - Tune threshold before limit: set a meaningful
threshold(e.g.0.25–0.4) to suppress noise, then uselimitto cap the list length. - Set
minQueryLengthfor your corpus size: the default3works well for most cases. Lower it for small corpora where single-char queries are expected; raise it for large corpora to avoid expensive O(n) scans. - Dispose reactive state: always call
search.dispose()or useusingwhen the component unmounts. - Weight by importance: name/title fields should have weight
2–3; secondary fields (description, tags) stay at1. - Segment CJK/Thai fields explicitly:
segmentWords()is opt-in per field, not automatic, to keepcreateIndex()fast for the common whitespace-delimited case.