@tursodatabase/sync-react-native 0.5.0-pre.4

package/README.md

@@ -0,0 +1,117 @@
+# Turso Sync React Native SDK
+
+React Native bindings for Turso embedded replicas - sync your local SQLite database with Turso cloud.
+
+## Installation
+
+```bash
+npm install @tursodatabase/sync-react-native
+```
+
+### iOS
+
+```bash
+cd ios && pod install
+```
+
+### Android
+
+Requires `minSdkVersion` 21+ in `android/build.gradle`.
+
+## Quick Start
+
+```typescript
+import { Database, getDbPath } from '@tursodatabase/sync-react-native';
+
+// Get platform-specific writable path
+const dbPath = getDbPath('myapp.db');
+
+// Create database with sync
+const db = new Database({
+  path: dbPath,
+  url: 'libsql://your-db.turso.io',
+  authToken: 'your-auth-token',
+});
+
+// Connect (bootstraps from remote if empty)
+await db.connect();
+
+// Query local replica (fast)
+const users = await db.all('SELECT * FROM users');
+
+// Make local changes
+await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+
+// Sync with remote
+await db.push();  // Push local changes
+await db.pull();  // Pull remote changes
+
+// Close when done
+await db.close();
+```
+
+## Local-Only Database
+
+```typescript
+const db = new Database({ path: getDbPath('local.db') });
+await db.connect();
+
+await db.exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
+await db.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
+const user = await db.get('SELECT * FROM users WHERE id = ?', [1]);
+
+await db.close();
+```
+
+## Encrypted Remote Database
+
+```typescript
+const db = new Database({
+  path: getDbPath('encrypted.db'),
+  url: 'libsql://your-db.turso.io',
+  authToken: 'your-auth-token',
+  remoteEncryption: {
+    cipher: 'aes256gcm',
+    key: 'base64-encoded-key',
+  },
+});
+```
+
+## API
+
+### Database Methods
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Open/bootstrap the database |
+| `exec(sql)` | Execute SQL (no results) |
+| `run(sql, params?)` | Execute SQL, return `{ changes, lastInsertRowid }` |
+| `get(sql, params?)` | Query single row |
+| `all(sql, params?)` | Query all rows |
+| `prepare(sql)` | Create prepared statement |
+| `close()` | Close database |
+
+### Sync Methods (when `url` is provided)
+
+| Method | Description |
+|--------|-------------|
+| `push()` | Push local changes to remote |
+| `pull()` | Pull remote changes to local |
+| `sync()` | Push then pull |
+| `stats()` | Get sync statistics |
+
+### Transactions
+
+```typescript
+await db.transaction(async () => {
+  await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
+  await db.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
+  // Commits on success, rolls back on error
+});
+```
+
+## Links
+
+- [Turso Documentation](https://docs.turso.tech)
+- [GitHub](https://github.com/tursodatabase/turso)
+- [npm](https://www.npmjs.com/package/@tursodatabase/sync-react-native)

package/android/CMakeLists.txt

@@ -0,0 +1,53 @@
+cmake_minimum_required(VERSION 3.22)
+project(turso-sync-react-native)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Find packages
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+# Source files
+set(TURSO_SOURCES
+    cpp-adapter.cpp
+    ../cpp/TursoHostObject.cpp
+    ../cpp/TursoDatabaseHostObject.cpp
+    ../cpp/TursoConnectionHostObject.cpp
+    ../cpp/TursoStatementHostObject.cpp
+    ../cpp/TursoSyncDatabaseHostObject.cpp
+    ../cpp/TursoSyncOperationHostObject.cpp
+    ../cpp/TursoSyncIoItemHostObject.cpp
+    ../cpp/TursoSyncChangesHostObject.cpp
+)
+
+# Create shared library
+add_library(${PROJECT_NAME} SHARED ${TURSO_SOURCES})
+
+# 16KB page alignment for Android 15+ compatibility
+target_link_options(${PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")
+
+# Include directories
+target_include_directories(${PROJECT_NAME} PRIVATE
+    ../cpp
+    ../libs/android
+)
+
+# Pre-built Rust shared library (.so) loaded at runtime
+add_library(turso_sync_sdk_kit SHARED IMPORTED)
+
+# IMPORTED_NO_SONAME is important to properly adjust import paths for runtime by linker (so they will not be reused from build time)
+set_target_properties(turso_sync_sdk_kit PROPERTIES
+    IMPORTED_LOCATION ${CMAKE_SOURCE_DIR}/../libs/android/${ANDROID_ABI}/libturso_sync_sdk_kit.so
+    IMPORTED_NO_SONAME TRUE
+)
+
+# Link libraries (record runtime dependency on Rust .so)
+target_link_libraries(${PROJECT_NAME}
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    fbjni::fbjni
+    turso_sync_sdk_kit
+    android
+    log
+)

package/android/build.gradle

@@ -0,0 +1,84 @@
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath "com.android.tools.build:gradle:8.2.0"
+    }
+}
+
+plugins {
+    id "com.android.library"
+}
+
+def reactNativeArchitectures() {
+    def value = project.getProperties().get("reactNativeArchitectures")
+    return value ? value.split(",") : ["armeabi-v7a", "arm64-v8a", "x86", "x86_64"]
+}
+
+android {
+    namespace "com.turso.sync.reactnative"
+    compileSdk 34
+
+    defaultConfig {
+        minSdk 24
+        targetSdk 34
+
+        externalNativeBuild {
+            cmake {
+                cppFlags "-O2 -frtti -fexceptions -Wall -fstack-protector-all"
+                abiFilters(*reactNativeArchitectures())
+                arguments "-DANDROID_STL=c++_shared"
+            }
+        }
+    }
+
+    buildFeatures {
+        prefab true
+        buildConfig true
+    }
+
+    externalNativeBuild {
+        cmake {
+            path "CMakeLists.txt"
+        }
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+
+    packaging {
+        excludes += [
+            "**/libjsi.so",
+            "**/libfbjni.so",
+            "**/libc++_shared.so",
+            "**/libreactnative.so"
+        ]
+    }
+    sourceSets {
+        main {
+            jniLibs.srcDirs = ["../libs/android"]
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    compileOnly "com.facebook.react:react-android"
+}
+
+// Task to build Rust library for Android
+task buildRustLibrary(type: Exec) {
+    workingDir "${projectDir}/.."
+    commandLine "make", "android"
+}
+
+preBuild.dependsOn buildRustLibrary

package/android/cpp-adapter.cpp

@@ -0,0 +1,49 @@
+#include "TursoHostObject.h"
+#include <ReactCommon/CallInvokerHolder.h>
+#include <fbjni/fbjni.h>
+#include <jni.h>
+#include <jsi/jsi.h>
+#include <typeinfo>
+
+namespace jsi = facebook::jsi;
+namespace react = facebook::react;
+namespace jni = facebook::jni;
+
+// This file is not using raw jni but rather fbjni, do not change how the native
+// functions are registered
+// https://github.com/facebookincubator/fbjni/blob/main/docs/quickref.md
+struct TursoBridge : jni::JavaClass<TursoBridge>
+{
+    static constexpr auto kJavaDescriptor = "Lcom/turso/sync/reactnative/TursoBridge;";
+
+    static void registerNatives()
+    {
+        javaClassStatic()->registerNatives(
+            {makeNativeMethod("installNativeJsi", TursoBridge::installNativeJsi),
+             makeNativeMethod("clearStateNativeJsi", TursoBridge::clearStateNativeJsi)});
+    }
+
+private:
+    static void installNativeJsi(
+        jni::alias_ref<jni::JObject> thiz, jlong jsiRuntimePtr,
+        jni::alias_ref<react::CallInvokerHolder::javaobject> jsCallInvokerHolder,
+        jni::alias_ref<jni::JString> dbPath)
+    {
+        auto jsiRuntime = reinterpret_cast<jsi::Runtime *>(jsiRuntimePtr);
+        auto jsCallInvoker = jsCallInvokerHolder->cthis()->getCallInvoker();
+        std::string dbPathStr = dbPath->toStdString();
+
+        turso::install(*jsiRuntime, jsCallInvoker, dbPathStr.c_str());
+    }
+
+    static void clearStateNativeJsi(jni::alias_ref<jni::JObject> thiz)
+    {
+        turso::invalidate();
+    }
+};
+
+JNIEXPORT jint JNI_OnLoad(JavaVM *vm, void *)
+{
+    return jni::initialize(vm, []
+                           { TursoBridge::registerNatives(); });
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/com/turso/sync/reactnative/TursoBridge.java

@@ -0,0 +1,44 @@
+package com.turso.sync.reactnative;
+
+import com.facebook.react.bridge.ReactContext;
+import com.facebook.react.turbomodule.core.CallInvokerHolderImpl;
+
+import java.lang.Exception;
+
+// bridge layer, installNativeJsi/clearStateNativeJsi methods are set through cpp-adapter.cpp
+public class TursoBridge {
+  private static final TursoBridge instance = new TursoBridge();
+
+  public static TursoBridge getInstance() {
+    return instance;
+  }
+
+  private TursoBridge() {
+  }
+
+  private native void installNativeJsi(
+      long jsContextNativePointer,
+      CallInvokerHolderImpl jsCallInvokerHolder,
+      String dbPath);
+
+  private native void clearStateNativeJsi();
+
+  public void install(ReactContext context) throws Exception {
+    long jsContextPointer = context.getJavaScriptContextHolder().get();
+    if (jsContextPointer == 0) {
+      throw new Exception("jsContextPointer == 0");
+    }
+    CallInvokerHolderImpl jsCallInvokerHolder = (CallInvokerHolderImpl) context.getCatalystInstance()
+        .getJSCallInvokerHolder();
+
+    // getDatabasePath(...) returns file path - so we pass dummy value and remove it
+    // after to get directory path
+    String dbPath = context.getDatabasePath("tursoDatabaseFile").getAbsolutePath().replace("tursoDatabaseFile", "");
+
+    installNativeJsi(jsContextPointer, jsCallInvokerHolder, dbPath);
+  }
+
+  public void invalidate() {
+    clearStateNativeJsi();
+  }
+}

package/android/src/main/java/com/turso/sync/reactnative/TursoModule.java

@@ -0,0 +1,82 @@
+package com.turso.sync.reactnative;
+
+import java.io.File;
+import java.lang.Exception;
+import java.util.HashMap;
+import java.util.Map;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.module.annotations.ReactModule;
+import com.facebook.react.turbomodule.core.CallInvokerHolderImpl;
+
+// The React Native bridge - exposes methods to JavaScript
+@ReactModule(name = TursoModule.NAME)
+public class TursoModule extends ReactContextBaseJavaModule {
+    public static final String NAME = "Turso";
+
+    static {
+        System.loadLibrary("turso_sync_sdk_kit");
+        System.loadLibrary("turso-sync-react-native");
+    }
+
+    public TursoModule(ReactApplicationContext reactContext) {
+        super(reactContext);
+    }
+
+    @Override
+    @NonNull
+    public String getName() {
+        return NAME;
+    }
+
+    @Override
+    public Map<String, Object> getConstants() {
+        final Map<String, Object> constants = new HashMap<>();
+        ReactApplicationContext context = getReactApplicationContext();
+
+        // getDatabasePath(...) returns file path - so we pass dummy value and remove it
+        // after to get directory path
+        String dbPath = context.getDatabasePath("tursoDatabaseFile").getAbsolutePath().replace("tursoDatabaseFile", "");
+        constants.put("ANDROID_DATABASE_PATH", dbPath);
+
+        String filesPath = context.getFilesDir().getAbsolutePath();
+        constants.put("ANDROID_FILES_PATH", filesPath);
+
+        File externalFilesDir = context.getExternalFilesDir(null);
+        constants.put("ANDROID_EXTERNAL_FILES_PATH",
+                externalFilesDir != null ? externalFilesDir.getAbsolutePath() : null);
+
+        // populate Android and IOS constants to simplify JS code (e.g.
+        // IOS_DOCUMENT_PATH ?? ANDROID_DATABASE_PATH)
+        constants.put("IOS_DOCUMENT_PATH", null);
+        constants.put("IOS_LIBRARY_PATH", null);
+
+        return constants;
+    }
+
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    public boolean install() {
+        try {
+            ReactApplicationContext context = getReactApplicationContext();
+            // Install native module
+            TursoBridge.getInstance().install(context);
+            return true;
+        } catch (Exception e) {
+            return false;
+        }
+    }
+
+    @Override
+    public void invalidate() {
+        super.invalidate();
+        TursoBridge.getInstance().invalidate();
+    }
+
+    private native void installNativeJsi(long jsiRuntimePtr, Object callInvokerHolder, String dbPath);
+
+    private native void clearStateNativeJsi();
+}

package/android/src/main/java/com/turso/sync/reactnative/TursoPackage.java

@@ -0,0 +1,29 @@
+package com.turso.sync.reactnative;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+// Entry point for React Native's module registration system
+public class TursoPackage implements ReactPackage {
+    @NonNull
+    @Override
+    public List<NativeModule> createNativeModules(@NonNull ReactApplicationContext reactContext) {
+        List<NativeModule> modules = new ArrayList<>();
+        modules.add(new TursoModule(reactContext));
+        return modules;
+    }
+
+    @NonNull
+    @Override
+    public List<ViewManager> createViewManagers(@NonNull ReactApplicationContext reactContext) {
+        return Collections.emptyList();
+    }
+}

package/cpp/TursoConnectionHostObject.cpp

@@ -0,0 +1,179 @@
+#include "TursoConnectionHostObject.h"
+#include "TursoStatementHostObject.h"
+
+extern "C" {
+#include <turso.h>
+}
+
+namespace turso {
+
+TursoConnectionHostObject::~TursoConnectionHostObject() {
+    if (conn_) {
+        turso_connection_deinit(conn_);
+        conn_ = nullptr;
+    }
+}
+
+void TursoConnectionHostObject::throwError(jsi::Runtime &rt, const char *error) {
+    throw jsi::JSError(rt, error ? error : "Unknown error");
+}
+
+jsi::Value TursoConnectionHostObject::get(jsi::Runtime &rt, const jsi::PropNameID &name) {
+    auto propName = name.utf8(rt);
+
+    if (propName == "prepareSingle") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 1,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args, size_t count) -> jsi::Value {
+                return this->prepareSingle(rt, args, count);
+            }
+        );
+    }
+
+    if (propName == "prepareFirst") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 1,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args, size_t count) -> jsi::Value {
+                return this->prepareFirst(rt, args, count);
+            }
+        );
+    }
+
+    if (propName == "lastInsertRowid") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 0,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *, size_t) -> jsi::Value {
+                return this->lastInsertRowid(rt);
+            }
+        );
+    }
+
+    if (propName == "getAutocommit") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 0,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *, size_t) -> jsi::Value {
+                return this->getAutocommit(rt);
+            }
+        );
+    }
+
+    if (propName == "setBusyTimeout") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 1,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args, size_t count) -> jsi::Value {
+                return this->setBusyTimeout(rt, args, count);
+            }
+        );
+    }
+
+    if (propName == "close") {
+        return jsi::Function::createFromHostFunction(
+            rt, name, 0,
+            [this](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *, size_t) -> jsi::Value {
+                return this->close(rt);
+            }
+        );
+    }
+
+    return jsi::Value::undefined();
+}
+
+void TursoConnectionHostObject::set(jsi::Runtime &rt, const jsi::PropNameID &name, const jsi::Value &value) {
+    // Read-only object
+}
+
+std::vector<jsi::PropNameID> TursoConnectionHostObject::getPropertyNames(jsi::Runtime &rt) {
+    std::vector<jsi::PropNameID> props;
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "prepareSingle"));
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "prepareFirst"));
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "lastInsertRowid"));
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "getAutocommit"));
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "setBusyTimeout"));
+    props.emplace_back(jsi::PropNameID::forAscii(rt, "close"));
+    return props;
+}
+
+// 1:1 C API mapping - NO logic, just calls through to C API
+jsi::Value TursoConnectionHostObject::prepareSingle(jsi::Runtime &rt, const jsi::Value *args, size_t count) {
+    if (count < 1 || !args[0].isString()) {
+        throw jsi::JSError(rt, "prepareSingle: expected string argument");
+    }
+
+    std::string sql = args[0].asString(rt).utf8(rt);
+    turso_statement_t* statement = nullptr;
+    const char* error = nullptr;
+
+    turso_status_code_t status = turso_connection_prepare_single(conn_, sql.c_str(), &statement, &error);
+
+    if (status != TURSO_OK) {
+        throwError(rt, error);
+    }
+
+    // Wrap statement in TursoStatementHostObject
+    auto statementObj = std::make_shared<TursoStatementHostObject>(statement);
+    return jsi::Object::createFromHostObject(rt, statementObj);
+}
+
+jsi::Value TursoConnectionHostObject::prepareFirst(jsi::Runtime &rt, const jsi::Value *args, size_t count) {
+    if (count < 1 || !args[0].isString()) {
+        throw jsi::JSError(rt, "prepareFirst: expected string argument");
+    }
+
+    std::string sql = args[0].asString(rt).utf8(rt);
+    turso_statement_t* statement = nullptr;
+    size_t tail_idx = 0;
+    const char* error = nullptr;
+
+    turso_status_code_t status = turso_connection_prepare_first(conn_, sql.c_str(), &statement, &tail_idx, &error);
+
+    if (status != TURSO_OK) {
+        throwError(rt, error);
+    }
+
+    // If statement is null, return null (no valid statement parsed)
+    if (!statement) {
+        return jsi::Value::null();
+    }
+
+    // Return object with statement and tail_idx
+    jsi::Object result(rt);
+    auto statementObj = std::make_shared<TursoStatementHostObject>(statement);
+    result.setProperty(rt, "statement", jsi::Object::createFromHostObject(rt, statementObj));
+    result.setProperty(rt, "tailIdx", jsi::Value(static_cast<double>(tail_idx)));
+
+    return result;
+}
+
+jsi::Value TursoConnectionHostObject::lastInsertRowid(jsi::Runtime &rt) {
+    int64_t rowid = turso_connection_last_insert_rowid(conn_);
+    return jsi::Value(static_cast<double>(rowid));
+}
+
+jsi::Value TursoConnectionHostObject::getAutocommit(jsi::Runtime &rt) {
+    bool autocommit = turso_connection_get_autocommit(conn_);
+    return jsi::Value(autocommit);
+}
+
+jsi::Value TursoConnectionHostObject::setBusyTimeout(jsi::Runtime &rt, const jsi::Value *args, size_t count) {
+    if (count < 1 || !args[0].isNumber()) {
+        throw jsi::JSError(rt, "setBusyTimeout: expected number argument");
+    }
+
+    int64_t timeout_ms = static_cast<int64_t>(args[0].asNumber());
+    turso_connection_set_busy_timeout_ms(conn_, timeout_ms);
+
+    return jsi::Value::undefined();
+}
+
+jsi::Value TursoConnectionHostObject::close(jsi::Runtime &rt) {
+    const char* error = nullptr;
+    turso_status_code_t status = turso_connection_close(conn_, &error);
+
+    if (status != TURSO_OK) {
+        throwError(rt, error);
+    }
+
+    return jsi::Value::undefined();
+}
+
+} // namespace turso

