@capgo/capacitor-fast-sql 8.0.37 → 8.0.38

package/dist/plugin.js

@@ -400,6 +400,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
             // Check if already connected
             const existing = this.connections.get(options.database);
             if (existing) {
+                this.sharedConnections.add(options.database);
                 return existing;
             }
             // Connect via native plugin
@@ -423,14 +424,22 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
          * @param database - Database name to close
          */
         static async disconnect(database) {
+            var _a;
             const connection = this.connections.get(database);
             if (!connection) {
                 throw new Error(`Database '${database}' is not connected`);
             }
+            if (((_a = this.connectionRetainers.get(database)) !== null && _a !== void 0 ? _a : 0) > 0) {
+                this.pendingDisconnects.add(database);
+                return;
+            }
             // Disconnect via native plugin
             await CapgoCapacitorFastSql.disconnect({ database });
             // Remove connection
             this.connections.delete(database);
+            this.sharedConnections.delete(database);
+            this.connectionRetainers.delete(database);
+            this.pendingDisconnects.delete(database);
         }
         /**
          * Get an existing connection
@@ -441,12 +450,50 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
         static getConnection(database) {
             return this.connections.get(database) || null;
         }
+        /**
+         * Check whether a connection has been handed out more than once.
+         */
+        static isConnectionShared(database) {
+            return this.sharedConnections.has(database);
+        }
+        /**
+         * Temporarily retain a connection for helpers that share cached connections.
+         */
+        static retainConnection(database) {
+            var _a;
+            if (!this.connections.has(database)) {
+                throw new Error(`Database '${database}' is not connected`);
+            }
+            this.connectionRetainers.set(database, ((_a = this.connectionRetainers.get(database)) !== null && _a !== void 0 ? _a : 0) + 1);
+        }
+        /**
+         * Release a retained connection. Returns true when a pending disconnect closed it.
+         */
+        static async releaseConnection(database) {
+            var _a;
+            const retainers = (_a = this.connectionRetainers.get(database)) !== null && _a !== void 0 ? _a : 0;
+            if (retainers > 1) {
+                this.connectionRetainers.set(database, retainers - 1);
+                return false;
+            }
+            this.connectionRetainers.delete(database);
+            if (this.pendingDisconnects.has(database)) {
+                this.pendingDisconnects.delete(database);
+                await this.disconnect(database);
+                return true;
+            }
+            return false;
+        }
         /**
          * Close all open connections
          */
         static async disconnectAll() {
             const databases = Array.from(this.connections.keys());
-            await Promise.all(databases.map((db) => this.disconnect(db)));
+            await Promise.all(databases.map((db) => {
+                this.connectionRetainers.delete(db);
+                this.pendingDisconnects.delete(db);
+                return this.disconnect(db);
+            }));
         }
         /**
          * Get list of all open database connections
@@ -458,6 +505,9 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
         }
     }
     FastSQL.connections = new Map();
+    FastSQL.sharedConnections = new Set();
+    FastSQL.connectionRetainers = new Map();
+    FastSQL.pendingDisconnects = new Set();
 
     /**
      * Key-value storage backed by the FastSQL database connection.
@@ -642,6 +692,383 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
         }
     }
 
+    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.
+     */
+    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();
+
     const DEFAULT_SQLJS_URL = 'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.js';
     const DEFAULT_WASM_URL = 'https://cdnjs.cloudflare.com/ajax/libs/sql.js/1.8.0/sql-wasm.wasm';
     /**
@@ -879,6 +1306,7 @@ var capacitorCapgoCapacitorFastSql = (function (exports, core) {
 
     exports.CapgoCapacitorFastSql = CapgoCapacitorFastSql;
     exports.FastSQL = FastSQL;
+    exports.FastSQLVectorStore = FastSQLVectorStore;
     exports.KeyValueStore = KeyValueStore;
     exports.NativeSQLConnection = NativeSQLConnection;
     exports.WebSQLConnection = WebSQLConnection;