mongo.do 0.1.0

package/dist/translator/hybrid-translator.d.ts

@@ -0,0 +1,70 @@
+/**
+ * HybridSearchTranslator - Combines vector and text search results using fusion algorithms
+ *
+ * Supports:
+ * - Reciprocal Rank Fusion (RRF): Combines results based on rank positions
+ * - Score Fusion: Combines normalized scores with configurable weights
+ *
+ * Used for hybrid search combining vector similarity and full-text search results
+ */
+export interface SearchResult {
+    docId: string;
+    score: number;
+}
+export interface FusedResult {
+    docId: string;
+    fusedScore: number;
+    vectorRank?: number;
+    textRank?: number;
+    vectorScore?: number;
+    textScore?: number;
+}
+export interface FusionWeights {
+    vector: number;
+    text: number;
+}
+export declare class HybridSearchTranslator {
+    private readonly RRF_K;
+    constructor();
+    /**
+     * Combine vector and text search results using Reciprocal Rank Fusion
+     *
+     * RRF score = sum(1 / (k + rank)) for each result list where the doc appears
+     *
+     * For vector results: higher score = better match (e.g., 0.95 > 0.87)
+     * For text results (FTS5): more negative = better match (e.g., -1.5 > -3.0)
+     *
+     * @param vectorResults - Results from vector similarity search (higher score = better)
+     * @param textResults - Results from FTS5 text search (more negative = better)
+     * @returns Combined results sorted by fused score (descending)
+     */
+    rankFusion(vectorResults: SearchResult[], textResults: SearchResult[]): FusedResult[];
+    /**
+     * Combine vector and text search results using weighted score fusion
+     *
+     * Normalizes scores to [0, 1] range before combining with weights
+     *
+     * For vector results: assumed to be in [0, 1] range (cosine similarity)
+     * For text results (FTS5): normalized where more negative = lower normalized score
+     *
+     * @param vectorResults - Results from vector similarity search
+     * @param textResults - Results from FTS5 text search
+     * @param weights - Optional weights for vector and text scores (default: 0.5, 0.5)
+     * @returns Combined results sorted by fused score (descending)
+     */
+    scoreFusion(vectorResults: SearchResult[], textResults: SearchResult[], weights?: FusionWeights): FusedResult[];
+    /**
+     * Normalize scores to [0, 1] range using min-max normalization
+     * For single results, preserve the original score (assumed to be in [0, 1] range)
+     */
+    private normalizeScores;
+    /**
+     * Normalize FTS5 text scores (negative values where closer to 0 is better)
+     * Converts to [0, 1] range where 1 is the best match
+     * For single results, preserve the original score if it's positive (e.g., already normalized)
+     * or return 1 for single negative score results
+     */
+    private normalizeTextScores;
+}
+export default HybridSearchTranslator;
+//# sourceMappingURL=hybrid-translator.d.ts.map

package/dist/translator/hybrid-translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-translator.d.ts","sourceRoot":"","sources":["../../src/translator/hybrid-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAMD,qBAAa,sBAAsB;IAGjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAM;;IAQ5B;;;;;;;;;;;OAWG;IACH,UAAU,CACR,aAAa,EAAE,YAAY,EAAE,EAC7B,WAAW,EAAE,YAAY,EAAE,GAC1B,WAAW,EAAE;IA4DhB;;;;;;;;;;;;OAYG;IACH,WAAW,CACT,aAAa,EAAE,YAAY,EAAE,EAC7B,WAAW,EAAE,YAAY,EAAE,EAC3B,OAAO,GAAE,aAA0C,GAClD,WAAW,EAAE;IAyDhB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;CA2B5B;AAED,eAAe,sBAAsB,CAAC"}

package/dist/translator/hybrid-translator.js

