@stablemodels/qmd-cf 0.1.0

package/dist/qmd.d.ts

@@ -0,0 +1,158 @@
+import type { Document, EmbedFn, FtsResult, HybridSearchOptions, IndexStats, QmdConfig, SearchOptions, SearchResult, VectorResult } from "./types.js";
+/**
+ * Qmd — Hybrid full-text + vector search for Cloudflare Durable Objects.
+ *
+ * A DO-native reimagination of qmd (https://github.com/tobi/qmd) that brings
+ * hybrid BM25 + semantic search to Cloudflare's edge.
+ *
+ * FTS5 runs co-located in the Durable Object's SQLite for zero-latency keyword search.
+ * Vector search optionally uses Cloudflare Vectorize for semantic similarity.
+ *
+ * Usage:
+ * ```ts
+ * // FTS-only (no external dependencies)
+ * const qmd = new Qmd(ctx.storage.sql);
+ *
+ * // Hybrid FTS + Vector
+ * const qmd = new Qmd(ctx.storage.sql, {
+ *   vectorize: env.VECTORIZE,
+ *   embedFn: (texts) => workerAiEmbed(env.AI, texts),
+ * });
+ *
+ * // Index a document
+ * await qmd.index({ id: "soul.md", content: "...", title: "Soul" });
+ *
+ * // Search
+ * const results = await qmd.search("what does the agent care about?");
+ * ```
+ */
+export declare class Qmd {
+    private sql;
+    private vectorize;
+    private embedFn;
+    private config;
+    private initialized;
+    constructor(sql: SqlStorage, options?: {
+        vectorize?: Vectorize;
+        embedFn?: EmbedFn;
+        config?: QmdConfig;
+    });
+    /** Ensure the FTS5 schema is initialized. Called automatically on first operation. */
+    private ensureInit;
+    /** Whether vector search is available. */
+    get hasVectorSearch(): boolean;
+    /**
+     * Index a document for search.
+     *
+     * The document is chunked and inserted into FTS5. If Vectorize is configured,
+     * chunks are also embedded and upserted into the vector index.
+     *
+     * If the content is unchanged (same hash), chunking and vector indexing are
+     * skipped. Document metadata (title, namespace, etc.) is always updated.
+     */
+    index(doc: Document): Promise<{
+        chunks: number;
+        skipped: boolean;
+    }>;
+    /**
+     * Index multiple documents in batch.
+     * More efficient than calling index() in a loop when Vectorize is configured,
+     * as embeddings are batched.
+     */
+    indexBatch(docs: Document[]): Promise<{
+        documents: number;
+        chunks: number;
+        skipped: number;
+    }>;
+    /**
+     * Remove a document and all its chunks from the index.
+     * Also removes vectors from Vectorize if configured.
+     */
+    remove(docId: string): Promise<void>;
+    /**
+     * Full-text search using FTS5 BM25 ranking.
+     * Always available — no external dependencies needed.
+     */
+    searchFts(query: string, options?: SearchOptions): FtsResult[];
+    /**
+     * Vector similarity search using Cloudflare Vectorize.
+     * Requires vectorize + embedFn to be configured.
+     */
+    searchVector(query: string, options?: SearchOptions): Promise<VectorResult[]>;
+    /**
+     * Hybrid search combining FTS5 BM25 + Vectorize similarity via Reciprocal Rank Fusion.
+     *
+     * If only FTS is available, falls back to FTS-only results wrapped as SearchResult[].
+     * If both are available, runs FTS first as a probe. If BM25 has a strong signal
+     * (top score >= 0.85 with gap >= 0.15 to second), returns FTS results directly
+     * without the Vectorize round-trip. Otherwise, runs vector search and fuses with RRF.
+     */
+    search(query: string, options?: HybridSearchOptions): Promise<SearchResult[]>;
+    /**
+     * Get a document by ID. Returns the full reconstructed content.
+     */
+    get(docId: string): {
+        content: string;
+        title: string | null;
+        docType: string | null;
+    } | null;
+    /**
+     * Check if a document exists in the index.
+     */
+    has(docId: string): boolean;
+    /**
+     * List all indexed document IDs, optionally filtered.
+     */
+    list(options?: {
+        namespace?: string;
+        docType?: string;
+    }): string[];
+    /**
+     * List documents by namespace pattern. Direct SQL query — no FTS or vector search.
+     * Supports glob patterns: "people/*" matches all namespaces starting with "people/".
+     * Returns documents ordered by most recently updated first.
+     */
+    listByNamespace(pattern: string, limit?: number): Array<{
+        docId: string;
+        title: string | null;
+        content: string;
+        namespace: string | null;
+    }>;
+    /**
+     * Get index statistics.
+     */
+    stats(): IndexStats;
+    /**
+     * Rebuild the FTS index from scratch.
+     * Useful after schema changes or data corruption.
+     */
+    rebuild(): void;
+    /**
+     * Set a context description for a path prefix.
+     * Contexts enrich vector embeddings for all documents matching the prefix.
+     */
+    setContext(prefix: string, description: string, namespace?: string): void;
+    /**
+     * Remove a context by prefix.
+     */
+    removeContext(prefix: string, namespace?: string): void;
+    /**
+     * List all contexts, optionally filtered by namespace.
+     */
+    listContexts(namespace?: string): Array<{
+        prefix: string;
+        description: string;
+        namespace: string;
+    }>;
+    /**
+     * Get all matching contexts for a document ID.
+     * Matches hierarchically: for "life/areas/health/exercise.md",
+     * returns contexts at "", "life/", "life/areas/", "life/areas/health/".
+     * Results ordered from most general to most specific.
+     */
+    getContextsForDoc(docId: string): Array<{
+        prefix: string;
+        description: string;
+    }>;
+}
+//# sourceMappingURL=qmd.d.ts.map

