pomegranate-db 0.1.0

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

@@ -0,0 +1,44 @@
+/**
+ * Shared types for the LokiJS Web Worker message protocol.
+ *
+ * Communication follows an RPC-over-postMessage pattern:
+ * - Main thread sends WorkerAction messages
+ * - Worker processes them sequentially and returns WorkerResponse messages
+ * - Matching is done via monotonically increasing message IDs (FIFO order)
+ */
+/** All valid command types that can be sent to the worker */
+export type WorkerCommandType = 'setUp' | 'find' | 'count' | 'findById' | 'insert' | 'update' | 'markAsDeleted' | 'destroyPermanently' | 'batch' | 'search' | 'getLocalChanges' | 'applyRemoteChanges' | 'markAsSynced' | 'getSchemaVersion' | 'migrate' | 'reset' | 'close';
+/** Message sent from main thread to worker */
+export interface WorkerAction {
+    id: number;
+    type: WorkerCommandType;
+    payload: unknown[];
+}
+/** Discriminated union for success/error results */
+export type WorkerResult<T = unknown> = {
+    value: T;
+} | {
+    error: {
+        message: string;
+        stack?: string;
+    };
+};
+/** Message sent from worker back to main thread */
+export interface WorkerResponse {
+    id: number;
+    result: WorkerResult;
+}
+/** Serializable configuration passed to the worker during setUp */
+export interface WorkerSetupPayload {
+    databaseName: string;
+    saveStrategy?: 'immediate' | 'auto';
+    autosaveInterval?: number;
+}
+/** Interface matching what Worker and SynchronousWorker both implement */
+export interface WorkerInterface {
+    postMessage(data: unknown): void;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    terminate?(): void;
+}

package/dist/adapters/loki/worker/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Shared types for the LokiJS Web Worker message protocol.
+ *
+ * Communication follows an RPC-over-postMessage pattern:
+ * - Main thread sends WorkerAction messages
+ * - Worker processes them sequentially and returns WorkerResponse messages
+ * - Matching is done via monotonically increasing message IDs (FIFO order)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/adapters/native-sqlite/NativeSQLiteDriver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Native SQLite Driver (JSI).
+ *
+ * Implements the SQLiteDriver interface using PomegranateDB's own JSI
+ * C++ bridge. This is the fastest possible option — direct synchronous
+ * calls from JS to C++ SQLite with zero bridge overhead.
+ *
+ * Requires:
+ *   - PomegranateJSIPackage added to MainApplication (Android)
+ *   - The native C++ module built and linked (via android-jsi module)
+ *
+ * Usage:
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *   import { createNativeSQLiteDriver } from 'pomegranate-db/src/adapters/native-sqlite';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createNativeSQLiteDriver(),
+ *   });
+ */
+import type { SQLiteDriver } from '../sqlite/SQLiteAdapter';
+/**
+ * The shape of the JSI adapter object returned by nativePomegranateCreateAdapter.
+ * All methods are synchronous JSI calls.
+ */
+interface NativeJSIAdapter {
+    execute(sql: string, args: unknown[]): void;
+    query(sql: string, args: unknown[]): Record<string, unknown>[];
+    executeBatch(commands: Array<{
+        sql: string;
+        args: unknown[];
+    }>): number;
+    close(): void;
+}
+declare global {
+    var nativePomegranateCreateAdapter: ((dbName: string) => NativeJSIAdapter) | undefined;
+}
+export interface NativeSQLiteDriverConfig {
+    /**
+     * If true, will attempt to auto-install the JSI binding by calling
+     * NativeModules.PomegranateJSIBridge.install().
+     * @default true
+     */
+    autoInstall?: boolean;
+}
+/**
+ * Create a SQLiteDriver backed by PomegranateDB's native JSI C++ bridge.
+ *
+ * This adapter communicates with C++ SQLite directly through JSI — no
+ * React Native bridge, no JSON serialization, no async queues.
+ * All calls are synchronous under the hood, wrapped in Promises for
+ * the SQLiteDriver interface.
+ */
+export declare function createNativeSQLiteDriver(config?: NativeSQLiteDriverConfig): SQLiteDriver;
+export {};

