pomegranate-db 0.1.0

package/dist/sync/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Sync types — compatible with the Watermelon backend sync protocol.
+ */
+import type { RawRecord } from '../schema/types';
+export interface SyncPullResult {
+    /** Changes from the server, grouped by table */
+    changes: SyncTableChanges;
+    /** Server timestamp of this pull */
+    timestamp: number;
+}
+/** Changes for all tables */
+export type SyncTableChanges = Record<string, SyncTableChangeSet>;
+/** Changes for a single table */
+export interface SyncTableChangeSet {
+    created: RawRecord[];
+    updated: RawRecord[];
+    deleted: string[];
+}
+export interface SyncPushPayload {
+    changes: SyncTableChanges;
+    lastPulledAt: number;
+}
+export interface SyncConfig {
+    pullChanges: (params: {
+        lastPulledAt: number | null;
+    }) => Promise<SyncPullResult>;
+    pushChanges: (params: SyncPushPayload) => Promise<void>;
+    /** Optional: called when sync encounters a conflict */
+    onConflict?: (local: RawRecord, remote: RawRecord) => RawRecord;
+    /** Optional: tables to sync. If not specified, all tables are synced. */
+    tables?: string[];
+}
+export type SyncState = 'idle' | 'pulling' | 'pushing' | 'applying' | 'complete' | 'error';
+export interface SyncLog {
+    startedAt: number;
+    finishedAt?: number;
+    state: SyncState;
+    pullTimestamp?: number;
+    pushedTables?: string[];
+    error?: string;
+}

package/dist/sync/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Sync types — compatible with the Watermelon backend sync protocol.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/utils/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Utility functions: ID generation, timestamps, etc.
+ */
+/**
+ * Generate a unique ID suitable for record primary keys.
+ * Uses a combination of timestamp + random to avoid collisions.
+ * In production, you'd swap this for a proper UUID or CUID generator.
+ */
+export declare function generateId(): string;
+/**
+ * Current timestamp in milliseconds (epoch).
+ */
+export declare function now(): number;
+/**
+ * Sanitize a table name to prevent injection.
+ */
+export declare function sanitizeTableName(name: string): string;
+/**
+ * Sanitize a column name to prevent injection.
+ */
+export declare function sanitizeColumnName(name: string): string;
+/**
+ * Convert a Date to epoch ms for storage.
+ */
+export declare function dateToTimestamp(date: Date | number | null): number | null;
+/**
+ * Convert epoch ms back to a Date.
+ */
+export declare function timestampToDate(ts: number | null): Date | null;
+/**
+ * Simple deep-freeze for objects (one level).
+ */
+export declare function freeze<T extends object>(obj: T): Readonly<T>;
+/**
+ * Invariant — throws if condition is falsy.
+ */
+export declare function invariant(condition: unknown, message: string): asserts condition;
+/**
+ * Logger (can be swapped out).
+ */
+export declare const logger: {
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+};

