pomegranate-db 0.1.0 → 1.0.0

package/README.md

@@ -110,12 +110,58 @@ function PostList() {
 }
 ```
 
+## Installation
+
+```sh
+npm install pomegranate-db
+```
+
+Install adapter-specific peers only when you use those entry points:
+
+- `pomegranate-db` -> `react`
+- `pomegranate-db/expo` -> `react`, `expo-sqlite`
+- `pomegranate-db/encryption` -> no extra peers, uses Web Crypto
+- `pomegranate-db/encryption/node` -> Node.js only
+- `pomegranate-db/encryption/react-native` -> React Native / Expo Web Crypto runtime
+- `pomegranate-db/op-sqlite` -> `@op-engineering/op-sqlite`
+- `pomegranate-db/native-sqlite` -> React Native app with the bundled native module
+
+## Entry Points
+
+PomegranateDB ships a small set of explicit subpath exports for common setups:
+
+```ts
+import { Database, LokiAdapter } from 'pomegranate-db'
+import { createExpoSQLiteDriver } from 'pomegranate-db/expo'
+import { EncryptingAdapter } from 'pomegranate-db/encryption'
+import { nodeCryptoProvider } from 'pomegranate-db/encryption/node'
+import { createOpSQLiteDriver } from 'pomegranate-db/op-sqlite'
+import { createNativeSQLiteDriver } from 'pomegranate-db/native-sqlite'
+```
+
+The root package intentionally excludes encryption exports so Expo Snack can install
+`pomegranate-db` without resolving Node's `crypto` module. Import encryption through
+the explicit `./encryption`, `./encryption/node`, or `./encryption/react-native`
+subpaths instead.
+
+## Migrations
+
+Manual migrations are supported across Loki and SQLite adapters with these step types:
+
+- `createTable`
+- `addColumn`
+- `destroyTable`
+- `sql`
+
+Use `sql` for targeted backfills such as setting a new column value on existing rows.
+Schema diff generation is not automated yet, so migration steps are still authored manually.
+
 ## Next Steps
 
-- [Installation](https://bobbyquantum.github.io/pomegranate/docs/installation) — add PomegranateDB to your project
-- [Schema & Models](https://bobbyquantum.github.io/pomegranate/docs/schema) — define your data model
-- [CRUD Operations](https://bobbyquantum.github.io/pomegranate/docs/crud) — create, read, update, delete
-- [React Hooks](https://bobbyquantum.github.io/pomegranate/docs/react-hooks) — reactive UI integration
+- [Installation](https://bobbyquantum.github.io/pomegranate/installation) — add PomegranateDB to your project
+- [Schema & Models](https://bobbyquantum.github.io/pomegranate/schema) — define your data model
+- [CRUD Operations](https://bobbyquantum.github.io/pomegranate/crud) — create, read, update, delete
+- [React Hooks](https://bobbyquantum.github.io/pomegranate/react-hooks) — reactive UI integration
 
 ## License
 

package/dist/adapters/expo-sqlite/ExpoSQLiteDriver.d.ts

@@ -6,24 +6,42 @@
  * using the Expo managed SQLite library instead of requiring
  * react-native-quick-sqlite or op-sqlite.
  *
+ * Supports both **async** and **sync** modes:
+ *   - `preferSync: false` (default) — uses async APIs (runAsync, getAllAsync).
+ *     Works on all platforms including web (wa-sqlite / OPFS).
+ *   - `preferSync: true` — uses synchronous JSI APIs (runSync, getAllSync).
+ *     Faster on native (no Promise overhead) but NOT available on web.
+ *     Falls back to async automatically on web.
+ *
  * Usage:
  *   import { createExpoSQLiteDriver } from 'pomegranate-db/expo';
  *   import { SQLiteAdapter } from 'pomegranate-db';
  *
- *   const adapter = new SQLiteAdapter({
- *     databaseName: 'myapp',
- *     driver: createExpoSQLiteDriver(),
- *   });
+ *   // Async (default — works everywhere)
+ *   const driver = createExpoSQLiteDriver();
+ *
+ *   // Sync (native-only, falls back to async on web)
+ *   const driverSync = createExpoSQLiteDriver({ preferSync: true });
  */
 import type { SQLiteDriver } from '../sqlite/SQLiteAdapter';
 export interface ExpoSQLiteDriverConfig {
     /**
-     * Options passed to expo-sqlite's openDatabaseAsync.
+     * Options passed to expo-sqlite's openDatabaseAsync/openDatabaseSync.
      * @default {}
      */
     openOptions?: {
         enableChangeListener?: boolean;
     };
+    /**
+     * When true, use synchronous JSI calls (runSync, getAllSync, etc.)
+     * for better performance on native platforms.
+     *
+     * On web (wa-sqlite), sync methods are not available — the driver
+     * will automatically fall back to async mode.
+     *
+     * @default false
+     */
+    preferSync?: boolean;
 }
 /**
  * Create a SQLiteDriver backed by expo-sqlite.

package/dist/adapters/expo-sqlite/ExpoSQLiteDriver.js

@@ -7,14 +7,22 @@
  * using the Expo managed SQLite library instead of requiring
  * react-native-quick-sqlite or op-sqlite.
  *
+ * Supports both **async** and **sync** modes:
+ *   - `preferSync: false` (default) — uses async APIs (runAsync, getAllAsync).
+ *     Works on all platforms including web (wa-sqlite / OPFS).
+ *   - `preferSync: true` — uses synchronous JSI APIs (runSync, getAllSync).
+ *     Faster on native (no Promise overhead) but NOT available on web.
+ *     Falls back to async automatically on web.
+ *
  * Usage:
  *   import { createExpoSQLiteDriver } from 'pomegranate-db/expo';
  *   import { SQLiteAdapter } from 'pomegranate-db';
  *
- *   const adapter = new SQLiteAdapter({
- *     databaseName: 'myapp',
- *     driver: createExpoSQLiteDriver(),
- *   });
+ *   // Async (default — works everywhere)
+ *   const driver = createExpoSQLiteDriver();
+ *
+ *   // Sync (native-only, falls back to async on web)
+ *   const driverSync = createExpoSQLiteDriver({ preferSync: true });
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -51,6 +59,27 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createExpoSQLiteDriver = createExpoSQLiteDriver;
+// ─── Helpers ──────────────────────────────────────────────────────────────
+/**
+ * Replace `?` placeholders in SQL with literal values.
+ *
+ * This is used for `execAsync(multiStatement)` which doesn't accept bindings.
+ * Safe because all values come from our own SQL generators with known types.
+ */
+function inlineBindings(sql, bindings) {
+    let index = 0;
+    return sql.replaceAll('?', () => {
+        const val = bindings[index++];
+        if (val === null || val === undefined)
+            return 'NULL';
+        if (typeof val === 'number')
+            return String(val);
+        if (typeof val === 'boolean')
+            return val ? '1' : '0';
+        return `'${String(val).replaceAll("'", "''")}'`;
+    });
+}
+// ─── Driver Factory ───────────────────────────────────────────────────────
 /**
  * Create a SQLiteDriver backed by expo-sqlite.
  *
@@ -60,6 +89,48 @@ exports.createExpoSQLiteDriver = createExpoSQLiteDriver;
 function createExpoSQLiteDriver(config) {
     let db = null;
     let expoSQLite = null;
+    // Whether we're actually using sync mode (resolved after open)
+    let useSync = false;
+    // ── Statement cache (sync mode only) ──────────────────────────────────
+    // Caches compiled sqlite3_stmt handles keyed by SQL string.
+    // Avoids re-calling sqlite3_prepare_v2 for repeated SQL (e.g. 1000 INSERTs
+    // with the same template). This mirrors NativeSQLite's cachedPrepare().
+    const stmtCache = new Map();
+    const MAX_CACHE_SIZE = 50;
+    function getCachedStmt(database, sql) {
+        if (!database.prepareSync)
+            return null;
+        let stmt = stmtCache.get(sql);
+        if (stmt)
+            return stmt;
+        // Evict oldest entry if cache is full
+        if (stmtCache.size >= MAX_CACHE_SIZE) {
+            const firstKey = stmtCache.keys().next().value;
+            const evicted = stmtCache.get(firstKey);
+            stmtCache.delete(firstKey);
+            try {
+                evicted?.finalizeSync();
+            }
+            catch { /* already finalized */ }
+        }
+        try {
+            stmt = database.prepareSync(sql);
+            stmtCache.set(sql, stmt);
+            return stmt;
+        }
+        catch {
+            return null; // Fall back to runSync/execSync
+        }
+    }
+    function clearStmtCache() {
+        for (const stmt of stmtCache.values()) {
+            try {
+                stmt.finalizeSync();
+            }
+            catch { /* ignore */ }
+        }
+        stmtCache.clear();
+    }
     // Lazily import expo-sqlite so this module can be imported
     // without expo-sqlite being installed (e.g. in tests).
     async function getExpoSQLite() {
@@ -83,26 +154,86 @@ function createExpoSQLiteDriver(config) {
     return {
         async open(name) {
             const sqlite = await getExpoSQLite();
-            db = await sqlite.openDatabaseAsync(name.endsWith('.db') ? name : `${name}.db`, config?.openOptions);
+            const dbName = name.endsWith('.db') ? name : `${name}.db`;
+            // Try sync open if preferred and available
+            if (config?.preferSync && typeof sqlite.openDatabaseSync === 'function') {
+                try {
+                    db = sqlite.openDatabaseSync(dbName, config?.openOptions);
+                    useSync = true;
+                }
+                catch {
+                    // openDatabaseSync not supported (e.g. web) — fall through
+                }
+            }
+            // Async fallback (or default path)
+            if (!db) {
+                db = await sqlite.openDatabaseAsync(dbName, config?.openOptions);
+                useSync = false;
+            }
             // Enable WAL mode for better performance (may not be supported on web/wa-sqlite)
             try {
-                await db.execAsync('PRAGMA journal_mode = WAL');
+                if (useSync && db.execSync) {
+                    db.execSync('PRAGMA journal_mode = WAL');
+                    db.execSync('PRAGMA synchronous = NORMAL');
+                    db.execSync('PRAGMA cache_size = -8000');
+                    db.execSync('PRAGMA temp_store = MEMORY');
+                    db.execSync('PRAGMA busy_timeout = 5000');
+                }
+                else {
+                    await db.execAsync('PRAGMA journal_mode = WAL');
+                    await db.execAsync('PRAGMA synchronous = NORMAL');
+                    await db.execAsync('PRAGMA cache_size = -8000');
+                    await db.execAsync('PRAGMA temp_store = MEMORY');
+                    await db.execAsync('PRAGMA busy_timeout = 5000');
+                }
             }
             catch {
-                // WAL not supported on this platform (e.g. web wa-sqlite), continue without it
+                // PRAGMAs not supported on this platform (e.g. web wa-sqlite), continue without them
             }
         },
         async execute(sql, bindings) {
             const database = requireDb();
-            if (bindings && bindings.length > 0) {
-                await database.runAsync(sql, ...bindings);
+            // DDL statements invalidate cached prepared statements
+            if (stmtCache.size > 0 && /^\s*(DROP|CREATE|ALTER)\s/i.test(sql)) {
+                clearStmtCache();
+            }
+            if (useSync && database.runSync) {
+                if (bindings && bindings.length > 0) {
+                    const stmt = getCachedStmt(database, sql);
+                    if (stmt) {
+                        stmt.executeSync(bindings);
+                    }
+                    else {
+                        database.runSync(sql, ...bindings);
+                    }
+                }
+                else if (database.execSync) {
+                    database.execSync(sql);
+                }
+                else {
+                    database.runSync(sql);
+                }
             }
             else {
-                await database.execAsync(sql);
+                if (bindings && bindings.length > 0) {
+                    await database.runAsync(sql, ...bindings);
+                }
+                else {
+                    await database.execAsync(sql);
+                }
             }
         },
         async query(sql, bindings) {
             const database = requireDb();
+            if (useSync && database.getAllSync) {
+                // Use database.getAllSync directly (no statement cache for queries).
+                // The bulk row transfer in getAllSync is faster than iterating via
+                // a prepared statement's getAllSync for large result sets.
+                if (bindings && bindings.length > 0) {
+                    return database.getAllSync(sql, ...bindings);
+                }
+                return database.getAllSync(sql);
+            }
             if (bindings && bindings.length > 0) {
                 return database.getAllAsync(sql, ...bindings);
             }
@@ -110,46 +241,212 @@ function createExpoSQLiteDriver(config) {
         },
         async executeInTransaction(fn) {
             const database = requireDb();
-            // expo-sqlite's withExclusiveTransactionAsync is not supported on web.
-            // Fall back to manual BEGIN/COMMIT/ROLLBACK for web compatibility.
+            // Sync transaction path (native only)
+            if (useSync && database.withTransactionSync) {
+                try {
+                    database.withTransactionSync(() => {
+                        // NOTE: fn() returns a Promise but our sync transaction
+                        // callback is synchronous. The inner operations will also
+                        // be sync (since useSync=true), so the await is a no-op.
+                        // We run the promise synchronously via the micro-task trick.
+                        let error;
+                        let done = false;
+                        fn().then(() => { done = true; }, (error_) => { error = error_; done = true; });
+                        // In sync mode all awaits inside fn() resolve immediately
+                        // (they're wrapping synchronous calls), so done should be true.
+                        if (!done) {
+                            throw new Error('ExpoSQLiteDriver: async operations inside sync transaction are not supported. ' +
+                                'Use preferSync: false for mixed async/sync workloads.');
+                        }
+                        if (error)
+                            throw error;
+                    });
+                    return;
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message.includes('not supported on web')) {
+                        // Fall through to async
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            // Async transaction path
             if (typeof database.withExclusiveTransactionAsync === 'function') {
                 try {
                     await database.withExclusiveTransactionAsync(async (_txn) => {
-                        // expo-sqlite's exclusive transaction scopes all queries
-                        // on this database connection to the transaction, so we
-                        // can just call fn() which uses the same `db` reference.
                         await fn();
                     });
                     return;
                 }
-                catch (e) {
-                    // On web, withExclusiveTransactionAsync throws even though the method exists.
-                    // Detect this and fall through to manual transaction handling.
-                    if (e instanceof Error && e.message.includes('not supported on web')) {
+                catch (error) {
+                    if (error instanceof Error && error.message.includes('not supported on web')) {
                         // Fall through to manual transaction below
                     }
                     else {
-                        throw e;
+                        throw error;
                     }
                 }
             }
             // Manual transaction fallback (web, or platforms without exclusive transactions)
-            await database.execAsync('BEGIN TRANSACTION');
-            try {
-                await fn();
-                await database.execAsync('COMMIT');
+            if (useSync && database.execSync) {
+                database.execSync('BEGIN TRANSACTION');
+                try {
+                    await fn();
+                    database.execSync('COMMIT');
+                }
+                catch (error) {
+                    database.execSync('ROLLBACK');
+                    throw error;
+                }
             }
-            catch (e) {
-                await database.execAsync('ROLLBACK');
-                throw e;
+            else {
+                await database.execAsync('BEGIN TRANSACTION');
+                try {
+                    await fn();
+                    await database.execAsync('COMMIT');
+                }
+                catch (error) {
+                    await database.execAsync('ROLLBACK');
+                    throw error;
+                }
             }
         },
         async close() {
             if (db) {
-                await db.closeAsync();
+                clearStmtCache();
+                if (useSync && db.closeSync) {
+                    db.closeSync();
+                }
+                else {
+                    await db.closeAsync();
+                }
                 db = null;
             }
         },
+        // ── Raw sync/async for benchmarking ──────────────────────────────────
+        executeSync(sql, bindings) {
+            const database = requireDb();
+            if (!database.runSync) {
+                throw new Error('ExpoSQLiteDriver: sync API not available (web platform). ' +
+                    'Set preferSync: true and run on native.');
+            }
+            if (bindings && bindings.length > 0) {
+                const stmt = getCachedStmt(database, sql);
+                if (stmt) {
+                    stmt.executeSync(bindings);
+                }
+                else {
+                    database.runSync(sql, ...bindings);
+                }
+            }
+            else if (database.execSync) {
+                database.execSync(sql);
+            }
+            else {
+                database.runSync(sql);
+            }
+        },
+        async executeAsync(sql, bindings) {
+            const database = requireDb();
+            if (bindings && bindings.length > 0) {
+                await database.runAsync(sql, ...bindings);
+            }
+            else {
+                await database.execAsync(sql);
+            }
+        },
+        // ── Batch without transaction wrapping ──────────────────────────────
+        // Uses execAsync with concatenated SQL to send all commands in a
+        // single native call. This avoids per-statement async bridge overhead
+        // which is the main bottleneck for expo-sqlite async mode.
+        //
+        // Values are inlined using SQLite literal escaping. This is safe
+        // because all values come from our own SQL generators (insertSQL,
+        // updateSQL, deleteSQL) with known types.
+        async executeBatchNoTx(commands) {
+            const database = requireDb();
+            if (commands.length === 0)
+                return;
+            // For sync mode, use cached prepared statements when possible
+            if (useSync && database.runSync) {
+                for (const [sql, bindings] of commands) {
+                    if (bindings && bindings.length > 0) {
+                        const stmt = getCachedStmt(database, sql);
+                        if (stmt) {
+                            stmt.executeSync(bindings);
+                        }
+                        else {
+                            database.runSync(sql, ...bindings);
+                        }
+                    }
+                    else if (database.execSync) {
+                        database.execSync(sql);
+                    }
+                    else {
+                        database.runSync(sql);
+                    }
+                }
+                return;
+            }
+            // Async mode: build a single SQL string with all statements.
+            // This sends one message across the async bridge instead of N.
+            const parts = [];
+            for (const [sql, bindings] of commands) {
+                if (!bindings || bindings.length === 0) {
+                    parts.push(sql);
+                }
+                else {
+                    parts.push(inlineBindings(sql, bindings));
+                }
+            }
+            await database.execAsync(parts.join(';\n'));
+        },
+        // ── Batch with transaction wrapping (for use outside writeTransaction) ──
+        async executeBatch(commands) {
+            const database = requireDb();
+            if (commands.length === 0)
+                return;
+            // For sync mode, use sync transaction with cached statements
+            if (useSync && database.runSync && database.execSync) {
+                database.execSync('BEGIN TRANSACTION');
+                try {
+                    for (const [sql, bindings] of commands) {
+                        if (bindings && bindings.length > 0) {
+                            const stmt = getCachedStmt(database, sql);
+                            if (stmt) {
+                                stmt.executeSync(bindings);
+                            }
+                            else {
+                                database.runSync(sql, ...bindings);
+                            }
+                        }
+                        else {
+                            database.execSync(sql);
+                        }
+                    }
+                    database.execSync('COMMIT');
+                }
+                catch (error) {
+                    database.execSync('ROLLBACK');
+                    throw error;
+                }
+                return;
+            }
+            // Async mode: concatenate with BEGIN/COMMIT wrapping
+            const parts = ['BEGIN TRANSACTION'];
+            for (const [sql, bindings] of commands) {
+                if (!bindings || bindings.length === 0) {
+                    parts.push(sql);
+                }
+                else {
+                    parts.push(inlineBindings(sql, bindings));
+                }
+            }
+            parts.push('COMMIT');
+            await database.execAsync(parts.join(';\n'));
+        },
     };
 }
 //# sourceMappingURL=ExpoSQLiteDriver.js.map

package/dist/adapters/loki/worker/LokiExecutor.d.ts

@@ -56,6 +56,10 @@ export declare class LokiExecutor {
     initialize(schema: DatabaseSchema): Promise<void>;
     private _createLokiDb;
     private _getCollection;
+    private _getMetadataCollection;
+    private _setSchemaVersion;
+    private _addColumn;
+    private _executeSqlMigration;
     /**
      * Persist to storage adapter.
      * No-op when: no persistence configured, or saveStrategy is 'auto' (timer handles it).