@powersync/common 1.49.0 → 1.51.0

package/lib/utils/mutex.d.ts

@@ -1,7 +1,49 @@
-import { Mutex } from 'async-mutex';
+export type UnlockFn = () => void;
 /**
- * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ * 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.
  */
-export declare function mutexRunExclusive<T>(mutex: Mutex, callback: () => Promise<T>, options?: {
-    timeoutMs?: number;
-}): Promise<T>;
+export declare class Semaphore<T> {
+    private readonly available;
+    readonly size: number;
+    private firstWaiter?;
+    private lastWaiter?;
+    constructor(elements: Iterable<T>);
+    private addWaiter;
+    private deactivateWaiter;
+    private requestPermits;
+    /**
+     * Requests a single item from the pool.
+     *
+     * The returned `release` callback must be invoked to return the item into the pool.
+     */
+    requestOne(abort?: AbortSignal): Promise<{
+        item: T;
+        release: UnlockFn;
+    }>;
+    /**
+     * Requests access to all items from the pool.
+     *
+     * The returned `release` callback must be invoked to return items into the pool.
+     */
+    requestAll(abort?: AbortSignal): Promise<{
+        items: T[];
+        release: UnlockFn;
+    }>;
+}
+/**
+ * An asynchronous mutex implementation.
+ *
+ * @internal This class is meant to be used in PowerSync SDKs only, and is not part of the public API.
+ */
+export declare class Mutex {
+    private inner;
+    acquire(abort?: AbortSignal): Promise<UnlockFn>;
+    runExclusive<T>(fn: () => PromiseLike<T> | T, abort?: AbortSignal): Promise<T>;
+}
+/**
+ * Creates a signal aborting after the set timeout.
+ */
+export declare function timeoutSignal(timeout: number): AbortSignal;
+export declare function timeoutSignal(timeout?: number): AbortSignal | undefined;

package/lib/utils/mutex.js

@@ -1,29 +1,154 @@
+import { Queue } from './queue.js';
 /**
- * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ * 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.
  */
-export 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);
+export 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 (timedOut)
-                return;
-            try {
-                resolve(await callback());
+            if (abort?.aborted) {
+                return rejectAborted();
             }
-            catch (ex) {
-                reject(ex);
+            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--;
             }
+            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.
+ */
+export 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();
+        }
+    }
+}
+export 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;
 }
 //# sourceMappingURL=mutex.js.map

package/lib/utils/mutex.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/utils/mutex.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAY,EACZ,QAA0B,EAC1B,OAAgC;IAEhC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,OAAO,EAAE,SAAS,CAAC;QACnC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,MAAM,SAAS,GAAG,OAAO;YACvB,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE;gBACd,QAAQ,GAAG,IAAI,CAAC;gBAChB,MAAM,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;YAChD,CAAC,EAAE,OAAO,CAAC;YACb,CAAC,CAAC,SAAS,CAAC;QAEd,KAAK,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE;YAC5B,IAAI,SAAS,EAAE,CAAC;gBACd,YAAY,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;YACD,IAAI,QAAQ;gBAAE,OAAO;YAErB,IAAI,CAAC;gBACH,OAAO,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;YAC5B,CAAC;YAAC,OAAO,EAAE,EAAE,CAAC;gBACZ,MAAM,CAAC,EAAE,CAAC,CAAC;YACb,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"mutex.js","sourceRoot":"","sources":["../../src/utils/mutex.ts"],"names":[],"mappings":"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"}

package/lib/utils/queue.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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}.
+ */
+export declare class Queue<T> {
+    private table;
+    private head;
+    private _length;
+    constructor(initialItems: Iterable<T>);
+    get isEmpty(): boolean;
+    get length(): number;
+    removeFirst(): T;
+    addLast(element: T): void;
+}

package/lib/utils/queue.js

