pomegranate-db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present PomegranateDB contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,38 @@
+# NOTICE
+
+## Acknowledgements
+
+PomegranateDB was inspired by and developed with reference to
+[WatermelonDB](https://github.com/Nozbe/WatermelonDB) by Nozbe.
+
+Portions of this codebase were adapted from WatermelonDB's source code. Huge
+thanks to the WatermelonDB team for their pioneering work on reactive,
+offline-first databases for React Native and web applications.
+
+---
+
+## WatermelonDB License
+
+```
+MIT License
+
+Copyright (c) Nozbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/PomegranateDB.podspec

@@ -0,0 +1,67 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "PomegranateDB"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.description  = package["description"]
+  s.homepage     = "https://github.com/#{package.dig("repository", "url") || "bobbyquantum/pomegranate"}"
+  s.license      = { :type => "MIT", :file => "LICENSE" }
+  s.author       = { "bobbyquantum" => "" }
+  s.platforms    = { :ios => "13.0" }
+  s.source       = { :git => "https://github.com/bobbyquantum/pomegranate.git",
+                     :tag => "v#{s.version}" }
+
+  # ─── Source files ────────────────────────────────────────────────────────────
+  #
+  # iOS platform glue (Obj-C++ bridge + platform implementation)
+  # + shared C++ JSI core (Database.cpp/h, Sqlite.cpp/h)
+  #
+  # NOTE: We intentionally exclude native/shared/sqlite3/ here; iOS links the
+  # system SQLite via s.libraries below, so we must not compile the amalgamation
+  # twice.
+  s.source_files = [
+    "native/ios/**/*.{h,m,mm}",
+    "native/shared/*.{h,cpp}",
+  ]
+
+  s.public_header_files = [
+    "native/ios/PomegranateJSI.h",
+  ]
+
+  # ─── Compiler settings ───────────────────────────────────────────────────────
+
+  s.requires_arc = true
+
+  # Optimise for size/speed even in debug — JSI is noticeably slower without it.
+  s.compiler_flags = "-Os"
+
+  s.pod_target_xcconfig = {
+    # C++17 features (structured bindings, string_view, …)
+    "CLANG_CXX_LANGUAGE_STANDARD"         => "c++17",
+    "CLANG_CXX_LIBRARY"                   => "libc++",
+    # Find jsi/jsi.h from React Native's ReactCommon
+    "HEADER_SEARCH_PATHS"                 => [
+      '"$(PODS_ROOT)/Headers/Public/React-Core"',
+      '"$(PODS_ROOT)/Headers/Public"',
+      '"$(PODS_TARGET_SRCROOT)/native/shared"',
+      '"$(PODS_TARGET_SRCROOT)/native/ios"',
+    ].join(" "),
+    # Silence noise from mixing C and C++ TUs
+    "GCC_WARN_INHIBIT_ALL_WARNINGS"       => "NO",
+  }
+
+  # ─── System libraries ────────────────────────────────────────────────────────
+
+  # Link the iOS/macOS system SQLite (sqlite3.h is in the SDK, no amalgamation needed)
+  s.libraries = "sqlite3"
+
+  # ─── Dependencies ────────────────────────────────────────────────────────────
+
+  # React-Core brings in React-jsi transitively (as of RN 0.71+).
+  # Specifying React-jsi directly fails pod spec lint because it isn't in the
+  # public trunk — it resolves from the consuming app's node_modules at install time.
+  s.dependency "React-Core"
+end

package/README.md

@@ -0,0 +1,122 @@
+<p align="center">
+  <img src="docs-website/static/img/logo.png" alt="PomegranateDB" width="200" />
+</p>
+
+<h2 align="center">PomegranateDB</h2>
+
+<h4 align="center">
+  Reactive offline-first database for React Native & Expo
+</h4>
+
+<p align="center">
+  Build powerful React and React Native apps that scale from hundreds to tens of thousands of records and remain <em>fast</em> ⚡️
+</p>
+
+---
+
+### ⚡️ Instant Launch
+Lazy-loaded — only fetch data when you need it. Your app starts fast no matter how much data you have.
+
+### 📈 Highly Scalable
+Handle hundreds to tens of thousands of records with consistent performance.
+
+### 🔄 Offline-First
+Built-in sync protocol with push/pull reconciliation. Works offline, syncs when connected.
+
+### ⚛️ Optimized for React
+Reactive hooks keep your UI in sync automatically. Zero boilerplate subscriptions.
+
+### 🔌 Pluggable Adapters
+LokiJS, Expo SQLite, op-sqlite, or JSI C++. Swap storage backends without changing app code.
+
+### 🔐 Encryption at Rest
+Optional AES-GCM encryption or SQLCipher via op-sqlite. Protect user data on-device.
+
+---
+
+## Why PomegranateDB?
+
+- **Schema-first**: Define your models declaratively with full type inference
+- **Reactive queries**: UI updates automatically when data changes — via hooks or observables
+- **Offline-first sync**: Built-in pull/push protocol that works offline and reconciles on reconnect
+- **Pluggable adapters**: Choose the right storage backend for your app — LokiJS (in-memory), Expo SQLite, op-sqlite, or our own JSI C++ adapter
+- **TypeScript-native**: The whole codebase is idiomatic TypeScript. Types flow from schema to model to query to component
+
+## Quick Example
+
+```ts
+import { m, Model, Database, LokiAdapter } from 'pomegranate-db';
+
+// 1. Define your schema
+const PostSchema = m.model('posts', {
+  title: m.text(),
+  body: m.text(),
+  status: m.text(),
+  createdAt: m.date('created_at').readonly(),
+});
+
+// 2. Create a model class
+class Post extends Model<typeof PostSchema> {
+  static schema = PostSchema;
+}
+
+// 3. Initialize the database
+const db = new Database({
+  adapter: new LokiAdapter({ databaseName: 'myapp' }),
+  models: [Post],
+});
+
+await db.initialize();
+
+// 4. Write data
+await db.write(async () => {
+  await db.get(Post).create({
+    title: 'Hello World',
+    body: 'My first post',
+    status: 'draft',
+  });
+});
+
+// 5. Query data
+const posts = await db.get(Post)
+  .query()
+  .where('status', 'draft')
+  .fetch();
+```
+
+## React Integration
+
+```tsx
+import { DatabaseProvider, useLiveQuery } from 'pomegranate-db';
+
+function App() {
+  return (
+    <DatabaseProvider value={db}>
+      <PostList />
+    </DatabaseProvider>
+  );
+}
+
+function PostList() {
+  const { results: posts, isLoading } = useLiveQuery(Post, (q) =>
+    q.where('status', 'eq', 'published').orderBy('created_at', 'desc'),
+  );
+
+  if (isLoading) return <Text>Loading...</Text>;
+
+  return posts.map((post) => (
+    <Text key={post.id}>{post.title}</Text>
+  ));
+}
+```
+
+## 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
+
+## License
+
+MIT

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

@@ -0,0 +1,34 @@
+/**
+ * Expo SQLite Driver.
+ *
+ * Implements the SQLiteDriver interface using expo-sqlite (v14+).
+ * This enables PomegranateDB to work seamlessly in Expo projects
+ * using the Expo managed SQLite library instead of requiring
+ * react-native-quick-sqlite or op-sqlite.
+ *
+ * Usage:
+ *   import { createExpoSQLiteDriver } from 'pomegranate-db/expo';
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createExpoSQLiteDriver(),
+ *   });
+ */
+import type { SQLiteDriver } from '../sqlite/SQLiteAdapter';
+export interface ExpoSQLiteDriverConfig {
+    /**
+     * Options passed to expo-sqlite's openDatabaseAsync.
+     * @default {}
+     */
+    openOptions?: {
+        enableChangeListener?: boolean;
+    };
+}
+/**
+ * Create a SQLiteDriver backed by expo-sqlite.
+ *
+ * expo-sqlite must be installed in the consuming project:
+ *   npx expo install expo-sqlite
+ */
+export declare function createExpoSQLiteDriver(config?: ExpoSQLiteDriverConfig): SQLiteDriver;

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

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Expo SQLite Driver.
+ *
+ * Implements the SQLiteDriver interface using expo-sqlite (v14+).
+ * This enables PomegranateDB to work seamlessly in Expo projects
+ * using the Expo managed SQLite library instead of requiring
+ * react-native-quick-sqlite or op-sqlite.
+ *
+ * Usage:
+ *   import { createExpoSQLiteDriver } from 'pomegranate-db/expo';
+ *   import { SQLiteAdapter } from 'pomegranate-db';
+ *
+ *   const adapter = new SQLiteAdapter({
+ *     databaseName: 'myapp',
+ *     driver: createExpoSQLiteDriver(),
+ *   });
+ */
+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.createExpoSQLiteDriver = createExpoSQLiteDriver;
+/**
+ * Create a SQLiteDriver backed by expo-sqlite.
+ *
+ * expo-sqlite must be installed in the consuming project:
+ *   npx expo install expo-sqlite
+ */
+function createExpoSQLiteDriver(config) {
+    let db = null;
+    let expoSQLite = null;
+    // Lazily import expo-sqlite so this module can be imported
+    // without expo-sqlite being installed (e.g. in tests).
+    async function getExpoSQLite() {
+        if (!expoSQLite) {
+            try {
+                // @ts-expect-error — expo-sqlite is an optional peer dependency
+                expoSQLite = (await Promise.resolve().then(() => __importStar(require('expo-sqlite'))));
+            }
+            catch {
+                throw new Error('expo-sqlite is not installed. Install it with: npx expo install expo-sqlite');
+            }
+        }
+        return expoSQLite;
+    }
+    function requireDb() {
+        if (!db) {
+            throw new Error('Database not open. Call open() first.');
+        }
+        return db;
+    }
+    return {
+        async open(name) {
+            const sqlite = await getExpoSQLite();
+            db = await sqlite.openDatabaseAsync(name.endsWith('.db') ? name : `${name}.db`, config?.openOptions);
+            // Enable WAL mode for better performance (may not be supported on web/wa-sqlite)
+            try {
+                await db.execAsync('PRAGMA journal_mode = WAL');
+            }
+            catch {
+                // WAL not supported on this platform (e.g. web wa-sqlite), continue without it
+            }
+        },
+        async execute(sql, bindings) {
+            const database = requireDb();
+            if (bindings && bindings.length > 0) {
+                await database.runAsync(sql, ...bindings);
+            }
+            else {
+                await database.execAsync(sql);
+            }
+        },
+        async query(sql, bindings) {
+            const database = requireDb();
+            if (bindings && bindings.length > 0) {
+                return database.getAllAsync(sql, ...bindings);
+            }
+            return database.getAllAsync(sql);
+        },
+        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.
+            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')) {
+                        // Fall through to manual transaction below
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            // Manual transaction fallback (web, or platforms without exclusive transactions)
+            await database.execAsync('BEGIN TRANSACTION');
+            try {
+                await fn();
+                await database.execAsync('COMMIT');
+            }
+            catch (e) {
+                await database.execAsync('ROLLBACK');
+                throw e;
+            }
+        },
+        async close() {
+            if (db) {
+                await db.closeAsync();
+                db = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=ExpoSQLiteDriver.js.map

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

@@ -0,0 +1,2 @@
+export { createExpoSQLiteDriver } from './ExpoSQLiteDriver';
+export type { ExpoSQLiteDriverConfig } from './ExpoSQLiteDriver';

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

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

package/dist/adapters/index.d.ts

@@ -0,0 +1,7 @@
+export type { StorageAdapter, AdapterConfig, EncryptionConfig, Migration, MigrationStep, } from './types';
+export { SQLiteAdapter } from './sqlite';
+export type { SQLiteAdapterConfig, SQLiteDriver } from './sqlite';
+export { LokiAdapter, LokiExecutor, LokiDispatcher, SynchronousWorker } from './loki';
+export type { LokiAdapterConfig, LokiExecutorConfig, WorkerInterface } from './loki';
+export { createExpoSQLiteDriver } from './expo-sqlite';
+export type { ExpoSQLiteDriverConfig } from './expo-sqlite';

package/dist/adapters/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpoSQLiteDriver = exports.SynchronousWorker = exports.LokiDispatcher = exports.LokiExecutor = exports.LokiAdapter = exports.SQLiteAdapter = void 0;
+var sqlite_1 = require("./sqlite");
+Object.defineProperty(exports, "SQLiteAdapter", { enumerable: true, get: function () { return sqlite_1.SQLiteAdapter; } });
+var loki_1 = require("./loki");
+Object.defineProperty(exports, "LokiAdapter", { enumerable: true, get: function () { return loki_1.LokiAdapter; } });
+Object.defineProperty(exports, "LokiExecutor", { enumerable: true, get: function () { return loki_1.LokiExecutor; } });
+Object.defineProperty(exports, "LokiDispatcher", { enumerable: true, get: function () { return loki_1.LokiDispatcher; } });
+Object.defineProperty(exports, "SynchronousWorker", { enumerable: true, get: function () { return loki_1.SynchronousWorker; } });
+var expo_sqlite_1 = require("./expo-sqlite");
+Object.defineProperty(exports, "createExpoSQLiteDriver", { enumerable: true, get: function () { return expo_sqlite_1.createExpoSQLiteDriver; } });
+//# sourceMappingURL=index.js.map

package/dist/adapters/loki/LokiAdapter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * LokiJS Adapter.
+ *
+ * In-memory database adapter using LokiJS, suitable for web and testing.
+ * Supports running LokiJS in a Web Worker for better UI performance.
+ *
+ * Architecture:
+ * - Direct mode (default): LokiExecutor runs in the main thread.
+ * - Worker mode: All operations are dispatched via postMessage to a Web Worker
+ *   (or SynchronousWorker for testing) that runs LokiExecutor internally.
+ *
+ * ```
+ * LokiAdapter  ──▶  LokiExecutor (direct mode)
+ *       │
+ *       └──▶  LokiDispatcher  ──▶  [Worker]  ──▶  LokiExecutor (worker mode)
+ * ```
+ */
+import type { StorageAdapter, AdapterConfig, Migration } from '../types';
+import type { QueryDescriptor, SearchDescriptor, BatchOperation } from '../../query/types';
+import type { DatabaseSchema, RawRecord } from '../../schema/types';
+import type { WorkerInterface } from './worker/types';
+export interface LokiAdapterConfig extends AdapterConfig {
+    /** Optional: provide your own Loki instance (direct mode only, not serializable). */
+    lokiInstance?: unknown;
+    /** Optional: LokiJS persistence adapter (e.g., IncrementalIndexedDBAdapter). Direct mode only. */
+    persistenceAdapter?: unknown;
+    /**
+     * When to persist data to storage. Only applies when `persistenceAdapter` is set
+     * (direct mode) or when running in a worker (which auto-creates IndexedDB persistence).
+     *
+     * - `'immediate'` — save after every mutation. Safest; data survives instant refresh.
+     *   Slightly slower for rapid writes. **(default)**
+     * - `'auto'` — use LokiJS autosave timer (`autosaveInterval` ms). Faster for bulk
+     *   writes but data written in the last interval may be lost on hard refresh.
+     */
+    saveStrategy?: 'immediate' | 'auto';
+    /** Autosave interval in ms when `saveStrategy: 'auto'`. Default: 500. */
+    autosaveInterval?: number;
+    /**
+     * Web Worker instance for off-main-thread LokiJS execution.
+     * When provided, all database operations dispatch to this worker via postMessage.
+     * The worker auto-creates IncrementalIDBAdapter for IndexedDB persistence.
+     *
+     * @example
+     * // Real Web Worker (bundler must support worker URLs):
+     * import { LokiAdapter } from 'pomegranate-db';
+     * const worker = new Worker(
+     *   new URL('pomegranate-db/dist/adapters/loki/worker/loki.worker.js', import.meta.url),
+     * );
+     * const adapter = new LokiAdapter({ databaseName: 'app', worker });
+     *
+     * @example
+     * // Synchronous fallback (for testing the worker protocol):
+     * import { LokiAdapter, SynchronousWorker } from 'pomegranate-db';
+     * const adapter = new LokiAdapter({ databaseName: 'test', worker: new SynchronousWorker() });
+     */
+    worker?: WorkerInterface | Worker;
+}
+export declare class LokiAdapter implements StorageAdapter {
+    private _executor;
+    private _dispatcher;
+    private _config;
+    private _initialized;
+    constructor(config: LokiAdapterConfig);
+    initialize(schema: DatabaseSchema): Promise<void>;
+    /**
+     * Route a command to either the local executor or the remote worker.
+     * In worker mode, arguments are serialized via postMessage (structured cloning).
+     * In direct mode, the executor method is called directly.
+     */
+    private _call;
+    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>;
+}
+export { type LokiExecutorConfig } from './worker/LokiExecutor';