package/dist/utils/index.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Utility functions: ID generation, timestamps, etc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+exports.generateId = generateId;
+exports.now = now;
+exports.sanitizeTableName = sanitizeTableName;
+exports.sanitizeColumnName = sanitizeColumnName;
+exports.dateToTimestamp = dateToTimestamp;
+exports.timestampToDate = timestampToDate;
+exports.freeze = freeze;
+exports.invariant = invariant;
+let _idCounter = 0;
+/**
+ * Generate a unique ID suitable for record primary keys.
+ * Uses a combination of timestamp + random to avoid collisions.
+ * In production, you'd swap this for a proper UUID or CUID generator.
+ */
+function generateId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 10);
+    const counter = (_idCounter++).toString(36);
+    return `${timestamp}${random}${counter}`;
+}
+/**
+ * Current timestamp in milliseconds (epoch).
+ */
+function now() {
+    return Date.now();
+}
+/**
+ * Sanitize a table name to prevent injection.
+ */
+function sanitizeTableName(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid table name: "${name}"`);
+    }
+    return name;
+}
+/**
+ * Sanitize a column name to prevent injection.
+ */
+function sanitizeColumnName(name) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+        throw new Error(`Invalid column name: "${name}"`);
+    }
+    return name;
+}
+/**
+ * Convert a Date to epoch ms for storage.
+ */
+function dateToTimestamp(date) {
+    if (date === null)
+        return null;
+    if (typeof date === 'number')
+        return date;
+    return date.getTime();
+}
+/**
+ * Convert epoch ms back to a Date.
+ */
+function timestampToDate(ts) {
+    if (ts === null)
+        return null;
+    return new Date(ts);
+}
+/**
+ * Simple deep-freeze for objects (one level).
+ */
+function freeze(obj) {
+    return Object.freeze(obj);
+}
+/**
+ * Invariant — throws if condition is falsy.
+ */
+function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(`Invariant violation: ${message}`);
+    }
+}
+/**
+ * Logger (can be swapped out).
+ */
+exports.logger = {
+    warn(msg, ...args) {
+        console.warn(`[PomegranateDB] ${msg}`, ...args);
+    },
+    error(msg, ...args) {
+        console.error(`[PomegranateDB] ${msg}`, ...args);
+    },
+    debug(msg, ...args) {
+        if (process.env.NODE_ENV === 'development') {
+            console.debug(`[PomegranateDB] ${msg}`, ...args);
+        }
+    },
+};
+//# sourceMappingURL=index.js.map

package/expo-plugin/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * PomegranateDB Expo Config Plugin.
+ *
+ * Provides first-class Expo support by configuring the native
+ * projects for optimal SQLite performance.
+ *
+ * Usage in app.json / app.config.js:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         "pomegranate-db/expo-plugin"
+ *       ]
+ *     }
+ *   }
+ *
+ * Or with options:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         ["pomegranate-db/expo-plugin", {
+ *           "enableFTS": true,
+ *           "useSQLCipher": false
+ *         }]
+ *       ]
+ *     }
+ *   }
+ *
+ * This plugin:
+ *  - Ensures expo-sqlite is configured with FTS support (optional)
+ *  - Adds iOS/Android build settings for SQLite performance
+ *  - Configures ProGuard rules for Android release builds
+ */
+interface PomegranatePluginConfig {
+    /**
+     * Enable SQLite FTS3, FTS4 and FTS5 full-text search extensions.
+     * Required if you use PomegranateDB's search() functionality with
+     * the SQLiteAdapter + ExpoSQLiteDriver.
+     * @default true
+     */
+    enableFTS?: boolean;
+    /**
+     * Use SQLCipher for encrypted database support.
+     * When true, the database file is encrypted at rest.
+     * @default false
+     */
+    useSQLCipher?: boolean;
+    /**
+     * Custom SQLite compile flags.
+     * Passed directly to expo-sqlite's config plugin.
+     */
+    customBuildFlags?: string;
+}
+type ExpoConfig = {
+    name: string;
+    slug: string;
+    plugins?: (string | [string, Record<string, unknown>])[];
+    [key: string]: unknown;
+};
+/**
+ * Expo config plugin for PomegranateDB.
+ *
+ * Automatically configures expo-sqlite with the right build flags
+ * for PomegranateDB features (FTS, encryption, etc.).
+ */
+declare function withPomegranateDB(config: ExpoConfig, pluginConfig?: PomegranatePluginConfig): ExpoConfig;
+export default withPomegranateDB;

package/expo-plugin/index.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * PomegranateDB Expo Config Plugin.
+ *
+ * Provides first-class Expo support by configuring the native
+ * projects for optimal SQLite performance.
+ *
+ * Usage in app.json / app.config.js:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         "pomegranate-db/expo-plugin"
+ *       ]
+ *     }
+ *   }
+ *
+ * Or with options:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         ["pomegranate-db/expo-plugin", {
+ *           "enableFTS": true,
+ *           "useSQLCipher": false
+ *         }]
+ *       ]
+ *     }
+ *   }
+ *
+ * This plugin:
+ *  - Ensures expo-sqlite is configured with FTS support (optional)
+ *  - Adds iOS/Android build settings for SQLite performance
+ *  - Configures ProGuard rules for Android release builds
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Expo config plugin for PomegranateDB.
+ *
+ * Automatically configures expo-sqlite with the right build flags
+ * for PomegranateDB features (FTS, encryption, etc.).
+ */
+function withPomegranateDB(config, pluginConfig = {}) {
+    const { enableFTS = true, useSQLCipher = false, customBuildFlags, } = pluginConfig;
+    // Build the expo-sqlite plugin config
+    const expoSQLiteConfig = {
+        enableFTS,
+        useSQLCipher,
+    };
+    if (customBuildFlags) {
+        expoSQLiteConfig.ios = { customBuildFlags };
+    }
+    // Check if expo-sqlite plugin already exists
+    const plugins = config.plugins || [];
+    const existingIndex = plugins.findIndex((p) => {
+        if (typeof p === 'string')
+            return p === 'expo-sqlite';
+        if (Array.isArray(p))
+            return p[0] === 'expo-sqlite';
+        return false;
+    });
+    if (existingIndex >= 0) {
+        // Merge our config with existing expo-sqlite config
+        const existing = plugins[existingIndex];
+        if (typeof existing === 'string') {
+            plugins[existingIndex] = ['expo-sqlite', expoSQLiteConfig];
+        }
+        else if (Array.isArray(existing)) {
+            plugins[existingIndex] = [
+                'expo-sqlite',
+                { ...(existing[1] || {}), ...expoSQLiteConfig },
+            ];
+        }
+    }
+    else {
+        // Add expo-sqlite plugin
+        plugins.push(['expo-sqlite', expoSQLiteConfig]);
+    }
+    config.plugins = plugins;
+    return config;
+}
+module.exports = withPomegranateDB;
+exports.default = withPomegranateDB;

package/native/android-jsi/build.gradle

@@ -0,0 +1,45 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def DEFAULT_COMPILE_SDK_VERSION = 36
+def DEFAULT_MIN_SDK_VERSION = 24
+def DEFAULT_TARGET_SDK_VERSION = 36
+def DEFAULT_NDK_VERSION = "27.1.12297006"
+
+android {
+    compileSdkVersion rootProject.hasProperty('compileSdkVersion') ? rootProject.compileSdkVersion : DEFAULT_COMPILE_SDK_VERSION
+    ndkVersion rootProject.hasProperty('ndkVersion') ? rootProject.ndkVersion : DEFAULT_NDK_VERSION
+
+    namespace "com.pomegranate.jsi"
+
+    defaultConfig {
+        minSdkVersion rootProject.hasProperty('minSdkVersion') ? rootProject.minSdkVersion : DEFAULT_MIN_SDK_VERSION
+        targetSdkVersion rootProject.hasProperty('targetSdkVersion') ? rootProject.targetSdkVersion : DEFAULT_TARGET_SDK_VERSION
+        versionCode 1
+        versionName "1.0"
+        externalNativeBuild {
+            cmake {
+                // Use C++17 for structured bindings, string_view, etc.
+                cppFlags "-std=c++17"
+            }
+        }
+    }
+    externalNativeBuild {
+        cmake {
+            path "src/main/cpp/CMakeLists.txt"
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-native:+'
+}

package/native/android-jsi/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest />

package/native/android-jsi/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,73 @@
+PROJECT(pomegranate-jsi C CXX)
+cmake_minimum_required(VERSION 3.13)
+
+# ─── Path resolution ──────────────────────────────────────────────────────────
+# This CMakeLists.txt lives at:
+#   native/android-jsi/src/main/cpp/CMakeLists.txt          (dev / source repo)
+#   node_modules/pomegranate-db/native/android-jsi/src/main/cpp/  (installed)
+#
+# In dev:       5 levels up  → repo root  → node_modules/react-native
+# In installed: 7 levels up  → consumer app root → node_modules/react-native
+
+set(SHARED_PATH ../../../../shared/)
+set(SQLITE_PATH ../../../../shared/sqlite3/)
+
+# Auto-detect react-native location (dev vs installed-in-node_modules)
+foreach(candidate
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules/react-native"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../../node_modules/react-native"
+)
+  if(EXISTS "${candidate}/ReactCommon/jsi/jsi/jsi.h")
+    set(REACT_NATIVE_ROOT "${candidate}")
+    break()
+  endif()
+endforeach()
+
+if(NOT REACT_NATIVE_ROOT)
+  message(FATAL_ERROR
+    "pomegranate-jsi: Cannot find react-native.\n"
+    "Looked at 5 and 7 parent directories from ${CMAKE_CURRENT_SOURCE_DIR}.\n"
+    "Ensure react-native is installed in your project's node_modules.")
+endif()
+
+message(STATUS "pomegranate-jsi: react-native found at ${REACT_NATIVE_ROOT}")
+
+# ─── Header search paths ─────────────────────────────────────────────────────
+
+include_directories(
+        ${SHARED_PATH}
+        ${SQLITE_PATH}
+        ${REACT_NATIVE_ROOT}/React
+        ${REACT_NATIVE_ROOT}/React/Base
+        ${REACT_NATIVE_ROOT}/ReactCommon
+        ${REACT_NATIVE_ROOT}/ReactCommon/jsi
+)
+
+# ─── Build configuration ─────────────────────────────────────────────────────
+
+set(CMAKE_CXX_FLAGS_DEBUG "-O2")
+set(CMAKE_CXX_FLAGS_RELEASE "-O2")
+
+# ─── Source files ─────────────────────────────────────────────────────────────
+
+file(GLOB ANDROID_JSI_SRC_FILES ./*.cpp)
+file(GLOB SHARED_SRC_FILES ${SHARED_PATH}/*.cpp)
+
+add_library(pomegranate-jsi SHARED
+        # SQLite amalgamation
+        ${SQLITE_PATH}/sqlite3.c
+        # Our shared C++ sources
+        ${SHARED_SRC_FILES}
+        # Android-specific JNI sources
+        ${ANDROID_JSI_SRC_FILES}
+        # JSI implementation (needed for linking)
+        ${REACT_NATIVE_ROOT}/ReactCommon/jsi/jsi/jsi.cpp
+)
+
+# Enable Android 16kb native library alignment (required for modern Android)
+target_link_options(pomegranate-jsi PRIVATE "-Wl,-z,max-page-size=16384")
+
+target_link_libraries(pomegranate-jsi
+        android
+        log
+)

package/native/android-jsi/src/main/cpp/DatabasePlatformAndroid.cpp

@@ -0,0 +1,107 @@
+/**
+ * PomegranateDB — Android platform implementation.
+ *
+ * Provides platform::resolveDatabasePath via JNI callback to Java,
+ * and platform::consoleLog/consoleError via Android log.
+ */
+
+#include <android/log.h>
+#include <cassert>
+#include <mutex>
+#include <sqlite3.h>
+
+#include "Database.h"
+#include "DatabasePlatformAndroid.h"
+
+#define LOG_TAG "pomegranate.jsi"
+
+namespace pomegranate {
+namespace platform {
+
+// ─── Logging ─────────────────────────────────────────────────────────────────
+
+void consoleLog(const std::string &message) {
+    __android_log_print(ANDROID_LOG_INFO, LOG_TAG, "%s\n", message.c_str());
+}
+
+void consoleError(const std::string &message) {
+    __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, "%s\n", message.c_str());
+}
+
+// ─── SQLite initialization ───────────────────────────────────────────────────
+
+static void sqliteLogCallback(void *, int err, const char *message) {
+    int errType = err & 255;
+    if (errType == SQLITE_WARNING) {
+        __android_log_print(ANDROID_LOG_WARN, LOG_TAG, "sqlite (%d) %s\n", err, message);
+    } else if (errType == 0 || errType == SQLITE_CONSTRAINT || errType == SQLITE_SCHEMA || errType == SQLITE_NOTICE) {
+        // verbose, skip
+    } else {
+        __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, "sqlite (%d) %s\n", err, message);
+    }
+}
+
+std::once_flag sqliteInitFlag;
+
+static void initializeSqlite() {
+    std::call_once(sqliteInitFlag, []() {
+        sqlite3_config(SQLITE_CONFIG_LOG, &sqliteLogCallback, nullptr);
+        sqlite3_soft_heap_limit(8 * 1024 * 1024);
+        sqlite3_initialize();
+    });
+}
+
+// ─── JNI path resolution ────────────────────────────────────────────────────
+
+static JavaVM *jvm = nullptr;
+
+void configureJNI(JNIEnv *env) {
+    assert(env);
+    if (env->GetJavaVM(&jvm) != JNI_OK) {
+        consoleError("PomegranateDB: cannot get JavaVM");
+        std::abort();
+    }
+    assert(jvm);
+    initializeSqlite();
+}
+
+std::string resolveDatabasePath(const std::string &dbName) {
+    JNIEnv *env;
+    assert(jvm);
+    if (jvm->AttachCurrentThread(&env, nullptr) != JNI_OK) {
+        throw std::runtime_error("PomegranateDB: JVM thread attach failed");
+    }
+    assert(env);
+
+    jclass clazz = env->FindClass("com/pomegranate/jsi/JSIInstaller");
+    if (clazz == nullptr) {
+        throw std::runtime_error("PomegranateDB: missing JSIInstaller class");
+    }
+
+    jmethodID mid = env->GetStaticMethodID(clazz, "_resolveDatabasePath", "(Ljava/lang/String;)Ljava/lang/String;");
+    if (mid == nullptr) {
+        throw std::runtime_error("PomegranateDB: missing _resolveDatabasePath method");
+    }
+
+    jobject jniPath = env->NewStringUTF(dbName.c_str());
+    if (jniPath == nullptr) {
+        throw std::runtime_error("PomegranateDB: could not construct Java string");
+    }
+
+    jstring jniResolvedPath = (jstring)env->CallStaticObjectMethod(clazz, mid, jniPath);
+    if (env->ExceptionCheck()) {
+        throw std::runtime_error("PomegranateDB: exception resolving database path");
+    }
+
+    const char *cResolvedPath = env->GetStringUTFChars(jniResolvedPath, 0);
+    if (cResolvedPath == nullptr) {
+        throw std::runtime_error("PomegranateDB: failed to get resolved path string");
+    }
+
+    std::string resolvedPath(cResolvedPath);
+    env->ReleaseStringUTFChars(jniResolvedPath, cResolvedPath);
+    return resolvedPath;
+}
+
+}  // namespace platform
+}  // namespace pomegranate

package/native/android-jsi/src/main/cpp/DatabasePlatformAndroid.h

@@ -0,0 +1,16 @@
+/**
+ * PomegranateDB — Android platform declarations.
+ */
+
+#pragma once
+
+#include <jni.h>
+
+namespace pomegranate {
+namespace platform {
+
+/** Must be called once from JNI before any database operations. */
+void configureJNI(JNIEnv *env);
+
+}  // namespace platform
+}  // namespace pomegranate

package/native/android-jsi/src/main/cpp/JSIInstaller.cpp

@@ -0,0 +1,27 @@
+/**
+ * PomegranateDB — JNI bridge.
+ *
+ * Called from Java to install the JSI binding into the JS runtime.
+ */
+
+#include <jni.h>
+#include <jsi/jsi.h>
+#include <cassert>
+
+#include "Database.h"
+#include "DatabasePlatformAndroid.h"
+
+using namespace facebook;
+
+extern "C" JNIEXPORT void JNICALL Java_com_pomegranate_jsi_JSIInstaller_installBinding(JNIEnv *env, jobject thiz,
+                                                                                       jlong runtimePtr) {
+    jsi::Runtime *runtime = reinterpret_cast<jsi::Runtime *>(runtimePtr);
+    assert(runtime != nullptr);
+
+    pomegranate::platform::configureJNI(env);
+    pomegranate::Database::install(*runtime);
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_pomegranate_jsi_JSIInstaller_destroy(JNIEnv *env, jclass clazz) {
+    // Cleanup if needed in future
+}

package/native/android-jsi/src/main/java/com/pomegranate/jsi/JSIInstaller.kt

@@ -0,0 +1,43 @@
+package com.pomegranate.jsi
+
+import android.content.Context
+
+/**
+ * JNI bridge between Kotlin and C++ JSI binding.
+ * Loads the native library and installs the JSI global function.
+ */
+internal object JSIInstaller {
+    private var context: Context? = null
+
+    init {
+        System.loadLibrary("pomegranate-jsi")
+    }
+
+    fun install(
+        context: Context,
+        javaScriptContextHolder: Long,
+    ) {
+        this.context = context
+        installBinding(javaScriptContextHolder)
+        // Call _resolveDatabasePath to prevent ProGuard/R8 from stripping it
+        _resolveDatabasePath("")
+    }
+
+    /**
+     * Called from C++ to resolve a database name to an absolute path.
+     */
+    @Suppress("FunctionName") // JNI naming convention
+    @JvmStatic
+    fun _resolveDatabasePath(dbName: String): String {
+        // On some systems there is a lock on /databases folder
+        return context!!
+            .getDatabasePath("$dbName.db")
+            .path
+            .replace("/databases", "")
+    }
+
+    private external fun installBinding(javaScriptContextHolder: Long)
+
+    @JvmStatic
+    external fun destroy()
+}