package/dist/qmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qmd.d.ts","sourceRoot":"","sources":["../src/qmd.ts"],"names":[],"mappings":"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"}

package/dist/qmd.js

@@ -0,0 +1,462 @@
+import { chunkText } from "./chunker.js";
+import { searchFts } from "./fts.js";
+import { fnv1a32 } from "./hash.js";
+import { reciprocalRankFusion } from "./rrf.js";
+import { initSchema } from "./schema.js";
+import { indexVectors, removeVectors, searchVector } from "./vector.js";
+/** Minimum normalized BM25 score to consider a "strong signal". */
+const STRONG_SIGNAL_MIN_SCORE = 0.85;
+/** Minimum gap between top-1 and top-2 BM25 scores for strong signal. */
+const STRONG_SIGNAL_MIN_GAP = 0.15;
+/**
+ * Qmd — Hybrid full-text + vector search for Cloudflare Durable Objects.
+ *
+ * A DO-native reimagination of qmd (https://github.com/tobi/qmd) that brings
+ * hybrid BM25 + semantic search to Cloudflare's edge.
+ *
+ * FTS5 runs co-located in the Durable Object's SQLite for zero-latency keyword search.
+ * Vector search optionally uses Cloudflare Vectorize for semantic similarity.
+ *
+ * Usage:
+ * ```ts
+ * // FTS-only (no external dependencies)
+ * const qmd = new Qmd(ctx.storage.sql);
+ *
+ * // Hybrid FTS + Vector
+ * const qmd = new Qmd(ctx.storage.sql, {
+ *   vectorize: env.VECTORIZE,
+ *   embedFn: (texts) => workerAiEmbed(env.AI, texts),
+ * });
+ *
+ * // Index a document
+ * await qmd.index({ id: "soul.md", content: "...", title: "Soul" });
+ *
+ * // Search
+ * const results = await qmd.search("what does the agent care about?");
+ * ```
+ */
+export class Qmd {
+    sql;
+    vectorize;
+    embedFn;
+    config;
+    initialized = false;
+    constructor(sql, options) {
+        this.sql = sql;
+        this.vectorize = options?.vectorize ?? null;
+        this.embedFn = options?.embedFn ?? null;
+        if (this.vectorize && !this.embedFn) {
+            throw new Error("embedFn is required when vectorize is provided");
+        }
+        this.config = {
+            chunkSize: options?.config?.chunkSize ?? 3200,
+            chunkOverlap: options?.config?.chunkOverlap ?? 480,
+            tokenizer: options?.config?.tokenizer ?? "unicode61",
+        };
+    }
+    /** Ensure the FTS5 schema is initialized. Called automatically on first operation. */
+    ensureInit() {
+        if (this.initialized)
+            return;
+        initSchema(this.sql, this.config.tokenizer);
+        this.initialized = true;
+    }
+    /** Whether vector search is available. */
+    get hasVectorSearch() {
+        return this.vectorize !== null && this.embedFn !== null;
+    }
+    /**
+     * Index a document for search.
+     *
+     * The document is chunked and inserted into FTS5. If Vectorize is configured,
+     * chunks are also embedded and upserted into the vector index.
+     *
+     * If the content is unchanged (same hash), chunking and vector indexing are
+     * skipped. Document metadata (title, namespace, etc.) is always updated.
+     */
+    async index(doc) {
+        this.ensureInit();
+        const contentHash = fnv1a32(doc.content);
+        const metadataJson = doc.metadata ? JSON.stringify(doc.metadata) : null;
+        // Check if content is unchanged
+        const existing = this.sql
+            .exec("SELECT content_hash FROM qmd_documents WHERE id = ?", doc.id)
+            .toArray();
+        if (existing.length > 0 && existing[0].content_hash === contentHash) {
+            // Content unchanged — update metadata but skip re-chunking
+            this.sql.exec(`UPDATE qmd_documents SET title = ?, doc_type = ?, namespace = ?, metadata = ?, updated_at = datetime('now')
+				 WHERE id = ?`, doc.title ?? null, doc.docType ?? null, doc.namespace ?? null, metadataJson, doc.id);
+            const chunkCount = this.sql
+                .exec("SELECT COUNT(*) as cnt FROM qmd_chunks WHERE doc_id = ?", doc.id)
+                .one().cnt;
+            return { chunks: chunkCount, skipped: true };
+        }
+        // Upsert document metadata with content hash
+        this.sql.exec(`INSERT OR REPLACE INTO qmd_documents (id, title, doc_type, namespace, metadata, content_hash, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`, doc.id, doc.title ?? null, doc.docType ?? null, doc.namespace ?? null, metadataJson, contentHash);
+        // Delete old chunks (triggers will clean up FTS)
+        this.sql.exec("DELETE FROM qmd_chunks WHERE doc_id = ?", doc.id);
+        // Chunk and insert
+        const chunks = chunkText(doc.id, doc.content, this.config.chunkSize, this.config.chunkOverlap);
+        for (const chunk of chunks) {
+            this.sql.exec("INSERT INTO qmd_chunks (doc_id, seq, content, char_offset) VALUES (?, ?, ?, ?)", chunk.docId, chunk.seq, chunk.text, chunk.charOffset);
+        }
+        // Vector indexing (async, non-blocking for FTS)
+        if (this.vectorize && this.embedFn) {
+            const contexts = this.getContextsForDoc(doc.id);
+            const contextText = contexts.map((c) => c.description).join(". ");
+            await indexVectors(this.vectorize, this.embedFn, chunks.map((c) => ({
+                docId: c.docId,
+                seq: c.seq,
+                text: c.text,
+                title: doc.title,
+                namespace: doc.namespace,
+                docType: doc.docType,
+                context: contextText || undefined,
+            })));
+        }
+        return { chunks: chunks.length, skipped: false };
+    }
+    /**
+     * Index multiple documents in batch.
+     * More efficient than calling index() in a loop when Vectorize is configured,
+     * as embeddings are batched.
+     */
+    async indexBatch(docs) {
+        this.ensureInit();
+        let totalChunks = 0;
+        let skippedCount = 0;
+        const allVectorChunks = [];
+        for (const doc of docs) {
+            const contentHash = fnv1a32(doc.content);
+            const metadataJson = doc.metadata ? JSON.stringify(doc.metadata) : null;
+            // Check if content is unchanged
+            const existing = this.sql
+                .exec("SELECT content_hash FROM qmd_documents WHERE id = ?", doc.id)
+                .toArray();
+            if (existing.length > 0 && existing[0].content_hash === contentHash) {
+                // Update metadata, skip re-chunking
+                this.sql.exec(`UPDATE qmd_documents SET title = ?, doc_type = ?, namespace = ?, metadata = ?, updated_at = datetime('now')
+					 WHERE id = ?`, doc.title ?? null, doc.docType ?? null, doc.namespace ?? null, metadataJson, doc.id);
+                const chunkCount = this.sql
+                    .exec("SELECT COUNT(*) as cnt FROM qmd_chunks WHERE doc_id = ?", doc.id)
+                    .one().cnt;
+                totalChunks += chunkCount;
+                skippedCount++;
+                continue;
+            }
+            this.sql.exec(`INSERT OR REPLACE INTO qmd_documents (id, title, doc_type, namespace, metadata, content_hash, updated_at)
+				 VALUES (?, ?, ?, ?, ?, ?, datetime('now'))`, doc.id, doc.title ?? null, doc.docType ?? null, doc.namespace ?? null, metadataJson, contentHash);
+            this.sql.exec("DELETE FROM qmd_chunks WHERE doc_id = ?", doc.id);
+            const chunks = chunkText(doc.id, doc.content, this.config.chunkSize, this.config.chunkOverlap);
+            for (const chunk of chunks) {
+                this.sql.exec("INSERT INTO qmd_chunks (doc_id, seq, content, char_offset) VALUES (?, ?, ?, ?)", chunk.docId, chunk.seq, chunk.text, chunk.charOffset);
+            }
+            totalChunks += chunks.length;
+            if (this.vectorize && this.embedFn) {
+                const contexts = this.getContextsForDoc(doc.id);
+                const contextText = contexts.map((c) => c.description).join(". ");
+                for (const c of chunks) {
+                    allVectorChunks.push({
+                        docId: c.docId,
+                        seq: c.seq,
+                        text: c.text,
+                        title: doc.title,
+                        namespace: doc.namespace,
+                        docType: doc.docType,
+                        context: contextText || undefined,
+                    });
+                }
+            }
+        }
+        // Batch embed and upsert vectors
+        if (this.vectorize && this.embedFn && allVectorChunks.length > 0) {
+            await indexVectors(this.vectorize, this.embedFn, allVectorChunks);
+        }
+        return {
+            documents: docs.length,
+            chunks: totalChunks,
+            skipped: skippedCount,
+        };
+    }
+    /**
+     * Remove a document and all its chunks from the index.
+     * Also removes vectors from Vectorize if configured.
+     */
+    async remove(docId) {
+        this.ensureInit();
+        if (this.vectorize) {
+            await removeVectors(this.vectorize, this.sql, docId);
+        }
+        // Delete chunks (FTS cleanup via trigger)
+        this.sql.exec("DELETE FROM qmd_chunks WHERE doc_id = ?", docId);
+        // Delete document
+        this.sql.exec("DELETE FROM qmd_documents WHERE id = ?", docId);
+    }
+    /**
+     * Full-text search using FTS5 BM25 ranking.
+     * Always available — no external dependencies needed.
+     */
+    searchFts(query, options) {
+        this.ensureInit();
+        return searchFts(this.sql, query, options);
+    }
+    /**
+     * Vector similarity search using Cloudflare Vectorize.
+     * Requires vectorize + embedFn to be configured.
+     */
+    async searchVector(query, options) {
+        if (!this.vectorize || !this.embedFn) {
+            throw new Error("Vector search requires vectorize and embedFn to be configured");
+        }
+        this.ensureInit();
+        return searchVector(this.vectorize, this.embedFn, this.sql, query, options);
+    }
+    /**
+     * Hybrid search combining FTS5 BM25 + Vectorize similarity via Reciprocal Rank Fusion.
+     *
+     * If only FTS is available, falls back to FTS-only results wrapped as SearchResult[].
+     * If both are available, runs FTS first as a probe. If BM25 has a strong signal
+     * (top score >= 0.85 with gap >= 0.15 to second), returns FTS results directly
+     * without the Vectorize round-trip. Otherwise, runs vector search and fuses with RRF.
+     */
+    async search(query, options) {
+        this.ensureInit();
+        const limit = options?.limit ?? 10;
+        // Fetch more from each source for better fusion
+        const sourceFetchLimit = limit * 3;
+        const ftsOptions = {
+            limit: sourceFetchLimit,
+            docType: options?.docType,
+            namespace: options?.namespace,
+        };
+        // FTS-only mode
+        if (!this.vectorize || !this.embedFn) {
+            const ftsResults = searchFts(this.sql, query, ftsOptions);
+            return ftsResults.slice(0, limit).map((r) => ({
+                docId: r.docId,
+                score: r.score,
+                snippet: r.snippet,
+                sources: ["fts"],
+                sourceScores: { fts: r.score },
+                title: r.title,
+                docType: r.docType,
+                namespace: r.namespace,
+                metadata: r.metadata,
+            }));
+        }
+        // Hybrid mode: run FTS first for strong signal probe
+        const ftsResults = searchFts(this.sql, query, ftsOptions);
+        // Strong signal detection: if BM25 has a clear winner, skip vector search
+        if (ftsResults.length >= 1) {
+            const topScore = ftsResults[0].score;
+            const secondScore = ftsResults.length >= 2 ? ftsResults[1].score : 0;
+            if (topScore >= STRONG_SIGNAL_MIN_SCORE &&
+                topScore - secondScore >= STRONG_SIGNAL_MIN_GAP) {
+                return ftsResults.slice(0, limit).map((r) => ({
+                    docId: r.docId,
+                    score: r.score,
+                    snippet: r.snippet,
+                    sources: ["fts"],
+                    sourceScores: { fts: r.score },
+                    title: r.title,
+                    docType: r.docType,
+                    namespace: r.namespace,
+                    metadata: r.metadata,
+                }));
+            }
+        }
+        // No strong signal — run vector search and fuse
+        const vectorOptions = {
+            limit: sourceFetchLimit,
+            docType: options?.docType,
+            namespace: options?.namespace,
+        };
+        const vectorResults = await searchVector(this.vectorize, this.embedFn, this.sql, query, vectorOptions);
+        return reciprocalRankFusion(ftsResults, vectorResults, {
+            ftsWeight: options?.ftsWeight,
+            vectorWeight: options?.vectorWeight,
+            k: options?.rrfK,
+            limit,
+        });
+    }
+    /**
+     * Get a document by ID. Returns the full reconstructed content.
+     */
+    get(docId) {
+        this.ensureInit();
+        const doc = this.sql
+            .exec("SELECT title, doc_type FROM qmd_documents WHERE id = ?", docId)
+            .toArray();
+        if (doc.length === 0)
+            return null;
+        const chunks = this.sql
+            .exec("SELECT content FROM qmd_chunks WHERE doc_id = ? ORDER BY seq", docId)
+            .toArray();
+        // Reconstruct content from chunks (overlap means we can't just concatenate)
+        // For now, return the first chunk's full text + subsequent chunks' non-overlapping portions
+        // This is an approximation — exact reconstruction would need char_offset tracking
+        const content = chunks.map((c) => c.content).join("\n\n");
+        return {
+            content,
+            title: doc[0].title,
+            docType: doc[0].doc_type,
+        };
+    }
+    /**
+     * Check if a document exists in the index.
+     */
+    has(docId) {
+        this.ensureInit();
+        const result = this.sql
+            .exec("SELECT COUNT(*) as cnt FROM qmd_documents WHERE id = ?", docId)
+            .toArray();
+        return result.length > 0 && result[0].cnt > 0;
+    }
+    /**
+     * List all indexed document IDs, optionally filtered.
+     */
+    list(options) {
+        this.ensureInit();
+        const filters = [];
+        const bindings = [];
+        if (options?.namespace) {
+            filters.push("namespace = ?");
+            bindings.push(options.namespace);
+        }
+        if (options?.docType) {
+            filters.push("doc_type = ?");
+            bindings.push(options.docType);
+        }
+        const where = filters.length > 0 ? `WHERE ${filters.join(" AND ")}` : "";
+        return this.sql
+            .exec(`SELECT id FROM qmd_documents ${where} ORDER BY id`, ...bindings)
+            .toArray()
+            .map((r) => r.id);
+    }
+    /**
+     * List documents by namespace pattern. Direct SQL query — no FTS or vector search.
+     * Supports glob patterns: "people/*" matches all namespaces starting with "people/".
+     * Returns documents ordered by most recently updated first.
+     */
+    listByNamespace(pattern, limit = 50) {
+        this.ensureInit();
+        let whereClause;
+        let binding;
+        if (pattern.includes("*")) {
+            const prefix = pattern.replace(/\*+$/, "").replace(/\/+$/, "");
+            whereClause = "d.namespace LIKE ?";
+            binding = `${prefix}/%`;
+        }
+        else {
+            whereClause = "d.namespace = ?";
+            binding = pattern;
+        }
+        const rows = this.sql
+            .exec(`SELECT d.id, d.title, d.namespace,
+					GROUP_CONCAT(c.content, '\n\n') as content
+				 FROM qmd_documents d
+				 JOIN qmd_chunks c ON c.doc_id = d.id
+				 WHERE ${whereClause}
+				 GROUP BY d.id
+				 ORDER BY d.updated_at DESC
+				 LIMIT ?`, binding, limit)
+            .toArray();
+        return rows.map((r) => ({
+            docId: r.id,
+            title: r.title,
+            content: r.content,
+            namespace: r.namespace,
+        }));
+    }
+    /**
+     * Get index statistics.
+     */
+    stats() {
+        this.ensureInit();
+        const docCount = this.sql
+            .exec("SELECT COUNT(*) as cnt FROM qmd_documents")
+            .one().cnt;
+        const chunkCount = this.sql
+            .exec("SELECT COUNT(*) as cnt FROM qmd_chunks")
+            .one().cnt;
+        const namespaces = this.sql
+            .exec("SELECT DISTINCT namespace FROM qmd_documents WHERE namespace IS NOT NULL")
+            .toArray()
+            .map((r) => r.namespace);
+        const docTypes = this.sql
+            .exec("SELECT DISTINCT doc_type FROM qmd_documents WHERE doc_type IS NOT NULL")
+            .toArray()
+            .map((r) => r.doc_type);
+        return {
+            totalDocuments: docCount,
+            totalChunks: chunkCount,
+            totalVectors: 0, // Can't query Vectorize count from binding
+            namespaces,
+            docTypes,
+        };
+    }
+    /**
+     * Rebuild the FTS index from scratch.
+     * Useful after schema changes or data corruption.
+     */
+    rebuild() {
+        this.ensureInit();
+        this.sql.exec("INSERT INTO qmd_chunks_fts(qmd_chunks_fts) VALUES('rebuild')");
+    }
+    // --- Context system ---
+    /**
+     * Set a context description for a path prefix.
+     * Contexts enrich vector embeddings for all documents matching the prefix.
+     */
+    setContext(prefix, description, namespace) {
+        this.ensureInit();
+        this.sql.exec("INSERT OR REPLACE INTO qmd_contexts (prefix, namespace, description) VALUES (?, ?, ?)", prefix, namespace ?? "", description);
+    }
+    /**
+     * Remove a context by prefix.
+     */
+    removeContext(prefix, namespace) {
+        this.ensureInit();
+        this.sql.exec("DELETE FROM qmd_contexts WHERE prefix = ? AND namespace = ?", prefix, namespace ?? "");
+    }
+    /**
+     * List all contexts, optionally filtered by namespace.
+     */
+    listContexts(namespace) {
+        this.ensureInit();
+        if (namespace !== undefined) {
+            return this.sql
+                .exec("SELECT prefix, description, namespace FROM qmd_contexts WHERE namespace = ? ORDER BY prefix", namespace)
+                .toArray();
+        }
+        return this.sql
+            .exec("SELECT prefix, description, namespace FROM qmd_contexts ORDER BY prefix")
+            .toArray();
+    }
+    /**
+     * Get all matching contexts for a document ID.
+     * Matches hierarchically: for "life/areas/health/exercise.md",
+     * returns contexts at "", "life/", "life/areas/", "life/areas/health/".
+     * Results ordered from most general to most specific.
+     */
+    getContextsForDoc(docId) {
+        this.ensureInit();
+        // Build all possible prefixes
+        const prefixes = [""];
+        const parts = docId.split("/");
+        let current = "";
+        for (let i = 0; i < parts.length - 1; i++) {
+            current += `${parts[i]}/`;
+            prefixes.push(current);
+        }
+        prefixes.push(docId);
+        const placeholders = prefixes.map(() => "?").join(", ");
+        return this.sql
+            .exec(`SELECT prefix, description FROM qmd_contexts
+				 WHERE prefix IN (${placeholders}) AND namespace = ''
+				 ORDER BY length(prefix)`, ...prefixes)
+            .toArray();
+    }
+}
+//# sourceMappingURL=qmd.js.map

