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

package/src/Statement.ts

@@ -0,0 +1,372 @@
+/**
+ * Statement
+ *
+ * High-level wrapper around NativeStatement providing a clean API.
+ * Handles parameter binding, row conversion, and result collection.
+ */
+
+import type {
+  NativeStatement,
+  SQLiteValue,
+  BindParams,
+  Row,
+  RunResult,
+} from './types';
+import { TursoStatus, TursoType } from './types';
+
+/**
+ * Prepared SQL statement
+ */
+export class Statement {
+  private _statement: NativeStatement;
+  private _finalized = false;
+  private _extraIo?: () => Promise<void>;
+
+  constructor(statement: NativeStatement, extraIo?: () => Promise<void>) {
+    this._statement = statement;
+    this._extraIo = extraIo;
+  }
+
+  /**
+   * Bind parameters to the statement
+   *
+   * @param params - Parameters to bind (array, object, or single value)
+   * @returns this for chaining
+   */
+  bind(...params: BindParams[]): this {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized');
+    }
+
+    // Flatten parameters if single array passed
+    let flatParams: SQLiteValue[];
+    if (params.length === 1 && Array.isArray(params[0])) {
+      flatParams = params[0];
+    } else if (params.length === 1 && typeof params[0] === 'object' && params[0] !== null) {
+      // Named parameters
+      const namedParams = params[0] as Record<string, SQLiteValue>;
+      this.bindNamed(namedParams);
+      return this;
+    } else {
+      flatParams = params as SQLiteValue[];
+    }
+
+    // Bind positional parameters
+    this.bindPositional(flatParams);
+    return this;
+  }
+
+  /**
+   * Bind positional parameters (1-indexed)
+   *
+   * @param params - Array of values to bind
+   */
+  private bindPositional(params: SQLiteValue[]): void {
+    for (let i = 0; i < params.length; i++) {
+      const position = i + 1; // 1-indexed
+      const value = params[i]!;
+
+      this.bindValue(position, value);
+    }
+  }
+
+  /**
+   * Bind named parameters
+   *
+   * @param params - Object with named parameters
+   */
+  private bindNamed(params: Record<string, SQLiteValue>): void {
+    for (const [name, value] of Object.entries(params)) {
+      // Get position for named parameter
+      const position = this._statement.namedPosition(name);
+      if (position < 0) {
+        throw new Error(`Unknown parameter name: ${name}`);
+      }
+
+      this.bindValue(position, value);
+    }
+  }
+
+  /**
+   * Bind a single value at a position
+   *
+   * @param position - 1-indexed position
+   * @param value - Value to bind
+   */
+  private bindValue(position: number, value: SQLiteValue): void {
+    if (value === null || value === undefined) {
+      this._statement.bindPositionalNull(position);
+    } else if (typeof value === 'number') {
+      // Check if integer or float
+      if (Number.isInteger(value)) {
+        this._statement.bindPositionalInt(position, value);
+      } else {
+        this._statement.bindPositionalDouble(position, value);
+      }
+    } else if (typeof value === 'string') {
+      this._statement.bindPositionalText(position, value);
+    } else if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+      const buffer = value as unknown as ArrayBuffer;
+      this._statement.bindPositionalBlob(position, buffer);
+    } else {
+      throw new Error(`Unsupported parameter type: ${typeof value}`);
+    }
+  }
+
+  /**
+   * Execute statement without returning rows (for INSERT, UPDATE, DELETE)
+   *
+   * @param params - Optional parameters to bind
+   * @returns Result with changes and lastInsertRowid
+   */
+  async run(...params: BindParams[]): Promise<RunResult> {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized');
+    }
+
+    // Bind parameters if provided
+    if (params.length > 0) {
+      this.bind(...params);
+    }
+
+    // Execute statement with IO handling
+    const result = await this.executeWithIo();
+
+    // Reset for next execution
+    this._statement.reset();
+
+    return {
+      changes: result.rowsChanged,
+      lastInsertRowid: 0, // Not available from execute, would need connection
+    };
+  }
+
+  /**
+   * Execute statement handling potential IO (for partial sync)
+   * Matches Python's _run_execute_with_io pattern
+   *
+   * @returns Execution result
+   */
+  private async executeWithIo(): Promise<{ status: number; rowsChanged: number }> {
+    while (true) {
+      const result = this._statement.execute();
+
+      if (result.status === TursoStatus.IO) {
+        // Statement needs IO (e.g., loading missing pages with partial sync)
+        this._statement.runIo();
+
+        // Drain sync engine IO queue
+        if (this._extraIo) {
+          await this._extraIo();
+        }
+
+        continue;
+      }
+
+      if (result.status !== TursoStatus.DONE) {
+        throw new Error(`Statement execution failed with status: ${result.status}`);
+      }
+
+      return result;
+    }
+  }
+
+  /**
+   * Step statement once handling potential IO (for partial sync)
+   * Matches Python's _step_once_with_io pattern
+   *
+   * @returns Status code
+   */
+  private async stepWithIo(): Promise<number> {
+    while (true) {
+      const status = this._statement.step();
+
+      if (status === TursoStatus.IO) {
+        // Statement needs IO (e.g., loading missing pages with partial sync)
+        this._statement.runIo();
+
+        // Drain sync engine IO queue
+        if (this._extraIo) {
+          await this._extraIo();
+        }
+
+        continue;
+      }
+
+      return status;
+    }
+  }
+
+  /**
+   * Execute statement and return first row
+   *
+   * @param params - Optional parameters to bind
+   * @returns First row or undefined
+   */
+  async get(...params: BindParams[]): Promise<Row | undefined> {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized');
+    }
+
+    // Bind parameters if provided
+    if (params.length > 0) {
+      this.bind(...params);
+    }
+
+    // Step once with async IO handling
+    const status = await this.stepWithIo();
+
+    if (status === TursoStatus.ROW) {
+      const row = this.readRow();
+      this._statement.reset();
+      return row;
+    }
+
+    if (status === TursoStatus.DONE) {
+      this._statement.reset();
+      return undefined;
+    }
+
+    throw new Error(`Statement step failed with status: ${status}`);
+  }
+
+  /**
+   * Execute statement and return all rows
+   *
+   * @param params - Optional parameters to bind
+   * @returns Array of rows
+   */
+  async all(...params: BindParams[]): Promise<Row[]> {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized');
+    }
+
+    // Bind parameters if provided
+    if (params.length > 0) {
+      this.bind(...params);
+    }
+
+    const rows: Row[] = [];
+
+    // Step through all rows with async IO handling
+    while (true) {
+      const status = await this.stepWithIo();
+
+      if (status === TursoStatus.ROW) {
+        rows.push(this.readRow());
+      } else if (status === TursoStatus.DONE) {
+        break;
+      } else {
+        throw new Error(`Statement step failed with status: ${status}`);
+      }
+    }
+
+    this._statement.reset();
+    return rows;
+  }
+
+  /**
+   * Read current row into an object
+   *
+   * @returns Row object with column name keys
+   */
+  private readRow(): Row {
+    const row: Row = {};
+    const columnCount = this._statement.columnCount();
+
+    for (let i = 0; i < columnCount; i++) {
+      const name = this._statement.columnName(i);
+      if (!name) {
+        throw new Error(`Failed to get column name at index ${i}`);
+      }
+
+      const value = this.readColumnValue(i);
+      row[name] = value;
+    }
+
+    return row;
+  }
+
+  /**
+   * Read value at column index
+   *
+   * @param index - Column index
+   * @returns Column value
+   */
+  private readColumnValue(index: number): SQLiteValue {
+    const kind = this._statement.rowValueKind(index);
+
+    switch (kind) {
+      case TursoType.NULL:
+        return null;
+
+      case TursoType.INTEGER:
+        return this._statement.rowValueInt(index);
+
+      case TursoType.REAL:
+        return this._statement.rowValueDouble(index);
+
+      case TursoType.TEXT:
+        // Use rowValueText which directly returns a string from C++ (avoids encoding issues)
+        return this._statement.rowValueText(index);
+
+      case TursoType.BLOB:
+        return this._statement.rowValueBytesPtr(index) || new ArrayBuffer(0);
+
+      default:
+        throw new Error(`Unknown column type: ${kind}`);
+    }
+  }
+
+  /**
+   * Reset statement for re-execution
+   *
+   * @returns this for chaining
+   */
+  reset(): this {
+    if (this._finalized) {
+      throw new Error('Statement has been finalized');
+    }
+
+    this._statement.reset();
+    return this;
+  }
+
+  /**
+   * Finalize and release statement resources
+   */
+  async finalize(): Promise<void> {
+    if (this._finalized) {
+      return;
+    }
+
+    while (true) {
+      const status = this._statement.finalize();
+
+      if (status === TursoStatus.IO) {
+        // Statement needs IO (e.g., loading missing pages with partial sync)
+        this._statement.runIo();
+
+        // Drain sync engine IO queue
+        if (this._extraIo) {
+          await this._extraIo();
+        }
+
+        continue;
+      }
+
+      if (status !== TursoStatus.DONE) {
+        throw new Error(`Statement finalization failed with status: ${status}`);
+      }
+      break;
+    }
+    this._finalized = true;
+  }
+
+  /**
+   * Check if statement has been finalized
+   */
+  get finalized(): boolean {
+    return this._finalized;
+  }
+}