@@ -0,0 +1,193 @@
+/**
+ * HybridSearchTranslator - Combines vector and text search results using fusion algorithms
+ *
+ * Supports:
+ * - Reciprocal Rank Fusion (RRF): Combines results based on rank positions
+ * - Score Fusion: Combines normalized scores with configurable weights
+ *
+ * Used for hybrid search combining vector similarity and full-text search results
+ */
+// ============================================================
+// HybridSearchTranslator Class
+// ============================================================
+export class HybridSearchTranslator {
+    // RRF constant k - controls how much weight is given to lower-ranked results
+    // Higher k values give more weight to items ranked lower in the list
+    RRF_K = 60;
+    constructor() { }
+    // ============================================================
+    // Reciprocal Rank Fusion (RRF)
+    // ============================================================
+    /**
+     * Combine vector and text search results using Reciprocal Rank Fusion
+     *
+     * RRF score = sum(1 / (k + rank)) for each result list where the doc appears
+     *
+     * For vector results: higher score = better match (e.g., 0.95 > 0.87)
+     * For text results (FTS5): more negative = better match (e.g., -1.5 > -3.0)
+     *
+     * @param vectorResults - Results from vector similarity search (higher score = better)
+     * @param textResults - Results from FTS5 text search (more negative = better)
+     * @returns Combined results sorted by fused score (descending)
+     */
+    rankFusion(vectorResults, textResults) {
+        const docScores = new Map();
+        // Process vector results - already sorted by score descending (higher = better)
+        const sortedVectorResults = [...vectorResults].sort((a, b) => b.score - a.score);
+        sortedVectorResults.forEach((result, index) => {
+            const rank = index + 1; // 1-indexed rank
+            const rrfScore = 1 / (this.RRF_K + rank);
+            const existing = docScores.get(result.docId);
+            if (existing) {
+                existing.fusedScore += rrfScore;
+                existing.vectorRank = rank;
+                existing.vectorScore = result.score;
+            }
+            else {
+                docScores.set(result.docId, {
+                    docId: result.docId,
+                    fusedScore: rrfScore,
+                    vectorRank: rank,
+                    vectorScore: result.score,
+                });
+            }
+        });
+        // Process text results - sort by score descending (less negative = better for FTS5)
+        // FTS5 returns negative scores where closer to 0 is better
+        const sortedTextResults = [...textResults].sort((a, b) => b.score - a.score);
+        sortedTextResults.forEach((result, index) => {
+            const rank = index + 1; // 1-indexed rank
+            const rrfScore = 1 / (this.RRF_K + rank);
+            const existing = docScores.get(result.docId);
+            if (existing) {
+                existing.fusedScore += rrfScore;
+                existing.textRank = rank;
+                existing.textScore = result.score;
+            }
+            else {
+                docScores.set(result.docId, {
+                    docId: result.docId,
+                    fusedScore: rrfScore,
+                    textRank: rank,
+                    textScore: result.score,
+                });
+            }
+        });
+        // Sort by fused score descending
+        return Array.from(docScores.values()).sort((a, b) => b.fusedScore - a.fusedScore);
+    }
+    // ============================================================
+    // Score Fusion
+    // ============================================================
+    /**
+     * Combine vector and text search results using weighted score fusion
+     *
+     * Normalizes scores to [0, 1] range before combining with weights
+     *
+     * For vector results: assumed to be in [0, 1] range (cosine similarity)
+     * For text results (FTS5): normalized where more negative = lower normalized score
+     *
+     * @param vectorResults - Results from vector similarity search
+     * @param textResults - Results from FTS5 text search
+     * @param weights - Optional weights for vector and text scores (default: 0.5, 0.5)
+     * @returns Combined results sorted by fused score (descending)
+     */
+    scoreFusion(vectorResults, textResults, weights = { vector: 0.5, text: 0.5 }) {
+        const docScores = new Map();
+        // Normalize vector scores (assuming already in reasonable range)
+        const normalizedVectorResults = this.normalizeScores(vectorResults);
+        // Normalize text scores (FTS5 negative scores)
+        const normalizedTextResults = this.normalizeTextScores(textResults);
+        // Create lookup maps for normalized scores
+        const vectorScoreMap = new Map();
+        normalizedVectorResults.forEach((r) => vectorScoreMap.set(r.docId, r.score));
+        const textScoreMap = new Map();
+        normalizedTextResults.forEach((r) => textScoreMap.set(r.docId, r.score));
+        // Collect all unique document IDs
+        const allDocIds = new Set([
+            ...vectorResults.map((r) => r.docId),
+            ...textResults.map((r) => r.docId),
+        ]);
+        // Calculate fused scores
+        for (const docId of allDocIds) {
+            const vectorScore = vectorScoreMap.get(docId) ?? 0;
+            const textScore = textScoreMap.get(docId) ?? 0;
+            const fusedScore = weights.vector * vectorScore + weights.text * textScore;
+            const vectorOriginal = vectorResults.find((r) => r.docId === docId);
+            const textOriginal = textResults.find((r) => r.docId === docId);
+            const result = {
+                docId,
+                fusedScore,
+            };
+            if (vectorOriginal !== undefined) {
+                result.vectorScore = vectorOriginal.score;
+            }
+            if (textOriginal !== undefined) {
+                result.textScore = textOriginal.score;
+            }
+            docScores.set(docId, result);
+        }
+        // Sort by fused score descending
+        return Array.from(docScores.values()).sort((a, b) => b.fusedScore - a.fusedScore);
+    }
+    // ============================================================
+    // Score Normalization
+    // ============================================================
+    /**
+     * Normalize scores to [0, 1] range using min-max normalization
+     * For single results, preserve the original score (assumed to be in [0, 1] range)
+     */
+    normalizeScores(results) {
+        if (results.length === 0)
+            return [];
+        // For single result, keep original score (vector scores assumed to be in [0, 1])
+        const first = results[0];
+        if (results.length === 1 && first)
+            return [{ docId: first.docId, score: first.score }];
+        const scores = results.map((r) => r.score);
+        const minScore = Math.min(...scores);
+        const maxScore = Math.max(...scores);
+        const range = maxScore - minScore;
+        if (range === 0) {
+            // All scores are the same - keep original scores
+            return results.map((r) => ({ ...r }));
+        }
+        return results.map((r) => ({
+            ...r,
+            score: (r.score - minScore) / range,
+        }));
+    }
+    /**
+     * Normalize FTS5 text scores (negative values where closer to 0 is better)
+     * Converts to [0, 1] range where 1 is the best match
+     * For single results, preserve the original score if it's positive (e.g., already normalized)
+     * or return 1 for single negative score results
+     */
+    normalizeTextScores(results) {
+        if (results.length === 0)
+            return [];
+        // For single result, keep original score if non-negative, otherwise use 1
+        const first = results[0];
+        if (results.length === 1 && first) {
+            const score = first.score;
+            // If score is non-negative, assume it's already normalized or in valid range
+            return [{ docId: first.docId, score: score >= 0 ? score : 1 }];
+        }
+        const scores = results.map((r) => r.score);
+        const minScore = Math.min(...scores); // Most negative (worst)
+        const maxScore = Math.max(...scores); // Least negative (best)
+        const range = maxScore - minScore;
+        if (range === 0) {
+            // All scores are the same - return 1 for all
+            return results.map((r) => ({ ...r, score: 1 }));
+        }
+        // Normalize so that the highest (least negative) score becomes 1
+        // and the lowest (most negative) score becomes 0
+        return results.map((r) => ({
+            ...r,
+            score: (r.score - minScore) / range,
+        }));
+    }
+}
+export default HybridSearchTranslator;
+//# sourceMappingURL=hybrid-translator.js.map

