@powersync/common 1.54.0 → 1.55.0

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');