@powersync/common 1.55.0 → 1.57.0

package/dist/bundle.node.cjs

@@ -391,6 +391,19 @@ exports.AttachmentState = void 0;
     AttachmentState[AttachmentState["SYNCED"] = 3] = "SYNCED";
     AttachmentState[AttachmentState["ARCHIVED"] = 4] = "ARCHIVED"; // Attachment has been orphaned, i.e. the associated record has been deleted
 })(exports.AttachmentState || (exports.AttachmentState = {}));
+/**
+ * @alpha
+ */
+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.
  *
@@ -398,16 +411,7 @@ exports.AttachmentState = void 0;
  */
 class AttachmentTable extends Table {
     constructor(options) {
-        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
-        }, {
+        super(ATTACHMENT_TABLE_COLUMNS, {
             ...options,
             viewName: options?.viewName ?? ATTACHMENT_TABLE,
             localOnly: true,
@@ -939,31 +943,51 @@ 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
-     */
-    async processAttachments(attachments, context) {
-        const updatedAttachments = [];
+     * @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, options) {
+        const signal = options?.signal;
+        this.logger.info(`Starting processAttachments with ${attachments.length} attachments`);
         for (const attachment of attachments) {
-            switch (attachment.state) {
-                case exports.AttachmentState.QUEUED_UPLOAD:
-                    const uploaded = await this.uploadAttachment(attachment);
-                    updatedAttachments.push(uploaded);
-                    break;
-                case exports.AttachmentState.QUEUED_DOWNLOAD:
-                    const downloaded = await this.downloadAttachment(attachment);
-                    updatedAttachments.push(downloaded);
-                    break;
-                case exports.AttachmentState.QUEUED_DELETE:
-                    const deleted = await this.deleteAttachment(attachment, context);
-                    updatedAttachments.push(deleted);
-                    break;
+            if (signal?.aborted) {
+                this.logger.info('Sync cancelled; stopping iteration early');
+                return;
+            }
+            try {
+                let updated;
+                switch (attachment.state) {
+                    case exports.AttachmentState.QUEUED_UPLOAD:
+                        updated = await this.uploadAttachment(attachment);
+                        break;
+                    case exports.AttachmentState.QUEUED_DOWNLOAD:
+                        updated = await this.downloadAttachment(attachment);
+                        break;
+                    case exports.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);
             }
         }
-        await context.saveAttachments(updatedAttachments);
     }
     /**
      * Uploads an attachment from local storage to remote storage.
@@ -1134,6 +1158,19 @@ class AttachmentQueue {
     statusListenerDispose;
     watchActiveAttachments;
     watchAttachmentsAbortController;
+    /**
+     * 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.
+     */
+    syncLoopMutex = new Mutex();
+    /**
+     * Aborted by `stopSync()` to interrupt an in-flight batch within one
+     * attachment's processing time. Polled between rows by `SyncingService`.
+     */
+    syncAbortController;
     /**
      * Creates a new AttachmentQueue instance.
      *
@@ -1173,6 +1210,7 @@ class AttachmentQueue {
      */
     async startSync() {
         await this.stopSync();
+        this.syncAbortController = new AbortController();
         this.watchActiveAttachments = this.attachmentService.watchActiveAttachments({
             throttleMs: this.syncThrottleDuration
         });
@@ -1287,23 +1325,44 @@ 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() {
-        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() {
         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) {
@@ -2139,11 +2198,7 @@ class SyncStatus {
          */
         const replacer = (_, value) => {
             if (value instanceof Error) {
-                return {
-                    name: value.name,
-                    message: value.message,
-                    stack: value.stack
-                };
+                return this.serializeError(value);
             }
             return value;
         };
@@ -2186,11 +2241,18 @@ class SyncStatus {
         if (typeof error == 'undefined') {
             return undefined;
         }
-        return {
+        const serialized = {
             name: error.name,
             message: error.message,
             stack: error.stack
         };
+        // `Error.cause` can be any value (the spec types it as unknown). Preserve it
+        // so consumers reading uploadError/downloadError keep the failure context.
+        // Recurse for Error causes so the whole chain is flattened the same way.
+        if (typeof error.cause != 'undefined') {
+            serialized.cause = error.cause instanceof Error ? this.serializeError(error.cause) : error.cause;
+        }
+        return serialized;
     }
     static comparePriorities(a, b) {
         return b.priority - a.priority; // Reverse because higher priorities have lower numbers
@@ -8544,7 +8606,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.55.0";
+var version = "1.57.0";
 var PACKAGE = {
 	version: version};
 
@@ -10675,7 +10737,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
             this.logger.warn('Schema validation failed. Unexpected behaviour could occur', ex);
         }
         this._schema = schema;
-        await this.database.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())]);
+        await this.database.writeTransaction((tx) => tx.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())]));
         await this.database.refreshSchema();
         this.iterateListeners(async (cb) => cb.schemaChanged?.(schema));
     }
@@ -11872,6 +11934,7 @@ const parseQuery = (query, parameters) => {
 };
 
 exports.ATTACHMENT_TABLE = ATTACHMENT_TABLE;
+exports.ATTACHMENT_TABLE_COLUMNS = ATTACHMENT_TABLE_COLUMNS;
 exports.AbortOperation = AbortOperation;
 exports.AbstractPowerSyncDatabase = AbstractPowerSyncDatabase;
 exports.AbstractPowerSyncDatabaseOpenFactory = AbstractPowerSyncDatabaseOpenFactory;