Skip to content

Basic Usage ​

Building an index ​

Pass your item array and field configuration to createIndex. All items are indexed immediately at construction time.

ts
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.

ts
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:

ts
index.search(''); // All items, score = 1 each

Per-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.

ts
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.

ts
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():

ts
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 document

segmentWords() 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.

ts
// 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.

ts
// 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 });

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:

ts
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 ​

ts
{
  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:

ts
const search = createSearch(index, { debounce: 0 });

search.setQuery('alice');
console.log(search.getSnapshot().results); // Already updated
ts
search.clear(); // Resets query, results, and isSearching atomically

Composing with Ripple ​

A complete SearchState implements Ripple's structural subscribable contract:

ts
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.

ts
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(), and setItems() identify items by reference equality (===): pass retained object references from the current corpus, and setItems() collapses duplicate references. With a key, 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:

ts
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 ​

ts
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:

ts
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():

ts
const unsubscribe = index.subscribe(() => {
  rerenderResultsList();
});

index.add(newProduct); // triggers rerenderResultsList()

unsubscribe(); // when done

subscribe() 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(result, field, text) is the shorthand that does the field lookup and fragment split in one step:

ts
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:

ts
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:

ts
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:

ts
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.

ts
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 ​

tsx
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 };
}
ts
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 };
}
svelte
<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.

ts
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) with source.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.

ts
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, or index.setItems() with the refreshed collection. Stale index entries return wrong scores.
  • Set a key for immutable data: when updates create fresh objects, key: (item) => item.id lets setItems() skip unchanged items and removeKey() delete by id.
  • Tune threshold before limit: set a meaningful threshold (e.g. 0.25–0.4) to suppress noise, then use limit to cap the list length.
  • Set minQueryLength for your corpus size: the default 3 works 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 use using when the component unmounts.
  • Weight by importance: name/title fields should have weight 2–3; secondary fields (description, tags) stay at 1.
  • Segment CJK/Thai fields explicitly: segmentWords() is opt-in per field, not automatic, to keep createIndex() fast for the common whitespace-delimited case.