@wcs-colab/plugin-fuzzy-phrase/dist/index.d.ts

Advanced fuzzy phrase matching plugin for Orama with semantic weighting and synonym expansion

import { SearchableValue, OramaPlugin, AnyOrama, Results, TypedDocument } from '@wcs-colab/orama';

/**
 * TypeScript type definitions for Fuzzy Phrase Plugin
 */

/**
 * Configuration for the Fuzzy Phrase Plugin
 */
interface FuzzyPhraseConfig {
    /**
     * Text property to search in
     * @default 'content'
     */
    textProperty?: string;
    /**
     * Base fuzzy matching tolerance (edit distance)
     * @default 1
     */
    tolerance?: number;
    /**
     * Enable adaptive tolerance (scales with query length)
     * @default true
     */
    adaptiveTolerance?: boolean;
    /**
     * Enable synonym expansion
     * @default false
     */
    enableSynonyms?: boolean;
    /**
     * Supabase configuration for loading synonyms
     */
    supabase?: {
        url: string;
        serviceKey: string;
    };
    /**
     * Scoring weight for synonym matches (0-1)
     * @default 0.8
     */
    synonymMatchScore?: number;
    /**
     * Scoring weights for different components
     */
    weights?: {
        /** Weight for exact matches */
        exact?: number;
        /** Weight for fuzzy matches */
        fuzzy?: number;
        /** Weight for phrase order */
        order?: number;
        /** Weight for proximity bonus */
        proximity?: number;
        /** Weight for density bonus */
        density?: number;
        /** Weight for TF-IDF semantic score */
        semantic?: number;
    };
    /**
     * Maximum gap between words in a phrase
     * @default 5
     */
    maxGap?: number;
    /**
     * Minimum phrase score to include in results
     * @default 0.1
     */
    minScore?: number;
}
/**
 * Match information for a single word
 */
interface WordMatch {
    /** The matched word from the document */
    word: string;
    /** The query token that matched */
    queryToken: string;
    /** Position of the word in the document */
    position: number;
    /** Type of match */
    type: 'exact' | 'fuzzy' | 'synonym';
    /** Edit distance for fuzzy matches */
    distance?: number;
    /** Match score (0-1) */
    score: number;
}
/**
 * Phrase match information
 */
interface PhraseMatch {
    /** All word matches in this phrase */
    words: WordMatch[];
    /** Start position in document */
    startPosition: number;
    /** End position in document */
    endPosition: number;
    /** Gap between words */
    gap: number;
    /** Whether words are in correct order */
    inOrder: boolean;
    /** Overall phrase score */
    score: number;
    /** Score breakdown by component */
    scoreBreakdown?: {
        base: number;
        order: number;
        proximity: number;
        density: number;
        semantic: number;
    };
}
/**
 * Document match with all phrase matches
 */
interface DocumentMatch {
    /** Document ID */
    id: string;
    /** All phrase matches found in this document */
    phrases: PhraseMatch[];
    /** Overall document score */
    score: number;
    /** Document data */
    document: Record<string, SearchableValue>;
}
/**
 * Synonym map structure
 */
interface SynonymMap {
    [word: string]: string[];
}
/**
 * Candidate word for matching
 */
interface Candidate {
    word: string;
    type: 'exact' | 'fuzzy' | 'synonym';
    queryToken: string;
    distance?: number;
    score: number;
}

/**
 * Fuzzy Phrase Plugin for Orama
 *
 * Advanced fuzzy phrase matching with semantic weighting and synonym expansion.
 * Completely independent from QPS - accesses Orama's radix tree directly.
 */

/**
 * Create the Fuzzy Phrase Plugin
 *
 * @param userConfig - User configuration options
 * @returns Orama plugin instance
 */
declare function pluginFuzzyPhrase(userConfig?: FuzzyPhraseConfig): OramaPlugin;
/**
 * Search with fuzzy phrase matching
 *
 * This function should be called instead of the regular search() function
 * to enable fuzzy phrase matching.
 */
declare function searchWithFuzzyPhrase<T extends AnyOrama>(orama: T, params: {
    term?: string;
    properties?: string[];
    limit?: number;
}, language?: string): Promise<Results<TypedDocument<T>>>;

export { Candidate, DocumentMatch, FuzzyPhraseConfig, PhraseMatch, SynonymMap, WordMatch, pluginFuzzyPhrase, searchWithFuzzyPhrase };