@powersync/common 1.49.0 → 1.51.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,198 @@ class SyncingService {
 }
 
 /**
- * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ * A simple fixed-capacity queue implementation.
+ *
+ * Unlike a naive queue implemented by `array.push()` and `array.shift()`, this avoids moving array elements around
+ * and is `O(1)` for {@link addLast} and {@link removeFirst}.
  */
-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 Queue {
+    table;
+    // Index of the first element in the table.
+    head;
+    // Amount of items currently in the queue.
+    _length;
+    constructor(initialItems) {
+        this.table = [...initialItems];
+        this.head = 0;
+        this._length = this.table.length;
+    }
+    get isEmpty() {
+        return this.length == 0;
+    }
+    get length() {
+        return this._length;
+    }
+    removeFirst() {
+        if (this.isEmpty) {
+            throw new Error('Queue is empty');
+        }
+        const result = this.table[this.head];
+        this._length--;
+        this.table[this.head] = undefined;
+        this.head = (this.head + 1) % this.table.length;
+        return result;
+    }
+    addLast(element) {
+        if (this.length == this.table.length) {
+            throw new Error('Queue is full');
+        }
+        this.table[(this.head + this._length) % this.table.length] = element;
+        this._length++;
+    }
+}
+
+/**
+ * An asynchronous semaphore implementation with associated items per lease.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+class Semaphore {
+    // Available items that are not currently assigned to a waiter.
+    available;
+    size;
+    // 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;
+    constructor(elements) {
+        this.available = new Queue(elements);
+        this.size = this.available.length;
+    }
+    addWaiter(requestedItems, onAcquire) {
+        const node = {
+            isActive: true,
+            acquiredItems: [],
+            remainingItems: requestedItems,
+            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;
+    }
+    requestPermits(amount, abort) {
+        if (amount <= 0 || amount > this.size) {
+            throw new Error(`Invalid amount of items requested (${amount}), must be between 1 and ${this.size}`);
+        }
+        return new Promise((resolve, reject) => {
+            function rejectAborted() {
+                reject(abort?.reason ?? new Error('Semaphore acquire aborted'));
+            }
+            if (abort?.aborted) {
+                return rejectAborted();
+            }
+            let waiter;
+            const markCompleted = () => {
+                const items = waiter.acquiredItems;
+                waiter.acquiredItems = []; // Avoid releasing items twice.
+                for (const element of items) {
+                    // Give to next waiter, if possible.
+                    const nextWaiter = this.firstWaiter;
+                    if (nextWaiter) {
+                        nextWaiter.acquiredItems.push(element);
+                        nextWaiter.remainingItems--;
+                        if (nextWaiter.remainingItems == 0) {
+                            nextWaiter.onAcquire();
+                        }
+                    }
+                    else {
+                        // No pending waiter, return lease into pool.
+                        this.available.addLast(element);
+                    }
+                }
+            };
+            const onAbort = () => {
+                abort?.removeEventListener('abort', onAbort);
+                if (waiter.isActive) {
+                    this.deactivateWaiter(waiter);
+                    rejectAborted();
+                }
+            };
+            const resolvePromise = () => {
+                this.deactivateWaiter(waiter);
+                abort?.removeEventListener('abort', onAbort);
+                const items = waiter.acquiredItems;
+                resolve({ items, release: markCompleted });
+            };
+            waiter = this.addWaiter(amount, resolvePromise);
+            // If there are items in the pool that haven't been assigned, we can pull them into this waiter. Note that this is
+            // only the case if we're the first waiter (otherwise, items would have been assigned to an earlier waiter).
+            while (!this.available.isEmpty && waiter.remainingItems > 0) {
+                waiter.acquiredItems.push(this.available.removeFirst());
+                waiter.remainingItems--;
             }
-            catch (ex) {
-                reject(ex);
+            if (waiter.remainingItems == 0) {
+                return resolvePromise();
             }
+            abort?.addEventListener('abort', onAbort);
         });
-    });
+    }
+    /**
+     * Requests a single item from the pool.
+     *
+     * The returned `release` callback must be invoked to return the item into the pool.
+     */
+    async requestOne(abort) {
+        const { items, release } = await this.requestPermits(1, abort);
+        return { release, item: items[0] };
+    }
+    /**
+     * Requests access to all items from the pool.
+     *
+     * The returned `release` callback must be invoked to return items into the pool.
+     */
+    requestAll(abort) {
+        return this.requestPermits(this.size, abort);
+    }
+}
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+class Mutex {
+    inner = new Semaphore([null]);
+    async acquire(abort) {
+        const { release } = await this.inner.requestOne(abort);
+        return release;
+    }
+    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 +988,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 +1025,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 +1061,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 +1093,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 +8231,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.49.0";
+var version = "1.51.0";
 var PACKAGE = {
 	version: version};
 
@@ -10453,7 +10623,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 +11088,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 +11188,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,10 +12218,12 @@ 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;
 exports.Schema = Schema;
+exports.Semaphore = Semaphore;
 exports.SqliteBucketStorage = SqliteBucketStorage;
 exports.SyncDataBatch = SyncDataBatch;
 exports.SyncDataBucket = SyncDataBucket;
@@ -12077,9 +12253,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