package/dist/translator/hybrid-translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hybrid-translator.js","sourceRoot":"","sources":["../../src/translator/hybrid-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyBH,+DAA+D;AAC/D,+BAA+B;AAC/B,+DAA+D;AAE/D,MAAM,OAAO,sBAAsB;IACjC,6EAA6E;IAC7E,qEAAqE;IACpD,KAAK,GAAG,EAAE,CAAC;IAE5B,gBAAe,CAAC;IAEhB,+DAA+D;IAC/D,+BAA+B;IAC/B,+DAA+D;IAE/D;;;;;;;;;;;OAWG;IACH,UAAU,CACR,aAA6B,EAC7B,WAA2B;QAE3B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;QAEjD,gFAAgF;QAChF,MAAM,mBAAmB,GAAG,CAAC,GAAG,aAAa,CAAC,CAAC,IAAI,CACjD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAC5B,CAAC;QACF,mBAAmB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,iBAAiB;YACzC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;YAEzC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC;gBAChC,QAAQ,CAAC,UAAU,GAAG,IAAI,CAAC;gBAC3B,QAAQ,CAAC,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE;oBAC1B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,QAAQ;oBACpB,UAAU,EAAE,IAAI;oBAChB,WAAW,EAAE,MAAM,CAAC,KAAK;iBAC1B,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,oFAAoF;QACpF,2DAA2D;QAC3D,MAAM,iBAAiB,GAAG,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAC7C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAC5B,CAAC;QACF,iBAAiB,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;YAC1C,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,iBAAiB;YACzC,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;YAEzC,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC7C,IAAI,QAAQ,EAAE,CAAC;gBACb,QAAQ,CAAC,UAAU,IAAI,QAAQ,CAAC;gBAChC,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC;gBACzB,QAAQ,CAAC,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE;oBAC1B,KAAK,EAAE,MAAM,CAAC,KAAK;oBACnB,UAAU,EAAE,QAAQ;oBACpB,QAAQ,EAAE,IAAI;oBACd,SAAS,EAAE,MAAM,CAAC,KAAK;iBACxB,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,iCAAiC;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CACtC,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,eAAe;IACf,+DAA+D;IAE/D;;;;;;;;;;;;OAYG;IACH,WAAW,CACT,aAA6B,EAC7B,WAA2B,EAC3B,UAAyB,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE;QAEnD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAuB,CAAC;QAEjD,iEAAiE;QACjE,MAAM,uBAAuB,GAAG,IAAI,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;QAEpE,+CAA+C;QAC/C,MAAM,qBAAqB,GAAG,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;QAEpE,2CAA2C;QAC3C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;QACjD,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAE7E,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC/C,qBAAqB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QAEzE,kCAAkC;QAClC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAS;YAChC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;YACpC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;SACnC,CAAC,CAAC;QAEH,yBAAyB;QACzB,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;YAC9B,MAAM,WAAW,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACnD,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAE/C,MAAM,UAAU,GACd,OAAO,CAAC,MAAM,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC;YAE1D,MAAM,cAAc,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;YACpE,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;YAEhE,MAAM,MAAM,GAAgB;gBAC1B,KAAK;gBACL,UAAU;aACX,CAAC;YACF,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,CAAC,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC;YAC5C,CAAC;YACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,CAAC,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC;YACxC,CAAC;YAED,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC/B,CAAC;QAED,iCAAiC;QACjC,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CACxC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CACtC,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,sBAAsB;IACtB,+DAA+D;IAE/D;;;OAGG;IACK,eAAe,CAAC,OAAuB;QAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACpC,iFAAiF;QACjF,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK;YAAE,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAEvF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAElC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,iDAAiD;YACjD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,GAAG,CAAC;YACJ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,KAAK;SACpC,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;;;;OAKG;IACK,mBAAmB,CAAC,OAAuB;QACjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACpC,0EAA0E;QAC1E,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YAC1B,6EAA6E;YAC7E,OAAO,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,wBAAwB;QAC9D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,wBAAwB;QAC9D,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAElC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,6CAA6C;YAC7C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAClD,CAAC;QAED,iEAAiE;QACjE,iDAAiD;QACjD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,GAAG,CAAC;YACJ,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,KAAK;SACpC,CAAC,CAAC,CAAC;IACN,CAAC;CACF;AAED,eAAe,sBAAsB,CAAC"}

