@wcs-colab/plugin-fuzzy-phrase 3.1.16-custom.newbase.3 → 3.1.16-custom.newbase.32

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OramaPlugin, AnyOrama, Results, TypedDocument } from '@wcs-colab/orama';
+import { AnyOrama, Results, TypedDocument, OramaPlugin } from '@wcs-colab/orama';
 
 /**
  * Shared types for the fuzzy phrase plugin.
@@ -30,8 +30,12 @@ interface FuzzyPhraseConfig {
     };
     /** Maximum gap between words in a phrase */
     maxGap?: number;
-    /** Minimum phrase score to include in results */
+    /** Minimum candidate score to include before phrase building */
     minScore?: number;
+    /** Enable final score filtering after phrase/document scoring */
+    enableFinalScoreMinimum?: boolean;
+    /** Minimum final document score threshold (only applies if enableFinalScoreMinimum is true) */
+    finalScoreMinimum?: number;
     /**
      * Multiplier for proximity window calculation.
      * proximityWindow = queryTokens.length × proximitySpanMultiplier
@@ -100,6 +104,108 @@ interface DocumentMatch {
     score: number;
     document: any;
 }
+interface PluginState {
+    synonymMap: SynonymMap;
+    config: Required<FuzzyPhraseConfig>;
+    documentFrequency: Map<string, number>;
+    totalDocuments: number;
+    /** Cached vocabulary extracted from radix tree (avoids O(V) extraction per query) */
+    vocabulary: Set<string>;
+}
+
+/**
+ * Optimized Search: QPS Candidate Pruning + Fuzzy Phrase Scoring
+ *
+ * This module provides an algorithmic pruning path where:
+ * 1. QPS (Quantum Proximity Scoring) finds candidate documents quickly (token-level, typo-tolerant)
+ * 2. Fuzzy Phrase scoring runs only on those candidates (expensive phrase scoring on smaller set)
+ *
+ * This dramatically reduces the search space for phrase scoring while maintaining
+ * the same result quality as full fuzzy phrase search.
+ */
+
+/**
+ * QPS Index data structure (matches plugin-qps internal format)
+ */
+interface QPSIndexData {
+    indexes: Record<string, {
+        type: string;
+        node: any;
+        isArray: boolean;
+    }>;
+    stats: Record<string, {
+        tokenQuantums: Record<string, Record<string, number>>;
+        tokensLength: Map<string, number>;
+    }>;
+    searchableProperties: string[];
+    searchablePropertiesWithTypes: Record<string, string>;
+    vectorIndexes: Record<string, any>;
+}
+/**
+ * Configuration for optimized search
+ */
+interface OptimizedSearchConfig extends FuzzyPhraseConfig {
+    /** Maximum number of QPS candidates to consider for phrase scoring */
+    maxQPSCandidates?: number;
+    /** Minimum QPS score to include a candidate (0-1, relative to best score) */
+    minQPSScore?: number;
+    /** Whether to use exact matching for QPS (faster but no typo tolerance) */
+    qpsExact?: boolean;
+    /** QPS tolerance (edit distance for fuzzy matching) */
+    qpsTolerance?: number;
+    /** Boost factors per property for QPS scoring */
+    qpsBoostPerProp?: Record<string, number>;
+}
+/**
+ * Normalize text using the same rules as Orama's French tokenizer
+ *
+ * CRITICAL: This must match normalizeFrenchText() in Orama's tokenizer exactly
+ */
+declare function normalizeText(text: string): string;
+/**
+ * Tokenize text using normalization matching Orama's French tokenizer
+ */
+declare function tokenize(text: string): string[];
+/**
+ * Optimized search combining QPS candidate pruning with fuzzy phrase scoring
+ *
+ * This is the main entry point for optimized search. It:
+ * 1. Uses QPS to quickly find candidate documents (token-level matching)
+ * 2. Filters to top candidates by QPS score
+ * 3. Runs full fuzzy phrase scoring only on those candidates
+ *
+ * @param orama - Orama instance
+ * @param qpsIndex - QPS index data (from pluginQPS.getComponents().index)
+ * @param pluginState - Fuzzy phrase plugin state
+ * @param params - Search parameters
+ * @param config - Optimized search configuration
+ * @param language - Language for tokenization (default: french)
+ * @returns Search results with fuzzy phrase scoring
+ */
+declare function searchWithQPSPruning<T extends AnyOrama>(orama: T, qpsIndex: QPSIndexData, pluginState: PluginState, params: {
+    term?: string;
+    properties?: string[];
+    limit?: number;
+    tokenCache?: Map<string, string[]>;
+}, config?: OptimizedSearchConfig, language?: string): Promise<Results<TypedDocument<T>>>;
+/**
+ * Create an optimized search function bound to a specific Orama + QPS index
+ *
+ * This is a convenience wrapper that captures the Orama instance and QPS index,
+ * returning a simpler search function.
+ *
+ * @param orama - Orama instance
+ * @param qpsIndex - QPS index data
+ * @param pluginState - Fuzzy phrase plugin state
+ * @param config - Optimized search configuration
+ * @returns Bound search function
+ */
+declare function createOptimizedSearch<T extends AnyOrama>(orama: T, qpsIndex: QPSIndexData, pluginState: PluginState, config?: OptimizedSearchConfig): (params: {
+    term?: string;
+    properties?: string[];
+    limit?: number;
+    tokenCache?: Map<string, string[]>;
+}, language?: string) => Promise<Results<TypedDocument<T>>>;
 
 /**
  * Fuzzy Phrase Plugin for Orama
@@ -125,6 +231,13 @@ declare function searchWithFuzzyPhrase<T extends AnyOrama>(orama: T, params: {
     term?: string;
     properties?: string[];
     limit?: number;
+    tokenCache?: Map<string, string[]>;
+    candidateIds?: Set<string> | string[];
 }, language?: string): Promise<Results<TypedDocument<T>>>;
 
-export { Candidate, DocumentMatch, FuzzyPhraseConfig, PhraseMatch, SynonymMap, WordMatch, pluginFuzzyPhrase, searchWithFuzzyPhrase };
+/**
+ * Re-export plugin state accessor for optimized search integration
+ */
+declare function getPluginState(orama: any): PluginState | undefined;
+
+export { Candidate, DocumentMatch, FuzzyPhraseConfig, OptimizedSearchConfig, PhraseMatch, PluginState, SynonymMap, WordMatch, createOptimizedSearch, getPluginState, normalizeText as normalizeTextOptimized, pluginFuzzyPhrase, searchWithFuzzyPhrase, searchWithQPSPruning, tokenize as tokenizeOptimized };