@vielzeug/scout 2.4.0 → 3.0.0

package/README.md

@@ -1,25 +1,16 @@
 # @vielzeug/scout
 
-Fast fuzzy-search. Builds a trigram inverted index at construction — O(candidates) per query instead of O(corpus × field_length).
+> Trigram fuzzy-search index with highlighting and reactive layer
 
-## Features
-
-- **Trigram index** — fast candidate lookup; overlap-coefficient scoring
-- **Multi-field weighted ranking** — per-field weights, custom stringifiers
-- **Match highlighting** — character-range offsets for UI rendering
-- **Reactive layer** — `createSearch()` wraps any index in `ripple` signals with debounce
-- **Framework adapters** — `toSearchMatcher()` for sourcerer, `toFilterPredicate()` for filter pipelines
-- **Corpus reconciliation** — `setItems()` reconciles reference-based additions, removals, reindexes, and order in one notification
-- **Unsegmented-script helper** — `segmentWords()` pre-splits CJK/Thai text into words via `Intl.Segmenter`
-- **Event subscription** — `search.tap()` observes `query`/`isSearching`/`results`/`dispose` transitions
-
-## Install
+## Installation
 
 ```sh
 pnpm add @vielzeug/scout
+npm install @vielzeug/scout
+yarn add @vielzeug/scout
 ```
 
-## Quick start
+## Quick Start
 
 ```ts
 import { createIndex } from '@vielzeug/scout';
@@ -39,39 +30,14 @@ const index = createIndex(users, {
 console.log(index.search('ada')[0]?.item.name); // Ada Lovelace
 ```
 
-## Reactive search
-
-```ts
-import { createIndex, createSearch } from '@vielzeug/scout';
-import { effect } from '@vielzeug/ripple';
-
-const users = [{ name: 'Ada Lovelace' }, { name: 'Grace Hopper' }];
-const index = createIndex(users, { fields: ['name'] });
-const search = createSearch(index, { debounce: 150 });
-
-effect(() => {
-  console.log(search.results.value);
-});
-
-search.query.value = 'alice';
-```
-
-## Sourcerer integration
-
-```ts
-import { createIndex, toSearchMatcher } from '@vielzeug/scout';
-import { createLocalSource } from '@vielzeug/sourcerer';
-
-const users = [{ email: 'ada@example.com', name: 'Ada Lovelace' }];
-const index = createIndex(users, { fields: ['name', 'email'] });
-const source = createLocalSource(users, { match: toSearchMatcher(index) });
-```
+## Documentation
 