package/dist/translator/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Query and Update translators
+ *
+ * Translates MongoDB query syntax to SQL for the SQLite backend
+ */
+export { QueryTranslator } from './query-translator';
+export { UpdateTranslator } from './update-translator';
+export { SearchTranslator } from './search-translator';
+export type { AutocompleteOperator } from './search-translator';
+export { HybridSearchTranslator } from './hybrid-translator';
+export { buildHighlightSQL, buildSnippetSQL, buildHighlightSelectClause, buildSnippetSelectClause } from './search-highlight';
+export type { HighlightOptions, SnippetOptions } from './search-highlight';
+//# sourceMappingURL=index.d.ts.map

package/dist/translator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/translator/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA;AAC7H,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/translator/index.js

@@ -0,0 +1,11 @@
+/**
+ * Query and Update translators
+ *
+ * Translates MongoDB query syntax to SQL for the SQLite backend
+ */
+export { QueryTranslator } from './query-translator';
+export { UpdateTranslator } from './update-translator';
+export { SearchTranslator } from './search-translator';
+export { HybridSearchTranslator } from './hybrid-translator';
+export { buildHighlightSQL, buildSnippetSQL, buildHighlightSelectClause, buildSnippetSelectClause } from './search-highlight';
+//# sourceMappingURL=index.js.map

package/dist/translator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/translator/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAC5D,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/translator/query-translator.d.ts

