@powersync/common 1.9.0 → 1.11.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/client/sync/stream/AbstractRemote.d.ts

@@ -16,6 +16,16 @@ export type SyncStreamOptions = {
     abortSignal?: AbortSignal;
     fetchOptions?: Request;
 };
+export type FetchImplementation = typeof fetch;
+/**
+ * Class wrapper for providing a fetch implementation.
+ * The class wrapper is used to distinguish the fetchImplementation
+ * option in [AbstractRemoteOptions] from the general fetch method
+ * which is typeof "function"
+ */
+export declare class FetchImplementationProvider {
+    getFetch(): FetchImplementation;
+}
 export type AbstractRemoteOptions = {
     /**
      * Transforms the PowerSync base URL which might contain
@@ -28,7 +38,7 @@ export type AbstractRemoteOptions = {
      * Note that this usually needs to be bound to the global scope.
      * Binding should be done before passing here.
      */
-    fetchImplementation: typeof fetch;
+    fetchImplementation: FetchImplementation | FetchImplementationProvider;
 };
 export declare const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions;
 export declare abstract class AbstractRemote {
@@ -37,7 +47,11 @@ export declare abstract class AbstractRemote {
     protected credentials: PowerSyncCredentials | null;
     protected options: AbstractRemoteOptions;
     constructor(connector: RemoteConnector, logger?: ILogger, options?: Partial<AbstractRemoteOptions>);
-    get fetch(): typeof globalThis.fetch;
+    /**
+     * @returns a fetch implementation (function)
+     * which can be called to perform fetch requests
+     */
+    get fetch(): FetchImplementation;
     getCredentials(): Promise<PowerSyncCredentials | null>;
     protected buildRequest(path: string): Promise<{
         url: string;

package/lib/client/sync/stream/AbstractRemote.js

@@ -15,11 +15,22 @@ const KEEP_ALIVE_MS = 20_000;
 // The ACK must be received in this period
 const KEEP_ALIVE_LIFETIME_MS = 30_000;
 export const DEFAULT_REMOTE_LOGGER = Logger.get('PowerSyncRemote');
+/**
+ * Class wrapper for providing a fetch implementation.
+ * The class wrapper is used to distinguish the fetchImplementation
+ * option in [AbstractRemoteOptions] from the general fetch method
+ * which is typeof "function"
+ */
+export class FetchImplementationProvider {
+    getFetch() {
+        return fetch.bind(globalThis);
+    }
+}
 export const DEFAULT_REMOTE_OPTIONS = {
     socketUrlTransformer: (url) => url.replace(/^https?:\/\//, function (match) {
         return match === 'https://' ? 'wss://' : 'ws://';
     }),
-    fetchImplementation: fetch.bind(globalThis)
+    fetchImplementation: new FetchImplementationProvider()
 };
 export class AbstractRemote {
     connector;
@@ -34,8 +45,15 @@ export class AbstractRemote {
             ...(options ?? {})
         };
     }
+    /**
+     * @returns a fetch implementation (function)
+     * which can be called to perform fetch requests
+     */
     get fetch() {
-        return this.options.fetchImplementation;
+        const { fetchImplementation } = this.options;
+        return fetchImplementation instanceof FetchImplementationProvider
+            ? fetchImplementation.getFetch()
+            : fetchImplementation;
     }
     async getCredentials() {
         const { expiresAt } = this.credentials ?? {};

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.11.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"