@trainstar/synchro-react-native 0.1.1 → 0.3.1

package/README.md

@@ -4,19 +4,31 @@ React Native TurboModule bridge for Synchro. The package wraps the native Swift
 
 ## Requirements
 
-- React Native `0.83.x`
+- React Native `0.83.x`. Use `0.83.5` or later with Xcode `26.4` or later.
 - iOS `16.0+`
 - Android `minSdk 24`
-- Node `20+`
+- Node `20.19.4+`
 - Android development and CI should use JDK `17`
 
 ## Installation
 
+Install the published package only after Synchro `0.3.1` is available. Before that,
+use the local artifact flow in
+[Client Consumption](https://trainstar.github.io/synchro/clients/consumption/).
+
 ```sh
-npm install @trainstar/synchro-react-native
+npm install @trainstar/synchro-react-native@0.3.1
+```
+
+Before you run `pod install`, add these published Synchro `0.3.1` dependencies to the
+application `ios/Podfile`:
+
+```ruby
+pod 'Synchro', :git => 'https://github.com/trainstar/synchro.git', :tag => 'v0.3.1'
+pod 'GRDB.swift', :git => 'https://github.com/groue/GRDB.swift.git', :tag => 'v7.0.0'
 ```
 
-iOS:
+Then install the pods:
 
 ```sh
 cd ios
@@ -25,25 +37,83 @@ pod install
 
 Android autolinks through the React Native Gradle plugin. No manual `MainApplication` edits are required.
 
+The Android library resolves the native SDK from Maven Central.
+Local Maven resolution is explicit in `example/android/build.gradle` for development.
+
 ## Usage
 
 ```ts
+import { Platform } from 'react-native';
 import { SynchroClient } from '@trainstar/synchro-react-native';
 
-const client = new SynchroClient({
-  dbPath: 'synchro.db',
-  serverURL: 'https://api.example.com',
-  authProvider: async () => '<jwt>',
-  clientID: 'device-1',
-  appVersion: '1.0.0',
-});
+export async function syncQuickstart(
+  accessToken: string,
+  clientID: string,
+  databaseFileName: string
+): Promise<void> {
+  const serverURL = Platform.OS === 'android'
+    ? 'http://10.0.2.2:8091'
+    : 'http://127.0.0.1:8091';
+  const noteID = '00000000-0000-4000-8000-000000000001';
+  const client = new SynchroClient({
+    dbPath: databaseFileName,
+    serverURL,
+    authProvider: async () => accessToken,
+    clientID,
+    appVersion: '0.3.0',
+  });
+
+  try {
+    await client.initialize();
+    await client.start();
+    await client.syncNow();
+
+    const note = await client.queryOne(
+      'SELECT id, body FROM notes WHERE id = ?',
+      [noteID]
+    );
+    if (note === null || typeof note.id !== 'string' || note.id !== noteID) {
+      throw new Error('The first pull did not contain the quickstart note');
+    }
+
+    await client.stop();
+    await client.execute(
+      'UPDATE notes SET body = ? WHERE id = ?',
+      ['Edited offline', noteID]
+    );
+    await client.start();
+    await client.syncNow();
+
+    const updated = await client.queryOne(
+      'SELECT body FROM notes WHERE id = ?',
+      [noteID]
+    );
+    if (
+      updated === null ||
+      typeof updated.body !== 'string' ||
+      updated.body !== 'Edited offline'
+    ) {
+      throw new Error('The synced note did not contain the offline edit');
+    }
+  } finally {
+    await client.close();
+  }
+}
+```
 
-await client.initialize();
-await client.start();
+The example uses the local tutorial adapter only. Android emulators reach the
+host at `10.0.2.2`; iOS simulators use `127.0.0.1`. The example app permits
+that cleartext development traffic. Production applications must use HTTPS and
+must not copy the cleartext network configuration.
 
-const rows = await client.query('SELECT * FROM tasks WHERE done = ?', [0]);
-await client.execute('UPDATE tasks SET done = ? WHERE id = ?', [1, rows[0].id]);
-```
+`start()` arms the lifecycle. Do not use it as a schema-readiness signal.
+`syncNow()` completes the requested cycle before this example reads the local
+database.
+
+SQL bind params are passed as native typed arrays, not as JSON strings. Supported React Native bind values are `null`, `string`, `number`, `boolean`, `{ type: 'int64', value: '...' }`, and `{ type: 'bytes', base64: '...' }`. Positional `null` values are preserved across iOS and Android for direct queries, batch execution, transactions, and query observers.
+
+`queryOne()` returns `Row | null`, and each row value is `unknown`. Check for
+both a non-null row and a string `id` before using the value as a note ID.
 
 ## Public API
 
@@ -67,11 +137,18 @@ Events and hooks:
 
 - `onStatusChange(callback)`
 - `onConflict(callback)`
-- `onSnapshotRequired(handler)`
 - `useQuery(client, sql, params?, tables?)`
 - `useSyncStatus(client)`
 - `usePendingChanges(client, pollInterval?)`
 
+`useQuery` compares `int64` and `bytes` parameters by tag type and payload.
+Equivalent tag objects do not restart the query or subscription.
+
+`useSyncStatus` subscribes before it reads current native status.
+New events take priority over the initial snapshot.
+Changing clients resets the displayed status until the new client supplies state.
+Snapshot failures reach the React error boundary unless a newer status event has arrived.
+
 ## Transactions
 
 `writeTransaction()` and `readTransaction()` mirror the native SDKs through a bridge-held transaction session.
@@ -85,8 +162,8 @@ Contract:
 ```ts
 await client.writeTransaction(async (tx) => {
   await tx.execute(
-    'INSERT INTO tasks (id, title, done) VALUES (?, ?, ?)',
-    ['task-1', 'Ship RN SDK', 0]
+    'UPDATE notes SET body = ? WHERE id = ?',
+    ['Edited offline', '00000000-0000-4000-8000-000000000001']
   );
 });
 ```
@@ -100,7 +177,6 @@ Native errors are normalized to typed JS errors, including:
 - `TableNotSyncedError`
 - `UpgradeRequiredError`
 - `SchemaMismatchError`
-- `SnapshotRequiredError`
 - `PushRejectedError`
 - `NetworkError`
 - `ServerError`
@@ -110,13 +186,16 @@ Native errors are normalized to typed JS errors, including:
 - `NotStartedError`
 - `TransactionTimeoutError`
 
+The iOS schema bridge rejects malformed JSON with the existing `UNKNOWN` error code.
+
 ## Development
 
+The published package accepts Node `20.19.4` or later. Repository development
+uses the Node `22.20.0` pin in `.nvmrc`.
+
 ```sh
-npm run typecheck
-npm run test:unit
-npm run prepare
-npm run pack:dry-run
+make lint-rn
+make test-rn-unit
 ```
 
 The example app in [`example/`](./example) is the end-to-end harness used for RN bridge verification on iOS and Android.

package/SynchroReactNative.podspec

@@ -11,12 +11,13 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => "16.0" }
-  s.source       = { :git => "https://github.com/trainstar/synchro.git", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/trainstar/synchro.git", :tag => "v#{s.version}" }
 
   s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
   s.private_header_files = "ios/**/*.h"
+  s.compiler_flags = "-Werror=protocol"
 
-  s.dependency "Synchro", "~> 0.1"
+  s.dependency "Synchro", "= #{s.version}"
 
   install_modules_dependencies(s)
 end

package/android/build.gradle

@@ -17,7 +17,6 @@ buildscript {
   repositories {
     google()
     mavenCentral()
-    mavenLocal()
   }
 
   dependencies {
@@ -33,6 +32,9 @@ apply plugin: "kotlin-android"
 
 apply plugin: "com.facebook.react"
 
+def defaultSynchroVersion = "0.3.1"
+def resolvedSynchroVersion = findProperty("synchroVersion")?.toString() ?: defaultSynchroVersion
+
 android {
   namespace "com.trainstar.synchro.rn"
 
@@ -66,16 +68,19 @@ android {
   compileOptions {
     sourceCompatibility JavaVersion.VERSION_1_8
     targetCompatibility JavaVersion.VERSION_1_8
+    coreLibraryDesugaringEnabled true
   }
 }
 
 repositories {
-  mavenLocal()
+  mavenCentral()
 }
 
 dependencies {
+  coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:2.0.4"
   implementation "com.facebook.react:react-android"
-  implementation "com.trainstar:synchro:0.1.0"
+  implementation "fit.trainstar:synchro:${resolvedSynchroVersion}"
+  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0"
   implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0"
 }