@powersync/common 1.49.0 → 1.50.0

package/dist/bundle.node.cjs

@@ -1,6 +1,5 @@
 'use strict';
 
-var asyncMutex = require('async-mutex');
 var eventIterator = require('event-iterator');
 var node_buffer = require('node:buffer');
 
@@ -661,7 +660,7 @@ class SyncingService {
                     updatedAttachments.push(downloaded);
                     break;
                 case exports.AttachmentState.QUEUED_DELETE:
-                    const deleted = await this.deleteAttachment(attachment);
+                    const deleted = await this.deleteAttachment(attachment, context);
                     updatedAttachments.push(deleted);
                     break;
             }
@@ -739,17 +738,16 @@ class SyncingService {
      * On failure, defers to error handler or archives.
      *
      * @param attachment - The attachment record to delete
+     * @param context - Attachment context for database operations
      * @returns Updated attachment record
      */
-    async deleteAttachment(attachment) {
+    async deleteAttachment(attachment, context) {
         try {
             await this.remoteStorage.deleteFile(attachment);
             if (attachment.localUri) {
                 await this.localStorage.deleteFile(attachment.localUri);
             }
-            await this.attachmentService.withContext(async (ctx) => {
-                await ctx.deleteAttachment(attachment.id);
-            });
+            await context.deleteAttachment(attachment.id);
             return {
                 ...attachment,
                 state: exports.AttachmentState.ARCHIVED
@@ -787,32 +785,108 @@ class SyncingService {
 }
 
 /**
- * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
  */
-async function mutexRunExclusive(mutex, callback, options) {
-    return new Promise((resolve, reject) => {
-        const timeout = options?.timeoutMs;
-        let timedOut = false;
-        const timeoutId = timeout
-            ? setTimeout(() => {
-                timedOut = true;
-                reject(new Error('Timeout waiting for lock'));
-            }, timeout)
-            : undefined;
-        mutex.runExclusive(async () => {
-            if (timeoutId) {
-                clearTimeout(timeoutId);
-            }
-            if (timedOut)
-                return;
-            try {
-                resolve(await callback());
+class Mutex {
+    inCriticalSection = false;
+    // Linked list of waiters. We don't expect the wait list to become particularly large, and this allows removing
+    // aborted waiters from the middle of the list efficiently.
+    firstWaiter;
+    lastWaiter;
+    addWaiter(onAcquire) {
+        const node = {
+            isActive: true,
+            onAcquire,
+            prev: this.lastWaiter
+        };
+        if (this.lastWaiter) {
+            this.lastWaiter.next = node;
+            this.lastWaiter = node;
+        }
+        else {
+            // First waiter
+            this.lastWaiter = this.firstWaiter = node;
+        }
+        return node;
+    }
+    deactivateWaiter(waiter) {
+        const { prev, next } = waiter;
+        waiter.isActive = false;
+        if (prev)
+            prev.next = next;
+        if (next)
+            next.prev = prev;
+        if (waiter == this.firstWaiter)
+            this.firstWaiter = next;
+        if (waiter == this.lastWaiter)
+            this.lastWaiter = prev;
+    }
+    acquire(abort) {
+        return new Promise((resolve, reject) => {
+            function rejectAborted() {
+                reject(abort?.reason ?? new Error('Mutex acquire aborted'));
             }
-            catch (ex) {
-                reject(ex);
+            if (abort?.aborted) {
+                return rejectAborted();
+            }
+            let holdsMutex = false;
+            const markCompleted = () => {
+                if (!holdsMutex)
+                    return;
+                holdsMutex = false;
+                const waiter = this.firstWaiter;
+                if (waiter) {
+                    this.deactivateWaiter(waiter);
+                    // Still in critical section, but owned by next waiter now.
+                    waiter.onAcquire();
+                }
+                else {
+                    this.inCriticalSection = false;
+                }
+            };
+            if (!this.inCriticalSection) {
+                this.inCriticalSection = true;
+                holdsMutex = true;
+                return resolve(markCompleted);
+            }
+            else {
+                let node;
+                const onAbort = () => {
+                    abort?.removeEventListener('abort', onAbort);
+                    if (node.isActive) {
+                        this.deactivateWaiter(node);
+                        rejectAborted();
+                    }
+                };
+                node = this.addWaiter(() => {
+                    abort?.removeEventListener('abort', onAbort);
+                    holdsMutex = true;
+                    resolve(markCompleted);
+                });
+                abort?.addEventListener('abort', onAbort);
             }
         });
-    });
+    }
+    async runExclusive(fn, abort) {
+        const returnMutex = await this.acquire(abort);
+        try {
+            return await fn();
+        }
+        finally {
+            returnMutex();
+        }
+    }
+}
+function timeoutSignal(timeout) {
+    if (timeout == null)
+        return;
+    if ('timeout' in AbortSignal)
+        return AbortSignal.timeout(timeout);
+    const controller = new AbortController();
+    setTimeout(() => controller.abort(new Error('Timeout waiting for lock')), timeout);
+    return controller.signal;
 }
 
 /**
@@ -824,7 +898,7 @@ class AttachmentService {
     db;
     logger;
     tableName;
-    mutex = new asyncMutex.Mutex();
+    mutex = new Mutex();
     context;
     constructor(db, logger, tableName = 'attachments', archivedCacheLimit = 100) {
         this.db = db;
@@ -861,7 +935,7 @@ class AttachmentService {
      * Executes a callback with exclusive access to the attachment context.
      */
     async withContext(callback) {
-        return mutexRunExclusive(this.mutex, async () => {
+        return this.mutex.runExclusive(async () => {
             return callback(this.context);
         });
     }
@@ -897,9 +971,15 @@ class AttachmentQueue {
     tableName;
     /** Logger instance for diagnostic information */
     logger;
-    /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+    /** Interval in milliseconds between periodic sync operations. Acts as a polling timer to retry
+     *  failed uploads/downloads, especially after the app goes offline. Default: 30000 (30 seconds) */
     syncIntervalMs = 30 * 1000;
-    /** Duration in milliseconds to throttle sync operations */
+    /** Throttle duration in milliseconds for the reactive watch query on the attachments table.
+     *  When attachment records change, a watch query detects the change and triggers a sync.
+     *  This throttle prevents the sync from firing too rapidly when many changes happen in
+     *  quick succession (e.g., bulk inserts). This is distinct from syncIntervalMs — it controls
+     *  how quickly the queue reacts to changes, while syncIntervalMs controls how often it polls
+     *  for retries. Default: 30 (from DEFAULT_WATCH_THROTTLE_MS) */
     syncThrottleDuration;
     /** Whether to automatically download remote attachments. Default: true */
     downloadAttachments = true;
@@ -923,8 +1003,8 @@ class AttachmentQueue {
      * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
      * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
      * @param options.logger - Logger instance. Defaults to db.logger
-     * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
-     * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
+     * @param options.syncIntervalMs - Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
+     * @param options.syncThrottleDuration - Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
      * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
      * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
      */
@@ -8061,7 +8141,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.49.0";
+var version = "1.50.0";
 var PACKAGE = {
 	version: version};
 
@@ -10453,7 +10533,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         this._schema = schema;
         this.ready = false;
         this.sdkVersion = '';
-        this.runExclusiveMutex = new asyncMutex.Mutex();
+        this.runExclusiveMutex = new Mutex();
         // Start async init
         this.subscriptions = {
             firstStatusMatching: (predicate, abort) => this.waitForStatus(predicate, abort),
@@ -10918,6 +10998,10 @@ SELECT * FROM crud_entries;
      * Execute a SQL write (INSERT/UPDATE/DELETE) query
      * and optionally return results.
      *
+     * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+     * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+     * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
+     *
      * @param sql The SQL query to execute
      * @param parameters Optional array of parameters to bind to the query
      * @returns The query result as an object with structured key-value pairs
@@ -11014,7 +11098,7 @@ SELECT * FROM crud_entries;
     async readTransaction(callback, lockTimeout = DEFAULT_LOCK_TIMEOUT_MS) {
         await this.waitForReady();
         return this.database.readTransaction(async (tx) => {
-            const res = await callback({ ...tx });
+            const res = await callback(tx);
             await tx.rollback();
             return res;
         }, { timeoutMs: lockTimeout });
@@ -12044,6 +12128,7 @@ exports.LogLevel = LogLevel;
 exports.MAX_AMOUNT_OF_COLUMNS = MAX_AMOUNT_OF_COLUMNS;
 exports.MAX_OP_ID = MAX_OP_ID;
 exports.MEMORY_TRIGGER_CLAIM_MANAGER = MEMORY_TRIGGER_CLAIM_MANAGER;
+exports.Mutex = Mutex;
 exports.OnChangeQueryProcessor = OnChangeQueryProcessor;
 exports.OpType = OpType;
 exports.OplogEntry = OplogEntry;
@@ -12077,9 +12162,9 @@ exports.isStreamingSyncCheckpointDiff = isStreamingSyncCheckpointDiff;
 exports.isStreamingSyncCheckpointPartiallyComplete = isStreamingSyncCheckpointPartiallyComplete;
 exports.isStreamingSyncData = isStreamingSyncData;
 exports.isSyncNewCheckpointRequest = isSyncNewCheckpointRequest;
-exports.mutexRunExclusive = mutexRunExclusive;
 exports.parseQuery = parseQuery;
 exports.runOnSchemaChange = runOnSchemaChange;
 exports.sanitizeSQL = sanitizeSQL;
 exports.sanitizeUUID = sanitizeUUID;
+exports.timeoutSignal = timeoutSignal;
 //# sourceMappingURL=bundle.node.cjs.map