@@ -0,0 +1,42 @@
+/**
+ * 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}.
+ */
+export 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++;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/lib/utils/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../../src/utils/queue.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,OAAO,KAAK;IACR,KAAK,CAAoB;IACjC,2CAA2C;IACnC,IAAI,CAAS;IACrB,0CAA0C;IAClC,OAAO,CAAS;IAExB,YAAY,YAAyB;QACnC,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QACd,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IACnC,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,WAAW;QACT,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACpC,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAM,CAAC;QAC1C,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QAChD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,OAAU;QAChB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;QACrE,IAAI,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -48,7 +48,6 @@
   },
   "homepage": "https://docs.powersync.com",
   "dependencies": {
-    "async-mutex": "^0.5.0",
     "event-iterator": "^2.0.0"
   },
   "devDependencies": {

package/src/attachments/AttachmentQueue.ts

@@ -51,10 +51,16 @@ export class AttachmentQueue {
   /** Logger instance for diagnostic information */
   readonly logger: ILogger;
 
-  /** 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) */
   readonly syncIntervalMs: number = 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) */
   readonly syncThrottleDuration: number;
 
   /** Whether to automatically download remote attachments. Default: true */
@@ -86,8 +92,8 @@ export 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
    */

package/src/attachments/AttachmentService.ts

@@ -1,8 +1,7 @@
-import { Mutex } from 'async-mutex';
 import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
 import { DifferentialWatchedQuery } from '../client/watched/processors/DifferentialQueryProcessor.js';
 import { ILogger } from '../utils/Logger.js';
-import { mutexRunExclusive } from '../utils/mutex.js';
+import { Mutex } from '../utils/mutex.js';
 import { AttachmentContext } from './AttachmentContext.js';
 import { AttachmentRecord, AttachmentState } from './Schema.js';
 
@@ -55,7 +54,7 @@ export class AttachmentService {
    * Executes a callback with exclusive access to the attachment context.
    */
   async withContext<T>(callback: (context: AttachmentContext) => Promise<T>): Promise<T> {
-    return mutexRunExclusive(this.mutex, async () => {
+    return this.mutex.runExclusive(async () => {
       return callback(this.context);
     });
   }

package/src/attachments/README.md

@@ -289,8 +289,8 @@ new AttachmentQueue(options: AttachmentQueueOptions)
 | `watchAttachments` | `(onUpdate: (attachments: WatchedAttachmentItem[]) => Promise<void>) => void` | Yes | - | Callback to determine which attachments to handle by the queue from your user defined query |
 | `tableName` | `string` | No | `'attachments'` | Name of the attachments table |
 | `logger` | `ILogger` | No | `db.logger` | Logger instance for diagnostic output |
-| `syncIntervalMs` | `number` | No | `30000` | Interval between automatic syncs in milliseconds |
-| `syncThrottleDuration` | `number` | No | `30` | Throttle duration for sync operations in milliseconds |
+| `syncIntervalMs` | `number` | No | `30000` | Periodic polling interval (in milliseconds) for retrying failed uploads/downloads. A `setInterval` timer that calls `syncStorage()` on this cadence, ensuring operations are retried even if no database changes occur (e.g., after coming back online). |
+| `syncThrottleDuration` | `number` | No | `30` | Throttle duration (in milliseconds) for the reactive watch query on the attachments table. When attachment records change (e.g., a new file is queued), 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. |
 | `downloadAttachments` | `boolean` | No | `true` | Whether to automatically download remote attachments |
 | `archivedCacheLimit` | `number` | No | `100` | Maximum number of archived attachments before cleanup |
 | `errorHandler` | `AttachmentErrorHandler` | No | `undefined` | Custom error handler for upload/download/delete operations |
@@ -676,11 +676,13 @@ Adjust sync frequency based on your needs:
 ```typescript
 const queue = new AttachmentQueue({
   // ... other options
-  syncIntervalMs: 60000, // Sync every 60 seconds instead of 30
+  syncIntervalMs: 60000, // Poll for retries every 60 seconds instead of 30
+  syncThrottleDuration: 100, // React to attachment changes within 100ms (default: 30ms)
 });
 ```
 
-Set to `0` to disable periodic syncing (manual `syncStorage()` calls only).
+- **`syncIntervalMs`** controls the periodic polling timer — how often the queue retries failed operations.
+- **`syncThrottleDuration`** controls how quickly the queue reacts to attachment table changes. The default (30ms) is fast enough for most use cases. Increase it if you see performance issues during bulk attachment operations.
 
 ### Archive and Cache Management
 

package/src/attachments/SyncingService.ts

@@ -54,7 +54,7 @@ export 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;
 
@@ -143,18 +143,17 @@ export 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: AttachmentRecord): Promise<AttachmentRecord> {
+  async deleteAttachment(attachment: AttachmentRecord, context: AttachmentContext): Promise<AttachmentRecord> {
     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,

package/src/client/AbstractPowerSyncDatabase.ts

@@ -1,4 +1,3 @@
-import { Mutex } from 'async-mutex';
 import { EventIterator } from 'event-iterator';
 import Logger, { ILogger } from 'js-logger';
 import {
@@ -46,6 +45,7 @@ import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { DEFAULT_WATCH_THROTTLE_MS, WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { Mutex } from '../utils/mutex.js';
 
 export interface DisconnectAndClearOptions {
   /** When set to false, data in local-only tables is preserved. */
@@ -813,6 +813,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
@@ -921,7 +925,7 @@ SELECT * FROM crud_entries;
     await this.waitForReady();
     return this.database.readTransaction(
       async (tx) => {
-        const res = await callback({ ...tx });
+        const res = await callback(tx);
         await tx.rollback();
         return res;
       },

package/src/db/DBAdapter.ts

@@ -16,7 +16,13 @@ import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
 export type QueryResult = {
   /** Represents the auto-generated row id if applicable. */
   insertId?: number;
-  /** Number of affected rows if result of a update query. */
+  /**
+   * Number of affected rows reported by SQLite for a write query.
+   *
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `rows` when you need to confirm which rows changed.
+   */
   rowsAffected: number;
   /** if status is undefined or 0 this object will contain the query results */
   rows?: {