@capgo/capacitor-fast-sql 8.0.36 → 8.0.38

package/dist/esm/vector-store.js

@@ -0,0 +1,377 @@
+import { FastSQL } from './fast-sql';
+const DEFAULT_STORE = 'default';
+const VECTOR_TABLE = '__fast_sql_vector_store';
+const VECTOR_META_TABLE = '__fast_sql_vector_store_meta';
+/**
+ * SQLite-backed VectorStore for local RAG usage.
+ *
+ * The helper is optional and dependency-free: pass your own embeddings provider,
+ * or use precomputed embeddings with `embeddingDimension`. Multiple stores can
+ * share one database by choosing different `store` names.
+ */
+export class FastSQLVectorStore {
+    constructor(connection, options = {}) {
+        var _a;
+        this.initialized = false;
+        this.ownsConnection = false;
+        this.shouldDisconnectConnection = false;
+        this.closed = false;
+        this.connection = connection;
+        this.store = (_a = options.store) !== null && _a !== void 0 ? _a : DEFAULT_STORE;
+        this.embeddings = options.embeddings;
+        this.configuredEmbeddingDim = options.embeddingDimension;
+        this.embeddingDim = options.embeddingDimension;
+    }
+    static retainConnection(database) {
+        var _a;
+        this.connectionRefs.set(database, ((_a = this.connectionRefs.get(database)) !== null && _a !== void 0 ? _a : 0) + 1);
+    }
+    static releaseConnection(database) {
+        var _a;
+        const refs = (_a = this.connectionRefs.get(database)) !== null && _a !== void 0 ? _a : 0;
+        if (refs > 1) {
+            this.connectionRefs.set(database, refs - 1);
+            return false;
+        }
+        this.connectionRefs.delete(database);
+        this.ownedConnections.delete(database);
+        return true;
+    }
+    /**
+     * Open a vector store from database connection options.
+     */
+    static async open(options) {
+        const existing = FastSQL.getConnection(options.database);
+        const ownsExistingVectorConnection = existing && FastSQLVectorStore.connectionRefs.has(options.database);
+        const connection = ownsExistingVectorConnection ? existing : await FastSQL.connect(options);
+        const vectorStore = new FastSQLVectorStore(connection, options);
+        vectorStore.ownsConnection = true;
+        vectorStore.shouldDisconnectConnection = !existing || FastSQLVectorStore.ownedConnections.has(options.database);
+        FastSQLVectorStore.retainConnection(connection.getDatabaseName());
+        FastSQL.retainConnection(connection.getDatabaseName());
+        if (vectorStore.shouldDisconnectConnection) {
+            FastSQLVectorStore.ownedConnections.add(connection.getDatabaseName());
+        }
+        try {
+            await vectorStore.load();
+            return vectorStore;
+        }
+        catch (error) {
+            await vectorStore.unload();
+            throw error;
+        }
+    }
+    /**
+     * Create a vector store from an existing SQL connection.
+     * The caller keeps ownership of the connection.
+     */
+    static async fromConnection(connection, options = {}) {
+        const vectorStore = new FastSQLVectorStore(connection, options);
+        await vectorStore.load();
+        return vectorStore;
+    }
+    getStoreName() {
+        return this.store;
+    }
+    getDatabaseName() {
+        return this.connection.getDatabaseName();
+    }
+    async load() {
+        var _a, _b;
+        this.assertOpen();
+        if (this.initialized) {
+            return this;
+        }
+        await ((_b = (_a = this.embeddings) === null || _a === void 0 ? void 0 : _a.load) === null || _b === void 0 ? void 0 : _b.call(_a));
+        await this.ensureSchema();
+        await this.ensureStoreDimension();
+        this.initialized = true;
+        return this;
+    }
+    async unload() {
+        var _a, _b;
+        if (this.closed) {
+            return;
+        }
+        await ((_b = (_a = this.embeddings) === null || _a === void 0 ? void 0 : _a.unload) === null || _b === void 0 ? void 0 : _b.call(_a));
+        if (this.ownsConnection) {
+            const database = this.connection.getDatabaseName();
+            const releasedLastVectorStore = FastSQLVectorStore.releaseConnection(database);
+            const closedFromPendingDisconnect = await FastSQL.releaseConnection(database);
+            if (releasedLastVectorStore &&
+                this.shouldDisconnectConnection &&
+                !FastSQL.isConnectionShared(database) &&
+                !closedFromPendingDisconnect) {
+                await FastSQL.disconnect(database);
+            }
+        }
+        this.initialized = false;
+        this.closed = true;
+    }
+    async close() {
+        await this.unload();
+    }
+    async add(params) {
+        await this.ensureReady();
+        const { id = this.createId(), document, embedding, metadata } = params;
+        if (document === undefined && embedding === undefined) {
+            throw new Error('document and embedding cannot both be undefined');
+        }
+        const existing = await this.connection.query(`SELECT 1 FROM ${VECTOR_TABLE} WHERE store = ? AND id = ? LIMIT 1`, [
+            this.store,
+            id,
+        ]);
+        if (existing.length > 0) {
+            throw new Error(`id already exists: ${id}`);
+        }
+        const resolvedEmbedding = embedding !== null && embedding !== void 0 ? embedding : (await this.embedDocument(document));
+        await this.ensureEmbeddingDimension(resolvedEmbedding);
+        const now = Date.now();
+        await this.connection.run(`INSERT INTO ${VECTOR_TABLE} (store, id, document, embedding, metadata, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, [
+            this.store,
+            id,
+            document !== null && document !== void 0 ? document : '',
+            this.encodeEmbedding(resolvedEmbedding),
+            this.encodeMetadata(metadata),
+            now,
+            now,
+        ]);
+        return id;
+    }
+    async update(params) {
+        var _a, _b;
+        await this.ensureReady();
+        const rows = await this.connection.query(`SELECT id, document, embedding, metadata FROM ${VECTOR_TABLE} WHERE store = ? AND id = ? LIMIT 1`, [this.store, params.id]);
+        if (rows.length === 0) {
+            throw new Error(`id not found: ${params.id}`);
+        }
+        const current = this.rowToGetResult(rows[0]);
+        const document = (_a = params.document) !== null && _a !== void 0 ? _a : current.document;
+        const embedding = (_b = params.embedding) !== null && _b !== void 0 ? _b : (params.document !== undefined ? await this.embedDocument(params.document) : current.embedding);
+        const metadata = params.metadata === undefined ? current.metadata : params.metadata;
+        await this.ensureEmbeddingDimension(embedding);
+        await this.connection.run(`UPDATE ${VECTOR_TABLE}
+       SET document = ?, embedding = ?, metadata = ?, updated_at = ?
+       WHERE store = ? AND id = ?`, [document, this.encodeEmbedding(embedding), this.encodeMetadata(metadata), Date.now(), this.store, params.id]);
+    }
+    async delete(params) {
+        await this.ensureReady();
+        const rows = await this.getStoreRows();
+        const ids = rows
+            .map((row) => this.rowToGetResult(row))
+            .filter(params.predicate)
+            .map((row) => row.id);
+        for (const id of ids) {
+            await this.connection.run(`DELETE FROM ${VECTOR_TABLE} WHERE store = ? AND id = ?`, [this.store, id]);
+        }
+    }
+    async query(params) {
+        await this.ensureReady();
+        const { queryText, queryEmbedding, nResults, predicate } = params;
+        if (queryText === undefined && queryEmbedding === undefined) {
+            throw new Error('queryText and queryEmbedding cannot both be undefined');
+        }
+        if (nResults !== undefined && nResults < 0) {
+            throw new Error('nResults cannot be negative');
+        }
+        const searchEmbedding = queryEmbedding !== null && queryEmbedding !== void 0 ? queryEmbedding : (await this.embedDocument(queryText));
+        await this.ensureEmbeddingDimension(searchEmbedding);
+        const results = (await this.getStoreRows())
+            .map((row) => {
+            const item = this.rowToGetResult(row);
+            return Object.assign(Object.assign({}, item), { similarity: this.cosineSimilarity(item.embedding, searchEmbedding) });
+        })
+            .filter(predicate !== null && predicate !== void 0 ? predicate : (() => true))
+            .sort((a, b) => b.similarity - a.similarity);
+        return nResults === undefined ? results : results.slice(0, nResults);
+    }
+    /**
+     * Delete only this logical vector store. Other stores in the same database stay intact.
+     */
+    async deleteVectorStore() {
+        await this.ensureReady();
+        await this.connection.run(`DELETE FROM ${VECTOR_TABLE} WHERE store = ?`, [this.store]);
+        await this.connection.run(`DELETE FROM ${VECTOR_META_TABLE} WHERE store = ?`, [this.store]);
+        this.embeddingDim = this.configuredEmbeddingDim;
+        if (this.embeddingDim !== undefined) {
+            await this.saveEmbeddingDimension();
+        }
+    }
+    async ensureReady() {
+        this.assertOpen();
+        if (!this.initialized) {
+            await this.load();
+        }
+    }
+    assertOpen() {
+        if (this.closed) {
+            throw new Error('Vector store is closed');
+        }
+    }
+    async ensureSchema() {
+        await this.connection.run(`CREATE TABLE IF NOT EXISTS ${VECTOR_TABLE} (
+        store TEXT NOT NULL,
+        id TEXT NOT NULL,
+        document TEXT NOT NULL,
+        embedding BLOB NOT NULL,
+        metadata TEXT DEFAULT NULL,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (store, id)
+      )`);
+        await this.connection.run(`CREATE INDEX IF NOT EXISTS ${VECTOR_TABLE}_store_idx ON ${VECTOR_TABLE} (store)`);
+        await this.connection.run(`CREATE TABLE IF NOT EXISTS ${VECTOR_META_TABLE} (
+        store TEXT PRIMARY KEY,
+        embedding_dim INTEGER NOT NULL
+      )`);
+    }
+    async ensureStoreDimension() {
+        const rows = await this.connection.query(`SELECT embedding_dim FROM ${VECTOR_META_TABLE} WHERE store = ? LIMIT 1`, [
+            this.store,
+        ]);
+        const storedDim = this.parseStoredDimension(rows[0]);
+        if (storedDim !== undefined && this.embeddingDim !== undefined && storedDim !== this.embeddingDim) {
+            throw new Error(`embedding dimension ${this.embeddingDim} does not match existing store dimension ${storedDim}`);
+        }
+        if (this.embeddingDim === undefined) {
+            this.embeddingDim = storedDim !== null && storedDim !== void 0 ? storedDim : (this.embeddings ? (await this.embedDocument('dummy')).length : undefined);
+        }
+        if (this.embeddingDim !== undefined) {
+            await this.saveEmbeddingDimension();
+        }
+    }
+    parseStoredDimension(row) {
+        if (!row) {
+            return undefined;
+        }
+        const value = row.embedding_dim;
+        if (typeof value === 'number') {
+            return value;
+        }
+        if (typeof value === 'string') {
+            const parsed = Number(value);
+            return Number.isFinite(parsed) ? parsed : undefined;
+        }
+        return undefined;
+    }
+    async saveEmbeddingDimension() {
+        if (this.embeddingDim === undefined) {
+            return;
+        }
+        await this.connection.run(`INSERT OR REPLACE INTO ${VECTOR_META_TABLE} (store, embedding_dim) VALUES (?, ?)`, [
+            this.store,
+            this.embeddingDim,
+        ]);
+    }
+    async ensureEmbeddingDimension(embedding) {
+        this.validateEmbedding(embedding);
+        if (this.embeddingDim === undefined) {
+            this.embeddingDim = embedding.length;
+            await this.saveEmbeddingDimension();
+            return;
+        }
+        if (embedding.length !== this.embeddingDim) {
+            throw new Error(`embedding dimension ${embedding.length} does not match vector store dimension ${this.embeddingDim}`);
+        }
+    }
+    async embedDocument(document) {
+        if (document === undefined) {
+            throw new Error('document is required when embedding is not provided');
+        }
+        if (!this.embeddings) {
+            throw new Error('embeddings provider is required for text operations');
+        }
+        return this.embeddings.embed(document);
+    }
+    validateEmbedding(embedding) {
+        if (!Array.isArray(embedding) || embedding.length === 0) {
+            throw new Error('embedding must be a non-empty number array');
+        }
+        for (const value of embedding) {
+            if (typeof value !== 'number' || !Number.isFinite(value)) {
+                throw new Error('embedding values must be finite numbers');
+            }
+        }
+    }
+    async getStoreRows() {
+        return this.connection.query(`SELECT id, document, embedding, metadata FROM ${VECTOR_TABLE} WHERE store = ? ORDER BY updated_at DESC`, [this.store]);
+    }
+    rowToGetResult(row) {
+        const result = {
+            id: String(row.id),
+            document: row.document === null || row.document === undefined ? '' : String(row.document),
+            embedding: this.decodeEmbedding(row.embedding),
+        };
+        const metadata = this.decodeMetadata(row.metadata);
+        if (metadata !== undefined) {
+            result.metadata = metadata;
+        }
+        return result;
+    }
+    encodeEmbedding(embedding) {
+        const bytes = new Uint8Array(embedding.length * Float32Array.BYTES_PER_ELEMENT);
+        const view = new DataView(bytes.buffer);
+        embedding.forEach((value, index) => view.setFloat32(index * Float32Array.BYTES_PER_ELEMENT, value, true));
+        return bytes;
+    }
+    decodeEmbedding(value) {
+        if (!(value instanceof Uint8Array)) {
+            throw new Error('stored embedding is not binary data');
+        }
+        if (value.byteLength % Float32Array.BYTES_PER_ELEMENT !== 0) {
+            throw new Error('stored embedding has invalid byte length');
+        }
+        const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+        const embedding = [];
+        for (let offset = 0; offset < value.byteLength; offset += Float32Array.BYTES_PER_ELEMENT) {
+            embedding.push(view.getFloat32(offset, true));
+        }
+        return embedding;
+    }
+    encodeMetadata(metadata) {
+        return metadata ? JSON.stringify(metadata) : null;
+    }
+    decodeMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    }
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length) {
+            throw new Error(`embedding dimension ${b.length} does not match stored embedding dimension ${a.length}`);
+        }
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (normA === 0 || normB === 0) {
+            return 0;
+        }
+        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+    createId() {
+        const cryptoApi = globalThis.crypto;
+        if (typeof (cryptoApi === null || cryptoApi === void 0 ? void 0 : cryptoApi.randomUUID) === 'function') {
+            return cryptoApi.randomUUID();
+        }
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
+            const value = Math.floor(Math.random() * 16);
+            const nibble = char === 'x' ? value : (value & 0x3) | 0x8;
+            return nibble.toString(16);
+        });
+    }
+}
+FastSQLVectorStore.connectionRefs = new Map();
+FastSQLVectorStore.ownedConnections = new Set();