package/cpp/TursoConnectionHostObject.h

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <memory>
+#include <string>
+
+// Forward declarations for Turso C API types
+extern "C" {
+    struct turso_connection;
+    struct turso_statement;
+    typedef struct turso_connection turso_connection_t;
+    typedef struct turso_statement turso_statement_t;
+}
+
+namespace turso {
+
+using namespace facebook;
+
+/**
+ * TursoConnectionHostObject wraps turso_connection_t* (core SDK-KIT type for database connection).
+ * This is a THIN wrapper - 1:1 mapping of SDK-KIT C API with NO logic.
+ * All logic belongs in TypeScript or Rust, not here.
+ */
+class TursoConnectionHostObject : public jsi::HostObject {
+public:
+    TursoConnectionHostObject(turso_connection_t* conn) : conn_(conn) {}
+    ~TursoConnectionHostObject();
+
+    // JSI HostObject interface
+    jsi::Value get(jsi::Runtime &rt, const jsi::PropNameID &name) override;
+    void set(jsi::Runtime &rt, const jsi::PropNameID &name, const jsi::Value &value) override;
+    std::vector<jsi::PropNameID> getPropertyNames(jsi::Runtime &rt) override;
+
+    // Direct access to wrapped pointer (for internal use)
+    turso_connection_t* getConnection() const { return conn_; }
+
+private:
+    turso_connection_t* conn_ = nullptr;
+
+    // Helper to throw JS errors
+    void throwError(jsi::Runtime &rt, const char *error);
+
+    // 1:1 C API mapping methods (NO logic - just calls through to C API)
+    jsi::Value prepareSingle(jsi::Runtime &rt, const jsi::Value *args, size_t count);
+    jsi::Value prepareFirst(jsi::Runtime &rt, const jsi::Value *args, size_t count);
+    jsi::Value lastInsertRowid(jsi::Runtime &rt);
+    jsi::Value getAutocommit(jsi::Runtime &rt);
+    jsi::Value setBusyTimeout(jsi::Runtime &rt, const jsi::Value *args, size_t count);
+    jsi::Value close(jsi::Runtime &rt);
+};
+
+} // namespace turso