API Reference
Complete API documentation for LumoSearch methods, options, and types.
Constructor
new LumoSearch<T>(docs: T[], options?: LumoSearchOptions)
LumoSearchOptions
keys: KeyConfig[]
Array of field configurations. Can be strings or objects with name and weight.
keys: ['title', { name: 'body', weight: 0.8 }]limit: number (default: 10)
Maximum number of results to return.
candidateLimit: number (default: 250)
Number of candidates to consider before final ranking. Higher values improve recall but reduce performance.
synonyms: Record<string, string[]>
Token-level aliases for query expansion.
synonyms: { js: ['javascript'], auth: ['authentication'] }search()
search(query: string, options?: SearchOptions): SearchResult<T>[]
Performs synchronous search and returns ranked results.
SearchOptions
limit: number
Override the default result limit.
filters: Record<string, any>
Exact-match filters on document fields.
filters: { category: 'books', published: true }predicate: (doc: T) => boolean
Custom filter function for complex filtering logic.
predicate: (doc) => doc.rating > 4.0
searchAsync()
searchAsync(query: string, options: AsyncSearchOptions): Promise<SearchResult<T>[]>
Async search with optional hybrid reranking. First retrieves candidates using lexical scoring, then optionally reranks with a custom reranker (e.g., semantic/ML model).
AsyncSearchOptions
reranker: Reranker
Custom reranker with async rerank method.
reranker: {
async rerank({ query, candidates }) {
// Your semantic/ML reranking logic
return candidates.map((c) => ({
refIndex: c.refIndex,
score: semanticScore
}))
}
}rerankLimit: number
Number of lexical candidates to send to the reranker.
autocomplete()
autocomplete(query: string, options?: SearchOptions): SearchResult<T>[]
Prefix-aware autocomplete suggestions using the same scoring pipeline as search.
Mutation Methods
add()
add(doc: T): void
Adds a document to the index without rebuilding.
removeAt()
removeAt(index: number): void
Removes a document by its index position.
remove()
remove(predicate: (doc: T) => boolean): void
Removes all documents matching the predicate.
setCollection()
setCollection(docs: T[]): void
Replaces the entire document collection and rebuilds indexes.
Persistence Methods
save()
async save(adapter: StorageAdapter): Promise<void>
Persists the search index to storage.
load()
static async load<T>(adapter: StorageAdapter): Promise<LumoSearch<T>>
Restores a search index from storage.
exportSnapshot()
exportSnapshot(): SearchSnapshot<T>
Synchronously exports a serializable snapshot.
fromSnapshot()
static fromSnapshot<T>(snapshot: SearchSnapshot<T>): LumoSearch<T>
Creates a search instance from a snapshot.
Types
SearchResult<T>
interface SearchResult<T> {
item: T // Original document
refIndex: number // Position in collection
score: number // Final relevance score
matchedFields: string[] // Fields with matches
highlights: SearchHighlight[] // Character-level match ranges
lexicalScore?: number // Present when reranked
rerankScore?: number // Present when reranked
}SearchHighlight
interface SearchHighlight {
field: string // Field name
value: string // Field content
indices: [number, number][] // Character ranges [start, end]
}