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

package/lib/typescript/Statement.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Statement
+ *
+ * High-level wrapper around NativeStatement providing a clean API.
+ * Handles parameter binding, row conversion, and result collection.
+ */
+import type { NativeStatement, BindParams, Row, RunResult } from './types';
+/**
+ * Prepared SQL statement
+ */
+export declare class Statement {
+    private _statement;
+    private _finalized;
+    private _extraIo?;
+    constructor(statement: NativeStatement, extraIo?: () => Promise<void>);
+    /**
+     * Bind parameters to the statement
+     *
+     * @param params - Parameters to bind (array, object, or single value)
+     * @returns this for chaining
+     */
+    bind(...params: BindParams[]): this;
+    /**
+     * Bind positional parameters (1-indexed)
+     *
+     * @param params - Array of values to bind
+     */
+    private bindPositional;
+    /**
+     * Bind named parameters
+     *
+     * @param params - Object with named parameters
+     */
+    private bindNamed;
+    /**
+     * Bind a single value at a position
+     *
+     * @param position - 1-indexed position
+     * @param value - Value to bind
+     */
+    private bindValue;
+    /**
+     * Execute statement without returning rows (for INSERT, UPDATE, DELETE)
+     *
+     * @param params - Optional parameters to bind
+     * @returns Result with changes and lastInsertRowid
+     */
+    run(...params: BindParams[]): Promise<RunResult>;
+    /**
+     * Execute statement handling potential IO (for partial sync)
+     * Matches Python's _run_execute_with_io pattern
+     *
+     * @returns Execution result
+     */
+    private executeWithIo;
+    /**
+     * Step statement once handling potential IO (for partial sync)
+     * Matches Python's _step_once_with_io pattern
+     *
+     * @returns Status code
+     */
+    private stepWithIo;
+    /**
+     * Execute statement and return first row
+     *
+     * @param params - Optional parameters to bind
+     * @returns First row or undefined
+     */
+    get(...params: BindParams[]): Promise<Row | undefined>;
+    /**
+     * Execute statement and return all rows
+     *
+     * @param params - Optional parameters to bind
+     * @returns Array of rows
+     */
+    all(...params: BindParams[]): Promise<Row[]>;
+    /**
+     * Read current row into an object
+     *
+     * @returns Row object with column name keys
+     */
+    private readRow;
+    /**
+     * Read value at column index
+     *
+     * @param index - Column index
+     * @returns Column value
+     */
+    private readColumnValue;
+    /**
+     * Reset statement for re-execution
+     *
+     * @returns this for chaining
+     */
+    reset(): this;
+    /**
+     * Finalize and release statement resources
+     */
+    finalize(): Promise<void>;
+    /**
+     * Check if statement has been finalized
+     */
+    get finalized(): boolean;
+}
+//# sourceMappingURL=Statement.d.ts.map

package/lib/typescript/Statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Statement.d.ts","sourceRoot":"","sources":["../../src/Statement.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,eAAe,EAEf,UAAU,EACV,GAAG,EACH,SAAS,EACV,MAAM,SAAS,CAAC;AAGjB;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,CAAsB;gBAE3B,SAAS,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC;IAKrE;;;;;OAKG;IACH,IAAI,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAStB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAYjB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAoBjB;;;;;OAKG;IACG,GAAG,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAsBtD;;;;;OAKG;YACW,aAAa;IAwB3B;;;;;OAKG;YACW,UAAU;IAoBxB;;;;;OAKG;IACG,GAAG,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC;IA2B5D;;;;;OAKG;IACG,GAAG,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IA6BlD;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAiBf;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IAyBvB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B/B;;OAEG;IACH,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF"}