package/dist/qmd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"qmd.js","sourceRoot":"","sources":["../src/qmd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAYzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAExE,mEAAmE;AACnE,MAAM,uBAAuB,GAAG,IAAI,CAAC;AACrC,yEAAyE;AACzE,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,OAAO,GAAG;IACP,GAAG,CAAa;IAChB,SAAS,CAAmB;IAC5B,OAAO,CAAiB;IACxB,MAAM,CAAsB;IAC5B,WAAW,GAAG,KAAK,CAAC;IAE5B,YACC,GAAe,EACf,OAIC;QAED,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC;QAC5C,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC;QAExC,IAAI,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACnE,CAAC;QAED,IAAI,CAAC,MAAM,GAAG;YACb,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,IAAI,IAAI;YAC7C,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,IAAI,GAAG;YAClD,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,IAAI,WAAW;SACpD,CAAC;IACH,CAAC;IAED,sFAAsF;IAC9E,UAAU;QACjB,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO;QAC7B,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,0CAA0C;IAC1C,IAAI,eAAe;QAClB,OAAO,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC;IACzD,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,CAAC,GAAa;QACxB,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,YAAY,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAExE,gCAAgC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG;aACvB,IAAI,CACJ,qDAAqD,EACrD,GAAG,CAAC,EAAE,CACN;aACA,OAAO,EAAE,CAAC;QAEZ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;YACrE,2DAA2D;YAC3D,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ;kBACc,EACd,GAAG,CAAC,KAAK,IAAI,IAAI,EACjB,GAAG,CAAC,OAAO,IAAI,IAAI,EACnB,GAAG,CAAC,SAAS,IAAI,IAAI,EACrB,YAAY,EACZ,GAAG,CAAC,EAAE,CACN,CAAC;YACF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG;iBACzB,IAAI,CACJ,yDAAyD,EACzD,GAAG,CAAC,EAAE,CACN;iBACA,GAAG,EAAE,CAAC,GAAG,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC9C,CAAC;QAED,6CAA6C;QAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ;+CAC4C,EAC5C,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,KAAK,IAAI,IAAI,EACjB,GAAG,CAAC,OAAO,IAAI,IAAI,EACnB,GAAG,CAAC,SAAS,IAAI,IAAI,EACrB,YAAY,EACZ,WAAW,CACX,CAAC;QAEF,iDAAiD;QACjD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yCAAyC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QAEjE,mBAAmB;QACnB,MAAM,MAAM,GAAG,SAAS,CACvB,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,OAAO,EACX,IAAI,CAAC,MAAM,CAAC,SAAS,EACrB,IAAI,CAAC,MAAM,CAAC,YAAY,CACxB,CAAC;QAEF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ,gFAAgF,EAChF,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,GAAG,EACT,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,UAAU,CAChB,CAAC;QACH,CAAC;QAED,gDAAgD;QAChD,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAChD,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAElE,MAAM,YAAY,CACjB,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,OAAO,EACZ,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,KAAK,EAAE,GAAG,CAAC,KAAK;gBAChB,SAAS,EAAE,GAAG,CAAC,SAAS;gBACxB,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,OAAO,EAAE,WAAW,IAAI,SAAS;aACjC,CAAC,CAAC,CACH,CAAC;QACH,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,UAAU,CACf,IAAgB;QAEhB,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,IAAI,WAAW,GAAG,CAAC,CAAC;QACpB,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,MAAM,eAAe,GAQhB,EAAE,CAAC;QAER,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACxB,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACzC,MAAM,YAAY,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAExE,gCAAgC;YAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG;iBACvB,IAAI,CACJ,qDAAqD,EACrD,GAAG,CAAC,EAAE,CACN;iBACA,OAAO,EAAE,CAAC;YAEZ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,YAAY,KAAK,WAAW,EAAE,CAAC;gBACrE,oCAAoC;gBACpC,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ;mBACc,EACd,GAAG,CAAC,KAAK,IAAI,IAAI,EACjB,GAAG,CAAC,OAAO,IAAI,IAAI,EACnB,GAAG,CAAC,SAAS,IAAI,IAAI,EACrB,YAAY,EACZ,GAAG,CAAC,EAAE,CACN,CAAC;gBACF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG;qBACzB,IAAI,CACJ,yDAAyD,EACzD,GAAG,CAAC,EAAE,CACN;qBACA,GAAG,EAAE,CAAC,GAAG,CAAC;gBACZ,WAAW,IAAI,UAAU,CAAC;gBAC1B,YAAY,EAAE,CAAC;gBACf,SAAS;YACV,CAAC;YAED,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ;gDAC4C,EAC5C,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,KAAK,IAAI,IAAI,EACjB,GAAG,CAAC,OAAO,IAAI,IAAI,EACnB,GAAG,CAAC,SAAS,IAAI,IAAI,EACrB,YAAY,EACZ,WAAW,CACX,CAAC;YAEF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yCAAyC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAEjE,MAAM,MAAM,GAAG,SAAS,CACvB,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,OAAO,EACX,IAAI,CAAC,MAAM,CAAC,SAAS,EACrB,IAAI,CAAC,MAAM,CAAC,YAAY,CACxB,CAAC;YAEF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ,gFAAgF,EAChF,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,GAAG,EACT,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,UAAU,CAChB,CAAC;YACH,CAAC;YAED,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC;YAE7B,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAChD,MAAM,WAAW,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAElE,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;oBACxB,eAAe,CAAC,IAAI,CAAC;wBACpB,KAAK,EAAE,CAAC,CAAC,KAAK;wBACd,GAAG,EAAE,CAAC,CAAC,GAAG;wBACV,IAAI,EAAE,CAAC,CAAC,IAAI;wBACZ,KAAK,EAAE,GAAG,CAAC,KAAK;wBAChB,SAAS,EAAE,GAAG,CAAC,SAAS;wBACxB,OAAO,EAAE,GAAG,CAAC,OAAO;wBACpB,OAAO,EAAE,WAAW,IAAI,SAAS;qBACjC,CAAC,CAAC;gBACJ,CAAC;YACF,CAAC;QACF,CAAC;QAED,iCAAiC;QACjC,IAAI,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,OAAO,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QACnE,CAAC;QAED,OAAO;YACN,SAAS,EAAE,IAAI,CAAC,MAAM;YACtB,MAAM,EAAE,WAAW;YACnB,OAAO,EAAE,YAAY;SACrB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa;QACzB,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACtD,CAAC;QAED,0CAA0C;QAC1C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,yCAAyC,EAAE,KAAK,CAAC,CAAC;QAChE,kBAAkB;QAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,KAAa,EAAE,OAAuB;QAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,OAAO,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,YAAY,CACjB,KAAa,EACb,OAAuB;QAEvB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CACd,+DAA+D,CAC/D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC7E,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CACX,KAAa,EACb,OAA6B;QAE7B,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;QACnC,gDAAgD;QAChD,MAAM,gBAAgB,GAAG,KAAK,GAAG,CAAC,CAAC;QAEnC,MAAM,UAAU,GAAkB;YACjC,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,SAAS,EAAE,OAAO,EAAE,SAAS;SAC7B,CAAC;QAEF,gBAAgB;QAChB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;YAC1D,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7C,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,OAAO,EAAE,CAAC,KAAK,CAA4B;gBAC3C,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,EAAE;gBAC9B,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,OAAO,EAAE,CAAC,CAAC,OAAO;gBAClB,SAAS,EAAE,CAAC,CAAC,SAAS;gBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;aACpB,CAAC,CAAC,CAAC;QACL,CAAC;QAED,qDAAqD;QACrD,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAE1D,0EAA0E;QAC1E,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,QAAQ,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACrC,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAErE,IACC,QAAQ,IAAI,uBAAuB;gBACnC,QAAQ,GAAG,WAAW,IAAI,qBAAqB,EAC9C,CAAC;gBACF,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAC7C,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,OAAO,EAAE,CAAC,KAAK,CAA4B;oBAC3C,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,KAAK,EAAE;oBAC9B,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,SAAS,EAAE,CAAC,CAAC,SAAS;oBACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;iBACpB,CAAC,CAAC,CAAC;YACL,CAAC;QACF,CAAC;QAED,gDAAgD;QAChD,MAAM,aAAa,GAAkB;YACpC,KAAK,EAAE,gBAAgB;YACvB,OAAO,EAAE,OAAO,EAAE,OAAO;YACzB,SAAS,EAAE,OAAO,EAAE,SAAS;SAC7B,CAAC;QAEF,MAAM,aAAa,GAAG,MAAM,YAAY,CACvC,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,GAAG,EACR,KAAK,EACL,aAAa,CACb,CAAC;QAEF,OAAO,oBAAoB,CAAC,UAAU,EAAE,aAAa,EAAE;YACtD,SAAS,EAAE,OAAO,EAAE,SAAS;YAC7B,YAAY,EAAE,OAAO,EAAE,YAAY;YACnC,CAAC,EAAE,OAAO,EAAE,IAAI;YAChB,KAAK;SACL,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,GAAG,CACF,KAAa;QAEb,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG;aAClB,IAAI,CACJ,wDAAwD,EACxD,KAAK,CACL;aACA,OAAO,EAAE,CAAC;QAEZ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAElC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG;aACrB,IAAI,CACJ,8DAA8D,EAC9D,KAAK,CACL;aACA,OAAO,EAAE,CAAC;QAEZ,4EAA4E;QAC5E,4FAA4F;QAC5F,kFAAkF;QAClF,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE1D,OAAO;YACN,OAAO;YACP,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK;YACnB,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ;SACxB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,KAAa;QAChB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG;aACrB,IAAI,CACJ,wDAAwD,EACxD,KAAK,CACL;aACA,OAAO,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAkD;QACtD,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;YAC9B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAEzE,OAAO,IAAI,CAAC,GAAG;aACb,IAAI,CACJ,gCAAgC,KAAK,cAAc,EACnD,GAAG,QAAQ,CACX;aACA,OAAO,EAAE;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED;;;;OAIG;IACH,eAAe,CACd,OAAe,EACf,KAAK,GAAG,EAAE;QAOV,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,IAAI,WAAmB,CAAC;QACxB,IAAI,OAAe,CAAC;QAEpB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC/D,WAAW,GAAG,oBAAoB,CAAC;YACnC,OAAO,GAAG,GAAG,MAAM,IAAI,CAAC;QACzB,CAAC;aAAM,CAAC;YACP,WAAW,GAAG,iBAAiB,CAAC;YAChC,OAAO,GAAG,OAAO,CAAC;QACnB,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG;aACnB,IAAI,CAMJ;;;;aAIS,WAAW;;;aAGX,EACT,OAAO,EACP,KAAK,CACL;aACA,OAAO,EAAE,CAAC;QAEZ,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvB,KAAK,EAAE,CAAC,CAAC,EAAE;YACX,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,SAAS,EAAE,CAAC,CAAC,SAAS;SACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK;QACJ,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG;aACvB,IAAI,CAAkB,2CAA2C,CAAC;aAClE,GAAG,EAAE,CAAC,GAAG,CAAC;QAEZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG;aACzB,IAAI,CAAkB,wCAAwC,CAAC;aAC/D,GAAG,EAAE,CAAC,GAAG,CAAC;QAEZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG;aACzB,IAAI,CACJ,0EAA0E,CAC1E;aACA,OAAO,EAAE;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAE1B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG;aACvB,IAAI,CACJ,wEAAwE,CACxE;aACA,OAAO,EAAE;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAEzB,OAAO;YACN,cAAc,EAAE,QAAQ;YACxB,WAAW,EAAE,UAAU;YACvB,YAAY,EAAE,CAAC,EAAE,2CAA2C;YAC5D,UAAU;YACV,QAAQ;SACR,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO;QACN,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ,8DAA8D,CAC9D,CAAC;IACH,CAAC;IAED,yBAAyB;IAEzB;;;OAGG;IACH,UAAU,CAAC,MAAc,EAAE,WAAmB,EAAE,SAAkB;QACjE,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ,uFAAuF,EACvF,MAAM,EACN,SAAS,IAAI,EAAE,EACf,WAAW,CACX,CAAC;IACH,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,MAAc,EAAE,SAAkB;QAC/C,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,IAAI,CACZ,6DAA6D,EAC7D,MAAM,EACN,SAAS,IAAI,EAAE,CACf,CAAC;IACH,CAAC;IAED;;OAEG;IACH,YAAY,CACX,SAAkB;QAElB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC,GAAG;iBACb,IAAI,CACJ,6FAA6F,EAC7F,SAAS,CACT;iBACA,OAAO,EAAE,CAAC;QACb,CAAC;QACD,OAAO,IAAI,CAAC,GAAG;aACb,IAAI,CACJ,yEAAyE,CACzE;aACA,OAAO,EAAE,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAChB,KAAa;QAEb,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,8BAA8B;QAC9B,MAAM,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,OAAO,GAAG,EAAE,CAAC;QACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,OAAO,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAErB,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxD,OAAO,IAAI,CAAC,GAAG;aACb,IAAI,CACJ;wBACoB,YAAY;6BACP,EACzB,GAAG,QAAQ,CACX;aACA,OAAO,EAAE,CAAC;IACb,CAAC;CACD"}

