@powersync/capacitor 0.5.1 → 0.5.3

package/src/adapter/CapacitorSQLiteAdapter.ts

@@ -10,11 +10,10 @@ import {
   DBAdapterListener,
   DBLockOptions,
   LockContext,
-  mutexRunExclusive,
+  Mutex,
   QueryResult,
-  Transaction
+  timeoutSignal
 } from '@powersync/web';
-import { Mutex } from 'async-mutex';
 import { PowerSyncCore } from '../plugin/PowerSyncCore.js';
 import { messageForErrorCode } from '../plugin/PowerSyncPlugin.js';
 import { CapacitorSQLiteOpenFactoryOptions, DEFAULT_SQLITE_OPTIONS } from './CapacitorSQLiteOpenFactory.js';
@@ -33,6 +32,46 @@ async function monitorQuery(sql: string, executor: () => Promise<QueryResult>):
   }
 }
 
+/**
+ * Maps SQLite query parameter values to Capacitor Community supported formats.
+ * This handles binary payloads for both iOS and Android.
+ */
+function mapSQLiteParameterValues({ platform, values }: { platform: string; values: any[] }) {
+  return values.map((value) => {
+    if (value instanceof Uint8Array) {
+      switch (platform) {
+        case 'ios': {
+          /**
+           * The Buffer polyfill, used in @powersync/common, is a Uint8Array subclass which defines additional fields like
+           * `_isBuffer` and `parent` on its `prototype`. The additional fields are serialized when passed through the native bridge.
+           * The Capacitor Community SQLite library expects a dictionary of indexes to numerical bytes.
+           * The additional fields (which are not an index to numerical byte mapping) cause the parsing logic in the SQLite library to throw an error:
+           *  "Error in reading buffer".
+           *
+           * Re-wrapping the same backing buffer as a plain Uint8Array removes the Buffer subclass wrapper
+           * while keeping the same underlying bytes. This creates a new view, not a byte copy, so the
+           * overhead should be minimal.
+           */
+          return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        }
+        case 'android': {
+          /**
+           * Android expects an object of the form:
+           * { type: 'Buffer', data: [...]}
+           */
+          return {
+            type: 'Buffer',
+            data: Array.from(value)
+          };
+        }
+      }
+    }
+
+    // return value as-is
+    return value;
+  });
+}
+
 class CapacitorConnectionPool extends BaseObserver<DBAdapterListener> implements ConnectionPool {
   protected _writeConnection: SQLiteDBConnection | null;
   protected _readConnection: SQLiteDBConnection | null;
@@ -119,7 +158,11 @@ class CapacitorConnectionPool extends BaseObserver<DBAdapterListener> implements
 
   protected generateLockContext(db: SQLiteDBConnection): LockContext {
     const _query = async (query: string, params: any[] = []) => {
-      const result = await db.query(query, params);
+      const mappedParams = mapSQLiteParameterValues({
+        platform: Capacitor.getPlatform(),
+        values: params
+      });
+      const result = await db.query(query, mappedParams);
       const arrayResult = result.values ?? [];
       return {
         rowsAffected: 0,
@@ -134,31 +177,35 @@ class CapacitorConnectionPool extends BaseObserver<DBAdapterListener> implements
     const _execute = async (query: string, params: any[] = []): Promise<QueryResult> => {
       const platform = Capacitor.getPlatform();
 
-      if (db.getConnectionReadOnly()) {
+      if (
+        db.getConnectionReadOnly() ||
+        // Android: use query for SELECT and executeSet for mutations
+        // We cannot use `run` here for both cases.
+        (platform == 'android' && query.toLowerCase().trim().startsWith('select'))
+      ) {
         return _query(query, params);
       }
 
+      const mappedParams = mapSQLiteParameterValues({
+        platform,
+        values: params
+      });
+
       if (platform == 'android') {
-        // Android: use query for SELECT and executeSet for mutations
-        // We cannot use `run` here for both cases.
-        if (query.toLowerCase().trim().startsWith('select')) {
-          return _query(query, params);
-        } else {
-          const result = await db.executeSet([{ statement: query, values: params }], false);
-          return {
-            insertId: result.changes?.lastId,
-            rowsAffected: result.changes?.changes ?? 0,
-            rows: {
-              _array: [],
-              length: 0,
-              item: () => null
-            }
-          };
-        }
+        const result = await db.executeSet([{ statement: query, values: mappedParams }], false);
+        return {
+          insertId: result.changes?.lastId,
+          rowsAffected: result.changes?.changes ?? 0,
+          rows: {
+            _array: [],
+            length: 0,
+            item: () => null
+          }
+        };
       }
 
       // iOS (and other platforms): use run("all")
-      const result = await db.run(query, params, false, 'all');
+      const result = await db.run(query, mappedParams, false, 'all');
       const resultSet = result.changes?.values ?? [];
       return {
         insertId: result.changes?.lastId,
@@ -204,10 +251,14 @@ class CapacitorConnectionPool extends BaseObserver<DBAdapterListener> implements
     };
 
     const executeBatch = async (query: string, params: any[][] = []): Promise<QueryResult> => {
+      const platform = Capacitor.getPlatform();
       let result = await db.executeSet(
         params.map((param) => ({
           statement: query,
-          values: param
+          values: mapSQLiteParameterValues({
+            platform,
+            values: param
+          })
         }))
       );
 
@@ -228,39 +279,31 @@ class CapacitorConnectionPool extends BaseObserver<DBAdapterListener> implements
   }
 
   readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
-    return mutexRunExclusive(
-      this.readMutex,
-      async () => {
-        await this.initializedPromise;
-        return await fn(this.generateLockContext(this.readConnection));
-      },
-      options
-    );
+    return this.readMutex.runExclusive(async () => {
+      await this.initializedPromise;
+      return fn(this.generateLockContext(this.readConnection));
+    }, timeoutSignal(options?.timeoutMs));
   }
 
   writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T> {
-    return mutexRunExclusive(
-      this.writeMutex,
-      async () => {
-        await this.initializedPromise;
-        const result = await fn(this.generateLockContext(this.writeConnection));
-
-        // Fetch table updates
-        const updates = await this.writeConnection.query("SELECT powersync_update_hooks('get') AS table_name");
-        const jsonUpdates = updates.values?.[0];
-        if (!jsonUpdates || !jsonUpdates.table_name) {
-          throw new Error('Could not fetch table updates');
-        }
-        const notification: BatchedUpdateNotification = {
-          rawUpdates: [],
-          tables: JSON.parse(jsonUpdates.table_name),
-          groupedUpdates: {}
-        };
-        this.iterateListeners((l) => l.tablesUpdated?.(notification));
-        return result;
-      },
-      options
-    );
+    return this.writeMutex.runExclusive(async () => {
+      await this.initializedPromise;
+      const result = await fn(this.generateLockContext(this.writeConnection));
+
+      // Fetch table updates
+      const updates = await this.writeConnection.query("SELECT powersync_update_hooks('get') AS table_name");
+      const jsonUpdates = updates.values?.[0];
+      if (!jsonUpdates || !jsonUpdates.table_name) {
+        throw new Error('Could not fetch table updates');
+      }
+      const notification: BatchedUpdateNotification = {
+        rawUpdates: [],
+        tables: JSON.parse(jsonUpdates.table_name),
+        groupedUpdates: {}
+      };
+      this.iterateListeners((l) => l.tablesUpdated?.(notification));
+      return result;
+    }, timeoutSignal(options?.timeoutMs));
   }
 
   refreshSchema(): Promise<void> {

package/src/sync/CapacitorRemote.ts

@@ -0,0 +1,23 @@
+import { WebRemote } from '@powersync/web';
+
+export class CapacitorRemote extends WebRemote {
+  protected get supportsStreamingBinaryResponses(): boolean {
+    /**
+     * We'd like to avoid passing Binary buffers to SQLite when using
+     * iOS and Android for now. This is due to inefficient binary processing.
+     * Syncing using Buffers and Capacitor Community SQLite has been observed to be notably
+     * slower than the NDJSON option.
+     * Capacitor Community SQLite serializes Buffer objects, which causes slowdown
+     * ios: https://github.com/capacitor-community/sqlite/blob/f507a1e779688ea72b9d7e8744c647f7b688c568/ios/Plugin/CapacitorSQLite.swift#L888-L912
+     * android: https://github.com/capacitor-community/sqlite/blob/master/android/src/main/java/com/getcapacitor/community/database/sqlite/SQLite/UtilsSQLite.java#L141-L147
+     * As a rough guideline, the time to locally sync 10_000 small records was observed as:
+     * iOS:
+     *   - NDJSON: 449ms
+     *   - Binary: 68_982ms
+     * Android:
+     *   - NDJSON: 452ms
+     *   - Binary: 1_847ms
+     */
+    return false;
+  }
+}

package/src/sync/CapacitorSyncImplementation.ts

@@ -1,5 +1,4 @@
-import { AbstractStreamingSyncImplementation, LockOptions, LockType, mutexRunExclusive } from '@powersync/web';
-import { Mutex } from 'async-mutex';
+import { AbstractStreamingSyncImplementation, LockOptions, LockType, Mutex } from '@powersync/web';
 
 type MutexMap = {
   /**
@@ -56,11 +55,8 @@ export class CapacitorStreamingSyncImplementation extends AbstractStreamingSyncI
     mutexRecord.tracking.add(this.instanceId);
     const mutex = mutexRecord.locks[lockOptions.type];
 
-    return mutexRunExclusive(mutex, async () => {
-      if (lockOptions.signal?.aborted) {
-        throw new Error('Aborted');
-      }
+    return mutex.runExclusive(async () => {
       return await lockOptions.callback();
-    });
+    }, lockOptions.signal);
   }
 }