package/lib/typescript/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Turso React Native SDK
+ *
+ * Main entry point for the SDK. Supports both local-only and sync databases.
+ */
+import { Database } from './Database';
+import type { DatabaseOpts } from './types';
+import { setFileSystemImpl } from './internal/ioProcessor';
+export type { SQLiteValue, BindParams, Row, RunResult, DatabaseOpts, EncryptionOpts, SyncStats, TursoStatus, TursoType, } from './types';
+export { Database } from './Database';
+export { Statement } from './Statement';
+export { setFileSystemImpl } from './internal/ioProcessor';
+/**
+ * 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 declare function getDbPath(filename: string, directory?: 'documents' | 'database' | 'library'): string;
+/**
+ * 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 declare function connect(opts: DatabaseOpts): Promise<Database>;
+/**
+ * Returns the Turso library version.
+ */
+export declare function version(): string;
+/**
+ * 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 declare function setup(options: {
+    logLevel?: string;
+}): void;
+/**
+ * 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 declare const paths: {
+    /**
+     * Primary documents/database directory (writable)
+     * - iOS: App's Documents directory (absolute path)
+     * - Android: App's database directory (absolute path) - preferred for databases
+     */
+    readonly documents: string;
+    /**
+     * Database-specific directory (writable)
+     * - iOS: Same as documents
+     * - Android: Database directory (absolute path)
+     */
+    readonly database: string;
+    /**
+     * Files directory (writable)
+     * - iOS: Same as documents
+     * - Android: App's files directory (absolute path)
+     */
+    readonly files: string;
+    /**
+     * Library directory (iOS only, writable)
+     * - iOS: App's Library directory (absolute path)
+     * - Android: Same as files
+     */
+    readonly library: string;
+};
+declare const _default: {
+    connect: typeof connect;
+    version: typeof version;
+    setup: typeof setup;
+    setFileSystemImpl: typeof setFileSystemImpl;
+    getDbPath: typeof getDbPath;
+    paths: {
+        /**
+         * Primary documents/database directory (writable)
+         * - iOS: App's Documents directory (absolute path)
+         * - Android: App's database directory (absolute path) - preferred for databases
+         */
+        readonly documents: string;
+        /**
+         * Database-specific directory (writable)
+         * - iOS: Same as documents
+         * - Android: Database directory (absolute path)
+         */
+        readonly database: string;
+        /**
+         * Files directory (writable)
+         * - iOS: Same as documents
+         * - Android: App's files directory (absolute path)
+         */
+        readonly files: string;
+        /**
+         * Library directory (iOS only, writable)
+         * - iOS: App's Library directory (absolute path)
+         * - Android: Same as files
+         */
+        readonly library: string;
+    };
+    Database: typeof Database;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,KAAK,EACV,YAAY,EAGb,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAG3D,YAAY,EAEV,WAAW,EACX,UAAU,EACV,GAAG,EACH,SAAS,EAGT,YAAY,EACZ,cAAc,EAGd,SAAS,EAGT,WAAW,EACX,SAAS,GACV,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgC3D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,WAAW,GAAG,UAAU,GAAG,SAAuB,GAAG,MAAM,CASjH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,QAAQ,CAAC,CAInE;AAED;;GAEG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAEhC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAC,GAAG,IAAI,CAExD;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK;IAChB;;;;OAIG;wBACc,MAAM;IAIvB;;;;OAIG;uBACa,MAAM;IAItB;;;;OAIG;oBACU,MAAM;IAInB;;;;OAIG;sBACY,MAAM;CAGtB,CAAC;;;;;;;;QAnCA;;;;WAIG;4BACc,MAAM;QAIvB;;;;WAIG;2BACa,MAAM;QAItB;;;;WAIG;wBACU,MAAM;QAInB;;;;WAIG;0BACY,MAAM;;;;AAMvB,wBAQE"}

package/lib/typescript/internal/asyncOperation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Async Operation Driver
+ *
+ * Drives async operations returned by sync SDK-KIT methods.
+ * This is where ALL the async logic lives - the C++ layer is just a thin bridge.
+ *
+ * Key responsibilities:
+ * - Call resume() in a loop until DONE
+ * - When IO is needed, process all pending IO items
+ * - Extract and return the final result
+ */
+import type { NativeSyncOperation, NativeSyncDatabase, NativeConnection, NativeSyncChanges, SyncStats } from '../types';
+import type { IoContext } from './ioProcessor';
+/**
+ * Drive an async operation to completion
+ *
+ * @param operation - The native operation to drive
+ * @param database - The native sync database (for IO queue access)
+ * @param context - IO context with auth and URL information
+ * @returns Promise that resolves when operation completes
+ */
+export declare function driveOperation<T = void>(operation: NativeSyncOperation, database: NativeSyncDatabase, context: IoContext): Promise<T>;
+/**
+ * Helper type for operations that return connections
+ */
+export declare function driveConnectionOperation(operation: NativeSyncOperation, database: NativeSyncDatabase, context: IoContext): Promise<NativeConnection>;
+/**
+ * Helper type for operations that return changes
+ */
+export declare function driveChangesOperation(operation: NativeSyncOperation, database: NativeSyncDatabase, context: IoContext): Promise<NativeSyncChanges | null>;
+/**
+ * Helper type for operations that return stats
+ */
+export declare function driveStatsOperation(operation: NativeSyncOperation, database: NativeSyncDatabase, context: IoContext): Promise<SyncStats>;
+/**
+ * Helper type for operations that return void
+ */
+export declare function driveVoidOperation(operation: NativeSyncOperation, database: NativeSyncDatabase, context: IoContext): Promise<void>;
+//# sourceMappingURL=asyncOperation.d.ts.map

package/lib/typescript/internal/asyncOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncOperation.d.ts","sourceRoot":"","sources":["../../../src/internal/asyncOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACV,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,IAAI,EAC3C,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,CAAC,CAAC,CA2CZ;AA0BD;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,gBAAgB,CAAC,CAE3B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAEnC;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,SAAS,CAAC,CAEpB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,mBAAmB,EAC9B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,SAAS,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf"}

package/lib/typescript/internal/ioProcessor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * IO Processor
+ *
+ * Processes IO requests from the sync engine using JavaScript APIs.
+ * This is the key benefit of the thin JSI layer - all IO is handled by
+ * React Native's standard APIs (fetch, file system), not C++ code.
+ *
+ * Benefits:
+ * - Network requests visible in React Native debugger
+ * - Can customize fetch (add proxies, custom headers, etc.)
+ * - Easier to test (can mock fetch)
+ * - Uses platform-native networking (not C++ HTTP libraries)
+ */
+import type { NativeSyncIoItem, NativeSyncDatabase } from '../types';
+/**
+ * IO context contains auth and URL information for HTTP requests
+ */
+export interface IoContext {
+    /** Auth token for HTTP requests */
+    authToken?: string | (() => string | Promise<string> | null);
+    /** Base URL for normalization (e.g., 'libsql://mydb.turso.io') */
+    baseUrl?: string;
+}
+/**
+ * Set custom file system implementation (optional)
+ * By default, uses built-in JSI file system functions.
+ * Only call this if you need custom behavior (e.g., encryption, compression).
+ *
+ * @param readFile - Function to read file as Uint8Array
+ * @param writeFile - Function to write Uint8Array to file
+ */
+export declare function setFileSystemImpl(readFile: (path: string) => Promise<Uint8Array>, writeFile: (path: string, data: Uint8Array) => Promise<void>): void;
+/**
+ * Process a single IO item
+ *
+ * @param item - The IO item to process
+ * @param context - IO context with auth and URL information
+ */
+export declare function processIoItem(item: NativeSyncIoItem, context: IoContext): Promise<void>;
+/**
+ * Drain all pending IO items from sync engine queue and process them.
+ * This is called during statement execution when partial sync needs to load missing pages.
+ *
+ * @param database - The native sync database
+ * @param context - IO context with auth and URL information
+ */
+export declare function drainSyncIo(database: NativeSyncDatabase, context: IoContext): Promise<void>;
+//# sourceMappingURL=ioProcessor.d.ts.map

package/lib/typescript/internal/ioProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ioProcessor.d.ts","sourceRoot":"","sources":["../../../src/internal/ioProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAC7D,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,EAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAC3D,IAAI,CAGN;AA+BD;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA4B7F;AA+LD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBjG"}