@powersync/common 1.45.0 → 1.46.0

package/dist/bundle.node.cjs

@@ -6722,7 +6722,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.45.0";
+var version = "1.46.0";
 var PACKAGE = {
 	version: version};
 
@@ -6793,6 +6793,16 @@ class DataStream extends BaseObserver {
      * @returns a Data payload or Null if the stream closed.
      */
     async read() {
+        if (this.closed) {
+            return null;
+        }
+        // Wait for any pending processing to complete first.
+        // This ensures we register our listener before calling processQueue(),
+        // avoiding a race where processQueue() sees no reader and returns early.
+        if (this.processingPromise) {
+            await this.processingPromise;
+        }
+        // Re-check after await - stream may have closed while we were waiting
         if (this.closed) {
             return null;
         }
@@ -6832,7 +6842,7 @@ class DataStream extends BaseObserver {
         }
         const promise = (this.processingPromise = this._processQueue());
         promise.finally(() => {
-            return (this.processingPromise = null);
+            this.processingPromise = null;
         });
         return promise;
     }
@@ -6864,7 +6874,6 @@ class DataStream extends BaseObserver {
             this.notifyDataAdded = null;
         }
         if (this.dataQueue.length > 0) {
-            // Next tick
             setTimeout(() => this.processQueue());
         }
     }
