@powersync/common 1.54.0 → 1.56.0

package/src/client/AbstractPowerSyncDatabase.ts

@@ -1,4 +1,3 @@
-import { EventIterator } from 'event-iterator';
 import Logger, { ILogger } from 'js-logger';
 import {
   BatchedUpdateNotification,
@@ -14,7 +13,7 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
-import { throttleTrailing } from '../utils/async.js';
+import { EventQueue, throttleTrailing } from '../utils/async.js';
 import {
   ConnectionManager,
   CreateSyncImplementationOptions,
@@ -47,6 +46,7 @@ import { DEFAULT_WATCH_THROTTLE_MS, WatchCompatibleQuery } from './watched/Watch
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
 import { Mutex } from '../utils/mutex.js';
+import { symbolAsyncIterator } from '../utils/compatibility.js';
 
 /**
  * @public
@@ -557,7 +557,9 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
     }
     this._schema = schema;
 
-    await this.database.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())]);
+    await this.database.writeTransaction((tx) =>
+      tx.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())])
+    );
     await this.database.refreshSchema();
     this.iterateListeners(async (cb) => cb.schemaChanged?.(schema));
   }
@@ -762,7 +764,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    * @returns A transaction of CRUD operations to upload, or null if there are none
    */
   async getNextCrudTransaction(): Promise<CrudTransaction | null> {
-    const iterator = this.getCrudTransactions()[Symbol.asyncIterator]();
+    const iterator = this.getCrudTransactions()[symbolAsyncIterator]();
     return (await iterator.next()).value;
   }
 
@@ -799,7 +801,7 @@ export abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDB
    */
   getCrudTransactions(): AsyncIterable<CrudTransaction, null> {
     return {
-      [Symbol.asyncIterator]: () => {
+      [symbolAsyncIterator]: () => {
         let lastCrudItemId = -1;
         const sql = `
 WITH RECURSIVE crud_entries AS (
@@ -1193,22 +1195,18 @@ SELECT * FROM crud_entries;
    * @returns An AsyncIterable that yields QueryResults whenever the data changes
    */
   watchWithAsyncGenerator(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult> {
-    return new EventIterator<QueryResult>((eventOptions) => {
+    return EventQueue.queueBasedAsyncIterable((queue, abort) => {
       const handler: WatchHandler = {
         onResult: (result) => {
-          eventOptions.push(result);
+          queue.notify(result);
         },
         onError: (error) => {
-          eventOptions.fail(error);
+          queue.notifyError(error);
         }
       };
 
-      this.watchWithCallback(sql, parameters, handler, options);
-
-      options?.signal?.addEventListener('abort', () => {
-        eventOptions.stop();
-      });
-    });
+      this.watchWithCallback(sql, parameters, handler, { ...options, signal: abort });
+    }, options?.signal);
   }
 
   /**
@@ -1353,34 +1351,27 @@ SELECT * FROM crud_entries;
    * This is preferred over {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator} when multiple queries need to be
    * performed together when data is changed.
    *
-   * Note: do not declare this as `async *onChange` as it will not work in React Native.
-   *
    * @param options - Options for configuring watch behavior
    * @returns An AsyncIterable that yields change events whenever the specified tables change
    */
+  // Note: do not declare this as `async *onChange` as it will not work in React Native.
   onChangeWithAsyncGenerator(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent> {
-    const resolvedOptions = options ?? {};
-
-    return new EventIterator<WatchOnChangeEvent>((eventOptions) => {
-      const dispose = this.onChangeWithCallback(
+    return EventQueue.queueBasedAsyncIterable((queue, abort) => {
+      this.onChangeWithCallback(
         {
           onChange: (event): void => {
-            eventOptions.push(event);
+            queue.notify(event);
           },
           onError: (error) => {
-            eventOptions.fail(error);
+            queue.notifyError(error);
           }
         },
-        options
+        { ...options, signal: abort }
       );
 
-      resolvedOptions.signal?.addEventListener('abort', () => {
-        eventOptions.stop();
-        // Maybe fail?
-      });
-
-      return () => dispose();
-    });
+      // Note: We don't have to track the dispose function returned by onChangeWithCallback, it cleans up
+      // after the abort signal completes.
+    }, options?.signal);
   }
 
   private handleTableChanges(

package/src/client/sync/stream/AbstractRemote.ts

@@ -9,10 +9,10 @@ import {
   doneResult,
   extractBsonObjects,
   extractJsonLines,
-  SimpleAsyncIterator
+  SimpleAsyncIterator,
+  valueResult
 } from '../../../utils/stream_transform.js';
-import { EventIterator } from 'event-iterator';
-import type { Queue } from 'event-iterator/lib/event-iterator.js';
+import { EventQueue } from '../../../utils/async.js';
 
 /**
  * @internal
@@ -329,8 +329,19 @@ export abstract class AbstractRemote {
     let pendingSocket: WebSocket | null = null;
     let keepAliveTimeout: any;
     let rsocket: RSocket | null = null;
-    let queue: Queue<Uint8Array> | null = null;
+    let paused = false;
+    const queue = new EventQueue<Uint8Array | null>({
+      eventDelivered: () => {
+        if (queue.countOutstandingEvents <= SYNC_QUEUE_REQUEST_LOW_WATER) {
+          paused = false;
+          requestMore();
+        }
+      }
+    });
     let didClose = false;
+    let connectionEstablished = false;
+    let pendingEventsCount = syncQueueRequestSize;
+    let res: Requestable | null = null;
 
     const abortRequest = () => {
       if (didClose) {
@@ -348,11 +359,26 @@ export abstract class AbstractRemote {
         rsocket.close();
       }
 
-      if (queue) {
-        queue.stop();
-      }
+      // Send a bogus event to the queue to ensure a pending listener gets woken up. We check for didClose and would
+      // return a doneEvent.
+      queue.notify(null);
     };
 
+    function push(event: Uint8Array) {
+      queue.notify(event);
+      if (queue.countOutstandingEvents >= SYNC_QUEUE_REQUEST_HIGH_WATER) {
+        paused = true;
+      }
+    }
+
+    function requestMore() {
+      const delta = syncQueueRequestSize - pendingEventsCount;
+      if (!paused && delta > 0) {
+        res?.request(delta);
+        pendingEventsCount = syncQueueRequestSize;
+      }
+    }
+
     // Handle upstream abort
     if (options.abortSignal.aborted) {
       throw new AbortOperation('Connection request aborted');
@@ -413,31 +439,18 @@ export abstract class AbstractRemote {
     rsocket.onClose(() => (rsocket = null));
 
     return await new Promise((resolve, reject) => {
-      let connectionEstablished = false;
-      let pendingEventsCount = syncQueueRequestSize;
-      let paused = false;
-      let res: Requestable | null = null;
-
-      function requestMore() {
-        const delta = syncQueueRequestSize - pendingEventsCount;
-        if (!paused && delta > 0) {
-          res?.request(delta);
-          pendingEventsCount = syncQueueRequestSize;
-        }
-      }
-
-      const events = new EventIterator<Uint8Array>(
-        (q) => {
-          queue = q;
+      const queueAsIterator: SimpleAsyncIterator<Uint8Array> = {
+        next: async () => {
+          if (didClose) return doneResult;
 
-          q.on('highWater', () => (paused = true));
-          q.on('lowWater', () => {
-            paused = false;
-            requestMore();
-          });
-        },
-        { highWaterMark: SYNC_QUEUE_REQUEST_HIGH_WATER, lowWaterMark: SYNC_QUEUE_REQUEST_LOW_WATER }
-      )[Symbol.asyncIterator]();
+          const notification = await queue.waitForEvent(options.abortSignal);
+          if (didClose) {
+            return doneResult;
+          } else {
+            return valueResult(notification!);
+          }
+        }
+      };
 
       res = rsocket!.requestStream(
         {
@@ -476,12 +489,12 @@ export abstract class AbstractRemote {
             // The connection is active
             if (!connectionEstablished) {
               connectionEstablished = true;
-              resolve(events);
+              resolve(queueAsIterator);
             }
             const { data } = payload;
 
             if (data) {
-              queue!.push(data);
+              push(data);
             }
 
             // Less events are now pending

package/src/db/crud/SyncStatus.ts

@@ -234,11 +234,7 @@ export class SyncStatus {
      */
     const replacer = (_: string, value: any) => {
       if (value instanceof Error) {
-        return {
-          name: value.name,
-          message: value.message,
-          stack: value.stack
-        };
+        return this.serializeError(value);
       }
       return value;
     };
@@ -281,15 +277,22 @@ export class SyncStatus {
    * Not all errors are serializable over a MessagePort. E.g. some `DomExceptions` fail to be passed across workers.
    * This explicitly serializes errors in the SyncStatus.
    */
-  protected serializeError(error?: Error) {
+  protected serializeError(error?: Error): Error | undefined {
     if (typeof error == 'undefined') {
       return undefined;
     }
-    return {
+    const serialized: Error = {
       name: error.name,
       message: error.message,
       stack: error.stack
     };
+    // `Error.cause` can be any value (the spec types it as unknown). Preserve it
+    // so consumers reading uploadError/downloadError keep the failure context.
+    // Recurse for Error causes so the whole chain is flattened the same way.
+    if (typeof error.cause != 'undefined') {
+      serialized.cause = error.cause instanceof Error ? this.serializeError(error.cause) : error.cause;
+    }
+    return serialized;
   }
 
   private static comparePriorities(a: SyncPriorityStatus, b: SyncPriorityStatus) {

package/src/utils/async.ts

@@ -1,3 +1,6 @@
+import { symbolAsyncIterator } from './compatibility.js';
+import { doneResult, valueResult } from './stream_transform.js';
+
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.
@@ -34,44 +37,149 @@ export interface AsyncNotifier {
 }
 
 export function asyncNotifier(): AsyncNotifier {
-  let waitingConsumer: (() => void) | null = null;
-  let hasPendingNotification = false;
+  const queue = new EventQueue<void>();
 
   return {
     notify() {
-      if (waitingConsumer != null) {
-        waitingConsumer();
-        waitingConsumer = null;
+      if (queue.countOutstandingEvents > 0) {
+        // Already has an outstanding event, no need to buffer another one.
       } else {
-        hasPendingNotification = true;
+        queue.notify();
       }
     },
     waitForNotification(signal: AbortSignal) {
-      return new Promise((resolve) => {
-        if (waitingConsumer != null) {
-          throw new Error('Illegal call to waitForNotification, already has a waiter.');
+      return queue.waitForEvent(signal);
+    }
+  };
+}
+
+type QueueWaiter<T> = { resolve: (event: T) => void; reject: (error: unknown) => void };
+
+export interface QueueOptions {
+  eventDelivered?: () => void;
+}
+
+export class EventQueue<T> {
+  private waitingConsumer: QueueWaiter<T> | undefined;
+  private readonly outstandingEvents: Array<(waiter: QueueWaiter<T>) => void>;
+
+  constructor(private readonly options: QueueOptions = {}) {
+    this.outstandingEvents = [];
+  }
+
+  /**
+   * The amount of buffered events not yet dispatched to listeners.
+   */
+  get countOutstandingEvents(): number {
+    return this.outstandingEvents.length;
+  }
+
+  private notifyInner(dispatch: (waiter: QueueWaiter<T>) => void) {
+    const existing = this.waitingConsumer;
+    this.waitingConsumer = undefined;
+
+    const dispatchAndNotifyListeners = (waiter: QueueWaiter<T>) => {
+      dispatch(waiter);
+      this.options.eventDelivered?.();
+    };
+
+    if (existing) {
+      dispatchAndNotifyListeners(existing);
+    } else {
+      this.outstandingEvents.push(dispatchAndNotifyListeners);
+    }
+  }
+
+  notify(value: T) {
+    this.notifyInner((l) => l.resolve(value));
+  }
+
+  notifyError(error: unknown) {
+    this.notifyInner((l) => l.reject(error));
+  }
+
+  waitForEvent(signal: AbortSignal): Promise<T | undefined> {
+    return new Promise((resolve, reject) => {
+      if (this.waitingConsumer != null) {
+        throw new Error('Illegal call to waitForEvent, already has a waiter.');
+      }
+
+      const complete = () => {
+        signal?.removeEventListener('abort', onAbort);
+      };
+
+      const onAbort = () => {
+        complete();
+        this.waitingConsumer = undefined;
+        resolve(undefined);
+      };
+
+      const waiter: QueueWaiter<T> = {
+        resolve: (value) => {
+          complete();
+          resolve(value);
+        },
+        reject: (error) => {
+          complete();
+          reject(error);
         }
+      };
 
-        if (signal.aborted) {
-          resolve();
-        } else if (hasPendingNotification) {
-          resolve();
-          hasPendingNotification = false;
-        } else {
-          function complete() {
-            signal.removeEventListener('abort', onAbort);
-            resolve();
-          }
+      if (signal.aborted) {
+        resolve(undefined);
+      } else if (this.countOutstandingEvents > 0) {
+        const [event] = this.outstandingEvents.splice(0, 1);
+        event(waiter);
+      } else {
+        this.waitingConsumer = waiter;
+        signal.addEventListener('abort', onAbort);
+      }
+    });
+  }
 
-          function onAbort() {
-            waitingConsumer = null;
-            resolve();
-          }
+  /**
+   * Creates an async iterable backed by event queues.
+   *
+   * @param run A function invoked for every new listener. It receives a queue backing the async iterator.
+   * @param abort An additional abort signal. The `run` callback will also be aborted when `AsyncIterator.return` is
+   * called.
+   * @returns An object conforming to the async iterable protocol.
+   */
+  static queueBasedAsyncIterable<T>(
+    run: (queue: EventQueue<T>, abort: AbortSignal) => void,
+    abort?: AbortSignal
+  ): AsyncIterable<T> {
+    return {
+      [symbolAsyncIterator]: () => {
+        const queue = new EventQueue<T>();
+        const controller = new AbortController();
 
-          waitingConsumer = complete;
-          signal.addEventListener('abort', onAbort);
+        function dispose() {
+          controller.abort();
+          abort?.removeEventListener('abort', dispose);
         }
-      });
-    }
-  };
+
+        if (abort) {
+          if (abort.aborted) {
+            controller.abort();
+          } else {
+            abort.addEventListener('abort', dispose);
+          }
+        }
+
+        run(queue, controller.signal);
+
+        return {
+          async next(): Promise<IteratorResult<T>> {
+            const event = await queue.waitForEvent(controller.signal);
+            return event == null ? doneResult : valueResult(event);
+          },
+          async return(): Promise<IteratorResult<T>> {
+            dispose();
+            return doneResult;
+          }
+        };
+      }
+    };
+  }
 }

package/src/utils/compatibility.ts

@@ -0,0 +1,9 @@
+/**
+ * Some JavaScript engines, in particular older versions of React Native, don't support Symbol.asyncIterator.
+ *
+ * For those, users relying on async generators typically lower them with a transpiler and [this polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6).
+ * This definition is compatible with that polyfill, so transpiled apps can use async iterables created by the PowerSync
+ * SDK.
+ */
+export const symbolAsyncIterator: typeof Symbol.asyncIterator =
+  Symbol.asyncIterator ?? Symbol.for('Symbol.asyncIterator');