package/dist/rrf.d.ts

@@ -0,0 +1,22 @@
+import type { FtsResult, SearchResult, VectorResult } from "./types.js";
+/**
+ * Reciprocal Rank Fusion (RRF) — merge ranked result lists into a single ranking.
+ *
+ * RRF score for document d = Σ(weight_i / (k + rank_i + 1)) across all lists
+ * where rank_i is the 0-based position in list i.
+ *
+ * From qmd: k=60 is the standard constant. Higher k reduces the impact of
+ * being ranked #1 vs #5, making the fusion more conservative.
+ *
+ * Additionally applies a top-rank bonus (from qmd):
+ * - Rank #1 in any list: +0.05
+ * - Rank #2-3 in any list: +0.02
+ * This prevents exact matches from being diluted by expansion queries.
+ */
+export declare function reciprocalRankFusion(ftsResults: FtsResult[], vectorResults: VectorResult[], options?: {
+    ftsWeight?: number;
+    vectorWeight?: number;
+    k?: number;
+    limit?: number;
+}): SearchResult[];
+//# sourceMappingURL=rrf.d.ts.map

package/dist/rrf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.d.ts","sourceRoot":"","sources":["../src/rrf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAExE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,SAAS,EAAE,EACvB,aAAa,EAAE,YAAY,EAAE,EAC7B,OAAO,GAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CACV,GACJ,YAAY,EAAE,CAyFhB"}