@@ -7484,7 +7493,11 @@ class AbstractRemote {
         };
         const stream = new DataStream({
             logger: this.logger,
-            mapLine: mapLine
+            mapLine: mapLine,
+            pressure: {
+                highWaterMark: 20,
+                lowWaterMark: 10
+            }
         });
         abortSignal?.addEventListener('abort', () => {
             closeReader();
@@ -7492,42 +7505,47 @@ class AbstractRemote {
         });
         const decoder = this.createTextDecoder();
         let buffer = '';
-        const l = stream.registerListener({
-            lowWater: async () => {
-                if (stream.closed || abortSignal?.aborted || readerReleased) {
+        const consumeStream = async () => {
+            while (!stream.closed && !abortSignal?.aborted && !readerReleased) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    const remaining = buffer.trim();
+                    if (remaining.length != 0) {
+                        stream.enqueueData(remaining);
+                    }
+                    stream.close();
+                    await closeReader();
                     return;
                 }
-                try {
-                    let didCompleteLine = false;
-                    while (!didCompleteLine) {
-                        const { done, value } = await reader.read();
-                        if (done) {
-                            const remaining = buffer.trim();
-                            if (remaining.length != 0) {
-                                stream.enqueueData(remaining);
-                            }
-                            stream.close();
-                            await closeReader();
-                            return;
-                        }
-                        const data = decoder.decode(value, { stream: true });
-                        buffer += data;
-                        const lines = buffer.split('\n');
-                        for (var i = 0; i < lines.length - 1; i++) {
-                            var l = lines[i].trim();
-                            if (l.length > 0) {
-                                stream.enqueueData(l);
-                                didCompleteLine = true;
-                            }
-                        }
-                        buffer = lines[lines.length - 1];
+                const data = decoder.decode(value, { stream: true });
+                buffer += data;
+                const lines = buffer.split('\n');
+                for (var i = 0; i < lines.length - 1; i++) {
+                    var l = lines[i].trim();
+                    if (l.length > 0) {
+                        stream.enqueueData(l);
                     }
                 }
-                catch (ex) {
-                    stream.close();
-                    throw ex;
+                buffer = lines[lines.length - 1];
+                // Implement backpressure by waiting for the low water mark to be reached
+                if (stream.dataQueue.length > stream.highWatermark) {
+                    await new Promise((resolve) => {
+                        const dispose = stream.registerListener({
+                            lowWater: async () => {
+                                resolve();
+                                dispose();
+                            },
+                            closed: () => {
+                                resolve();
+                                dispose();
+                            }
+                        });
+                    });
                 }
-            },
+            }
+        };
+        consumeStream().catch(ex => this.logger.error('Error consuming stream', ex));
+        const l = stream.registerListener({
             closed: () => {
                 closeReader();
                 l?.();
@@ -7606,18 +7624,17 @@ exports.SyncClientImplementation = void 0;
      *
      * This is the default option.
      *
-     * @deprecated Don't use {@link SyncClientImplementation.JAVASCRIPT} directly. Instead, use
-     * {@link DEFAULT_SYNC_CLIENT_IMPLEMENTATION} or omit the option. The explicit choice to use
-     * the JavaScript-based sync implementation will be removed from a future version of the SDK.
+     * @deprecated We recommend the {@link RUST} client implementation for all apps. If you have issues with
+     * the Rust client, please file an issue or reach out to us. The JavaScript client will be removed in a future
+     * version of the PowerSync SDK.
      */
     SyncClientImplementation["JAVASCRIPT"] = "js";
     /**
      * This implementation offloads the sync line decoding and handling into the PowerSync
      * core extension.
      *
-     * @experimental
-     * While this implementation is more performant than {@link SyncClientImplementation.JAVASCRIPT},
-     * it has seen less real-world testing and is marked as __experimental__ at the moment.
+     * This option is more performant than the {@link JAVASCRIPT} client, enabled by default and the
+     * recommended client implementation for all apps.
      *
      * ## Compatibility warning
      *
@@ -7635,13 +7652,9 @@ exports.SyncClientImplementation = void 0;
     SyncClientImplementation["RUST"] = "rust";
 })(exports.SyncClientImplementation || (exports.SyncClientImplementation = {}));
 /**
- * The default {@link SyncClientImplementation} to use.
- *
- * Please use this field instead of {@link SyncClientImplementation.JAVASCRIPT} directly. A future version
- * of the PowerSync SDK will enable {@link SyncClientImplementation.RUST} by default and remove the JavaScript
- * option.
+ * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
  */
-const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = exports.SyncClientImplementation.JAVASCRIPT;
+const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = exports.SyncClientImplementation.RUST;
 const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 const DEFAULT_RETRY_DELAY_MS = 5000;
 const DEFAULT_STREAMING_SYNC_OPTIONS = {
@@ -8051,6 +8064,9 @@ The next upload iteration will be delayed.`);
         if (rawTables != null && rawTables.length) {
             this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
         }
+        if (this.activeStreams.length) {
+            this.logger.error('Sync streams require `clientImplementation: SyncClientImplementation.RUST` when connecting.');
+        }
         this.logger.debug('Streaming sync iteration started');
         this.options.adapter.startSession();
         let [req, bucketMap] = await this.collectLocalBucketState();
@@ -8566,6 +8582,27 @@ The next upload iteration will be delayed.`);
     }
 }
 
+const CLAIM_STORE = new Map();
+/**
+ * @internal
+ * @experimental
+ */
+const MEMORY_TRIGGER_CLAIM_MANAGER = {
+    async obtainClaim(identifier) {
+        if (CLAIM_STORE.has(identifier)) {
+            throw new Error(`A claim is already present for ${identifier}`);
+        }
+        const release = async () => {
+            CLAIM_STORE.delete(identifier);
+        };
+        CLAIM_STORE.set(identifier, release);
+        return release;
+    },
+    async checkClaim(identifier) {
+        return CLAIM_STORE.has(identifier);
+    }
+};
+
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
  * @experimental
@@ -8577,9 +8614,20 @@ exports.DiffTriggerOperation = void 0;
     DiffTriggerOperation["DELETE"] = "DELETE";
 })(exports.DiffTriggerOperation || (exports.DiffTriggerOperation = {}));
 
+const DEFAULT_TRIGGER_MANAGER_CONFIGURATION = {
+    useStorageByDefault: false
+};
+const TRIGGER_CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
+/**
+ * @internal
+ * @experimental
+ */
 class TriggerManagerImpl {
     options;
     schema;
+    defaultConfig;
+    cleanupTimeout;
+    isDisposed;
     constructor(options) {
         this.options = options;
         this.schema = options.schema;
@@ -8588,6 +8636,33 @@ class TriggerManagerImpl {
                 this.schema = schema;
             }
         });
+        this.isDisposed = false;
+        /**
+         * Configure a cleanup to run on an interval.
+         * The interval is configured using setTimeout to take the async
+         * execution time of the callback into account.
+         */
+        this.defaultConfig = DEFAULT_TRIGGER_MANAGER_CONFIGURATION;
+        const cleanupCallback = async () => {
+            this.cleanupTimeout = null;
+            if (this.isDisposed) {
+                return;
+            }
+            try {
+                await this.cleanupResources();
+            }
+            catch (ex) {
+                this.db.logger.error(`Caught error while attempting to cleanup triggers`, ex);
+            }
+            finally {
+                // if not closed, set another timeout
+                if (this.isDisposed) {
+                    return;
+                }
+                this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
+            }
+        };
+        this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
     }
     get db() {
         return this.options.db;
@@ -8605,13 +8680,95 @@ class TriggerManagerImpl {
             await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
         }
     }
+    dispose() {
+        this.isDisposed = true;
+        if (this.cleanupTimeout) {
+            clearTimeout(this.cleanupTimeout);
+        }
+    }
+    /**
+     * Updates default config settings for platform specific use-cases.
+     */
+    updateDefaults(config) {
+        this.defaultConfig = {
+            ...this.defaultConfig,
+            ...config
+        };
+    }
+    generateTriggerName(operation, destinationTable, triggerId) {
+        return `__ps_temp_trigger_${operation.toLowerCase()}__${destinationTable}__${triggerId}`;
+    }
+    /**
+     * Cleanup any SQLite triggers or tables that are no longer in use.
+     */
+    async cleanupResources() {
+        // we use the database here since cleanupResources is called during the PowerSyncDatabase initialization
+        await this.db.database.writeLock(async (ctx) => {
+            /**
+             * Note: We only cleanup persisted triggers. These are tracked in the sqlite_master table.
+             * temporary triggers will not be affected by this.
+             * Query all triggers that match our naming pattern
+             */
+            const triggers = await ctx.getAll(/* sql */ `
+        SELECT
+          name
+        FROM
+          sqlite_master
+        WHERE
+          type = 'trigger'
+          AND name LIKE '__ps_temp_trigger_%'
+      `);
+            /** Use regex to extract table names and IDs from trigger names
+             * Trigger naming convention: __ps_temp_trigger_<operation>__<destination_table>__<id>
+             */
+            const triggerPattern = /^__ps_temp_trigger_(?:insert|update|delete)__(.+)__([a-f0-9_]{36})$/i;
+            const trackedItems = new Map();
+            for (const trigger of triggers) {
+                const match = trigger.name.match(triggerPattern);
+                if (match) {
+                    const [, table, id] = match;
+                    // Collect all trigger names for each id combo
+                    const existing = trackedItems.get(id);
+                    if (existing) {
+                        existing.triggerNames.push(trigger.name);
+                    }
+                    else {
+                        trackedItems.set(id, { table, id, triggerNames: [trigger.name] });
+                    }
+                }
+            }
+            for (const trackedItem of trackedItems.values()) {
+                // check if there is anything holding on to this item
+                const hasClaim = await this.options.claimManager.checkClaim(trackedItem.id);
+                if (hasClaim) {
+                    // This does not require cleanup
+                    continue;
+                }
+                this.db.logger.debug(`Clearing resources for trigger ${trackedItem.id} with table ${trackedItem.table}`);
+                // We need to delete the triggers and table
+                for (const triggerName of trackedItem.triggerNames) {
+                    await ctx.execute(`DROP TRIGGER IF EXISTS ${triggerName}`);
+                }
+                await ctx.execute(`DROP TABLE IF EXISTS ${trackedItem.table}`);
+            }
+        });
+    }
     async createDiffTrigger(options) {
         await this.db.waitForReady();
-        const { source, destination, columns, when, hooks } = options;
+        const { source, destination, columns, when, hooks, 
+        // Fall back to the provided default if not given on this level
+        useStorage = this.defaultConfig.useStorageByDefault } = options;
         const operations = Object.keys(when);
         if (operations.length == 0) {
             throw new Error('At least one WHEN operation must be specified for the trigger.');
         }
+        /**
+         * The clause to use when executing
+         * CREATE ${tableTriggerTypeClause} TABLE
+         * OR
+         * CREATE ${tableTriggerTypeClause} TRIGGER
+         */
+        const tableTriggerTypeClause = !useStorage ? 'TEMP' : '';
         const whenClauses = Object.fromEntries(Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`]));
         /**
          * Allow specifying the View name as the source.
@@ -8625,6 +8782,7 @@ class TriggerManagerImpl {
         const internalSource = sourceDefinition.internalName;
         const triggerIds = [];
         const id = await this.getUUID();
+        const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
         /**
          * We default to replicating all columns if no columns array is provided.
          */
@@ -8657,26 +8815,27 @@ class TriggerManagerImpl {
             return this.db.writeLock(async (tx) => {
                 await this.removeTriggers(tx, triggerIds);
                 await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+                await releaseStorageClaim?.();
             });
         };
         const setup = async (tx) => {
             // Allow user code to execute in this lock context before the trigger is created.
             await hooks?.beforeCreate?.(tx);
             await tx.execute(/* sql */ `
-        CREATE TEMP TABLE ${destination} (
+        CREATE ${tableTriggerTypeClause} TABLE ${destination} (
           operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
           id TEXT,
           operation TEXT,
           timestamp TEXT,
           value TEXT,
           previous_value TEXT
-        );
+        )
       `);
             if (operations.includes(exports.DiffTriggerOperation.INSERT)) {
-                const insertTriggerId = `ps_temp_trigger_insert_${id}`;
+                const insertTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.INSERT, destination, id);
                 triggerIds.push(insertTriggerId);
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.INSERT]} BEGIN
+          CREATE ${tableTriggerTypeClause} TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.INSERT]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value)
           VALUES
@@ -8687,14 +8846,14 @@ class TriggerManagerImpl {
               ${jsonFragment('NEW')}
             );
 
-          END;
+          END
         `);
             }
             if (operations.includes(exports.DiffTriggerOperation.UPDATE)) {
-                const updateTriggerId = `ps_temp_trigger_update_${id}`;
+                const updateTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.UPDATE, destination, id);
                 triggerIds.push(updateTriggerId);
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${updateTriggerId} AFTER
+          CREATE ${tableTriggerTypeClause} TRIGGER ${updateTriggerId} AFTER
           UPDATE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.UPDATE]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value, previous_value)
@@ -8711,11 +8870,11 @@ class TriggerManagerImpl {
         `);
             }
             if (operations.includes(exports.DiffTriggerOperation.DELETE)) {
-                const deleteTriggerId = `ps_temp_trigger_delete_${id}`;
+                const deleteTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.DELETE, destination, id);
                 triggerIds.push(deleteTriggerId);
                 // Create delete trigger for basic JSON
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.DELETE]} BEGIN
+          CREATE ${tableTriggerTypeClause} TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.DELETE]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value)
           VALUES
@@ -8759,7 +8918,7 @@ class TriggerManagerImpl {
         // If no array is provided, we use all columns from the source table.
         const contextColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
         const id = await this.getUUID();
-        const destination = `ps_temp_track_${source}_${id}`;
+        const destination = `__ps_temp_track_${source}_${id}`;
         // register an onChange before the trigger is created
         const abortController = new AbortController();
         const abortOnChange = () => abortController.abort();
@@ -8914,6 +9073,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
      */
     triggers;
+    triggersImpl;
     logger;
     constructor(options) {
         super();
@@ -8977,9 +9137,10 @@ class AbstractPowerSyncDatabase extends BaseObserver {
             logger: this.logger
         });
         this._isReadyPromise = this.initialize();
-        this.triggers = new TriggerManagerImpl({
+        this.triggers = this.triggersImpl = new TriggerManagerImpl({
             db: this,
-            schema: this.schema
+            schema: this.schema,
+            ...this.generateTriggerManagerConfig()
         });
     }
     /**
@@ -9005,6 +9166,15 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     get connecting() {
         return this.currentStatus?.connecting || false;
     }
+    /**
+     * Generates a base configuration for {@link TriggerManagerImpl}.
+     * Implementations should override this if necessary.
+     */
+    generateTriggerManagerConfig() {
+        return {
+            claimManager: MEMORY_TRIGGER_CLAIM_MANAGER
+        };
+    }
     /**
      * @returns A promise which will resolve once initialization is completed.
      */
@@ -9065,14 +9235,15 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     async initialize() {
         await this._initialize();
         await this.bucketStorageAdapter.init();
-        await this._loadVersion();
+        await this.loadVersion();
         await this.updateSchema(this.options.schema);
         await this.resolveOfflineSyncStatus();
         await this.database.execute('PRAGMA RECURSIVE_TRIGGERS=TRUE');
+        await this.triggersImpl.cleanupResources();
         this.ready = true;
         this.iterateListeners((cb) => cb.initialized?.());
     }
-    async _loadVersion() {
+    async loadVersion() {
         try {
             const { version } = await this.database.get('SELECT powersync_rs_version() as version');
             this.sdkVersion = version;
@@ -9188,7 +9359,6 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         await this.disconnect();
         await this.waitForReady();
         const { clearLocal } = options;
-        // TODO DB name, verify this is necessary with extension
         await this.database.writeTransaction(async (tx) => {
             await tx.execute('SELECT powersync_clear(?)', [clearLocal ? 1 : 0]);
         });
@@ -9220,6 +9390,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             return;
         }
+        this.triggersImpl.dispose();
         await this.iterateAsyncListeners(async (cb) => cb.closing?.());
         const { disconnect } = options;
         if (disconnect) {
@@ -10831,9 +11002,11 @@ exports.InvalidSQLCharacters = InvalidSQLCharacters;
 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.OnChangeQueryProcessor = OnChangeQueryProcessor;
 exports.OpType = OpType;
 exports.OplogEntry = OplogEntry;
+exports.RawTable = RawTable;
 exports.Schema = Schema;
 exports.SqliteBucketStorage = SqliteBucketStorage;
 exports.SyncDataBatch = SyncDataBatch;
@@ -10842,6 +11015,7 @@ exports.SyncProgress = SyncProgress;
 exports.SyncStatus = SyncStatus;
 exports.Table = Table;
 exports.TableV2 = TableV2;
+exports.TriggerManagerImpl = TriggerManagerImpl;
 exports.UploadQueueStats = UploadQueueStats;
 exports.column = column;
 exports.compilableQueryWatch = compilableQueryWatch;