@powersync/common 1.9.0 → 1.10.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -50,7 +50,7 @@ export interface WatchHandler {
     onError?: (error: Error) => void;
 }
 export interface WatchOnChangeHandler {
-    onChange: (event: WatchOnChangeEvent) => void;
+    onChange: (event: WatchOnChangeEvent) => Promise<void> | void;
     onError?: (error: Error) => void;
 }
 export interface PowerSyncDBListener extends StreamingSyncImplementationListener {

package/lib/client/AbstractPowerSyncDatabase.js

@@ -13,6 +13,7 @@ import { CrudBatch } from './sync/bucket/CrudBatch';
 import { CrudEntry } from './sync/bucket/CrudEntry';
 import { CrudTransaction } from './sync/bucket/CrudTransaction';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS } from './sync/stream/AbstractStreamingSyncImplementation';
+import { ControlledExecutor } from '../utils/ControlledExecutor';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -565,10 +566,13 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const watchedTables = new Set(resolvedOptions.tables ?? []);
         const changedTables = new Set();
         const throttleMs = resolvedOptions.throttleMs ?? DEFAULT_WATCH_THROTTLE_MS;
+        const executor = new ControlledExecutor(async (e) => {
+            await onChange(e);
+        });
         const flushTableUpdates = throttle(() => this.handleTableChanges(changedTables, watchedTables, (intersection) => {
             if (resolvedOptions?.signal?.aborted)
                 return;
-            onChange({ changedTables: intersection });
+            executor.schedule({ changedTables: intersection });
         }), throttleMs, { leading: false, trailing: true });
         const dispose = this.database.registerListener({
             tablesUpdated: async (update) => {
@@ -583,6 +587,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             }
         });
         resolvedOptions.signal?.addEventListener('abort', () => {
+            executor.dispose();
             dispose();
         });
         return () => dispose();

package/lib/utils/ControlledExecutor.d.ts

@@ -0,0 +1,25 @@
+export interface ControlledExecutorOptions {
+    /**
+     * If throttling is enabled, it ensures only one task runs at a time,
+     * and only one additional task can be scheduled to run after the current task completes. The pending task will be overwritten by the latest task.
+     * Enabled by default.
+     */
+    throttleEnabled?: boolean;
+}
+export declare class ControlledExecutor<T> {
+    private task;
+    /**
+     * Represents the currently running task, which could be a Promise or undefined if no task is running.
+     */
+    private runningTask;
+    private pendingTaskParam;
+    /**
+     * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
+     */
+    private isThrottling;
+    private closed;
+    constructor(task: (param: T) => Promise<void> | void, options?: ControlledExecutorOptions);
+    schedule(param: T): void;
+    dispose(): void;
+    private execute;
+}

package/lib/utils/ControlledExecutor.js

@@ -0,0 +1,50 @@
+export class ControlledExecutor {
+    task;
+    /**
+     * Represents the currently running task, which could be a Promise or undefined if no task is running.
+     */
+    runningTask;
+    pendingTaskParam;
+    /**
+     * Flag to determine if throttling is enabled, which controls whether tasks are queued or run immediately.
+     */
+    isThrottling;
+    closed;
+    constructor(task, options) {
+        this.task = task;
+        const { throttleEnabled = true } = options ?? {};
+        this.isThrottling = throttleEnabled;
+        this.closed = false;
+    }
+    schedule(param) {
+        if (this.closed) {
+            return;
+        }
+        if (!this.isThrottling) {
+            this.task(param);
+            return;
+        }
+        if (this.runningTask) {
+            // set or replace the pending task param with latest one
+            this.pendingTaskParam = param;
+            return;
+        }
+        this.execute(param);
+    }
+    dispose() {
+        this.closed = true;
+        if (this.runningTask) {
+            this.runningTask = undefined;
+        }
+    }
+    async execute(param) {
+        this.runningTask = this.task(param);
+        await this.runningTask;
+        this.runningTask = undefined;
+        if (this.pendingTaskParam) {
+            const pendingParam = this.pendingTaskParam;
+            this.pendingTaskParam = undefined;
+            this.execute(pendingParam);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"