@@ -0,0 +1,211 @@
+/**
+ * QueryTranslator - Translates MongoDB-style queries to SQL
+ * using json_extract for field access on JSON documents.
+ *
+ * Features:
+ * - Operator registry pattern for extensibility
+ * - Automatic flattening of nested $and/$or for SQL optimization
+ * - CTE-based optimization for multiple array operations
+ * - Parameterized queries for SQL injection prevention
+ * - $text operator for full-text search with FTS5
+ * - Multi-dialect support (SQLite, ClickHouse)
+ */
+import { type DialectOptions } from './dialect.js';
+export interface TranslatedQuery {
+    sql: string;
+    params: unknown[];
+    /** Whether this query requires an FTS5 join */
+    requiresFTS?: boolean;
+    /** The FTS5 match expression (for building full query) */
+    ftsMatch?: string;
+}
+type QueryValue = unknown;
+/**
+ * Operator handler type for the registry pattern
+ */
+type OperatorHandler = (path: string, value: QueryValue, params: unknown[]) => string;
+/**
+ * Options for query translation
+ */
+export interface TranslateOptions extends DialectOptions {
+    /**
+     * Enable CTE optimization for array operations
+     * When enabled, multiple array checks on the same field use a single CTE
+     */
+    useCTE?: boolean;
+    /**
+     * Flatten nested logical operators
+     * When enabled, nested $and/$or of the same type are merged
+     */
+    flattenLogical?: boolean;
+}
+/**
+ * QueryTranslator - Converts MongoDB query syntax to SQL with json_extract
+ */
+export declare class QueryTranslator {
+    private options;
+    private dialect;
+    constructor(options?: TranslateOptions);
+    /**
+     * Registry of comparison operators and their SQL translations
+     */
+    private comparisonOperators;
+    /**
+     * Registry of element operators
+     */
+    private elementOperators;
+    /**
+     * Registry of array operators
+     */
+    private arrayOperators;
+    /**
+     * Main entry point - translate a MongoDB query to SQL
+     */
+    translate(query: Record<string, unknown>): TranslatedQuery;
+    /**
+     * Flatten nested logical operators of the same type
+     * E.g., $and: [{ $and: [a, b] }, c] -> $and: [a, b, c]
+     */
+    private flattenLogicalOperators;
+    /**
+     * Translate a query document (top-level or nested)
+     */
+    private translateDocument;
+    /**
+     * Translate a field condition
+     */
+    private translateField;
+    /**
+     * Translate conditions on a single field
+     */
+    private translateFieldConditions;
+    /**
+     * Translate logical operators ($and, $or, $not, $nor, $text)
+     */
+    private translateLogicalOperator;
+    /**
+     * Convert a field name to a JSON path
+     * e.g., "a.b.c" -> "$.a.b.c"
+     * e.g., "items.0.name" -> "$.items[0].name"
+     *
+     * SECURITY: Validates field name to prevent SQL injection attacks.
+     * @throws Error if field contains invalid characters
+     */
+    private fieldToJsonPath;
+    /**
+     * Generate json_extract SQL for a path
+     */
+    private jsonExtract;
+    /**
+     * Convert a bitwise operator value to a bitmask
+     * Accepts either:
+     * - A number (used directly as bitmask)
+     * - An array of bit positions (converted to bitmask)
+     */
+    private resolveBitmask;
+    /**
+     * Generate path for elemMatch field access
+     * SECURITY: Validates field name to prevent SQL injection attacks.
+     */
+    private elemMatchFieldPath;
+    /**
+     * Convert a regex pattern to SQLite LIKE/GLOB pattern
+     * This handles common regex patterns:
+     * - ^pattern -> pattern% (starts with)
+     * - pattern$ -> %pattern (ends with)
+     * - ^pattern$ -> pattern (exact match)
+     * - .* or .+ -> % (any characters)
+     * - . -> _ (single character)
+     * - [0-9] -> character class (converted to GLOB syntax)
+     * - [a-z] -> character class (converted to GLOB syntax)
+     * - Literal text -> %text% (contains, default behavior)
+     *
+     * @param pattern The regex pattern to convert
+     * @param options Regex options (i=case-insensitive, m=multiline)
+     */
+    private regexToLike;
+    /**
+     * Translate conditions inside $elemMatch
+     * This handles document conditions like { field: value, field: { $op: value } }
+     * SECURITY: Validates field names to prevent SQL injection attacks.
+     */
+    private translateElemMatchConditions;
+    /**
+     * Translate a single operator for elemMatch context
+     */
+    private translateElemMatchOperator;
+    /**
+     * Generate optimized SQL with CTE for multiple array operations on the same field
+     * This is useful when you have multiple $all checks or $elemMatch on the same array
+     *
+     * Example output:
+     * WITH array_cte AS (
+     *   SELECT value FROM json_each(json_extract(data, '$.tags'))
+     * )
+     * SELECT * FROM documents WHERE
+     *   EXISTS (SELECT 1 FROM array_cte WHERE value = ?) AND
+     *   EXISTS (SELECT 1 FROM array_cte WHERE value = ?)
+     */
+    translateWithCTE(query: Record<string, unknown>, tableName?: string): TranslatedQuery;
+    /**
+     * Collect array operations for CTE optimization analysis
+     */
+    private collectArrayOperations;
+    /**
+     * Translate document using CTE aliases where applicable
+     */
+    private translateDocumentWithCTE;
+    /**
+     * Register a custom comparison operator
+     * Allows extending the translator with custom operators
+     */
+    registerOperator(name: string, handler: OperatorHandler): void;
+    /**
+     * Register a custom element operator
+     */
+    registerElementOperator(name: string, handler: OperatorHandler): void;
+    /**
+     * Register a custom array operator
+     */
+    registerArrayOperator(name: string, handler: OperatorHandler): void;
+    /**
+     * Translate a MongoDB $text query to FTS5 MATCH SQL
+     */
+    private translateTextOperator;
+    /**
+     * Convert MongoDB text search syntax to FTS5 query syntax
+     *
+     * MongoDB syntax:
+     * - "word" -> matches word
+     * - "word1 word2" -> matches word1 OR word2
+     * - "\"phrase\"" -> matches exact phrase
+     * - "-word" -> excludes word (negation)
+     *
+     * FTS5 syntax:
+     * - "word" -> matches word
+     * - "word1 OR word2" -> matches word1 or word2
+     * - "word1 word2" -> matches word1 AND word2
+     * - "\"phrase\"" -> matches exact phrase
+     * - "NOT word" -> excludes word
+     */
+    private convertToFTS5Query;
+    /**
+     * Translate a query with $meta projection support for textScore
+     *
+     * @param query The MongoDB query (must contain $text for textScore)
+     * @param projection The projection with potential {$meta: "textScore"} fields
+     * @param sort Optional sort with potential {$meta: "textScore"} fields
+     */
+    translateWithMeta(query: Record<string, unknown>, projection?: Record<string, unknown>, sort?: Record<string, unknown>): TranslatedQuery;
+    /**
+     * Translate a JSON Schema to SQL conditions
+     * Supports common JSON Schema validation keywords
+     *
+     * @param schema The JSON Schema to validate against
+     * @param path The current JSON path (e.g., "$.field.nested")
+     * @param params The parameters array to push values to
+     */
+    private translateJsonSchema;
+}
+export {};
+//# sourceMappingURL=query-translator.d.ts.map

