@powersync/common 1.49.0 → 1.50.0

package/dist/bundle.node.mjs

@@ -1,4 +1,3 @@
-import { Mutex } from 'async-mutex';
 import { EventIterator } from 'event-iterator';
 import { Buffer } from 'node:buffer';
 
@@ -659,7 +658,7 @@ class SyncingService {
                     updatedAttachments.push(downloaded);
                     break;
                 case AttachmentState.QUEUED_DELETE:
-                    const deleted = await this.deleteAttachment(attachment);
+                    const deleted = await this.deleteAttachment(attachment, context);
                     updatedAttachments.push(deleted);
                     break;
             }
@@ -737,17 +736,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: AttachmentState.ARCHIVED
@@ -785,32 +783,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;
 }
 
 /**
@@ -859,7 +933,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);
         });
     }
@@ -895,9 +969,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;
@@ -921,8 +1001,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
      */
@@ -8059,7 +8139,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.49.0";
+var version = "1.50.0";
 var PACKAGE = {
 	version: version};
 
@@ -10916,6 +10996,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
@@ -11012,7 +11096,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 });
@@ -11989,5 +12073,5 @@ const parseQuery = (query, parameters) => {
     return { sqlStatement, parameters: parameters };
 };
 
-export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DBAdapterDefaultMixin, DBGetUtilsDefaultMixin, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, mutexRunExclusive, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
+export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DBAdapterDefaultMixin, DBGetUtilsDefaultMixin, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, Mutex, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID, timeoutSignal };
 //# sourceMappingURL=bundle.node.mjs.map