package/src/index.ts

@@ -0,0 +1,240 @@
+/**
+ * Turso React Native SDK
+ *
+ * Main entry point for the SDK. Supports both local-only and sync databases.
+ */
+
+import { NativeModules } from 'react-native';
+import { Database } from './Database';
+import type {
+  DatabaseOpts,
+  TursoNativeModule,
+  TursoProxy as TursoProxyType,
+} from './types';
+import { setFileSystemImpl } from './internal/ioProcessor';
+
+// Re-export all public types
+export type {
+  // Core types
+  SQLiteValue,
+  BindParams,
+  Row,
+  RunResult,
+
+  // Database config
+  DatabaseOpts,
+  EncryptionOpts,
+
+  // Sync types
+  SyncStats,
+
+  // Enums
+  TursoStatus,
+  TursoType,
+} from './types';
+
+// Re-export classes
+export { Database } from './Database';
+export { Statement } from './Statement';
+
+// Export file system configuration function
+export { setFileSystemImpl } from './internal/ioProcessor';
+
+// Get the native module
+const TursoNative: TursoNativeModule | undefined = NativeModules.Turso;
+
+// Check if native module is available
+if (!TursoNative) {
+  throw new Error(
+    `@tursodatabase/sync-react-native: Native module not found. Make sure you have properly linked the library.\n` +
+    `- iOS: Run 'pod install' in your ios directory\n` +
+    `- Android: Make sure the package is properly included in your MainApplication.java`
+  );
+}
+
+// Install the JSI bindings
+const installed = TursoNative.install();
+if (!installed) {
+  throw new Error(
+    '@tursodatabase/sync-react-native: Failed to install JSI bindings. Make sure the New Architecture is enabled.'
+  );
+}
+
+// Get the proxy that was installed on the global object
+// __TursoProxy is declared globally in types.ts
+const TursoProxy: TursoProxyType = __TursoProxy;
+
+if (!TursoProxy) {
+  throw new Error(
+    '@tursodatabase/sync-react-native: JSI bindings not found on global object. This is a bug.'
+  );
+}
+
+/**
+ * Helper function to construct a database path in a writable directory.
+ * On mobile platforms, you must use writable directories (not relative paths).
+ *
+ * @param filename - Database filename (e.g., 'mydb.db')
+ * @param directory - Directory to use ('documents', 'database', or 'library')
+ * @returns Absolute path to the database file
+ *
+ * @example
+ * ```ts
+ * import { getDbPath, connect } from '@tursodatabase/sync-react-native';
+ *
+ * const dbPath = getDbPath('mydb.db');
+ * const db = await connect({ path: dbPath });
+ * ```
+ */
+export function getDbPath(filename: string, directory: 'documents' | 'database' | 'library' = 'documents'): string {
+  const basePath = paths[directory];
+  if (!basePath || basePath === '.') {
+    throw new Error(
+      `Unable to get ${directory} path for this platform. ` +
+      'Make sure the native module is properly loaded.'
+    );
+  }
+  return `${basePath}/${filename}`;
+}
+
+/**
+ * Connect to a database asynchronously (matches JavaScript bindings API)
+ *
+ * This is the main entry point for the SDK, matching the API from
+ * @tursodatabase/sync-native and @tursodatabase/database-native.
+ *
+ * **Path handling**: Relative paths are automatically placed in writable directories:
+ * - Android: app's database directory (`/data/data/com.app/databases/`)
+ * - iOS: app's documents directory
+ *
+ * Absolute paths and `:memory:` are used as-is.
+ *
+ * @param opts - Database options
+ * @returns Promise resolving to Database instance
+ *
+ * @example Local database (relative path)
+ * ```ts
+ * import { connect } from '@tursodatabase/sync-react-native';
+ *
+ * // Relative path automatically placed in writable directory
+ * const db = await connect({ path: 'local.db' });
+ * await db.exec('CREATE TABLE users (id INTEGER, name TEXT)');
+ * ```
+ *
+ * @example Using :memory: for in-memory database
+ * ```ts
+ * const db = await connect({ path: ':memory:' });
+ * ```
+ *
+ * @example Sync database
+ * ```ts
+ * const db = await connect({
+ *   path: 'replica.db',
+ *   url: 'libsql://mydb.turso.io',
+ *   authToken: 'token-here',
+ * });
+ * const users = await db.all('SELECT * FROM users');
+ * await db.push();
+ * await db.pull();
+ * ```
+ *
+ * @example Using absolute path (advanced)
+ * ```ts
+ * import { connect, paths } from '@tursodatabase/sync-react-native';
+ *
+ * const db = await connect({ path: `${paths.documents}/mydb.db` });
+ * ```
+ */
+export async function connect(opts: DatabaseOpts): Promise<Database> {
+  const db = new Database(opts);
+  await db.connect();
+  return db;
+}
+
+/**
+ * Returns the Turso library version.
+ */
+export function version(): string {
+  return TursoProxy.version();
+}
+
+/**
+ * Configure Turso settings such as logging.
+ * Should be called before any database operations.
+ *
+ * @param options - Configuration options
+ * @example
+ * ```ts
+ * import { setup } from '@tursodatabase/sync-react-native';
+ *
+ * setup({ logLevel: 'debug' });
+ * ```
+ */
+export function setup(options: {logLevel?: string}): void {
+  TursoProxy.setup(options);
+}
+
+/**
+ * Platform-specific writable directory paths.
+ * Use these to construct absolute paths for database files.
+ *
+ * NOTE: With automatic path normalization, you typically don't need this.
+ * Just pass relative paths like 'mydb.db' and they'll be placed in the correct directory.
+ *
+ * @example
+ * ```ts
+ * import { paths, connect } from '@tursodatabase/sync-react-native';
+ *
+ * // Create database in app's documents/files directory
+ * const dbPath = `${paths.documents}/mydb.db`;
+ * const db = await connect({ path: dbPath });
+ * ```
+ */
+export const paths = {
+  /**
+   * Primary documents/database directory (writable)
+   * - iOS: App's Documents directory (absolute path)
+   * - Android: App's database directory (absolute path) - preferred for databases
+   */
+  get documents(): string {
+    return TursoNative?.IOS_DOCUMENT_PATH || TursoNative?.ANDROID_DATABASE_PATH || '.';
+  },
+
+  /**
+   * Database-specific directory (writable)
+   * - iOS: Same as documents
+   * - Android: Database directory (absolute path)
+   */
+  get database(): string {
+    return TursoNative?.IOS_DOCUMENT_PATH || TursoNative?.ANDROID_DATABASE_PATH || '.';
+  },
+
+  /**
+   * Files directory (writable)
+   * - iOS: Same as documents
+   * - Android: App's files directory (absolute path)
+   */
+  get files(): string {
+    return TursoNative?.IOS_DOCUMENT_PATH || TursoNative?.ANDROID_FILES_PATH || '.';
+  },
+
+  /**
+   * Library directory (iOS only, writable)
+   * - iOS: App's Library directory (absolute path)
+   * - Android: Same as files
+   */
+  get library(): string {
+    return TursoNative?.IOS_LIBRARY_PATH || TursoNative?.ANDROID_FILES_PATH || '.';
+  },
+};
+
+// Default export
+export default {
+  connect,
+  version,
+  setup,
+  setFileSystemImpl,
+  getDbPath,
+  paths,
+  Database,
+};