@capgo/capacitor-fast-sql 8.0.42 → 8.0.44

package/README.md

@@ -1,305 +1,319 @@
-# @capgo/capacitor-fast-sql
-<a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-fast-sql" alt="Capgo - Instant updates for Capacitor" /></a>
-
-<div align="center">
-  <h2><a href="https://capgo.app/?ref=plugin_fast_sql"> ➡️ Get Instant updates for your App with Capgo</a></h2>
-  <h2><a href="https://capgo.app/consulting/?ref=plugin_fast_sql"> Missing a feature? We'll build the plugin for you 💪</a></h2>
-</div>
-
-High-performance native SQLite plugin with HTTP server for efficient sync operations and IndexedDB replacement.
-Official Capgo alternative to Ionic Appflow Secure Storage.
-
-## Why Fast SQL?
-
-Traditional Capacitor plugins serialize data through the JavaScript bridge, which becomes inefficient with large datasets. Fast SQL solves this by establishing a local HTTP server for direct native communication, making it ideal for:
-
-- **Local-first sync systems** (CRDTs, operational transforms)
-- **IndexedDB replacement** on platforms with broken/limited implementations
-- **Large dataset operations** requiring high throughput
-- **Batch operations** with thousands of rows
-- **Binary data storage** (BLOBs, files)
-
-## Documentation
-
-The most complete doc is available here: https://capgo.app/docs/plugins/fast-sql/
-
-## Compatibility
-
-| Plugin version | Capacitor compatibility | Maintained |
-| -------------- | ----------------------- | ---------- |
-| v8.\*.\*       | v8.\*.\*                | ✅          |
-| v7.\*.\*       | v7.\*.\*                | On demand   |
-| v6.\*.\*       | v6.\*.\*                | ❌          |
-| v5.\*.\*       | v5.\*.\*                | ❌          |
-
-> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
-
-## Install
-
-```bash
-npm install @capgo/capacitor-fast-sql
-npx cap sync
-```
-
-## Overview
-
-This plugin provides direct native SQLite database access with a custom communication protocol inspired by [capacitor-blob-writer](https://github.com/diachedelic/capacitor-blob-writer). Instead of using Capacitor's standard bridge (which serializes data inefficiently), it establishes a local HTTP server for optimal performance with large datasets and sync operations.
-
-### Key Features
-
-- **Custom HTTP Protocol**: Bypasses Capacitor's bridge for up to 25x faster performance with large data
-- **Direct Native SQLite**: Full SQL support with transactions, batch operations, and binary data
-- **Sync-Friendly**: Designed for local sync systems (CRDTs, operational transforms, etc.)
-- **IndexedDB Replacement**: Provides reliable alternative to broken/limited IndexedDB implementations
-- **Cross-Platform**: iOS, Android, and Web (using sql.js + IndexedDB for persistence)
-- **Optional RAG VectorStore**: Persist many named vector stores for retrieval-augmented generation without adding a native dependency
-
-## iOS Configuration
-
-This plugin runs a local HTTP server on `localhost`. iOS App Transport Security (ATS) blocks cleartext HTTP by default, so you **must** allow local networking in your `Info.plist`:
-
-```xml
-<key>NSAppTransportSecurity</key>
-<dict>
-    <key>NSAllowsLocalNetworking</key>
-    <true/>
-</dict>
-```
-
-This only permits cleartext to loopback addresses (`localhost` / `127.0.0.1`) — it does not weaken ATS for external connections.
-
-## Android Configuration
-
-This plugin runs a local HTTP server on `localhost` to bypass Capacitor's bridge for performance. Android 9+ blocks cleartext (non-HTTPS) traffic by default, so you **must** allow it for `localhost`.
-
-**Option A — Scoped to localhost only (recommended):**
-
-Create `android/app/src/main/res/xml/network_security_config.xml`:
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<network-security-config>
-    <domain-config cleartextTrafficPermitted="true">
-        <domain includeSubdomains="false">localhost</domain>
-        <domain includeSubdomains="false">127.0.0.1</domain>
-    </domain-config>
-</network-security-config>
-```
-
-Then reference it in your `AndroidManifest.xml`:
-
-```xml
-<application
-    android:networkSecurityConfig="@xml/network_security_config">
-    ...
-</application>
-```
-
-**Option B — Allow all cleartext (simpler but less secure):**
-
-```xml
-<application
-    android:usesCleartextTraffic="true">
-    ...
-</application>
-```
-
-## Encryption
-
-### Android
-
-Encryption uses [SQLCipher](https://www.zetetic.net/sqlcipher/) and is opt-in. Add the SQLCipher dependency to your **app-level** `build.gradle`:
-
-```gradle
-dependencies {
-    implementation 'net.zetetic:sqlcipher-android:4.13.0'
-}
-```
-
-Then connect with encryption enabled:
-
-```typescript
-const db = await FastSQL.connect({
-  database: 'secure',
-  encrypted: true,
-  encryptionKey: 'my-secret-key',
-});
-```
-
-If SQLCipher is not installed and `encrypted: true` is passed, the plugin returns a clear error message instead of crashing.
-
-### iOS
-
-SQLCipher is optional on iOS. The plugin builds without it; encryption calls will return `Encryption is not available in this build` unless SQLCipher is installed.
-
-To enable encryption via CocoaPods, update your `ios/App/Podfile` after `capacitor install`/`cap sync` to use the SQLCipher subspec:
-
-```ruby
-pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql'
-```
-
-Then run `pod install` in the `ios/App` directory. If you skip this subspec, keep `encrypted: false`.
-
-## Web Platform
-
-On the web, this plugin uses [sql.js](https://sql.js.org/) (SQLite compiled to WebAssembly) with IndexedDB for persistence.
-
-By default, the plugin loads `sql-wasm.js` and `sql-wasm.wasm` from the cdnjs CDN. If you want to bundle these files with your web application (to avoid a CDN dependency), call `configureWeb()` once at startup **before** the first `connect()`:
-
-```typescript
-import { CapgoCapacitorFastSql, FastSQL } from '@capgo/capacitor-fast-sql';
-
-// Point to your locally bundled sql.js files
-await CapgoCapacitorFastSql.configureWeb({
-  sqlJsUrl: '/assets/sql-wasm.js',
-  wasmUrl: '/assets/sql-wasm.wasm',
-});
-
-const db = await FastSQL.connect({ database: 'myapp' });
-```
-
-`configureWeb()` is a no-op on iOS and Android — it is safe to call unconditionally.
-
-## Usage
-
-### Basic Example
-
-```typescript
-import { FastSQL } from '@capgo/capacitor-fast-sql';
-
-// Connect to database
-const db = await FastSQL.connect({ database: 'myapp' });
-
-// Create table
-await db.execute(`
-  CREATE TABLE IF NOT EXISTS users (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    email TEXT UNIQUE
-  )
-`);
-
-// Insert data
-const result = await db.run(
-  'INSERT INTO users (name, email) VALUES (?, ?)',
-  ['John Doe', 'john@example.com']
-);
-console.log('Inserted row ID:', result.insertId);
-
-// Query data
-const users = await db.query('SELECT * FROM users WHERE name LIKE ?', ['John%']);
-console.log('Users:', users);
-
-// Close connection
-await FastSQL.disconnect('myapp');
-```
-
-### Transaction Example
-
-```typescript
-const db = await FastSQL.connect({ database: 'myapp' });
-
-try {
-  await db.transaction(async (tx) => {
-    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Alice', 1000]);
-    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Bob', 500]);
-    await tx.run('UPDATE accounts SET balance = balance - 100 WHERE name = ?', ['Alice']);
-    await tx.run('UPDATE accounts SET balance = balance + 100 WHERE name = ?', ['Bob']);
-  });
-  console.log('Transaction successful!');
-} catch (error) {
-  console.error('Transaction failed:', error);
-}
-```
-
-### Batch Operations
-
-```typescript
-const db = await FastSQL.connect({ database: 'myapp' });
-
-const results = await db.executeBatch([
-  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 1'] },
-  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 2'] },
-  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 3'] },
-]);
-```
-
-### Key-Value Storage (Mobile-focused)
-
-```typescript
-import { KeyValueStore } from '@capgo/capacitor-fast-sql';
-
-const kv = await KeyValueStore.open({
-  database: 'myapp',
-  encrypted: true,
-  encryptionKey: 'super-secret-key',
-});
-
-await kv.set('session', { token: 'abc123', expiresAt: 1710000000 });
-const session = await kv.get('session');
-await kv.remove('session');
-```
-
-### RAG Vector Stores (Optional)
-
-`FastSQLVectorStore` provides a dependency-free VectorStore-compatible helper inspired by `@react-native-rag/op-sqlite`. It stores embeddings in SQLite as binary Float32 vectors and computes cosine similarity in TypeScript, so it works anywhere this plugin works.
-
-Each store is namespaced by the `store` option, so one database can hold as many independent vector stores as you need:
-
-```typescript
-import { FastSQLVectorStore } from '@capgo/capacitor-fast-sql';
-
-const docs = await FastSQLVectorStore.open({
-  database: 'rag',
-  store: 'docs',
-  embeddings,
-});
-
-const tickets = await FastSQLVectorStore.open({
-  database: 'rag',
-  store: 'tickets',
-  embeddings,
-});
-
-await docs.add({
-  document: 'Capgo ships instant updates for Capacitor apps.',
-  metadata: { source: 'docs' },
-});
-
-const results = await docs.query({
-  queryText: 'How do instant updates work?',
-  nResults: 3,
-});
-
-await docs.close();
-await tickets.close();
-```
-
-You can also use precomputed embeddings without an embeddings provider:
-
-```typescript
-const store = await FastSQLVectorStore.open({
-  database: 'rag',
-  store: 'offline-embeddings',
-  embeddingDimension: 384,
-});
-
-await store.add({
-  id: 'intro',
-  document: 'Local RAG entry',
-  embedding: [0.12, 0.08, 0.31 /* ...384 values */],
-});
-
-const matches = await store.query({
-  queryEmbedding: [0.11, 0.09, 0.29 /* ...384 values */],
-  nResults: 5,
-});
-```
-
-> Note: Web support is intended for minimal testing only. The primary focus is iOS/Android.
-
-## API
-
+# @capgo/capacitor-fast-sql
+<a href="https://capgo.app/"><img src="https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-fast-sql" alt="Capgo - Instant updates for Capacitor" /></a>
+
+<div align="center">
+  <h2><a href="https://capgo.app/?ref=plugin_fast_sql"> ➡️ Get Instant updates for your App with Capgo</a></h2>
+  <h2><a href="https://capgo.app/consulting/?ref=plugin_fast_sql"> Missing a feature? We'll build the plugin for you 💪</a></h2>
+</div>
+
+High-performance native SQLite plugin with HTTP server for efficient sync operations and IndexedDB replacement.
+Official Capgo alternative to Ionic Appflow Secure Storage.
+
+## Why Fast SQL?
+
+Traditional Capacitor plugins serialize data through the JavaScript bridge, which becomes inefficient with large datasets. Fast SQL solves this by establishing a local HTTP server for direct native communication, making it ideal for:
+
+- **Local-first sync systems** (CRDTs, operational transforms)
+- **IndexedDB replacement** on platforms with broken/limited implementations
+- **Large dataset operations** requiring high throughput
+- **Batch operations** with thousands of rows
+- **Binary data storage** (BLOBs, files)
+
+## Documentation
+
+The most complete doc is available here: https://capgo.app/docs/plugins/fast-sql/
+
+## Compatibility
+
+| Plugin version | Capacitor compatibility | Maintained |
+| -------------- | ----------------------- | ---------- |
+| v8.\*.\*       | v8.\*.\*                | ✅          |
+| v7.\*.\*       | v7.\*.\*                | On demand   |
+| v6.\*.\*       | v6.\*.\*                | ❌          |
+| v5.\*.\*       | v5.\*.\*                | ❌          |
+
+> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
+
+## Install
+
+You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
+
+```bash
+npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```text
+Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-fast-sql` plugin in my project.
+```
+
+If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
+
+```bash
+npm install @capgo/capacitor-fast-sql
+npx cap sync
+```
+
+## Overview
+
+This plugin provides direct native SQLite database access with a custom communication protocol inspired by [capacitor-blob-writer](https://github.com/diachedelic/capacitor-blob-writer). Instead of using Capacitor's standard bridge (which serializes data inefficiently), it establishes a local HTTP server for optimal performance with large datasets and sync operations.
+
+### Key Features
+
+- **Custom HTTP Protocol**: Bypasses Capacitor's bridge for up to 25x faster performance with large data
+- **Direct Native SQLite**: Full SQL support with transactions, batch operations, and binary data
+- **Sync-Friendly**: Designed for local sync systems (CRDTs, operational transforms, etc.)
+- **IndexedDB Replacement**: Provides reliable alternative to broken/limited IndexedDB implementations
+- **Cross-Platform**: iOS, Android, and Web (using sql.js + IndexedDB for persistence)
+- **Optional RAG VectorStore**: Persist many named vector stores for retrieval-augmented generation without adding a native dependency
+
+## iOS Configuration
+
+This plugin runs a local HTTP server on `localhost`. iOS App Transport Security (ATS) blocks cleartext HTTP by default, so you **must** allow local networking in your `Info.plist`:
+
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+    <key>NSAllowsLocalNetworking</key>
+    <true/>
+</dict>
+```
+
+This only permits cleartext to loopback addresses (`localhost` / `127.0.0.1`) — it does not weaken ATS for external connections.
+
+## Android Configuration
+
+This plugin runs a local HTTP server on `localhost` to bypass Capacitor's bridge for performance. Android 9+ blocks cleartext (non-HTTPS) traffic by default, so you **must** allow it for `localhost`.
+
+**Option A — Scoped to localhost only (recommended):**
+
+Create `android/app/src/main/res/xml/network_security_config.xml`:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">localhost</domain>
+        <domain includeSubdomains="false">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>
+```
+
+Then reference it in your `AndroidManifest.xml`:
+
+```xml
+<application
+    android:networkSecurityConfig="@xml/network_security_config">
+    ...
+</application>
+```
+
+**Option B — Allow all cleartext (simpler but less secure):**
+
+```xml
+<application
+    android:usesCleartextTraffic="true">
+    ...
+</application>
+```
+
+## Encryption
+
+### Android
+
+Encryption uses [SQLCipher](https://www.zetetic.net/sqlcipher/) and is opt-in. Add the SQLCipher dependency to your **app-level** `build.gradle`:
+
+```gradle
+dependencies {
+    implementation 'net.zetetic:sqlcipher-android:4.13.0'
+}
+```
+
+Then connect with encryption enabled:
+
+```typescript
+const db = await FastSQL.connect({
+  database: 'secure',
+  encrypted: true,
+  encryptionKey: 'my-secret-key',
+});
+```
+
+If SQLCipher is not installed and `encrypted: true` is passed, the plugin returns a clear error message instead of crashing.
+
+### iOS
+
+SQLCipher is optional on iOS. The plugin builds without it; encryption calls will return `Encryption is not available in this build` unless SQLCipher is installed.
+
+To enable encryption via CocoaPods, update your `ios/App/Podfile` after `capacitor install`/`cap sync` to use the SQLCipher subspec:
+
+```ruby
+pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql'
+```
+
+Then run `pod install` in the `ios/App` directory. If you skip this subspec, keep `encrypted: false`.
+
+## Web Platform
+
+On the web, this plugin uses [sql.js](https://sql.js.org/) (SQLite compiled to WebAssembly) with IndexedDB for persistence.
+
+By default, the plugin loads `sql-wasm.js` and `sql-wasm.wasm` from the cdnjs CDN. If you want to bundle these files with your web application (to avoid a CDN dependency), call `configureWeb()` once at startup **before** the first `connect()`:
+
+```typescript
+import { CapgoCapacitorFastSql, FastSQL } from '@capgo/capacitor-fast-sql';
+
+// Point to your locally bundled sql.js files
+await CapgoCapacitorFastSql.configureWeb({
+  sqlJsUrl: '/assets/sql-wasm.js',
+  wasmUrl: '/assets/sql-wasm.wasm',
+});
+
+const db = await FastSQL.connect({ database: 'myapp' });
+```
+
+`configureWeb()` is a no-op on iOS and Android — it is safe to call unconditionally.
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { FastSQL } from '@capgo/capacitor-fast-sql';
+
+// Connect to database
+const db = await FastSQL.connect({ database: 'myapp' });
+
+// Create table
+await db.execute(`
+  CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    email TEXT UNIQUE
+  )
+`);
+
+// Insert data
+const result = await db.run(
+  'INSERT INTO users (name, email) VALUES (?, ?)',
+  ['John Doe', 'john@example.com']
+);
+console.log('Inserted row ID:', result.insertId);
+
+// Query data
+const users = await db.query('SELECT * FROM users WHERE name LIKE ?', ['John%']);
+console.log('Users:', users);
+
+// Close connection
+await FastSQL.disconnect('myapp');
+```
+
+### Transaction Example
+
+```typescript
+const db = await FastSQL.connect({ database: 'myapp' });
+
+try {
+  await db.transaction(async (tx) => {
+    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Alice', 1000]);
+    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Bob', 500]);
+    await tx.run('UPDATE accounts SET balance = balance - 100 WHERE name = ?', ['Alice']);
+    await tx.run('UPDATE accounts SET balance = balance + 100 WHERE name = ?', ['Bob']);
+  });
+  console.log('Transaction successful!');
+} catch (error) {
+  console.error('Transaction failed:', error);
+}
+```
+
+### Batch Operations
+
+```typescript
+const db = await FastSQL.connect({ database: 'myapp' });
+
+const results = await db.executeBatch([
+  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 1'] },
+  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 2'] },
+  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 3'] },
+]);
+```
+
+### Key-Value Storage (Mobile-focused)
+
+```typescript
+import { KeyValueStore } from '@capgo/capacitor-fast-sql';
+
+const kv = await KeyValueStore.open({
+  database: 'myapp',
+  encrypted: true,
+  encryptionKey: 'super-secret-key',
+});
+
+await kv.set('session', { token: 'abc123', expiresAt: 1710000000 });
+const session = await kv.get('session');
+await kv.remove('session');
+```
+
+### RAG Vector Stores (Optional)
+
+`FastSQLVectorStore` provides a dependency-free VectorStore-compatible helper inspired by `@react-native-rag/op-sqlite`. It stores embeddings in SQLite as binary Float32 vectors and computes cosine similarity in TypeScript, so it works anywhere this plugin works.
+
+Each store is namespaced by the `store` option, so one database can hold as many independent vector stores as you need:
+
+```typescript
+import { FastSQLVectorStore } from '@capgo/capacitor-fast-sql';
+
+const docs = await FastSQLVectorStore.open({
+  database: 'rag',
+  store: 'docs',
+  embeddings,
+});
+
+const tickets = await FastSQLVectorStore.open({
+  database: 'rag',
+  store: 'tickets',
+  embeddings,
+});
+
+await docs.add({
+  document: 'Capgo ships instant updates for Capacitor apps.',
+  metadata: { source: 'docs' },
+});
+
+const results = await docs.query({
+  queryText: 'How do instant updates work?',
+  nResults: 3,
+});
+
+await docs.close();
+await tickets.close();
+```
+
+You can also use precomputed embeddings without an embeddings provider:
+
+```typescript
+const store = await FastSQLVectorStore.open({
+  database: 'rag',
+  store: 'offline-embeddings',
+  embeddingDimension: 384,
+});
+
+await store.add({
+  id: 'intro',
+  document: 'Local RAG entry',
+  embedding: [0.12, 0.08, 0.31 /* ...384 values */],
+});
+
+const matches = await store.query({
+  queryEmbedding: [0.11, 0.09, 0.29 /* ...384 values */],
+  nResults: 5,
+});
+```
+
+> Note: Web support is intended for minimal testing only. The primary focus is iOS/Android.
+
+## API
+
 <docgen-index>
 
 * [`connect(...)`](#connect)
@@ -315,8 +329,8 @@ const matches = await store.query({
 * [Type Aliases](#type-aliases)
 * [Enums](#enums)
 
-</docgen-index>
-
+</docgen-index>
+
 <docgen-api>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 
@@ -632,4 +646,4 @@ SQL value types supported by the plugin
 | **`RepeatableRead`**  | <code>'REPEATABLE READ'</code>  |
 | **`Serializable`**    | <code>'SERIALIZABLE'</code>     |
 
-</docgen-api>
+</docgen-api>

package/android/src/main/java/app/capgo/capacitor/fastsql/CapgoCapacitorFastSqlPlugin.java

@@ -19,7 +19,7 @@ import java.util.Map;
 @CapacitorPlugin(name = "CapgoCapacitorFastSql")
 public class CapgoCapacitorFastSqlPlugin extends Plugin {
 
-    private final String pluginVersion = "8.0.42";
+    private final String pluginVersion = "8.0.44";
 
     private Map<String, DatabaseConnection> databases = new HashMap<>();
     private SQLHTTPServer server;

package/ios/Sources/CapgoCapacitorFastSqlPlugin/CapgoCapacitorFastSqlPlugin.swift

@@ -10,7 +10,7 @@ import SQLite3
  */
 @objc(CapgoCapacitorFastSqlPlugin)
 public class CapgoCapacitorFastSqlPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.0.42"
+    private let pluginVersion: String = "8.0.44"
     public let identifier = "CapgoCapacitorFastSqlPlugin"
     public let jsName = "CapgoCapacitorFastSql"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-fast-sql",
-  "version": "8.0.42",
+  "version": "8.0.44",
   "description": "High-performance native SQLite plugin with custom protocol for efficient sync operations and IndexedDB replacement",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",