package/dist/adapters/native-sqlite/NativeSQLiteDriver.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Native SQLite Driver (JSI).
+ *
+ * Implements the SQLiteDriver interface using PomegranateDB's own JSI
+ * C++ bridge. This is the fastest possible option — direct synchronous
+ * calls from JS to C++ SQLite with zero bridge overhead.
+ *
+ * Requires:
+ *   - PomegranateJSIPackage added to MainApplication (Android)
+ *   - The native C++ module built and linked (via android-jsi module)
+ *
+ * Usage:
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *   import { createNativeSQLiteDriver } from 'pomegranate-db/src/adapters/native-sqlite';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createNativeSQLiteDriver(),
+ *   });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNativeSQLiteDriver = createNativeSQLiteDriver;
+// ─── Driver ───────────────────────────────────────────────────────────────
+/**
+ * Create a SQLiteDriver backed by PomegranateDB's native JSI C++ bridge.
+ *
+ * This adapter communicates with C++ SQLite directly through JSI — no
+ * React Native bridge, no JSON serialization, no async queues.
+ * All calls are synchronous under the hood, wrapped in Promises for
+ * the SQLiteDriver interface.
+ */
+function createNativeSQLiteDriver(config) {
+    let adapter = null;
+    const autoInstall = config?.autoInstall !== false;
+    /**
+     * Ensure the JSI binding is installed.
+     * On Android, this requires calling NativeModules.PomegranateJSIBridge.install()
+     * which loads the .so and registers the global function.
+     */
+    async function ensureInstalled() {
+        if (typeof globalThis.nativePomegranateCreateAdapter === 'function') {
+            return; // Already installed
+        }
+        if (!autoInstall) {
+            throw new Error('PomegranateDB JSI binding is not installed. ' +
+                'Call NativeModules.PomegranateJSIBridge.install() first, ' +
+                'or pass autoInstall: true to createNativeSQLiteDriver().');
+        }
+        // Auto-install by calling the native module
+        try {
+            const { NativeModules } = await Promise.resolve().then(() => __importStar(require('react-native')));
+            const bridge = NativeModules.PomegranateJSIBridge;
+            if (!bridge) {
+                throw new Error('PomegranateJSIBridge native module not found. ' +
+                    'Make sure PomegranateJSIPackage is added to your MainApplication.');
+            }
+            const success = bridge.install();
+            if (!success) {
+                throw new Error('PomegranateJSIBridge.install() returned false');
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error('Failed to install PomegranateDB JSI binding: ' + message, { cause: error });
+        }
+        if (typeof globalThis.nativePomegranateCreateAdapter !== 'function') {
+            throw new TypeError('PomegranateDB JSI binding installation succeeded but ' +
+                'global.nativePomegranateCreateAdapter is not available. ' +
+                'This may indicate a native build issue.');
+        }
+    }
+    function requireAdapter() {
+        if (!adapter) {
+            throw new Error('Database not open. Call open() first.');
+        }
+        return adapter;
+    }
+    return {
+        async open(name) {
+            await ensureInstalled();
+            adapter = globalThis.nativePomegranateCreateAdapter(name);
+        },
+        async execute(sql, bindings) {
+            const db = requireAdapter();
+            db.execute(sql, bindings ?? []);
+        },
+        async query(sql, bindings) {
+            const db = requireAdapter();
+            return db.query(sql, bindings ?? []);
+        },
+        async executeInTransaction(fn) {
+            const db = requireAdapter();
+            db.execute('BEGIN EXCLUSIVE TRANSACTION', []);
+            try {
+                await fn();
+                db.execute('COMMIT', []);
+            }
+            catch (error) {
+                db.execute('ROLLBACK', []);
+                throw error;
+            }
+        },
+        async close() {
+            if (adapter) {
+                adapter.close();
+                adapter = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=NativeSQLiteDriver.js.map

package/dist/adapters/native-sqlite/index.d.ts

@@ -0,0 +1,2 @@
+export { createNativeSQLiteDriver } from './NativeSQLiteDriver';
+export type { NativeSQLiteDriverConfig } from './NativeSQLiteDriver';

package/dist/adapters/native-sqlite/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNativeSQLiteDriver = void 0;
+var NativeSQLiteDriver_1 = require("./NativeSQLiteDriver");
+Object.defineProperty(exports, "createNativeSQLiteDriver", { enumerable: true, get: function () { return NativeSQLiteDriver_1.createNativeSQLiteDriver; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/op-sqlite/OpSQLiteDriver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * op-sqlite Driver.
+ *
+ * Implements the SQLiteDriver interface using @op-engineering/op-sqlite.
+ * Provides JSI-based synchronous SQLite access for React Native apps
+ * — the fastest SQLite option for bare RN projects.
+ *
+ * Features:
+ *   - JSI synchronous execution (no bridge overhead)
+ *   - SQLCipher encryption support (via encryptionKey)
+ *   - Prepared statement support
+ *   - Batch execution in transactions
+ *   - Update hooks for reactive queries
+ *
+ * Usage:
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *   import { createOpSQLiteDriver } from 'pomegranate-db/src/adapters/op-sqlite';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createOpSQLiteDriver({ encryptionKey: 'secret' }),
+ *   });
+ */
+import type { SQLiteDriver } from '../sqlite/SQLiteAdapter';
+export interface OpSQLiteDriverConfig {
+    /**
+     * SQLCipher encryption key.
+     * If provided, the database will be encrypted at rest.
+     * Requires op-sqlite to be compiled with SQLCipher support.
+     */
+    encryptionKey?: string;
+    /**
+     * Custom storage location for the database file.
+     * If not specified, uses the app's default database directory.
+     */
+    location?: string;
+    /**
+     * Optional callback invoked on every database write.
+     * Useful for driving reactive queries / cache invalidation.
+     */
+    onTableChanged?: (table: string, operation: 'INSERT' | 'UPDATE' | 'DELETE') => void;
+}
+/**
+ * Create a SQLiteDriver backed by @op-engineering/op-sqlite.
+ *
+ * @param config Optional driver configuration (encryption, hooks, etc.)
+ * @returns A SQLiteDriver that can be passed to SQLiteAdapter.
+ */
+export declare function createOpSQLiteDriver(config?: OpSQLiteDriverConfig): SQLiteDriver;

package/dist/adapters/op-sqlite/OpSQLiteDriver.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * op-sqlite Driver.
+ *
+ * Implements the SQLiteDriver interface using @op-engineering/op-sqlite.
+ * Provides JSI-based synchronous SQLite access for React Native apps
+ * — the fastest SQLite option for bare RN projects.
+ *
+ * Features:
+ *   - JSI synchronous execution (no bridge overhead)
+ *   - SQLCipher encryption support (via encryptionKey)
+ *   - Prepared statement support
+ *   - Batch execution in transactions
+ *   - Update hooks for reactive queries
+ *
+ * Usage:
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *   import { createOpSQLiteDriver } from 'pomegranate-db/src/adapters/op-sqlite';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createOpSQLiteDriver({ encryptionKey: 'secret' }),
+ *   });
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpSQLiteDriver = createOpSQLiteDriver;
+// ─── Driver Factory ───────────────────────────────────────────────────────
+/**
+ * Create a SQLiteDriver backed by @op-engineering/op-sqlite.
+ *
+ * @param config Optional driver configuration (encryption, hooks, etc.)
+ * @returns A SQLiteDriver that can be passed to SQLiteAdapter.
+ */
+function createOpSQLiteDriver(config) {
+    let db = null;
+    let opSQLite = null;
+    async function getOpSQLite() {
+        if (!opSQLite) {
+            try {
+                // @ts-expect-error — @op-engineering/op-sqlite is an optional peer dependency
+                opSQLite = (await Promise.resolve().then(() => __importStar(require('@op-engineering/op-sqlite'))));
+            }
+            catch {
+                throw new Error('@op-engineering/op-sqlite is not installed. Install it with:\n' +
+                    '  npm install @op-engineering/op-sqlite\n' +
+                    'Then rebuild your native app.');
+            }
+        }
+        return opSQLite;
+    }
+    function requireDb() {
+        if (!db) {
+            throw new Error('Database not open. Call open() first.');
+        }
+        return db;
+    }
+    return {
+        async open(name) {
+            const sqlite = await getOpSQLite();
+            const dbName = name.endsWith('.db') ? name : `${name}.db`;
+            const openOptions = { name: dbName };
+            if (config?.location) {
+                openOptions.location = config.location;
+            }
+            if (config?.encryptionKey) {
+                openOptions.encryptionKey = config.encryptionKey;
+            }
+            db = sqlite.open(openOptions);
+            // Enable WAL mode for better concurrent read performance
+            db.executeSync('PRAGMA journal_mode = WAL');
+            // Busy timeout for concurrent access
+            db.executeSync('PRAGMA busy_timeout = 5000');
+            // Install update hook if requested
+            if (config?.onTableChanged) {
+                const callback = config.onTableChanged;
+                db.updateHook(({ table, operation }) => {
+                    callback(table, operation);
+                });
+            }
+        },
+        async execute(sql, bindings) {
+            const database = requireDb();
+            await database.execute(sql, bindings);
+        },
+        async query(sql, bindings) {
+            const database = requireDb();
+            const result = await database.execute(sql, bindings);
+            return result.rows;
+        },
+        async executeInTransaction(fn) {
+            const database = requireDb();
+            await database.transaction(async (_tx) => {
+                // op-sqlite's transaction scopes all operations on the
+                // connection to the transaction, similar to expo-sqlite.
+                await fn();
+            });
+        },
+        async close() {
+            if (db) {
+                db.updateHook(null); // Remove hook before closing
+                db.close();
+                db = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=OpSQLiteDriver.js.map

package/dist/adapters/op-sqlite/index.d.ts

@@ -0,0 +1,2 @@
+export { createOpSQLiteDriver } from './OpSQLiteDriver';
+export type { OpSQLiteDriverConfig } from './OpSQLiteDriver';

package/dist/adapters/op-sqlite/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpSQLiteDriver = void 0;
+var OpSQLiteDriver_1 = require("./OpSQLiteDriver");
+Object.defineProperty(exports, "createOpSQLiteDriver", { enumerable: true, get: function () { return OpSQLiteDriver_1.createOpSQLiteDriver; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/sqlite/SQLiteAdapter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * SQLite Adapter.
+ *
+ * Implements the StorageAdapter interface using a SQL driver.
+ * The actual SQLite driver is injected — this adapter generates SQL
+ * and delegates execution, enabling different drivers for
+ * React Native (react-native-sqlite-storage) and web (sql.js).
+ *
+ * The driver interface is intentionally minimal so it can wrap
+ * any SQLite library.
+ */
+import type { StorageAdapter, AdapterConfig, EncryptionConfig, Migration } from '../types';
+import type { QueryDescriptor, SearchDescriptor, BatchOperation } from '../../query/types';
+import type { DatabaseSchema, RawRecord } from '../../schema/types';
+/**
+ * Minimal driver interface that wraps any SQLite library.
+ *
+ * Implementations:
+ *  - For React Native: wrap react-native-quick-sqlite or op-sqlite
+ *  - For Web: wrap sql.js
+ *  - For Node tests: wrap better-sqlite3
+ */
+export interface SQLiteDriver {
+    open(name: string): Promise<void>;
+    execute(sql: string, bindings?: unknown[]): Promise<void>;
+    query(sql: string, bindings?: unknown[]): Promise<Record<string, unknown>[]>;
+    executeInTransaction(fn: () => Promise<void>): Promise<void>;
+    close(): Promise<void>;
+}
+export interface SQLiteAdapterConfig extends AdapterConfig {
+    /** The SQLite driver to use. If not provided, a default will be selected. */
+    driver?: SQLiteDriver;
+    /** Optional encryption config */
+    encryption?: EncryptionConfig;
+}
+export declare class SQLiteAdapter implements StorageAdapter {
+    private _driver;
+    private _databaseName;
+    private _encryption?;
+    private _initialized;
+    constructor(config: SQLiteAdapterConfig);
+    initialize(schema: DatabaseSchema): Promise<void>;
+    find(query: QueryDescriptor): Promise<RawRecord[]>;
+    count(query: QueryDescriptor): Promise<number>;
+    findById(table: string, id: string): Promise<RawRecord | null>;
+    insert(table: string, raw: RawRecord): Promise<void>;
+    update(table: string, raw: RawRecord): Promise<void>;
+    markAsDeleted(table: string, id: string): Promise<void>;
+    destroyPermanently(table: string, id: string): Promise<void>;
+    batch(operations: BatchOperation[]): Promise<void>;
+    search(descriptor: SearchDescriptor): Promise<{
+        records: RawRecord[];
+        total: number;
+    }>;
+    getLocalChanges(tables: string[]): Promise<Record<string, {
+        created: RawRecord[];
+        updated: RawRecord[];
+        deleted: string[];
+    }>>;
+    applyRemoteChanges(changes: Record<string, {
+        created: RawRecord[];
+        updated: RawRecord[];
+        deleted: string[];
+    }>): Promise<void>;
+    markAsSynced(table: string, ids: string[]): Promise<void>;
+    getSchemaVersion(): Promise<number>;
+    migrate(migrations: Migration[]): Promise<void>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+}