@powersync/common 1.48.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
      */
@@ -1532,6 +1612,49 @@ var Logger = /*@__PURE__*/getDefaultExportFromCjs(loggerExports);
  * Set of generic interfaces to allow PowerSync compatibility with
  * different SQLite DB implementations.
  */
+/**
+ * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ */
+function DBGetUtilsDefaultMixin(Base) {
+    return class extends Base {
+        async getAll(sql, parameters) {
+            const res = await this.execute(sql, parameters);
+            return res.rows?._array ?? [];
+        }
+        async getOptional(sql, parameters) {
+            const res = await this.execute(sql, parameters);
+            return res.rows?.item(0) ?? null;
+        }
+        async get(sql, parameters) {
+            const res = await this.execute(sql, parameters);
+            const first = res.rows?.item(0);
+            if (!first) {
+                throw new Error('Result set is empty');
+            }
+            return first;
+        }
+        async executeBatch(query, params = []) {
+            // If this context can run batch statements natively, use that.
+            // @ts-ignore
+            if (super.executeBatch) {
+                // @ts-ignore
+                return super.executeBatch(query, params);
+            }
+            // Emulate executeBatch by running statements individually.
+            let lastInsertId;
+            let rowsAffected = 0;
+            for (const set of params) {
+                const result = await this.execute(query, set);
+                lastInsertId = result.insertId;
+                rowsAffected += result.rowsAffected;
+            }
+            return {
+                rowsAffected,
+                insertId: lastInsertId
+            };
+        }
+    };
+}
 /**
  * Update table operation numbers from SQLite
  */
@@ -1541,6 +1664,89 @@ exports.RowUpdateType = void 0;
     RowUpdateType[RowUpdateType["SQLITE_DELETE"] = 9] = "SQLITE_DELETE";
     RowUpdateType[RowUpdateType["SQLITE_UPDATE"] = 23] = "SQLITE_UPDATE";
 })(exports.RowUpdateType || (exports.RowUpdateType = {}));
+/**
+ * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool.readLock} and
+ * {@link ConnectionPool.writeLock}.
+ */
+function DBAdapterDefaultMixin(Base) {
+    return class extends Base {
+        readTransaction(fn, options) {
+            return this.readLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
+        }
+        writeTransaction(fn, options) {
+            return this.writeLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
+        }
+        getAll(sql, parameters) {
+            return this.readLock((ctx) => ctx.getAll(sql, parameters));
+        }
+        getOptional(sql, parameters) {
+            return this.readLock((ctx) => ctx.getOptional(sql, parameters));
+        }
+        get(sql, parameters) {
+            return this.readLock((ctx) => ctx.get(sql, parameters));
+        }
+        execute(query, params) {
+            return this.writeLock((ctx) => ctx.execute(query, params));
+        }
+        executeRaw(query, params) {
+            return this.writeLock((ctx) => ctx.executeRaw(query, params));
+        }
+        executeBatch(query, params) {
+            return this.writeTransaction((tx) => tx.executeBatch(query, params));
+        }
+    };
+}
+class BaseTransaction {
+    inner;
+    finalized = false;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    async commit() {
+        if (this.finalized) {
+            return { rowsAffected: 0 };
+        }
+        this.finalized = true;
+        return this.inner.execute('COMMIT');
+    }
+    async rollback() {
+        if (this.finalized) {
+            return { rowsAffected: 0 };
+        }
+        this.finalized = true;
+        return this.inner.execute('ROLLBACK');
+    }
+    execute(query, params) {
+        return this.inner.execute(query, params);
+    }
+    executeRaw(query, params) {
+        return this.inner.executeRaw(query, params);
+    }
+    executeBatch(query, params) {
+        return this.inner.executeBatch(query, params);
+    }
+}
+class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction) {
+    static async runWith(ctx, fn) {
+        let tx = new TransactionImplementation(ctx);
+        try {
+            await ctx.execute('BEGIN IMMEDIATE');
+            const result = await fn(tx);
+            await tx.commit();
+            return result;
+        }
+        catch (ex) {
+            try {
+                await tx.rollback();
+            }
+            catch (ex2) {
+                // In rare cases, a rollback may fail.
+                // Safe to ignore.
+            }
+            throw ex;
+        }
+    }
+}
 function isBatchedUpdateNotification(update) {
     return 'tables' in update;
 }
@@ -7935,7 +8141,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.48.0";
+var version = "1.50.0";
 var PACKAGE = {
 	version: version};
 
@@ -9968,7 +10174,7 @@ class TriggerManagerImpl {
     }
     async createDiffTrigger(options) {
         await this.db.waitForReady();
-        const { source, destination, columns, when, hooks, 
+        const { source, destination, columns, when, hooks, setupContext, 
         // Fall back to the provided default if not given on this level
         useStorage = this.defaultConfig.useStorageByDefault } = options;
         const operations = Object.keys(when);
@@ -10023,13 +10229,20 @@ class TriggerManagerImpl {
          * we need to ensure we can cleanup the created resources.
          * We unfortunately cannot rely on transaction rollback.
          */
-        const cleanup = async () => {
+        const cleanup = async (options) => {
+            const { context } = options ?? {};
             disposeWarningListener();
-            return this.db.writeLock(async (tx) => {
+            const doCleanup = async (tx) => {
                 await this.removeTriggers(tx, triggerIds);
-                await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+                await tx.execute(`DROP TABLE IF EXISTS ${destination};`);
                 await releaseStorageClaim?.();
-            });
+            };
+            if (context) {
+                await doCleanup(context);
+            }
+            else {
+                await this.db.writeLock(doCleanup);
+            }
         };
         const setup = async (tx) => {
             // Allow user code to execute in this lock context before the trigger is created.
@@ -10103,12 +10316,17 @@ class TriggerManagerImpl {
             }
         };
         try {
-            await this.db.writeLock(setup);
+            if (setupContext) {
+                await setup(setupContext);
+            }
+            else {
+                await this.db.writeLock(setup);
+            }
             return cleanup;
         }
         catch (error) {
             try {
-                await cleanup();
+                await cleanup(setupContext ? { context: setupContext } : undefined);
             }
             catch (cleanupError) {
                 throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
@@ -10315,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),
@@ -10780,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
@@ -10876,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 });
@@ -11873,6 +12095,8 @@ exports.ControlledExecutor = ControlledExecutor;
 exports.CrudBatch = CrudBatch;
 exports.CrudEntry = CrudEntry;
 exports.CrudTransaction = CrudTransaction;
+exports.DBAdapterDefaultMixin = DBAdapterDefaultMixin;
+exports.DBGetUtilsDefaultMixin = DBGetUtilsDefaultMixin;
 exports.DEFAULT_CRUD_BATCH_LIMIT = DEFAULT_CRUD_BATCH_LIMIT;
 exports.DEFAULT_CRUD_UPLOAD_THROTTLE_MS = DEFAULT_CRUD_UPLOAD_THROTTLE_MS;
 exports.DEFAULT_INDEX_COLUMN_OPTIONS = DEFAULT_INDEX_COLUMN_OPTIONS;
@@ -11904,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;
@@ -11937,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