@powersync/common 1.48.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
      */
@@ -1530,6 +1610,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
  */
@@ -1539,6 +1662,89 @@ var RowUpdateType;
     RowUpdateType[RowUpdateType["SQLITE_DELETE"] = 9] = "SQLITE_DELETE";
     RowUpdateType[RowUpdateType["SQLITE_UPDATE"] = 23] = "SQLITE_UPDATE";
 })(RowUpdateType || (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;
 }
@@ -7933,7 +8139,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.48.0";
+var version = "1.50.0";
 var PACKAGE = {
 	version: version};
 
@@ -9966,7 +10172,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);
@@ -10021,13 +10227,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.
@@ -10101,12 +10314,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');
@@ -10778,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
@@ -10874,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 });
@@ -11851,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, 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