Skip to content
scout logoScoutUtilities
Trigram-indexed fuzzy search with per-field weights, match highlighting, and an optional reactive layer.
Version
v26.11.20
Size
4.1 KB gzip
BrowserNode ≥22SSRDeno
createIndexcreateSearchScoutConfigErrorScoutDisposedErrorScoutError View all 11 exports

Why Scout? ​

Arsenal's fuzzy / fuzzyFilter helpers perform pairwise Levenshtein distance: O(n·m) per item per query. For ≤200 items they are fine. For 500–100k items with real-time keystrokes, you need an index.

Scout builds a trigram inverted index at construction time. Query time scores only items sharing a trigram with the query; broad queries can still approach O(n), while selective queries avoid scoring the whole corpus.

ts
// Before
const matches = users.filter((user) => user.name.toLowerCase().includes(query.toLowerCase()));

// After
import { createIndex } from '@vielzeug/scout';

const index = createIndex(users, { fields: ['name', 'email'] });
const matches = index.search(query);
FeatureArsenal fuzzy*Scout createIndexFuse.js
Bundle size~3 KB4.1 KB~23 KB
Zero dependencies
AlgorithmLevenshteinTrigram + query coverageBitap
Query timeO(n·m)O(candidates)O(n·m)
Stateful index
Match highlighting
Reactive layerAtomic external-store snapshots + debounce
Incremental updatesPartial

Use Scout when you need search over 500+ items, real-time UI search boxes (combobox, command palette), or framework-neutral subscribable search state.

Consider arsenal.fuzzyFilter when you have fewer than 200 items and don't need a persistent index.

Installation ​

sh
pnpm add @vielzeug/scout
sh
npm install @vielzeug/scout
sh
yarn add @vielzeug/scout

Quick Start ​

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: [{ field: 'name', weight: 2 }, { field: 'email' }],
});

const results = index.search('ada');
console.log(results[0]?.item.name); // Ada Lovelace

Features ​

  • createIndex(): Trigram inverted index; construction O(corpus × field_length), query O(candidates)
  • Per-field weights: Promote name matches over secondary fields; finite positive weights and custom stringify functions supported
  • createSearch(): Reactive search state backed by a ScoutIndex; share one index across many states
  • highlight() / highlightField(): Split field text into HighlightPart[] fragments for styled rendering
  • findMatchRanges(): Compute match ranges for custom display strings (truncated previews, formatted values)
  • toSearchMatcher(): Matcher adapter for filtering in-memory collections with a ScoutIndex
  • toFilterPredicate(): Snapshot (item: T) => boolean predicate for Array.filter or vault queries
  • setItems(): Reconcile a refreshed corpus by key, preserve incoming order, and notify once
  • key option + removeKey(): Stable item identity for immutable data; skip unchanged work with fresh copies and delete by id
  • Incremental updates: add() / remove() / reindex() patch individual items in O(field_length)
  • subscribe(): Subscribe to index mutations; powers createSearch()'s reactivity and bulk reconciliation
  • segmentWords(): Split unsegmented-script text (CJK, Thai, ...) into words via native Intl.Segmenter

Documentation ​

See Also ​

  • Arsenal: Use fuzzyFilter for ad-hoc filtering of small lists (< 200 items) without building an index
  • Ripple: bridge a complete Scout SearchState with fromSubscribable() when composing a larger reactive graph
  • Sourcerer: use a ScoutIndex matcher to filter in-memory collections alongside remote sources
  • Vault: toFilterPredicate() wraps a one-time Scout query as a vault-compatible filter() predicate