@trainstar/synchro-react-native 0.1.0

package/src/SynchroClient.ts

@@ -0,0 +1,424 @@
+import { Platform } from 'react-native';
+import type { EventSubscription } from 'react-native';
+import NativeSynchro from './NativeSynchro';
+import { mapNativeError } from './errors';
+import type {
+  Row,
+  ExecResult,
+  BatchResult,
+  SQLStatement,
+  ColumnDef,
+  TableOptions,
+  Transaction,
+  CheckpointMode,
+  SyncStatus,
+  SyncStatusType,
+  ConflictEvent,
+  SynchroConfig,
+  Unsubscribe,
+} from './types';
+
+let observerCounter = 0;
+function nextObserverID(): string {
+  return `obs_${++observerCounter}_${Date.now()}`;
+}
+
+export class SynchroClient {
+  private readonly native = NativeSynchro;
+  private readonly config: SynchroConfig;
+  private authSubscription: EventSubscription | null = null;
+
+  constructor(config: SynchroConfig) {
+    this.config = config;
+
+    // Wire auth callback using Codegen EventEmitter pattern
+    this.authSubscription = this.native.onAuthRequest(
+      (event: { requestID: string }) => {
+        this.config
+          .authProvider()
+          .then((token) => {
+            this.native.resolveAuthRequest(event.requestID, token);
+          })
+          .catch((err) => {
+            this.native.rejectAuthRequest(
+              event.requestID,
+              err instanceof Error ? err.message : String(err)
+            );
+          });
+      }
+    );
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      await this.native.initialize({
+        dbPath: this.config.dbPath,
+        serverURL: this.config.serverURL,
+        clientID: this.config.clientID,
+        platform: this.config.platform ?? Platform.OS,
+        appVersion: this.config.appVersion,
+        syncInterval: this.config.syncInterval ?? 30,
+        pushDebounce: this.config.pushDebounce ?? 0.5,
+        maxRetryAttempts: this.config.maxRetryAttempts ?? 5,
+        pullPageSize: this.config.pullPageSize ?? 100,
+        pushBatchSize: this.config.pushBatchSize ?? 100,
+        snapshotPageSize: this.config.snapshotPageSize ?? 100,
+      });
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Core SQL --
+
+  async query(sql: string, params?: unknown[]): Promise<Row[]> {
+    try {
+      const json = await this.native.query(
+        sql,
+        JSON.stringify(params ?? [])
+      );
+      return JSON.parse(json) as Row[];
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async queryOne(sql: string, params?: unknown[]): Promise<Row | null> {
+    try {
+      const json = await this.native.queryOne(
+        sql,
+        JSON.stringify(params ?? [])
+      );
+      return json ? (JSON.parse(json) as Row) : null;
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async execute(sql: string, params?: unknown[]): Promise<ExecResult> {
+    try {
+      return await this.native.execute(
+        sql,
+        JSON.stringify(params ?? [])
+      );
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async executeBatch(statements: SQLStatement[]): Promise<BatchResult> {
+    try {
+      const payload = statements.map((s) => ({
+        sql: s.sql,
+        params: s.params ?? [],
+      }));
+      return await this.native.executeBatch(JSON.stringify(payload));
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Transactions --
+
+  async writeTransaction<T>(
+    callback: (tx: Transaction) => Promise<T>
+  ): Promise<T> {
+    let txID: string;
+    try {
+      txID = await this.native.beginWriteTransaction();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+
+    try {
+      const tx: Transaction = {
+        query: async (sql, params) => {
+          const json = await this.native.txQuery(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+          return JSON.parse(json) as Row[];
+        },
+        queryOne: async (sql, params) => {
+          const json = await this.native.txQueryOne(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+          return json ? (JSON.parse(json) as Row) : null;
+        },
+        execute: async (sql, params) => {
+          return await this.native.txExecute(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+        },
+      };
+      const result = await callback(tx);
+      await this.native.commitTransaction(txID);
+      return result;
+    } catch (error) {
+      try {
+        await this.native.rollbackTransaction(txID);
+      } catch {
+        // rollback best-effort
+      }
+      throw mapNativeError(error);
+    }
+  }
+
+  async readTransaction<T>(
+    callback: (tx: Transaction) => Promise<T>
+  ): Promise<T> {
+    let txID: string;
+    try {
+      txID = await this.native.beginReadTransaction();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+
+    try {
+      const tx: Transaction = {
+        query: async (sql, params) => {
+          const json = await this.native.txQuery(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+          return JSON.parse(json) as Row[];
+        },
+        queryOne: async (sql, params) => {
+          const json = await this.native.txQueryOne(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+          return json ? (JSON.parse(json) as Row) : null;
+        },
+        execute: async (sql, params) => {
+          return await this.native.txExecute(
+            txID,
+            sql,
+            JSON.stringify(params ?? [])
+          );
+        },
+      };
+      const result = await callback(tx);
+      await this.native.commitTransaction(txID);
+      return result;
+    } catch (error) {
+      try {
+        await this.native.rollbackTransaction(txID);
+      } catch {
+        // rollback best-effort
+      }
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Schema (local-only) --
+
+  async createTable(
+    name: string,
+    columns: ColumnDef[],
+    options?: TableOptions
+  ): Promise<void> {
+    try {
+      await this.native.createTable(
+        name,
+        JSON.stringify(columns),
+        options ? JSON.stringify(options) : null
+      );
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async alterTable(name: string, addColumns: ColumnDef[]): Promise<void> {
+    try {
+      await this.native.alterTable(name, JSON.stringify(addColumns));
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async createIndex(
+    table: string,
+    columns: string[],
+    unique = false
+  ): Promise<void> {
+    try {
+      await this.native.createIndex(table, columns, unique);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Observation --
+
+  onChange(tables: string[], callback: () => void): Unsubscribe {
+    const observerID = nextObserverID();
+
+    const subscription = this.native.onChange(
+      (event: { observerID: string }) => {
+        if (event.observerID === observerID) {
+          callback();
+        }
+      }
+    );
+
+    this.native.addChangeObserver(observerID, tables);
+
+    return () => {
+      subscription.remove();
+      this.native.removeObserver(observerID);
+    };
+  }
+
+  watch(
+    sql: string,
+    params: unknown[] | undefined,
+    tables: string[],
+    callback: (rows: Row[]) => void
+  ): Unsubscribe {
+    const observerID = nextObserverID();
+
+    const subscription = this.native.onQueryResult(
+      (event: { observerID: string; rowsJson: string }) => {
+        if (event.observerID === observerID) {
+          callback(JSON.parse(event.rowsJson) as Row[]);
+        }
+      }
+    );
+
+    this.native.addQueryObserver(
+      observerID,
+      sql,
+      JSON.stringify(params ?? []),
+      tables
+    );
+
+    return () => {
+      subscription.remove();
+      this.native.removeObserver(observerID);
+    };
+  }
+
+  // -- WAL --
+
+  async checkpoint(mode: CheckpointMode = 'passive'): Promise<void> {
+    try {
+      await this.native.checkpoint(mode);
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Lifecycle --
+
+  async close(): Promise<void> {
+    try {
+      await this.native.close();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async getPath(): Promise<string> {
+    try {
+      return await this.native.getPath();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async pendingChangeCount(): Promise<number> {
+    try {
+      return await this.native.pendingChangeCount();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Sync --
+
+  async start(): Promise<void> {
+    try {
+      await this.native.start();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async stop(): Promise<void> {
+    try {
+      await this.native.stop();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  async syncNow(): Promise<void> {
+    try {
+      await this.native.syncNow();
+    } catch (error) {
+      throw mapNativeError(error);
+    }
+  }
+
+  // -- Status & Events --
+
+  onStatusChange(callback: (status: SyncStatus) => void): Unsubscribe {
+    const subscription = this.native.onStatusChange(
+      (event: { status: string; retryAt: string | null }) => {
+        callback({
+          status: event.status as SyncStatusType,
+          retryAt: event.retryAt ? new Date(event.retryAt) : null,
+        });
+      }
+    );
+    return () => subscription.remove();
+  }
+
+  onConflict(callback: (event: ConflictEvent) => void): Unsubscribe {
+    const subscription = this.native.onConflict(
+      (event: {
+        table: string;
+        recordID: string;
+        clientDataJson: string | null;
+        serverDataJson: string | null;
+      }) => {
+        callback({
+          table: event.table,
+          recordID: event.recordID,
+          clientData: event.clientDataJson
+            ? JSON.parse(event.clientDataJson)
+            : null,
+          serverData: event.serverDataJson
+            ? JSON.parse(event.serverDataJson)
+            : null,
+        });
+      }
+    );
+    return () => subscription.remove();
+  }
+
+  onSnapshotRequired(
+    handler: () => Promise<boolean>
+  ): Unsubscribe {
+    const subscription = this.native.onSnapshotRequired(
+      (event: { requestID: string }) => {
+        handler()
+          .then((approved) => {
+            this.native.resolveSnapshotRequest(event.requestID, approved);
+          })
+          .catch(() => {
+            this.native.resolveSnapshotRequest(event.requestID, false);
+          });
+      }
+    );
+    return () => subscription.remove();
+  }
+}

package/src/errors.ts

@@ -0,0 +1,205 @@
+export class SynchroError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'SynchroError';
+  }
+}
+
+export class NotConnectedError extends SynchroError {
+  constructor() {
+    super('NOT_CONNECTED', 'Not connected to sync server');
+    this.name = 'NotConnectedError';
+  }
+}
+
+export class SchemaNotLoadedError extends SynchroError {
+  constructor() {
+    super('SCHEMA_NOT_LOADED', 'Schema has not been loaded from server');
+    this.name = 'SchemaNotLoadedError';
+  }
+}
+
+export class TableNotSyncedError extends SynchroError {
+  readonly table: string;
+
+  constructor(table: string) {
+    super('TABLE_NOT_SYNCED', `Table '${table}' is not a synced table`);
+    this.name = 'TableNotSyncedError';
+    this.table = table;
+  }
+}
+
+export class UpgradeRequiredError extends SynchroError {
+  readonly currentVersion: string;
+  readonly minimumVersion: string;
+
+  constructor(currentVersion: string, minimumVersion: string) {
+    super(
+      'UPGRADE_REQUIRED',
+      `App version ${currentVersion} is below minimum ${minimumVersion}`
+    );
+    this.name = 'UpgradeRequiredError';
+    this.currentVersion = currentVersion;
+    this.minimumVersion = minimumVersion;
+  }
+}
+
+export class SchemaMismatchError extends SynchroError {
+  readonly serverVersion: number;
+  readonly serverHash: string;
+
+  constructor(serverVersion: number, serverHash: string) {
+    super(
+      'SCHEMA_MISMATCH',
+      `Schema mismatch: server version ${serverVersion}, hash ${serverHash}`
+    );
+    this.name = 'SchemaMismatchError';
+    this.serverVersion = serverVersion;
+    this.serverHash = serverHash;
+  }
+}
+
+export class SnapshotRequiredError extends SynchroError {
+  constructor() {
+    super('SNAPSHOT_REQUIRED', 'Full snapshot required');
+    this.name = 'SnapshotRequiredError';
+  }
+}
+
+export interface PushResultItem {
+  recordID: string;
+  table: string;
+  status: string;
+  message?: string;
+}
+
+export class PushRejectedError extends SynchroError {
+  readonly results: PushResultItem[];
+
+  constructor(results: PushResultItem[]) {
+    super('PUSH_REJECTED', `Push rejected: ${results.length} record(s)`);
+    this.name = 'PushRejectedError';
+    this.results = results;
+  }
+}
+
+export class NetworkError extends SynchroError {
+  constructor(message: string) {
+    super('NETWORK_ERROR', `Network error: ${message}`);
+    this.name = 'NetworkError';
+  }
+}
+
+export class ServerError extends SynchroError {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super('SERVER_ERROR', `Server error ${status}: ${message}`);
+    this.name = 'ServerError';
+    this.status = status;
+  }
+}
+
+export class DatabaseError extends SynchroError {
+  constructor(message: string) {
+    super('DATABASE_ERROR', `Database error: ${message}`);
+    this.name = 'DatabaseError';
+  }
+}
+
+export class InvalidResponseError extends SynchroError {
+  constructor(message: string) {
+    super('INVALID_RESPONSE', `Invalid response: ${message}`);
+    this.name = 'InvalidResponseError';
+  }
+}
+
+export class AlreadyStartedError extends SynchroError {
+  constructor() {
+    super('ALREADY_STARTED', 'Sync has already been started');
+    this.name = 'AlreadyStartedError';
+  }
+}
+
+export class NotStartedError extends SynchroError {
+  constructor() {
+    super('NOT_STARTED', 'Sync has not been started');
+    this.name = 'NotStartedError';
+  }
+}
+
+export class TransactionTimeoutError extends SynchroError {
+  constructor() {
+    super('TRANSACTION_TIMEOUT', 'Transaction timed out due to inactivity');
+    this.name = 'TransactionTimeoutError';
+  }
+}
+
+interface NativeErrorLike {
+  code?: string;
+  message?: string;
+  userInfo?: Record<string, string>;
+}
+
+export function mapNativeError(error: unknown): SynchroError {
+  if (error instanceof SynchroError) {
+    return error;
+  }
+
+  const nativeError = error as NativeErrorLike;
+  const code = nativeError?.code;
+  const message = nativeError?.message ?? 'Unknown error';
+  const userInfo = nativeError?.userInfo ?? {};
+
+  switch (code) {
+    case 'NOT_CONNECTED':
+      return new NotConnectedError();
+    case 'SCHEMA_NOT_LOADED':
+      return new SchemaNotLoadedError();
+    case 'TABLE_NOT_SYNCED':
+      return new TableNotSyncedError(userInfo.table ?? '');
+    case 'UPGRADE_REQUIRED':
+      return new UpgradeRequiredError(
+        userInfo.currentVersion ?? '',
+        userInfo.minimumVersion ?? ''
+      );
+    case 'SCHEMA_MISMATCH':
+      return new SchemaMismatchError(
+        parseInt(userInfo.serverVersion ?? '0', 10),
+        userInfo.serverHash ?? ''
+      );
+    case 'SNAPSHOT_REQUIRED':
+      return new SnapshotRequiredError();
+    case 'PUSH_REJECTED': {
+      let results: PushResultItem[] = [];
+      try {
+        results = JSON.parse(userInfo.results ?? '[]');
+      } catch {
+        // leave empty
+      }
+      return new PushRejectedError(results);
+    }
+    case 'NETWORK_ERROR':
+      return new NetworkError(userInfo.message ?? message);
+    case 'SERVER_ERROR':
+      return new ServerError(
+        parseInt(userInfo.status ?? '0', 10),
+        userInfo.message ?? message
+      );
+    case 'DATABASE_ERROR':
+      return new DatabaseError(userInfo.message ?? message);
+    case 'INVALID_RESPONSE':
+      return new InvalidResponseError(userInfo.message ?? message);
+    case 'ALREADY_STARTED':
+      return new AlreadyStartedError();
+    case 'NOT_STARTED':
+      return new NotStartedError();
+    case 'TRANSACTION_TIMEOUT':
+      return new TransactionTimeoutError();
+    default:
+      return new SynchroError(code ?? 'UNKNOWN', message);
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export { useQuery } from './useQuery';
+export { useSyncStatus } from './useSyncStatus';
+export { usePendingChanges } from './usePendingChanges';

package/src/hooks/usePendingChanges.ts

@@ -0,0 +1,32 @@
+import { useState, useEffect } from 'react';
+import type { SynchroClient } from '../SynchroClient';
+
+export function usePendingChanges(
+  client: SynchroClient,
+  pollInterval = 2000
+): number {
+  const [count, setCount] = useState(0);
+
+  useEffect(() => {
+    let active = true;
+
+    const poll = async () => {
+      try {
+        const c = await client.pendingChangeCount();
+        if (active) setCount(c);
+      } catch {
+        // ignore poll errors
+      }
+    };
+
+    poll();
+    const interval = setInterval(poll, pollInterval);
+
+    return () => {
+      active = false;
+      clearInterval(interval);
+    };
+  }, [client, pollInterval]);
+
+  return count;
+}