@powersync/common 1.56.0 → 1.57.1

package/src/attachments/AttachmentQueue.ts

@@ -1,6 +1,7 @@
 import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
 import { DEFAULT_WATCH_THROTTLE_MS } from '../client/watched/WatchedQuery.js';
 import { DifferentialWatchedQuery } from '../client/watched/processors/DifferentialQueryProcessor.js';
+import { Mutex } from '../utils/mutex.js';
 import { Transaction } from '../db/DBAdapter.js';
 import { ILogger } from '../utils/Logger.js';
 import { AttachmentContext } from './AttachmentContext.js';
@@ -135,6 +136,21 @@ export class AttachmentQueue {
 
   private watchAttachmentsAbortController!: AbortController;
 
+  /**
+   * Serializes concurrent `syncStorage()` triggers (periodic timer, watch-onDiff,
+   * status-changed). Held across the whole batch, but only contended by other
+   * sync triggers — foreground `saveFile` / `deleteFile` / watched-attachment
+   * processing don't take this lock and proceed in parallel via the
+   * `AttachmentService` mutex, which is acquired only briefly per row.
+   */
+  private syncLoopMutex = new Mutex();
+
+  /**
+   * Aborted by `stopSync()` to interrupt an in-flight batch within one
+   * attachment's processing time. Polled between rows by `SyncingService`.
+   */
+  private syncAbortController?: AbortController;
+
   /**
    * Creates a new AttachmentQueue instance.
    *
@@ -195,6 +211,8 @@ export class AttachmentQueue {
   async startSync(): Promise<void> {
     await this.stopSync();
 
+    this.syncAbortController = new AbortController();
+
     this.watchActiveAttachments = this.attachmentService.watchActiveAttachments({
       throttleMs: this.syncThrottleDuration
     });
@@ -325,24 +343,45 @@ export class AttachmentQueue {
    *
    * This is called automatically at regular intervals when sync is started,
    * but can also be called manually to trigger an immediate sync.
+   *
+   * Concurrent invocations are serialized via `syncLoopMutex`.
    */
   async syncStorage(): Promise<void> {
-    await this.attachmentService.withContext(async (ctx) => {
-      const activeAttachments = await ctx.getActiveAttachments();
-      await this.localStorage.initialize();
-      await this.syncingService.processAttachments(activeAttachments, ctx);
-      await this.syncingService.deleteArchivedAttachments(ctx);
-    });
+    const signal = this.syncAbortController?.signal;
+    if (signal?.aborted) return;
+
+    try {
+      await this.syncLoopMutex.runExclusive(async () => {
+        const activeAttachments = await this.attachmentService.withContext((ctx) => ctx.getActiveAttachments());
+        await this.localStorage.initialize();
+
+        await this.syncingService.processAttachments(activeAttachments, { signal });
+
+        if (signal?.aborted) return;
+
+        await this.attachmentService.withContext((ctx) => this.syncingService.deleteArchivedAttachments(ctx));
+      }, signal);
+    } catch (error) {
+      // A queued batch's acquire rejects when `stopSync` aborts — expected, not an error.
+      if (signal?.aborted) return;
+      throw error;
+    }
   }
 
   /**
    * Stops the attachment synchronization process.
    *
-   * Clears the periodic sync timer and closes all active attachment watchers.
+   * Clears the periodic sync timer, closes all active attachment watchers, and
+   * aborts any in-flight `syncStorage()` call so it exits within one
+   * attachment's processing time instead of running the batch to completion.
    */
   async stopSync(): Promise<void> {
     clearInterval(this.periodicSyncTimer);
     this.periodicSyncTimer = undefined;
+    if (this.syncAbortController) {
+      this.syncAbortController.abort();
+      this.syncAbortController = undefined;
+    }
     if (this.watchActiveAttachments) await this.watchActiveAttachments.close();
     if (this.watchAttachmentsAbortController) {
       this.watchAttachmentsAbortController.abort();

package/src/attachments/Schema.ts

@@ -1,5 +1,5 @@
 import { column } from '../db/schema/Column.js';
-import { Table } from '../db/schema/Table.js';
+import { RowType, Table } from '../db/schema/Table.js';
 import { TableV2Options } from '../db/schema/Table.js';
 
 /**
@@ -66,30 +66,39 @@ export enum AttachmentState {
  */
 export interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {}
 
+/**
+ * @alpha
+ */
+export const ATTACHMENT_TABLE_COLUMNS = {
+  filename: column.text,
+  local_uri: column.text,
+  timestamp: column.integer,
+  size: column.integer,
+  media_type: column.text,
+  state: column.integer, // Corresponds to AttachmentState
+  has_synced: column.integer,
+  meta_data: column.text
+};
+
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
  * @alpha
  */
-export class AttachmentTable extends Table {
+export class AttachmentTable extends Table<typeof ATTACHMENT_TABLE_COLUMNS> {
   constructor(options?: AttachmentTableOptions) {
-    super(
-      {
-        filename: column.text,
-        local_uri: column.text,
-        timestamp: column.integer,
-        size: column.integer,
-        media_type: column.text,
-        state: column.integer, // Corresponds to AttachmentState
-        has_synced: column.integer,
-        meta_data: column.text
-      },
-      {
-        ...options,
-        viewName: options?.viewName ?? ATTACHMENT_TABLE,
-        localOnly: true,
-        insertOnly: false
-      }
-    );
+    super(ATTACHMENT_TABLE_COLUMNS, {
+      ...options,
+      viewName: options?.viewName ?? ATTACHMENT_TABLE,
+      localOnly: true,
+      insertOnly: false
+    });
   }
 }
+
+/**
+ * AttachmentTableRecord represents the row type of the attachment table.
+ *
+ * @alpha
+ */
+export type AttachmentTableRecord = RowType<AttachmentTable>;

package/src/attachments/SyncingService.ts

@@ -35,35 +35,58 @@ export class SyncingService {
 
   /**
    * Processes attachments based on their state (upload, download, or delete).
-   * All updates are saved in a single batch after processing.
+   *
+   * Each attachment's I/O runs outside the attachment-service mutex, and the row's
+   * state transition is persisted immediately after it completes. This keeps the
+   * mutex available to concurrent `saveFile` / `deleteFile` / watched-attachment
+   * processing while a batch is in flight, and means consumer queries against the
+   * attachments queue see incremental progress instead of one atomic commit at the
+   * end of the batch.
    *
    * @param attachments - Array of attachment records to process
-   * @param context - Attachment context for database operations
-   * @returns Promise that resolves when all attachments have been processed and saved
+   * @param options - Optional controls. Pass `signal` (an `AbortSignal`) to interrupt
+   *                  the batch: it is checked between attachments and, once aborted, the
+   *                  loop exits early — letting `stopSync` stop a running batch within
+   *                  one attachment's processing time.
    */
-  async processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void> {
-    const updatedAttachments: AttachmentRecord[] = [];
+  async processAttachments(
+    attachments: AttachmentRecord[],
+    options?: {
+      signal?: AbortSignal;
+    }
+  ): Promise<void> {
+    const signal = options?.signal;
+    this.logger.info(`Starting processAttachments with ${attachments.length} attachments`);
+
     for (const attachment of attachments) {
-      switch (attachment.state) {
-        case AttachmentState.QUEUED_UPLOAD:
-          const uploaded = await this.uploadAttachment(attachment);
-          updatedAttachments.push(uploaded);
-          break;
-        case AttachmentState.QUEUED_DOWNLOAD:
-          const downloaded = await this.downloadAttachment(attachment);
-          updatedAttachments.push(downloaded);
-          break;
-        case AttachmentState.QUEUED_DELETE:
-          const deleted = await this.deleteAttachment(attachment, context);
-          updatedAttachments.push(deleted);
-          break;
-
-        default:
-          break;
+      if (signal?.aborted) {
+        this.logger.info('Sync cancelled; stopping iteration early');
+        return;
       }
-    }
 
-    await context.saveAttachments(updatedAttachments);
+      try {
+        let updated: AttachmentRecord;
+        switch (attachment.state) {
+          case AttachmentState.QUEUED_UPLOAD:
+            updated = await this.uploadAttachment(attachment);
+            break;
+          case AttachmentState.QUEUED_DOWNLOAD:
+            updated = await this.downloadAttachment(attachment);
+            break;
+          case AttachmentState.QUEUED_DELETE:
+            // `deleteAttachment` needs a context (it removes the row in a
+            // transaction); briefly re-acquire the mutex for just this row.
+            updated = await this.attachmentService.withContext((ctx) => this.deleteAttachment(attachment, ctx));
+            break;
+          default:
+            continue;
+        }
+
+        await this.attachmentService.withContext((ctx) => ctx.saveAttachments([updated]));
+      } catch (error) {
+        this.logger.warn(`Error during sync for ${attachment.id}`, error);
+      }
+    }
   }
 
   /**

package/src/client/triggers/TriggerManagerImpl.ts

@@ -419,7 +419,12 @@ export class TriggerManagerImpl implements TriggerManager {
           // destination table consistent.
           await this.db.writeTransaction(async (tx) => {
             const callbackResult = await options.onChange({
-              ...tx,
+              execute: (query, params) => tx.execute(query, params),
+              executeBatch: (query, params) => tx.executeBatch(query, params),
+              executeRaw: (query, params) => tx.executeRaw(query, params),
+              get: (query, params) => tx.get(query, params),
+              getAll: (query, params) => tx.getAll(query, params),
+              getOptional: (query, params) => tx.getOptional(query, params),
               destinationTable: destination,
               withDiff: async <T>(query: string, params: any, options?: WithDiffOptions) => {
                 // Wrap the query to expose the destination table

package/src/db/crud/SyncStatus.ts

@@ -138,7 +138,7 @@ export class SyncStatus {
   }
 
   /**
-   * All sync streams currently being tracked in teh database.
+   * All sync streams currently being tracked in the database.
    *
    * This returns null when the database is currently being opened and we don't have reliable information about all
    * included streams yet.