package/dist/translator/query-translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-translator.d.ts","sourceRoot":"","sources":["../../src/translator/query-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAEL,KAAK,cAAc,EAOpB,MAAM,cAAc,CAAC;AAGtB,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,EAAE,CAAC;IAClB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,UAAU,GAAG,OAAO,CAAC;AAG1B;;GAEG;AACH,KAAK,eAAe,GAAG,CACrB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,OAAO,EAAE,KACd,MAAM,CAAC;AA8CZ;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAQD;;GAEG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAmB;IAClC,OAAO,CAAC,OAAO,CAAa;gBAEhB,OAAO,GAAE,gBAAqB;IAO1C;;OAEG;IACH,OAAO,CAAC,mBAAmB,CA+IzB;IAEF;;OAEG;IACH,OAAO,CAAC,gBAAgB,CAqDtB;IAEF;;OAEG;IACH,OAAO,CAAC,cAAc,CA0BpB;IAEF;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe;IAgB1D;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAwD/B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IA6BzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAyBtB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAkEhC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAgFhC;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,OAAO,CAAC,WAAW;IASnB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAYtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAkB1B;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,WAAW;IAmHnB;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;IA+CpC;;OAEG;IACH,OAAO,CAAC,0BAA0B;IA4FlC;;;;;;;;;;;OAWG;IACH,gBAAgB,CACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,GAAE,MAAoB,GAC9B,eAAe;IAsClB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAsB9B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAWhC;;;OAGG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAO9D;;OAEG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAOrE;;OAEG;IACH,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI;IAOnE;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,kBAAkB;IA6E1B;;;;;;OAMG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,eAAe;IAgElB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;CAgK5B"}