@powersync/common 0.0.0-dev-20240516143814 → 0.0.0-dev-20240610133845

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 ?? {};
@@ -119,7 +137,7 @@ export class AbstractRemote {
     async socketStream(options) {
         const { path } = options;
         const request = await this.buildRequest(path);
-        const BSON = await this.getBSON();
+        const bson = await this.getBSON();
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url: this.options.socketUrlTransformer(request.url)
@@ -131,7 +149,7 @@ export class AbstractRemote {
                 metadataMimeType: 'application/bson',
                 payload: {
                     data: null,
-                    metadata: Buffer.from(BSON.serialize({
+                    metadata: Buffer.from(bson.serialize({
                         token: request.headers.Authorization
                     }))
                 }
@@ -167,8 +185,8 @@ export class AbstractRemote {
         const socket = await new Promise((resolve, reject) => {
             let connectionEstablished = false;
             const res = rsocket.requestStream({
-                data: Buffer.from(BSON.serialize(options.data)),
-                metadata: Buffer.from(BSON.serialize({
+                data: Buffer.from(bson.serialize(options.data)),
+                metadata: Buffer.from(bson.serialize({
                     path
                 }))
             }, SYNC_QUEUE_REQUEST_N, // The initial N amount
@@ -199,7 +217,7 @@ export class AbstractRemote {
                     if (!data) {
                         return;
                     }
-                    const deserializedData = BSON.deserialize(data);
+                    const deserializedData = bson.deserialize(data);
                     stream.enqueueData(deserializedData);
                 },
                 onComplete: () => {

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -54,6 +54,10 @@ export interface PowerSyncConnectionOptions {
      * Defaults to a HTTP streaming connection.
      */
     connectionMethod?: SyncStreamConnectionMethod;
+    /**
+     * Parameters to be passed to the sync rules. Parameters be available under the`user_parameters` object.
+     */
+    params?: Record<string, any>;
 }
 export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
     /**

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

@@ -22,7 +22,8 @@ export const DEFAULT_STREAMING_SYNC_OPTIONS = {
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
-    connectionMethod: SyncStreamConnectionMethod.HTTP
+    connectionMethod: SyncStreamConnectionMethod.HTTP,
+    params: {}
 };
 export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
@@ -116,13 +117,16 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                     }
                     catch (ex) {
                         this.updateSyncStatus({
-                            connected: false,
                             dataFlow: {
                                 uploading: false
                             }
                         });
                         await this.delayRetry();
-                        break;
+                        if (!this.isConnected) {
+                            // Exit the upload loop if the sync stream is no longer connected
+                            break;
+                        }
+                        this.logger.debug(`Caught exception when uploading. Upload will retry after a delay. Exception: ${ex.message}`);
                     }
                     finally {
                         this.updateSyncStatus({
@@ -312,7 +316,8 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                     data: {
                         buckets: req,
                         include_checksum: true,
-                        raw_data: true
+                        raw_data: true,
+                        parameters: resolvedOptions.params
                     }
                 };
                 const stream = resolvedOptions?.connectionMethod == SyncStreamConnectionMethod.HTTP

package/lib/client/sync/stream/streaming-sync-types.d.ts

@@ -59,6 +59,10 @@ export interface StreamingSyncRequest {
      * Changes the response to stringified data in each OplogEntry
      */
     raw_data: boolean;
+    /**
+     * Client parameters to be passed to the sync rules.
+     */
+    parameters?: Record<string, any>;
 }
 export interface StreamingSyncCheckpoint {
     checkpoint: Checkpoint;

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": "0.0.0-dev-20240516143814",
+  "version": "0.0.0-dev-20240610133845",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"