-## Highlighting
+- [Overview](https://vielzeug.dev/scout/)
+- [Usage Guide](https://vielzeug.dev/scout/usage)
+- [API Reference](https://vielzeug.dev/scout/api)
+- [Examples](https://vielzeug.dev/scout/examples)
+- [Migration Guide](https://vielzeug.dev/scout/migration)
 
-```ts
-import { highlight } from '@vielzeug/scout';
+## License
 
-const parts = highlight('Hello World', [[0, 5]]);
-// [{ text: 'Hello', highlighted: true }, { text: ' World', highlighted: false }]
-```
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/index.d.ts

@@ -6,5 +6,5 @@ export { createReactiveSearch, createSearch } from './reactive';
 export type { ScoutIndex } from './scout-index';
 export { createIndex } from './scout-index';
 export { segmentWords } from './segment';
-export type { CreateSearchOptions, FieldDef, FieldMatch, HighlightPart, ScoutIndexOptions, SearchConstraints, SearchResult, SearchState, } from './types';
+export type { CreateSearchOptions, FieldDef, FieldMatch, HighlightPart, ScoutEvent, ScoutIndexOptions, SearchConstraints, SearchResult, SearchSnapshot, SearchState, SearchSubscribeOptions, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,sBAAsB,GACvB,MAAM,SAAS,CAAC"}

package/dist/reactive.cjs

@@ -1,2 +1,2 @@
-const e=require("./errors.cjs"),t=require("./scout-index.cjs");let n=require("@vielzeug/ripple");var r=200;function i(t,i={}){let{debounce:a=r,limit:o,minQueryLength:s,threshold:c}=i;if(!Number.isFinite(a)||!Number.isInteger(a)||a<0)throw new e.ScoutConfigurationError(`debounce must be a finite non-negative integer.`);let l=(0,n.signal)(``,{name:`scout:query`}),u=(0,n.signal)(``,{name:`scout:committedQuery`}),d=(0,n.signal)(0,{name:`scout:indexVersion`}),f=t.onMutate(()=>{d.value++}),p=(0,n.computed)(()=>l.value!==u.value,{name:`scout:isSearching`}),m=(0,n.computed)(()=>(d.value,t.search(u.value,{limit:o,minQueryLength:s,threshold:c})),{name:`scout:results`}),h=null;function g(){h!==null&&(clearTimeout(h),h=null)}let _=l.subscribe(()=>{let e=l.peek();if(g(),e!==u.peek()){if(a===0){u.value=e;return}h=setTimeout(()=>{u.value=e,h=null},a)}});function v(){if(y)throw new e.ScoutDisposedError(`SearchState.clear() called after dispose()`);g(),(0,n.batch)(()=>{l.value=``,u.value=``})}let y=!1,b=new AbortController;function x(){y||(y=!0,b.abort(),g(),_(),f())}return{clear:v,get disposalSignal(){return b.signal},dispose:x,get disposed(){return y},isSearching:p,query:l,results:m,[Symbol.dispose](){x()}}}function a(e,n){let r=t.createIndex(e,{fields:n.fields,limit:n.limit,minQueryLength:n.minQueryLength,threshold:n.threshold}),a=i(r,{debounce:n.debounce});return{clear:a.clear,get disposalSignal(){return a.disposalSignal},dispose:a.dispose,get disposed(){return a.disposed},index:r,isSearching:a.isSearching,query:a.query,results:a.results,[Symbol.dispose](){a[Symbol.dispose]()}}}exports.createReactiveSearch=a,exports.createSearch=i;
+const e=require("./errors.cjs"),t=require("./scout-index.cjs");var n=200;function r(e){for(let t of[...e])try{t()}catch(e){queueMicrotask(()=>{throw e})}}function i(e,t){if(e.size!==0)for(let n of[...e])try{n(t)}catch{}}function a(e,t,n,r,i){if(r||n?.signal?.aborted)return()=>{};e.add(t);let a=()=>{e.delete(t),n?.signal?.removeEventListener(`abort`,a)};return n?.signal?.addEventListener(`abort`,a,{once:!0,signal:i}),a}function o(t,o={}){let{debounce:s=n,limit:c,minQueryLength:l,threshold:u}=o;if(!Number.isSafeInteger(s)||s<0)throw new e.ScoutConfigurationError(`debounce must be a finite non-negative integer.`);let d=e=>t.search(e,{limit:c,minQueryLength:l,threshold:u}),f=(e,t,n)=>Object.freeze({isSearching:t,query:e,results:Object.freeze(n)}),p=new Set,m=new Set,h=new AbortController,g=f(``,!1,d(``)),_=``,v=!1,y,b=e=>{g=e,r(p),i(m,{snapshot:e,type:`state-change`})},x=e=>{_=e,b(f(e,!1,d(e)))},S=t.onMutate(()=>{b(f(g.query,g.isSearching,d(_)))}),C=t=>{if(v)throw new e.ScoutDisposedError(`SearchState.${t}() called after dispose()`)},w=()=>{v||(v=!0,y!==void 0&&clearTimeout(y),y=void 0,S(),i(m,{type:`dispose`}),p.clear(),m.clear(),h.abort())};return{clear(){C(`clear`),(g.query!==``||g.isSearching)&&(y!==void 0&&clearTimeout(y),y=void 0,x(``))},get disposalSignal(){return h.signal},dispose:w,get disposed(){return v},getSnapshot(){return g},setQuery(e){if(C(`setQuery`),e!==g.query){if(y!==void 0&&clearTimeout(y),y=void 0,e===_){b(f(e,!1,g.results));return}if(s===0){x(e);return}b(f(e,!0,g.results)),y=setTimeout(()=>{y=void 0,x(e)},s)}},subscribe(e,t){return a(p,e,t,v,h.signal)},tap(e,t){return a(m,e,t,v,h.signal)},[Symbol.dispose]:w}}function s(e,n){let r=t.createIndex(e,n),i=o(r,n);return{clear:i.clear,get disposalSignal(){return i.disposalSignal},dispose:i.dispose,get disposed(){return i.disposed},getSnapshot:i.getSnapshot,index:r,setQuery:i.setQuery,subscribe:i.subscribe,tap:i.tap,[Symbol.dispose]:i[Symbol.dispose]}}exports.createReactiveSearch=s,exports.createSearch=o;
 //# sourceMappingURL=reactive.cjs.map

package/dist/reactive.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.cjs","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    if (isDisposed) return;\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return {\n    clear: state.clear,\n    get disposalSignal() {\n      return state.disposalSignal;\n    },\n    dispose: state.dispose,\n    get disposed() {\n      return state.disposed;\n    },\n    index,\n    isSearching: state.isSearching,\n    query: state.query,\n    results: state.results,\n    [Symbol.dispose]() {\n      state[Symbol.dispose]();\n    },\n  };\n}\n"],"mappings":"iGAaA,IAAM,EAAmB,IAsCzB,SAAgB,EAAgB,EAAsB,EAA+B,CAAC,EAAmB,CACvG,GAAM,CAAE,SAAU,EAAa,EAAkB,QAAO,iBAAgB,aAAc,EAEtF,GAAI,CAAC,OAAO,SAAS,CAAU,GAAK,CAAC,OAAO,UAAU,CAAU,GAAK,EAAa,EAChF,MAAM,IAAI,EAAA,wBAAwB,iDAAiD,EAGrF,IAAM,GAAA,EAAQ,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,aAAc,CAAC,EAClD,GAAA,EAAiB,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,sBAAuB,CAAC,EACpE,GAAA,EAAe,EAAA,OAAA,CAAO,EAAG,CAAE,KAAM,oBAAqB,CAAC,EAEvD,EAAuB,EAAM,aAAe,CAChD,EAAa,OACf,CAAC,EAEK,GAAA,EAAc,EAAA,SAAA,KAAe,EAAM,QAAU,EAAe,MAAO,CAAE,KAAM,mBAAoB,CAAC,EAEhG,GAAA,EAAU,EAAA,SAAA,MAGZ,EAAkB,MAEX,EAAM,OAAO,EAAe,MAAO,CAAE,QAAO,iBAAgB,WAAU,CAAC,GAEhF,CAAE,KAAM,eAAgB,CAC1B,EAEI,EAA8C,KAElD,SAAS,GAAoB,CACvB,IAAU,OACZ,aAAa,CAAK,EAClB,EAAQ,KAEZ,CAEA,IAAM,EAAe,EAAM,cAAgB,CACzC,IAAM,EAAI,EAAM,KAAK,EAErB,KAAY,EAER,IAAM,EAAe,KAAK,EAE9B,IAAI,IAAe,EAAG,CACpB,EAAe,MAAQ,EAEvB,MACF,CAEA,EAAQ,eAAiB,CACvB,EAAe,MAAQ,EACvB,EAAQ,IACV,EAAG,CAAU,CALb,CAMF,CAAC,EAED,SAAS,GAAc,CACrB,GAAI,EAAY,MAAM,IAAI,EAAA,mBAAmB,4CAA4C,EAEzF,EAAY,GAEZ,EAAA,EAAA,MAAA,KAAY,CACV,EAAM,MAAQ,GACd,EAAe,MAAQ,EACzB,CAAC,CACH,CAEA,IAAI,EAAa,GACX,EAAK,IAAI,gBAEf,SAAS,GAAgB,CACnB,IACJ,EAAa,GACb,EAAG,MAAM,EACT,EAAY,EACZ,EAAa,EACb,EAAqB,EACvB,CAEA,MAAO,CACL,QACA,IAAI,gBAA8B,CAChC,OAAO,EAAG,MACZ,EACA,UACA,IAAI,UAAoB,CACtB,OAAO,CACT,EACA,cACA,QACA,UACA,CAAC,OAAO,UAAiB,CACvB,EAAQ,CACV,CACF,CACF,CA4BA,SAAgB,EACd,EACA,EACmB,CACnB,IAAM,EAAQ,EAAA,YAAY,EAAO,CAC/B,OAAQ,EAAQ,OAChB,MAAO,EAAQ,MACf,eAAgB,EAAQ,eACxB,UAAW,EAAQ,SACrB,CAAC,EACK,EAAQ,EAAa,EAAO,CAAE,SAAU,EAAQ,QAAS,CAAC,EAEhE,MAAO,CACL,MAAO,EAAM,MACb,IAAI,gBAAiB,CACnB,OAAO,EAAM,cACf,EACA,QAAS,EAAM,QACf,IAAI,UAAW,CACb,OAAO,EAAM,QACf,EACA,QACA,YAAa,EAAM,YACnB,MAAO,EAAM,MACb,QAAS,EAAM,QACf,CAAC,OAAO,UAAW,CACjB,EAAM,OAAO,QAAQ,CAAC,CACxB,CACF,CACF"}
+{"version":3,"file":"reactive.cjs","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type {\n  CreateSearchOptions,\n  ScoutEvent,\n  ScoutIndexOptions,\n  SearchResult,\n  SearchSnapshot,\n  SearchState,\n  SearchSubscribeOptions,\n} from './types';\n\nexport type ReactiveSearch<T> = SearchState<T> & { readonly index: ScoutIndex<T> };\n\nconst DEFAULT_DEBOUNCE = 200;\n\nfunction notify(listeners: Set<() => void>): void {\n  for (const listener of [...listeners]) {\n    try {\n      listener();\n    } catch (error) {\n      queueMicrotask(() => {\n        throw error;\n      });\n    }\n  }\n}\n\nfunction emit<T>(tappers: Set<(event: ScoutEvent<T>) => void>, event: ScoutEvent<T>): void {\n  if (tappers.size === 0) return;\n\n  for (const tapper of [...tappers]) {\n    try {\n      tapper(event);\n    } catch {}\n  }\n}\n\nfunction subscribe<T>(\n  listeners: Set<T>,\n  listener: T,\n  options: SearchSubscribeOptions | undefined,\n  disposed: boolean,\n  lifetimeSignal: AbortSignal,\n): () => void {\n  if (disposed || options?.signal?.aborted) return () => {};\n\n  listeners.add(listener);\n  const unsubscribe = (): void => {\n    listeners.delete(listener);\n    options?.signal?.removeEventListener('abort', unsubscribe);\n  };\n  options?.signal?.addEventListener('abort', unsubscribe, { once: true, signal: lifetimeSignal });\n  return unsubscribe;\n}\n\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isSafeInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const search = (query: string) => index.search(query, { limit, minQueryLength, threshold });\n  const createSnapshot = (\n    query: string,\n    isSearching: boolean,\n    results: ReadonlyArray<SearchResult<T>>,\n  ): SearchSnapshot<T> => Object.freeze({ isSearching, query, results: Object.freeze(results) });\n  const listeners = new Set<() => void>();\n  const tappers = new Set<(event: ScoutEvent<T>) => void>();\n  const controller = new AbortController();\n  let snapshot = createSnapshot('', false, search(''));\n  let committedQuery = '';\n  let disposed = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  const publish = (next: SearchSnapshot<T>): void => {\n    snapshot = next;\n    notify(listeners);\n    emit(tappers, { snapshot: next, type: 'state-change' });\n  };\n  const commit = (query: string): void => {\n    committedQuery = query;\n    publish(createSnapshot(query, false, search(query)));\n  };\n  const unsubscribeIndex = index.onMutate(() => {\n    publish(createSnapshot(snapshot.query, snapshot.isSearching, search(committedQuery)));\n  });\n  const assertActive = (method: string): void => {\n    if (disposed) throw new ScoutDisposedError(`SearchState.${method}() called after dispose()`);\n  };\n  const dispose = (): void => {\n    if (disposed) return;\n    disposed = true;\n    if (timer !== undefined) clearTimeout(timer);\n    timer = undefined;\n    unsubscribeIndex();\n    emit(tappers, { type: 'dispose' });\n    listeners.clear();\n    tappers.clear();\n    controller.abort();\n  };\n\n  return {\n    clear() {\n      assertActive('clear');\n      if (snapshot.query === '' && !snapshot.isSearching) return;\n      if (timer !== undefined) clearTimeout(timer);\n      timer = undefined;\n      commit('');\n    },\n    get disposalSignal() {\n      return controller.signal;\n    },\n    dispose,\n    get disposed() {\n      return disposed;\n    },\n    getSnapshot() {\n      return snapshot;\n    },\n    setQuery(query) {\n      assertActive('setQuery');\n      if (query === snapshot.query) return;\n      if (timer !== undefined) clearTimeout(timer);\n      timer = undefined;\n\n      if (query === committedQuery) {\n        publish(createSnapshot(query, false, snapshot.results));\n        return;\n      }\n\n      if (debounceMs === 0) {\n        commit(query);\n        return;\n      }\n\n      publish(createSnapshot(query, true, snapshot.results));\n      timer = setTimeout(() => {\n        timer = undefined;\n        commit(query);\n      }, debounceMs);\n    },\n    subscribe(listener, subscribeOptions) {\n      return subscribe(listeners, listener, subscribeOptions, disposed, controller.signal);\n    },\n    tap(handler, tapOptions) {\n      return subscribe(tappers, handler, tapOptions, disposed, controller.signal);\n    },\n    [Symbol.dispose]: dispose,\n  };\n}\n\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, options);\n  const state = createSearch(index, options);\n\n  return {\n    clear: state.clear,\n    get disposalSignal() {\n      return state.disposalSignal;\n    },\n    dispose: state.dispose,\n    get disposed() {\n      return state.disposed;\n    },\n    getSnapshot: state.getSnapshot,\n    index,\n    setQuery: state.setQuery,\n    subscribe: state.subscribe,\n    tap: state.tap,\n    [Symbol.dispose]: state[Symbol.dispose],\n  };\n}\n"],"mappings":"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"}

package/dist/reactive.d.ts

@@ -1,74 +1,8 @@
 import { type ScoutIndex } from './scout-index';
 import type { CreateSearchOptions, ScoutIndexOptions, SearchState } from './types';
-/**
- * Combined index + reactive search state returned by `createReactiveSearch()`.
- * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).
- */
 export type ReactiveSearch<T> = SearchState<T> & {
     readonly index: ScoutIndex<T>;
 };
-/**
- * Creates a reactive search state backed by a `ScoutIndex`.
- *
- * - Set `state.query.value` to trigger a (debounced) search.
- * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.
- * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.
- * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.
- *
- * @example
- * ```ts
- * const index = createIndex(users, { fields: ['name', 'email'] });
- * const search = createSearch(index, { debounce: 150 });
- *
- * effect(() => {
- *   const results = search.results.value;
- *   renderList(results.map(r => r.item));
- * });
- *
- * // Wire to an input
- * input.addEventListener('input', e => {
- *   search.query.value = e.currentTarget.value;
- * });
- *
- * // Clean up
- * search.dispose();
- * ```
- *
- * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`
- * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.
- *
- * @param index - A `ScoutIndex` built with `createIndex()`.
- * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.
- * @param options.limit - Override the index-level result limit.
- * @param options.minQueryLength - Override the index-level minimum query length.
- * @param options.threshold - Override the index-level score threshold.
- */
 export declare function createSearch<T>(index: ScoutIndex<T>, options?: CreateSearchOptions): SearchState<T>;
-/**
- * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand
- * for the common pattern of `createIndex` + `createSearch`.
- *
- * The returned `ReactiveSearch` exposes the underlying index via `.index` for
- * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.
- *
- * @example
- * ```ts
- * const search = createReactiveSearch(users, {
- *   fields: [{ field: 'name', weight: 2 }, 'email'],
- *   debounce: 150,
- * });
- *
- * effect(() => renderList(search.results.value.map(r => r.item)));
- *
- * // Wire to an input
- * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });
- *
- * // Add a new item at runtime
- * search.index.add(newUser);
- * ```
- *
- * @param items - Initial corpus to index.
- * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.
- */
 export declare function createReactiveSearch<T>(items: T[], options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>): ReactiveSearch<T>;
 //# sourceMappingURL=reactive.d.ts.map

package/dist/reactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAgB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEjG;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAC/C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC/B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAAC,CAAC,CAAC,CA8FvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,GACpE,cAAc,CAAC,CAAC,CAAC,CA0BnB"}
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EACV,mBAAmB,EAEnB,iBAAiB,EAGjB,WAAW,EAEZ,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC;AA4CnF,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAAC,CAAC,CAAC,CAgGvG;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,GACpE,cAAc,CAAC,CAAC,CAAC,CAoBnB"}

package/dist/reactive.js

@@ -1,67 +1,97 @@
 import { ScoutConfigurationError as e, ScoutDisposedError as t } from "./errors.js";
 import { createIndex as n } from "./scout-index.js";
-import { batch as r, computed as i, signal as a } from "@vielzeug/ripple";
 //#region src/reactive.ts
-var o = 200;
+var r = 200;
+function i(e) {
+	for (let t of [...e]) try {
+		t();
+	} catch (e) {
+		queueMicrotask(() => {
+			throw e;
+		});
+	}
+}
+function a(e, t) {
+	if (e.size !== 0) for (let n of [...e]) try {
+		n(t);
+	} catch {}
+}
+function o(e, t, n, r, i) {
+	if (r || n?.signal?.aborted) return () => {};
+	e.add(t);
+	let a = () => {
+		e.delete(t), n?.signal?.removeEventListener("abort", a);
+	};
+	return n?.signal?.addEventListener("abort", a, {
+		once: !0,
+		signal: i
+	}), a;
+}
 function s(n, s = {}) {
-	let { debounce: c = o, limit: l, minQueryLength: u, threshold: d } = s;
-	if (!Number.isFinite(c) || !Number.isInteger(c) || c < 0) throw new e("debounce must be a finite non-negative integer.");
-	let f = a("", { name: "scout:query" }), p = a("", { name: "scout:committedQuery" }), m = a(0, { name: "scout:indexVersion" }), h = n.onMutate(() => {
-		m.value++;
-	}), g = i(() => f.value !== p.value, { name: "scout:isSearching" }), _ = i(() => (m.value, n.search(p.value, {
+	let { debounce: c = r, limit: l, minQueryLength: u, threshold: d } = s;
+	if (!Number.isSafeInteger(c) || c < 0) throw new e("debounce must be a finite non-negative integer.");
+	let f = (e) => n.search(e, {
 		limit: l,
 		minQueryLength: u,
 		threshold: d
-	})), { name: "scout:results" }), v = null;
-	function y() {
-		v !== null && (clearTimeout(v), v = null);
-	}
-	let b = f.subscribe(() => {
-		let e = f.peek();
-		if (y(), e !== p.peek()) {
-			if (c === 0) {
-				p.value = e;
-				return;
-			}
-			v = setTimeout(() => {
-				p.value = e, v = null;
-			}, c);
-		}
-	});
-	function x() {
-		if (S) throw new t("SearchState.clear() called after dispose()");
-		y(), r(() => {
-			f.value = "", p.value = "";
+	}), p = (e, t, n) => Object.freeze({
+		isSearching: t,
+		query: e,
+		results: Object.freeze(n)
+	}), m = /* @__PURE__ */ new Set(), h = /* @__PURE__ */ new Set(), g = new AbortController(), _ = p("", !1, f("")), v = "", y = !1, b, x = (e) => {
+		_ = e, i(m), a(h, {
+			snapshot: e,
+			type: "state-change"
 		});
-	}
-	let S = !1, C = new AbortController();
-	function w() {
-		S || (S = !0, C.abort(), y(), b(), h());
-	}
+	}, S = (e) => {
+		v = e, x(p(e, !1, f(e)));
+	}, C = n.onMutate(() => {
+		x(p(_.query, _.isSearching, f(v)));
+	}), w = (e) => {
+		if (y) throw new t(`SearchState.${e}() called after dispose()`);
+	}, T = () => {
+		y || (y = !0, b !== void 0 && clearTimeout(b), b = void 0, C(), a(h, { type: "dispose" }), m.clear(), h.clear(), g.abort());
+	};
 	return {
-		clear: x,
+		clear() {
+			w("clear"), (_.query !== "" || _.isSearching) && (b !== void 0 && clearTimeout(b), b = void 0, S(""));
+		},
 		get disposalSignal() {
-			return C.signal;
+			return g.signal;
 		},
-		dispose: w,
+		dispose: T,
 		get disposed() {
-			return S;
+			return y;
+		},
+		getSnapshot() {
+			return _;
+		},
+		setQuery(e) {
+			if (w("setQuery"), e !== _.query) {
+				if (b !== void 0 && clearTimeout(b), b = void 0, e === v) {
+					x(p(e, !1, _.results));
+					return;
+				}
+				if (c === 0) {
+					S(e);
+					return;
+				}
+				x(p(e, !0, _.results)), b = setTimeout(() => {
+					b = void 0, S(e);
+				}, c);
+			}
+		},
+		subscribe(e, t) {
+			return o(m, e, t, y, g.signal);
+		},
+		tap(e, t) {
+			return o(h, e, t, y, g.signal);
 		},
-		isSearching: g,
-		query: f,
-		results: _,
-		[Symbol.dispose]() {
-			w();
-		}
+		[Symbol.dispose]: T
 	};
 }
 function c(e, t) {
-	let r = n(e, {
-		fields: t.fields,
-		limit: t.limit,
-		minQueryLength: t.minQueryLength,
-		threshold: t.threshold
-	}), i = s(r, { debounce: t.debounce });
+	let r = n(e, t), i = s(r, t);
 	return {
 		clear: i.clear,
 		get disposalSignal() {
@@ -71,13 +101,12 @@ function c(e, t) {
 		get disposed() {
 			return i.disposed;
 		},
+		getSnapshot: i.getSnapshot,
 		index: r,
-		isSearching: i.isSearching,
-		query: i.query,
-		results: i.results,
-		[Symbol.dispose]() {
-			i[Symbol.dispose]();
-		}
+		setQuery: i.setQuery,
+		subscribe: i.subscribe,
+		tap: i.tap,
+		[Symbol.dispose]: i[Symbol.dispose]
 	};
 }
 //#endregion

package/dist/reactive.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.js","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    if (isDisposed) return;\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return {\n    clear: state.clear,\n    get disposalSignal() {\n      return state.disposalSignal;\n    },\n    dispose: state.dispose,\n    get disposed() {\n      return state.disposed;\n    },\n    index,\n    isSearching: state.isSearching,\n    query: state.query,\n    results: state.results,\n    [Symbol.dispose]() {\n      state[Symbol.dispose]();\n    },\n  };\n}\n"],"mappings":";;;;AAaA,IAAM,IAAmB;AAsCzB,SAAgB,EAAgB,GAAsB,IAA+B,CAAC,GAAmB;CACvG,IAAM,EAAE,UAAU,IAAa,GAAkB,UAAO,mBAAgB,iBAAc;CAEtF,IAAI,CAAC,OAAO,SAAS,CAAU,KAAK,CAAC,OAAO,UAAU,CAAU,KAAK,IAAa,GAChF,MAAM,IAAI,EAAwB,iDAAiD;CAGrF,IAAM,IAAQ,EAAe,IAAI,EAAE,MAAM,cAAc,CAAC,GAClD,IAAiB,EAAe,IAAI,EAAE,MAAM,uBAAuB,CAAC,GACpE,IAAe,EAAO,GAAG,EAAE,MAAM,qBAAqB,CAAC,GAEvD,IAAuB,EAAM,eAAe;EAChD,EAAa;CACf,CAAC,GAEK,IAAc,QAAe,EAAM,UAAU,EAAe,OAAO,EAAE,MAAM,oBAAoB,CAAC,GAEhG,IAAU,SAGZ,EAAkB,OAEX,EAAM,OAAO,EAAe,OAAO;EAAE;EAAO;EAAgB;CAAU,CAAC,IAEhF,EAAE,MAAM,gBAAgB,CAC1B,GAEI,IAA8C;CAElD,SAAS,IAAoB;EAC3B,AAAI,MAAU,SACZ,aAAa,CAAK,GAClB,IAAQ;CAEZ;CAEA,IAAM,IAAe,EAAM,gBAAgB;EACzC,IAAM,IAAI,EAAM,KAAK;EAErB,MAAY,GAER,MAAM,EAAe,KAAK,GAE9B;OAAI,MAAe,GAAG;IACpB,EAAe,QAAQ;IAEvB;GACF;GAEA,IAAQ,iBAAiB;IAEvB,AADA,EAAe,QAAQ,GACvB,IAAQ;GACV,GAAG,CAAU;EALb;CAMF,CAAC;CAED,SAAS,IAAc;EACrB,IAAI,GAAY,MAAM,IAAI,EAAmB,4CAA4C;EAIzF,AAFA,EAAY,GAEZ,QAAY;GAEV,AADA,EAAM,QAAQ,IACd,EAAe,QAAQ;EACzB,CAAC;CACH;CAEA,IAAI,IAAa,IACX,IAAK,IAAI,gBAAgB;CAE/B,SAAS,IAAgB;EACnB,MACJ,IAAa,IACb,EAAG,MAAM,GACT,EAAY,GACZ,EAAa,GACb,EAAqB;CACvB;CAEA,OAAO;EACL;EACA,IAAI,iBAA8B;GAChC,OAAO,EAAG;EACZ;EACA;EACA,IAAI,WAAoB;GACtB,OAAO;EACT;EACA;EACA;EACA;EACA,CAAC,OAAO,WAAiB;GACvB,EAAQ;EACV;CACF;AACF;AA4BA,SAAgB,EACd,GACA,GACmB;CACnB,IAAM,IAAQ,EAAY,GAAO;EAC/B,QAAQ,EAAQ;EAChB,OAAO,EAAQ;EACf,gBAAgB,EAAQ;EACxB,WAAW,EAAQ;CACrB,CAAC,GACK,IAAQ,EAAa,GAAO,EAAE,UAAU,EAAQ,SAAS,CAAC;CAEhE,OAAO;EACL,OAAO,EAAM;EACb,IAAI,iBAAiB;GACnB,OAAO,EAAM;EACf;EACA,SAAS,EAAM;EACf,IAAI,WAAW;GACb,OAAO,EAAM;EACf;EACA;EACA,aAAa,EAAM;EACnB,OAAO,EAAM;EACb,SAAS,EAAM;EACf,CAAC,OAAO,WAAW;GACjB,EAAM,OAAO,QAAQ,CAAC;EACxB;CACF;AACF"}
+{"version":3,"file":"reactive.js","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type {\n  CreateSearchOptions,\n  ScoutEvent,\n  ScoutIndexOptions,\n  SearchResult,\n  SearchSnapshot,\n  SearchState,\n  SearchSubscribeOptions,\n} from './types';\n\nexport type ReactiveSearch<T> = SearchState<T> & { readonly index: ScoutIndex<T> };\n\nconst DEFAULT_DEBOUNCE = 200;\n\nfunction notify(listeners: Set<() => void>): void {\n  for (const listener of [...listeners]) {\n    try {\n      listener();\n    } catch (error) {\n      queueMicrotask(() => {\n        throw error;\n      });\n    }\n  }\n}\n\nfunction emit<T>(tappers: Set<(event: ScoutEvent<T>) => void>, event: ScoutEvent<T>): void {\n  if (tappers.size === 0) return;\n\n  for (const tapper of [...tappers]) {\n    try {\n      tapper(event);\n    } catch {}\n  }\n}\n\nfunction subscribe<T>(\n  listeners: Set<T>,\n  listener: T,\n  options: SearchSubscribeOptions | undefined,\n  disposed: boolean,\n  lifetimeSignal: AbortSignal,\n): () => void {\n  if (disposed || options?.signal?.aborted) return () => {};\n\n  listeners.add(listener);\n  const unsubscribe = (): void => {\n    listeners.delete(listener);\n    options?.signal?.removeEventListener('abort', unsubscribe);\n  };\n  options?.signal?.addEventListener('abort', unsubscribe, { once: true, signal: lifetimeSignal });\n  return unsubscribe;\n}\n\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isSafeInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const search = (query: string) => index.search(query, { limit, minQueryLength, threshold });\n  const createSnapshot = (\n    query: string,\n    isSearching: boolean,\n    results: ReadonlyArray<SearchResult<T>>,\n  ): SearchSnapshot<T> => Object.freeze({ isSearching, query, results: Object.freeze(results) });\n  const listeners = new Set<() => void>();\n  const tappers = new Set<(event: ScoutEvent<T>) => void>();\n  const controller = new AbortController();\n  let snapshot = createSnapshot('', false, search(''));\n  let committedQuery = '';\n  let disposed = false;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  const publish = (next: SearchSnapshot<T>): void => {\n    snapshot = next;\n    notify(listeners);\n    emit(tappers, { snapshot: next, type: 'state-change' });\n  };\n  const commit = (query: string): void => {\n    committedQuery = query;\n    publish(createSnapshot(query, false, search(query)));\n  };\n  const unsubscribeIndex = index.onMutate(() => {\n    publish(createSnapshot(snapshot.query, snapshot.isSearching, search(committedQuery)));\n  });\n  const assertActive = (method: string): void => {\n    if (disposed) throw new ScoutDisposedError(`SearchState.${method}() called after dispose()`);\n  };\n  const dispose = (): void => {\n    if (disposed) return;\n    disposed = true;\n    if (timer !== undefined) clearTimeout(timer);\n    timer = undefined;\n    unsubscribeIndex();\n    emit(tappers, { type: 'dispose' });\n    listeners.clear();\n    tappers.clear();\n    controller.abort();\n  };\n\n  return {\n    clear() {\n      assertActive('clear');\n      if (snapshot.query === '' && !snapshot.isSearching) return;\n      if (timer !== undefined) clearTimeout(timer);\n      timer = undefined;\n      commit('');\n    },\n    get disposalSignal() {\n      return controller.signal;\n    },\n    dispose,\n    get disposed() {\n      return disposed;\n    },\n    getSnapshot() {\n      return snapshot;\n    },\n    setQuery(query) {\n      assertActive('setQuery');\n      if (query === snapshot.query) return;\n      if (timer !== undefined) clearTimeout(timer);\n      timer = undefined;\n\n      if (query === committedQuery) {\n        publish(createSnapshot(query, false, snapshot.results));\n        return;\n      }\n\n      if (debounceMs === 0) {\n        commit(query);\n        return;\n      }\n\n      publish(createSnapshot(query, true, snapshot.results));\n      timer = setTimeout(() => {\n        timer = undefined;\n        commit(query);\n      }, debounceMs);\n    },\n    subscribe(listener, subscribeOptions) {\n      return subscribe(listeners, listener, subscribeOptions, disposed, controller.signal);\n    },\n    tap(handler, tapOptions) {\n      return subscribe(tappers, handler, tapOptions, disposed, controller.signal);\n    },\n    [Symbol.dispose]: dispose,\n  };\n}\n\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, options);\n  const state = createSearch(index, options);\n\n  return {\n    clear: state.clear,\n    get disposalSignal() {\n      return state.disposalSignal;\n    },\n    dispose: state.dispose,\n    get disposed() {\n      return state.disposed;\n    },\n    getSnapshot: state.getSnapshot,\n    index,\n    setQuery: state.setQuery,\n    subscribe: state.subscribe,\n    tap: state.tap,\n    [Symbol.dispose]: state[Symbol.dispose],\n  };\n}\n"],"mappings":"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"}

package/dist/scout-index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"scout-index.cjs","names":[],"sources":["../src/scout-index.ts"],"sourcesContent":["import { ScoutConfigurationError } from './errors';\nimport { findMatchRanges } from './highlight';\nimport { defaultStringify, tokenize } from './tokenize';\nimport { generateTrigrams, overlapSimilarity } from './trigram';\nimport type { FieldDef, FieldMatch, ScoutIndexOptions, SearchConstraints, SearchResult } from './types';\n\ntype FieldConfig<T> = {\n  field: keyof T & string;\n  stringify: (v: unknown) => string;\n  weight: number;\n};\n\ntype ItemRecord = {\n  /** Per-field trigrams for scoring. */\n  trigrams: Map<string, Set<string>>;\n  /** Per-field original text for highlighting. */\n  values: Map<string, string>;\n};\n\n/**\n * A stateful, indexed search corpus. Created via `createIndex()`.\n *\n * Supports incremental `add()`, `remove()`, and `reindex()` operations — each patches\n * the trigram index in O(field_length) without a full rebuild.\n */\nexport interface ScoutIndex<T> {\n  /** Adds `item` to the index. No-op if the item is already indexed (by reference). */\n  add(item: T): void;\n  /** All items currently in the index, in insertion order. */\n  readonly items: readonly T[];\n  /**\n   * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`\n   * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an\n   * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.\n   * Returns an unsubscribe function.\n   *\n   * Framework-agnostic extension point: `createSearch()` uses this internally to keep\n   * reactive `results` in sync with index mutations. Most callers won't need this directly.\n   */\n  onMutate(listener: () => void): () => void;\n  /**\n   * Re-reads the item's current field values and rebuilds its index entry in-place,\n   * only updating fields whose values have changed. Preserves insertion order.\n   * No-op if the item is not in the index.\n   */\n  reindex(item: T): void;\n  /**\n   * Removes `item` from the index by reference equality.\n   * No-op if the item is not in the index.\n   */\n  remove(item: T): void;\n  /**\n   * Monotonically increasing counter, incremented after every changed `add()` / `remove()` /\n   * `reindex()` / `setItems()` operation. Use as a cache-busting token when caching search\n   * results outside the index — `toSearchMatcher()` uses it for this purpose.\n   */\n  readonly revision: number;\n  /**\n   * Searches the index for `query` and returns results sorted by score descending.\n   *\n   * An empty (or whitespace-only) `query` returns all indexed items with `score = 1`.\n   * A `query` with no indexable content after normalization (e.g. punctuation-only) returns\n   * no results. Results below `threshold` are excluded. At most `limit` results are returned.\n   */\n  search(query: string, options?: SearchConstraints): SearchResult<T>[];\n  /**\n   * Reconciles the index to `items` by reference identity. Retained items are reindexed,\n   * new items are added, missing items are removed, and one mutation notification fires\n   * when indexed corpus or field values change. Duplicate references collapse to one item.\n   */\n  setItems(items: readonly T[]): void;\n  /** Number of items currently in the index. */\n  readonly size: number;\n}\n\nfunction requireFiniteInteger(value: number, name: string, minimum: number): number {\n  if (!Number.isFinite(value) || !Number.isInteger(value) || value < minimum) {\n    throw new ScoutConfigurationError(`${name} must be a finite integer greater than or equal to ${minimum}.`);\n  }\n\n  return value;\n}\n\nfunction requireFiniteNumber(value: number, name: string, minimum: number, maximum = Number.POSITIVE_INFINITY): number {\n  if (!Number.isFinite(value) || value < minimum || value > maximum) {\n    throw new ScoutConfigurationError(`${name} must be a finite number between ${minimum} and ${maximum}.`);\n  }\n\n  return value;\n}\n\nfunction resolveFields<T>(defs: ReadonlyArray<FieldDef<T>>): FieldConfig<T>[] {\n  return defs.map((def) => {\n    if (typeof def === 'string') {\n      return { field: def, stringify: defaultStringify, weight: 1 };\n    }\n\n    return {\n      field: def.field,\n      stringify: def.stringify ?? defaultStringify,\n      weight: requireFiniteNumber(def.weight ?? 1, `weight for field \"${def.field}\"`, Number.MIN_VALUE),\n    };\n  });\n}\n\n/**\n * Builds a trigram inverted index over `items` for fast fuzzy search.\n *\n * Construction is O(corpus × field_length). Subsequent `search()` calls are\n * O(candidates) — far faster than per-query Levenshtein for large corpora.\n *\n * @example\n * ```ts\n * const index = createIndex(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   threshold: 0.3,\n *   limit: 20,\n * });\n *\n * const results = index.search('alice');\n * ```\n *\n * @throws {ScoutConfigurationError} If options use an invalid field or numeric configuration.\n */\nexport function createIndex<T>(items: T[], options: ScoutIndexOptions<T>): ScoutIndex<T> {\n  if (options.fields.length === 0) {\n    throw new ScoutConfigurationError('createIndex: at least one field is required.');\n  }\n\n  const fields = resolveFields(options.fields);\n  const maxWeight = fields.reduce((max, f) => Math.max(max, f.weight), 1);\n  const defaultThreshold = requireFiniteNumber(options.threshold ?? 0.2, 'threshold', 0, 1);\n  const defaultLimit = requireFiniteInteger(options.limit ?? 50, 'limit', 0);\n  const defaultMinQueryLength = requireFiniteInteger(options.minQueryLength ?? 3, 'minQueryLength', 1);\n\n  /** item → per-item record, preserves insertion order for `items` getter */\n  const itemData = new Map<T, ItemRecord>();\n  /** trigram → set of items that contain it */\n  const invertedIndex = new Map<string, Set<T>>();\n  const mutationListeners = new Set<() => void>();\n  let revision = 0;\n\n  function notifyMutation(): void {\n    revision++;\n\n    for (const listener of mutationListeners) listener();\n  }\n\n  /** Single-entry cache for the most recent normalized query's trigrams (F2). */\n  let cachedNormalized: string | null = null;\n  let cachedTrigrams: Set<string> | null = null;\n\n  function getQueryTrigrams(normalized: string): Set<string> {\n    if (normalized === cachedNormalized && cachedTrigrams !== null) return cachedTrigrams;\n\n    cachedNormalized = normalized;\n    cachedTrigrams = generateTrigrams(normalized);\n\n    return cachedTrigrams;\n  }\n\n  function addFieldToIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      let bucket = invertedIndex.get(trigram);\n\n      if (!bucket) {\n        bucket = new Set<T>();\n        invertedIndex.set(trigram, bucket);\n      }\n\n      bucket.add(item);\n    }\n  }\n\n  function removeFieldFromIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      const bucket = invertedIndex.get(trigram);\n\n      if (bucket) {\n        bucket.delete(item);\n\n        if (bucket.size === 0) invertedIndex.delete(trigram);\n      }\n    }\n  }\n\n  function addItem(item: T): void {\n    const trigrams = new Map<string, Set<string>>();\n    const values = new Map<string, string>();\n\n    for (const { field, stringify } of fields) {\n      const raw = item[field];\n      const text = stringify(raw);\n      const normalized = tokenize(text);\n      const fieldTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      trigrams.set(field, fieldTrigrams);\n      values.set(field, text);\n      addFieldToIndex(item, fieldTrigrams);\n    }\n\n    itemData.set(item, { trigrams, values });\n  }\n\n  /**\n   * Performs a full linear scan over all items for short queries.\n   * O(n × field_count) — acceptable for small corpora; consider raising\n   * `minQueryLength` on large datasets to avoid triggering this path.\n   */\n  function containmentScan(query: string): Set<T> {\n    const result = new Set<T>();\n\n    for (const [item, record] of itemData) {\n      for (const value of record.values.values()) {\n        if (value.toLowerCase().includes(query)) {\n          result.add(item);\n          break;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  function trigramCandidates(queryTrigrams: Set<string>): Set<T> {\n    const candidates = new Set<T>();\n\n    for (const trigram of queryTrigrams) {\n      const items = invertedIndex.get(trigram);\n\n      if (items) {\n        for (const item of items) candidates.add(item);\n      }\n    }\n\n    return candidates;\n  }\n\n  function scoreCandidate(normalized: string, queryTrigrams: Set<string> | null, record: ItemRecord): number {\n    let bestScore = 0;\n\n    for (const { field, weight } of fields) {\n      let fieldScore: number;\n\n      if (queryTrigrams === null) {\n        const raw = record.values.get(field) ?? '';\n\n        fieldScore = raw.toLowerCase().includes(normalized) ? 1.0 : 0;\n      } else {\n        const itemTrigrams = record.trigrams.get(field);\n\n        if (!itemTrigrams || itemTrigrams.size === 0) continue;\n\n        fieldScore = overlapSimilarity(queryTrigrams, itemTrigrams);\n      }\n\n      const weighted = fieldScore * (weight / maxWeight);\n\n      if (weighted > bestScore) bestScore = weighted;\n    }\n\n    return bestScore;\n  }\n\n  function computeMatches(query: string, values: Map<string, string>): FieldMatch<keyof T & string>[] {\n    const matches: FieldMatch<keyof T & string>[] = [];\n\n    for (const { field } of fields) {\n      const text = values.get(field);\n\n      if (!text) continue;\n\n      const ranges = findMatchRanges(text, query);\n\n      if (ranges.length > 0) matches.push({ field, ranges });\n    }\n\n    return matches;\n  }\n\n  function reindexItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    let changed = false;\n\n    for (const { field, stringify } of fields) {\n      const newText = stringify(item[field]);\n      const oldText = record.values.get(field);\n\n      if (newText === oldText) continue;\n\n      changed = true;\n\n      const oldTrigrams = record.trigrams.get(field);\n\n      if (oldTrigrams) removeFieldFromIndex(item, oldTrigrams);\n\n      const normalized = tokenize(newText);\n      const newTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      record.trigrams.set(field, newTrigrams);\n      record.values.set(field, newText);\n      addFieldToIndex(item, newTrigrams);\n    }\n\n    return changed;\n  }\n\n  function removeItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    for (const fieldTrigrams of record.trigrams.values()) {\n      removeFieldFromIndex(item, fieldTrigrams);\n    }\n\n    itemData.delete(item);\n\n    return true;\n  }\n\n  for (const item of items) {\n    if (!itemData.has(item)) addItem(item);\n  }\n\n  const index: ScoutIndex<T> = {\n    add(item: T): void {\n      if (itemData.has(item)) return;\n\n      addItem(item);\n      notifyMutation();\n    },\n\n    get items(): readonly T[] {\n      return [...itemData.keys()];\n    },\n\n    onMutate(listener: () => void): () => void {\n      mutationListeners.add(listener);\n\n      return () => {\n        mutationListeners.delete(listener);\n      };\n    },\n\n    reindex(item: T): void {\n      if (reindexItem(item)) notifyMutation();\n    },\n\n    remove(item: T): void {\n      if (removeItem(item)) notifyMutation();\n    },\n\n    get revision(): number {\n      return revision;\n    },\n\n    search(query: string, options?: SearchConstraints): SearchResult<T>[] {\n      const threshold = requireFiniteNumber(options?.threshold ?? defaultThreshold, 'threshold', 0, 1);\n      const limit = requireFiniteInteger(options?.limit ?? defaultLimit, 'limit', 0);\n      const minQueryLength = requireFiniteInteger(\n        options?.minQueryLength ?? defaultMinQueryLength,\n        'minQueryLength',\n        1,\n      );\n\n      if (!query.trim()) {\n        return [...itemData.keys()].slice(0, limit).map((item) => ({ item, matches: [], score: 1 }));\n      }\n\n      const normalized = tokenize(query);\n\n      // Query had no indexable content (e.g. punctuation-only) — no match, not \"match all\".\n      if (!normalized) return [];\n\n      const isShort = normalized.length < minQueryLength;\n      const queryTrigrams = isShort ? null : getQueryTrigrams(normalized);\n      const candidates = queryTrigrams === null ? containmentScan(normalized) : trigramCandidates(queryTrigrams);\n      const results: SearchResult<T>[] = [];\n\n      for (const item of candidates) {\n        const record = itemData.get(item);\n\n        if (!record) continue;\n\n        const score = scoreCandidate(normalized, queryTrigrams, record);\n\n        if (score >= threshold) {\n          const matches = computeMatches(normalized, record.values);\n\n          results.push({ item, matches, score });\n        }\n      }\n\n      return results.sort((a, b) => b.score - a.score).slice(0, limit);\n    },\n\n    setItems(items: readonly T[]): void {\n      const incoming = new Set(items);\n      const next = [...incoming];\n      let changed = false;\n\n      for (const item of [...itemData.keys()]) {\n        if (incoming.has(item)) continue;\n\n        removeItem(item);\n        changed = true;\n      }\n\n      for (const item of next) {\n        if (!itemData.has(item)) {\n          addItem(item);\n          changed = true;\n        } else if (reindexItem(item)) {\n          changed = true;\n        }\n      }\n\n      const current = [...itemData.keys()];\n      const orderChanged = current.length !== next.length || current.some((item, index) => item !== next[index]);\n\n      if (orderChanged) {\n        const records = new Map(next.map((item) => [item, itemData.get(item)!]));\n\n        itemData.clear();\n\n        for (const [item, record] of records) itemData.set(item, record);\n\n        changed = true;\n      }\n\n      if (changed) notifyMutation();\n    },\n\n    get size(): number {\n      return itemData.size;\n    },\n  };\n\n  return index;\n}\n"],"mappings":"oHA2EA,SAAS,EAAqB,EAAe,EAAc,EAAyB,CAClF,GAAI,CAAC,OAAO,SAAS,CAAK,GAAK,CAAC,OAAO,UAAU,CAAK,GAAK,EAAQ,EACjE,MAAM,IAAI,EAAA,wBAAwB,GAAG,EAAK,qDAAqD,EAAQ,EAAE,EAG3G,OAAO,CACT,CAEA,SAAS,EAAoB,EAAe,EAAc,EAAiB,EAAU,IAAkC,CACrH,GAAI,CAAC,OAAO,SAAS,CAAK,GAAK,EAAQ,GAAW,EAAQ,EACxD,MAAM,IAAI,EAAA,wBAAwB,GAAG,EAAK,mCAAmC,EAAQ,OAAO,EAAQ,EAAE,EAGxG,OAAO,CACT,CAEA,SAAS,EAAiB,EAAoD,CAC5E,OAAO,EAAK,IAAK,GACX,OAAO,GAAQ,SACV,CAAE,MAAO,EAAK,UAAW,EAAA,iBAAkB,OAAQ,CAAE,EAGvD,CACL,MAAO,EAAI,MACX,UAAW,EAAI,WAAa,EAAA,iBAC5B,OAAQ,EAAoB,EAAI,QAAU,EAAG,qBAAqB,EAAI,MAAM,GAAI,OAAO,SAAS,CAClG,CACD,CACH,CAqBA,SAAgB,EAAe,EAAY,EAA8C,CACvF,GAAI,EAAQ,OAAO,SAAW,EAC5B,MAAM,IAAI,EAAA,wBAAwB,8CAA8C,EAGlF,IAAM,EAAS,EAAc,EAAQ,MAAM,EACrC,EAAY,EAAO,QAAQ,EAAK,IAAM,KAAK,IAAI,EAAK,EAAE,MAAM,EAAG,CAAC,EAChE,EAAmB,EAAoB,EAAQ,WAAa,GAAK,YAAa,EAAG,CAAC,EAClF,EAAe,EAAqB,EAAQ,OAAS,GAAI,QAAS,CAAC,EACnE,EAAwB,EAAqB,EAAQ,gBAAkB,EAAG,iBAAkB,CAAC,EAG7F,EAAW,IAAI,IAEf,EAAgB,IAAI,IACpB,EAAoB,IAAI,IAC1B,EAAW,EAEf,SAAS,GAAuB,CAC9B,IAEA,IAAK,IAAM,KAAY,EAAmB,EAAS,CACrD,CAGA,IAAI,EAAkC,KAClC,EAAqC,KAEzC,SAAS,EAAiB,EAAiC,CAMzD,OALI,IAAe,GAAoB,IAAmB,KAAa,GAEvE,EAAmB,EACnB,EAAiB,EAAA,iBAAiB,CAAU,EAErC,EACT,CAEA,SAAS,EAAgB,EAAS,EAAkC,CAClE,IAAK,IAAM,KAAW,EAAe,CACnC,IAAI,EAAS,EAAc,IAAI,CAAO,EAEjC,IACH,EAAS,IAAI,IACb,EAAc,IAAI,EAAS,CAAM,GAGnC,EAAO,IAAI,CAAI,CACjB,CACF,CAEA,SAAS,EAAqB,EAAS,EAAkC,CACvE,IAAK,IAAM,KAAW,EAAe,CACnC,IAAM,EAAS,EAAc,IAAI,CAAO,EAEpC,IACF,EAAO,OAAO,CAAI,EAEd,EAAO,OAAS,GAAG,EAAc,OAAO,CAAO,EAEvD,CACF,CAEA,SAAS,EAAQ,EAAe,CAC9B,IAAM,EAAW,IAAI,IACf,EAAS,IAAI,IAEnB,IAAK,GAAM,CAAE,QAAO,eAAe,EAAQ,CACzC,IAAM,EAAM,EAAK,GACX,EAAO,EAAU,CAAG,EACpB,EAAa,EAAA,SAAS,CAAI,EAC1B,EAAgB,EAAW,QAAU,EAAI,EAAA,iBAAiB,CAAU,EAAI,IAAI,IAElF,EAAS,IAAI,EAAO,CAAa,EACjC,EAAO,IAAI,EAAO,CAAI,EACtB,EAAgB,EAAM,CAAa,CACrC,CAEA,EAAS,IAAI,EAAM,CAAE,WAAU,QAAO,CAAC,CACzC,CAOA,SAAS,EAAgB,EAAuB,CAC9C,IAAM,EAAS,IAAI,IAEnB,IAAK,GAAM,CAAC,EAAM,KAAW,EAC3B,IAAK,IAAM,KAAS,EAAO,OAAO,OAAO,EACvC,GAAI,EAAM,YAAY,CAAC,CAAC,SAAS,CAAK,EAAG,CACvC,EAAO,IAAI,CAAI,EACf,KACF,CAIJ,OAAO,CACT,CAEA,SAAS,EAAkB,EAAoC,CAC7D,IAAM,EAAa,IAAI,IAEvB,IAAK,IAAM,KAAW,EAAe,CACnC,IAAM,EAAQ,EAAc,IAAI,CAAO,EAEvC,GAAI,EACF,IAAK,IAAM,KAAQ,EAAO,EAAW,IAAI,CAAI,CAEjD,CAEA,OAAO,CACT,CAEA,SAAS,EAAe,EAAoB,EAAmC,EAA4B,CACzG,IAAI,EAAY,EAEhB,IAAK,GAAM,CAAE,QAAO,YAAY,EAAQ,CACtC,IAAI,EAEJ,GAAI,IAAkB,KAGpB,EAAA,IAFY,EAAO,OAAO,IAAI,CAAK,GAAK,GAAA,CAEvB,YAAY,CAAC,CAAC,SAAS,CAAU,MAC7C,CACL,IAAM,EAAe,EAAO,SAAS,IAAI,CAAK,EAE9C,GAAI,CAAC,GAAgB,EAAa,OAAS,EAAG,SAE9C,EAAa,EAAA,kBAAkB,EAAe,CAAY,CAC5D,CAEA,IAAM,EAAyB,EAAS,EAAvB,EAEb,EAAW,IAAW,EAAY,EACxC,CAEA,OAAO,CACT,CAEA,SAAS,EAAe,EAAe,EAA6D,CAClG,IAAM,EAA0C,CAAC,EAEjD,IAAK,GAAM,CAAE,WAAW,EAAQ,CAC9B,IAAM,EAAO,EAAO,IAAI,CAAK,EAE7B,GAAI,CAAC,EAAM,SAEX,IAAM,EAAS,EAAA,gBAAgB,EAAM,CAAK,EAEtC,EAAO,OAAS,GAAG,EAAQ,KAAK,CAAE,QAAO,QAAO,CAAC,CACvD,CAEA,OAAO,CACT,CAEA,SAAS,EAAY,EAAkB,CACrC,IAAM,EAAS,EAAS,IAAI,CAAI,EAEhC,GAAI,CAAC,EAAQ,MAAO,GAEpB,IAAI,EAAU,GAEd,IAAK,GAAM,CAAE,QAAO,eAAe,EAAQ,CACzC,IAAM,EAAU,EAAU,EAAK,EAAM,EAGrC,GAAI,IAFY,EAAO,OAAO,IAAI,CAElB,EAAS,SAEzB,EAAU,GAEV,IAAM,EAAc,EAAO,SAAS,IAAI,CAAK,EAEzC,GAAa,EAAqB,EAAM,CAAW,EAEvD,IAAM,EAAa,EAAA,SAAS,CAAO,EAC7B,EAAc,EAAW,QAAU,EAAI,EAAA,iBAAiB,CAAU,EAAI,IAAI,IAEhF,EAAO,SAAS,IAAI,EAAO,CAAW,EACtC,EAAO,OAAO,IAAI,EAAO,CAAO,EAChC,EAAgB,EAAM,CAAW,CACnC,CAEA,OAAO,CACT,CAEA,SAAS,EAAW,EAAkB,CACpC,IAAM,EAAS,EAAS,IAAI,CAAI,EAEhC,GAAI,CAAC,EAAQ,MAAO,GAEpB,IAAK,IAAM,KAAiB,EAAO,SAAS,OAAO,EACjD,EAAqB,EAAM,CAAa,EAK1C,OAFA,EAAS,OAAO,CAAI,EAEb,EACT,CAEA,IAAK,IAAM,KAAQ,EACZ,EAAS,IAAI,CAAI,GAAG,EAAQ,CAAI,EAqHvC,MAAO,CAjHL,IAAI,EAAe,CACb,EAAS,IAAI,CAAI,IAErB,EAAQ,CAAI,EACZ,EAAe,EACjB,EAEA,IAAI,OAAsB,CACxB,MAAO,CAAC,GAAG,EAAS,KAAK,CAAC,CAC5B,EAEA,SAAS,EAAkC,CAGzC,OAFA,EAAkB,IAAI,CAAQ,MAEjB,CACX,EAAkB,OAAO,CAAQ,CACnC,CACF,EAEA,QAAQ,EAAe,CACjB,EAAY,CAAI,GAAG,EAAe,CACxC,EAEA,OAAO,EAAe,CAChB,EAAW,CAAI,GAAG,EAAe,CACvC,EAEA,IAAI,UAAmB,CACrB,OAAO,CACT,EAEA,OAAO,EAAe,EAAgD,CACpE,IAAM,EAAY,EAAoB,GAAS,WAAa,EAAkB,YAAa,EAAG,CAAC,EACzF,EAAQ,EAAqB,GAAS,OAAS,EAAc,QAAS,CAAC,EACvE,EAAiB,EACrB,GAAS,gBAAkB,EAC3B,iBACA,CACF,EAEA,GAAI,CAAC,EAAM,KAAK,EACd,MAAO,CAAC,GAAG,EAAS,KAAK,CAAC,CAAC,CAAC,MAAM,EAAG,CAAK,CAAC,CAAC,IAAK,IAAU,CAAE,OAAM,QAAS,CAAC,EAAG,MAAO,CAAE,EAAE,EAG7F,IAAM,EAAa,EAAA,SAAS,CAAK,EAGjC,GAAI,CAAC,EAAY,MAAO,CAAC,EAGzB,IAAM,EADU,EAAW,OAAS,EACJ,KAAO,EAAiB,CAAU,EAC5D,EAAa,IAAkB,KAAO,EAAgB,CAAU,EAAI,EAAkB,CAAa,EACnG,EAA6B,CAAC,EAEpC,IAAK,IAAM,KAAQ,EAAY,CAC7B,IAAM,EAAS,EAAS,IAAI,CAAI,EAEhC,GAAI,CAAC,EAAQ,SAEb,IAAM,EAAQ,EAAe,EAAY,EAAe,CAAM,EAE9D,GAAI,GAAS,EAAW,CACtB,IAAM,EAAU,EAAe,EAAY,EAAO,MAAM,EAExD,EAAQ,KAAK,CAAE,OAAM,UAAS,OAAM,CAAC,CACvC,CACF,CAEA,OAAO,EAAQ,MAAM,EAAG,IAAM,EAAE,MAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,EAAG,CAAK,CACjE,EAEA,SAAS,EAA2B,CAClC,IAAM,EAAW,IAAI,IAAI,CAAK,EACxB,EAAO,CAAC,GAAG,CAAQ,EACrB,EAAU,GAEd,IAAK,IAAM,IAAQ,CAAC,GAAG,EAAS,KAAK,CAAC,EAChC,EAAS,IAAI,CAAI,IAErB,EAAW,CAAI,EACf,EAAU,IAGZ,IAAK,IAAM,KAAQ,EACZ,EAAS,IAAI,CAAI,EAGX,EAAY,CAAI,IACzB,EAAU,KAHV,EAAQ,CAAI,EACZ,EAAU,IAMd,IAAM,EAAU,CAAC,GAAG,EAAS,KAAK,CAAC,EAGnC,GAFqB,EAAQ,SAAW,EAAK,QAAU,EAAQ,MAAM,EAAM,IAAU,IAAS,EAAK,EAAM,EAEvF,CAChB,IAAM,EAAU,IAAI,IAAI,EAAK,IAAK,GAAS,CAAC,EAAM,EAAS,IAAI,CAAI,CAAE,CAAC,CAAC,EAEvE,EAAS,MAAM,EAEf,IAAK,GAAM,CAAC,EAAM,KAAW,EAAS,EAAS,IAAI,EAAM,CAAM,EAE/D,EAAU,EACZ,CAEI,GAAS,EAAe,CAC9B,EAEA,IAAI,MAAe,CACjB,OAAO,EAAS,IAClB,CAGK,CACT"}
+{"version":3,"file":"scout-index.cjs","names":[],"sources":["../src/scout-index.ts"],"sourcesContent":["import { ScoutConfigurationError } from './errors';\nimport { findMatchRanges } from './highlight';\nimport { defaultStringify, tokenize } from './tokenize';\nimport { generateTrigrams, overlapSimilarity } from './trigram';\nimport type { FieldDef, FieldMatch, ScoutIndexOptions, SearchConstraints, SearchResult } from './types';\n\ntype FieldConfig<T> = {\n  field: keyof T & string;\n  stringify: (v: unknown) => string;\n  weight: number;\n};\n\ntype ItemRecord = {\n  /** Per-field trigrams for scoring. */\n  trigrams: Map<string, Set<string>>;\n  /** Per-field original text for highlighting. */\n  values: Map<string, string>;\n};\n\n/**\n * A stateful, indexed search corpus. Created via `createIndex()`.\n *\n * Supports incremental `add()`, `remove()`, and `reindex()` operations — each patches\n * the trigram index in O(field_length) without a full rebuild.\n */\nexport interface ScoutIndex<T> {\n  /** Adds `item` to the index. No-op if the item is already indexed (by reference). */\n  add(item: T): void;\n  /** All items currently in the index, in insertion order. */\n  readonly items: readonly T[];\n  /**\n   * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`\n   * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an\n   * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.\n   * Returns an unsubscribe function.\n   *\n   * Framework-agnostic extension point: `createSearch()` uses this internally to keep\n   * its snapshot in sync with index mutations. Most callers won't need this directly.\n   */\n  onMutate(listener: () => void): () => void;\n  /**\n   * Re-reads the item's current field values and rebuilds its index entry in-place,\n   * only updating fields whose values have changed. Preserves insertion order.\n   * No-op if the item is not in the index.\n   */\n  reindex(item: T): void;\n  /**\n   * Removes `item` from the index by reference equality.\n   * No-op if the item is not in the index.\n   */\n  remove(item: T): void;\n  /**\n   * Monotonically increasing counter, incremented after every changed `add()` / `remove()` /\n   * `reindex()` / `setItems()` operation. Use as a cache-busting token when caching search\n   * results outside the index — `toSearchMatcher()` uses it for this purpose.\n   */\n  readonly revision: number;\n  /**\n   * Searches the index for `query` and returns results sorted by score descending.\n   *\n   * An empty (or whitespace-only) `query` returns all indexed items with `score = 1`.\n   * A `query` with no indexable content after normalization (e.g. punctuation-only) returns\n   * no results. Results below `threshold` are excluded. At most `limit` results are returned.\n   */\n  search(query: string, options?: SearchConstraints): SearchResult<T>[];\n  /**\n   * Reconciles the index to `items` by reference identity. Retained items are reindexed,\n   * new items are added, missing items are removed, and one mutation notification fires\n   * when indexed corpus or field values change. Duplicate references collapse to one item.\n   */\n  setItems(items: readonly T[]): void;\n  /** Number of items currently in the index. */\n  readonly size: number;\n}\n\nfunction requireFiniteInteger(value: number, name: string, minimum: number): number {\n  if (!Number.isFinite(value) || !Number.isInteger(value) || value < minimum) {\n    throw new ScoutConfigurationError(`${name} must be a finite integer greater than or equal to ${minimum}.`);\n  }\n\n  return value;\n}\n\nfunction requireFiniteNumber(value: number, name: string, minimum: number, maximum = Number.POSITIVE_INFINITY): number {\n  if (!Number.isFinite(value) || value < minimum || value > maximum) {\n    throw new ScoutConfigurationError(`${name} must be a finite number between ${minimum} and ${maximum}.`);\n  }\n\n  return value;\n}\n\nfunction resolveFields<T>(defs: ReadonlyArray<FieldDef<T>>): FieldConfig<T>[] {\n  return defs.map((def) => {\n    if (typeof def === 'string') {\n      return { field: def, stringify: defaultStringify, weight: 1 };\n    }\n\n    return {\n      field: def.field,\n      stringify: def.stringify ?? defaultStringify,\n      weight: requireFiniteNumber(def.weight ?? 1, `weight for field \"${def.field}\"`, Number.MIN_VALUE),\n    };\n  });\n}\n\n/**\n * Builds a trigram inverted index over `items` for fast fuzzy search.\n *\n * Construction is O(corpus × field_length). Subsequent `search()` calls are\n * O(candidates) — far faster than per-query Levenshtein for large corpora.\n *\n * @example\n * ```ts\n * const index = createIndex(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   threshold: 0.3,\n *   limit: 20,\n * });\n *\n * const results = index.search('alice');\n * ```\n *\n * @throws {ScoutConfigurationError} If options use an invalid field or numeric configuration.\n */\nexport function createIndex<T>(items: T[], options: ScoutIndexOptions<T>): ScoutIndex<T> {\n  if (options.fields.length === 0) {\n    throw new ScoutConfigurationError('createIndex: at least one field is required.');\n  }\n\n  const fields = resolveFields(options.fields);\n  const maxWeight = fields.reduce((max, f) => Math.max(max, f.weight), 1);\n  const defaultThreshold = requireFiniteNumber(options.threshold ?? 0.2, 'threshold', 0, 1);\n  const defaultLimit = requireFiniteInteger(options.limit ?? 50, 'limit', 0);\n  const defaultMinQueryLength = requireFiniteInteger(options.minQueryLength ?? 3, 'minQueryLength', 1);\n\n  /** item → per-item record, preserves insertion order for `items` getter */\n  const itemData = new Map<T, ItemRecord>();\n  /** trigram → set of items that contain it */\n  const invertedIndex = new Map<string, Set<T>>();\n  const mutationListeners = new Set<() => void>();\n  let revision = 0;\n\n  function notifyMutation(): void {\n    revision++;\n\n    for (const listener of mutationListeners) listener();\n  }\n\n  /** Single-entry cache for the most recent normalized query's trigrams (F2). */\n  let cachedNormalized: string | null = null;\n  let cachedTrigrams: Set<string> | null = null;\n\n  function getQueryTrigrams(normalized: string): Set<string> {\n    if (normalized === cachedNormalized && cachedTrigrams !== null) return cachedTrigrams;\n\n    cachedNormalized = normalized;\n    cachedTrigrams = generateTrigrams(normalized);\n\n    return cachedTrigrams;\n  }\n\n  function addFieldToIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      let bucket = invertedIndex.get(trigram);\n\n      if (!bucket) {\n        bucket = new Set<T>();\n        invertedIndex.set(trigram, bucket);\n      }\n\n      bucket.add(item);\n    }\n  }\n\n  function removeFieldFromIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      const bucket = invertedIndex.get(trigram);\n\n      if (bucket) {\n        bucket.delete(item);\n\n        if (bucket.size === 0) invertedIndex.delete(trigram);\n      }\n    }\n  }\n\n  function addItem(item: T): void {\n    const trigrams = new Map<string, Set<string>>();\n    const values = new Map<string, string>();\n\n    for (const { field, stringify } of fields) {\n      const raw = item[field];\n      const text = stringify(raw);\n      const normalized = tokenize(text);\n      const fieldTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      trigrams.set(field, fieldTrigrams);\n      values.set(field, text);\n      addFieldToIndex(item, fieldTrigrams);\n    }\n\n    itemData.set(item, { trigrams, values });\n  }\n\n  /**\n   * Performs a full linear scan over all items for short queries.\n   * O(n × field_count) — acceptable for small corpora; consider raising\n   * `minQueryLength` on large datasets to avoid triggering this path.\n   */\n  function containmentScan(query: string): Set<T> {\n    const result = new Set<T>();\n\n    for (const [item, record] of itemData) {\n      for (const value of record.values.values()) {\n        if (value.toLowerCase().includes(query)) {\n          result.add(item);\n          break;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  function trigramCandidates(queryTrigrams: Set<string>): Set<T> {\n    const candidates = new Set<T>();\n\n    for (const trigram of queryTrigrams) {\n      const items = invertedIndex.get(trigram);\n\n      if (items) {\n        for (const item of items) candidates.add(item);\n      }\n    }\n\n    return candidates;\n  }\n\n  function scoreCandidate(normalized: string, queryTrigrams: Set<string> | null, record: ItemRecord): number {\n    let bestScore = 0;\n\n    for (const { field, weight } of fields) {\n      let fieldScore: number;\n\n      if (queryTrigrams === null) {\n        const raw = record.values.get(field) ?? '';\n\n        fieldScore = raw.toLowerCase().includes(normalized) ? 1.0 : 0;\n      } else {\n        const itemTrigrams = record.trigrams.get(field);\n\n        if (!itemTrigrams || itemTrigrams.size === 0) continue;\n\n        fieldScore = overlapSimilarity(queryTrigrams, itemTrigrams);\n      }\n\n      const weighted = fieldScore * (weight / maxWeight);\n\n      if (weighted > bestScore) bestScore = weighted;\n    }\n\n    return bestScore;\n  }\n\n  function computeMatches(query: string, values: Map<string, string>): FieldMatch<keyof T & string>[] {\n    const matches: FieldMatch<keyof T & string>[] = [];\n\n    for (const { field } of fields) {\n      const text = values.get(field);\n\n      if (!text) continue;\n\n      const ranges = findMatchRanges(text, query);\n\n      if (ranges.length > 0) matches.push({ field, ranges });\n    }\n\n    return matches;\n  }\n\n  function reindexItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    let changed = false;\n\n    for (const { field, stringify } of fields) {\n      const newText = stringify(item[field]);\n      const oldText = record.values.get(field);\n\n      if (newText === oldText) continue;\n\n      changed = true;\n\n      const oldTrigrams = record.trigrams.get(field);\n\n      if (oldTrigrams) removeFieldFromIndex(item, oldTrigrams);\n\n      const normalized = tokenize(newText);\n      const newTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      record.trigrams.set(field, newTrigrams);\n      record.values.set(field, newText);\n      addFieldToIndex(item, newTrigrams);\n    }\n\n    return changed;\n  }\n\n  function removeItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    for (const fieldTrigrams of record.trigrams.values()) {\n      removeFieldFromIndex(item, fieldTrigrams);\n    }\n\n    itemData.delete(item);\n\n    return true;\n  }\n\n  for (const item of items) {\n    if (!itemData.has(item)) addItem(item);\n  }\n\n  const index: ScoutIndex<T> = {\n    add(item: T): void {\n      if (itemData.has(item)) return;\n\n      addItem(item);\n      notifyMutation();\n    },\n\n    get items(): readonly T[] {\n      return [...itemData.keys()];\n    },\n\n    onMutate(listener: () => void): () => void {\n      mutationListeners.add(listener);\n\n      return () => {\n        mutationListeners.delete(listener);\n      };\n    },\n\n    reindex(item: T): void {\n      if (reindexItem(item)) notifyMutation();\n    },\n\n    remove(item: T): void {\n      if (removeItem(item)) notifyMutation();\n    },\n\n    get revision(): number {\n      return revision;\n    },\n\n    search(query: string, options?: SearchConstraints): SearchResult<T>[] {\n      const threshold = requireFiniteNumber(options?.threshold ?? defaultThreshold, 'threshold', 0, 1);\n      const limit = requireFiniteInteger(options?.limit ?? defaultLimit, 'limit', 0);\n      const minQueryLength = requireFiniteInteger(\n        options?.minQueryLength ?? defaultMinQueryLength,\n        'minQueryLength',\n        1,\n      );\n\n      if (!query.trim()) {\n        return [...itemData.keys()].slice(0, limit).map((item) => ({ item, matches: [], score: 1 }));\n      }\n\n      const normalized = tokenize(query);\n\n      // Query had no indexable content (e.g. punctuation-only) — no match, not \"match all\".\n      if (!normalized) return [];\n\n      const isShort = normalized.length < minQueryLength;\n      const queryTrigrams = isShort ? null : getQueryTrigrams(normalized);\n      const candidates = queryTrigrams === null ? containmentScan(normalized) : trigramCandidates(queryTrigrams);\n      const results: SearchResult<T>[] = [];\n\n      for (const item of candidates) {\n        const record = itemData.get(item);\n\n        if (!record) continue;\n\n        const score = scoreCandidate(normalized, queryTrigrams, record);\n\n        if (score >= threshold) {\n          const matches = computeMatches(normalized, record.values);\n\n          results.push({ item, matches, score });\n        }\n      }\n\n      return results.sort((a, b) => b.score - a.score).slice(0, limit);\n    },\n\n    setItems(items: readonly T[]): void {\n      const incoming = new Set(items);\n      const next = [...incoming];\n      let changed = false;\n\n      for (const item of [...itemData.keys()]) {\n        if (incoming.has(item)) continue;\n\n        removeItem(item);\n        changed = true;\n      }\n\n      for (const item of next) {\n        if (!itemData.has(item)) {\n          addItem(item);\n          changed = true;\n        } else if (reindexItem(item)) {\n          changed = true;\n        }\n      }\n\n      const current = [...itemData.keys()];\n      const orderChanged = current.length !== next.length || current.some((item, index) => item !== next[index]);\n\n      if (orderChanged) {\n        const records = new Map(next.map((item) => [item, itemData.get(item)!]));\n\n        itemData.clear();\n\n        for (const [item, record] of records) itemData.set(item, record);\n\n        changed = true;\n      }\n\n      if (changed) notifyMutation();\n    },\n\n    get size(): number {\n      return itemData.size;\n    },\n  };\n\n  return index;\n}\n"],"mappings":"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"}

package/dist/scout-index.d.ts

@@ -17,7 +17,7 @@ export interface ScoutIndex<T> {
      * Returns an unsubscribe function.
      *
      * Framework-agnostic extension point: `createSearch()` uses this internally to keep
-     * reactive `results` in sync with index mutations. Most callers won't need this directly.
+     * its snapshot in sync with index mutations. Most callers won't need this directly.
      */
     onMutate(listener: () => void): () => void;
     /**