@powersync/common 1.53.2 → 1.55.0

package/src/index.ts

@@ -35,7 +35,7 @@ export * from './db/DBAdapter.js';
 export * from './db/schema/Column.js';
 export * from './db/schema/Index.js';
 export * from './db/schema/IndexedColumn.js';
-export { RawTableType, PendingStatementParameter, PendingStatement } from './db/schema/RawTable.js';
+export { PendingStatement, PendingStatementParameter, RawTableType } from './db/schema/RawTable.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';

package/src/types/types.ts

@@ -1,8 +1,14 @@
+/**
+ * @public
+ */
 export interface CompilableQuery<T> {
   execute(): Promise<T[]>;
   compile(): CompiledQuery;
 }
 
+/**
+ * @public
+ */
 export interface CompiledQuery {
   readonly sql: string;
   readonly parameters: ReadonlyArray<unknown>;

package/src/utils/AbortOperation.ts

@@ -2,6 +2,8 @@
  * Calls to Abortcontroller.abort(reason: any) will result in the
  * `reason` being thrown. This is not necessarily an error,
  *  but extends error for better logging purposes.
+ *
+ * @internal
  */
 export class AbortOperation extends Error {
   constructor(protected reason: string) {

package/src/utils/BaseObserver.ts

@@ -1,13 +1,25 @@
+/**
+ * @public
+ */
 export interface Disposable {
   dispose: () => Promise<void> | void;
 }
 
+/**
+ * @public
+ */
 export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
 
+/**
+ * @public
+ */
 export interface BaseObserverInterface<T extends BaseListener> {
   registerListener(listener: Partial<T>): () => void;
 }
 
+/**
+ * @internal
+ */
 export class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
   protected listeners = new Set<Partial<T>>();
 

package/src/utils/ControlledExecutor.ts

@@ -1,3 +1,6 @@
+/**
+ * @internal
+ */
 export interface ControlledExecutorOptions {
   /**
    * If throttling is enabled, it ensures only one task runs at a time,
@@ -7,6 +10,9 @@ export interface ControlledExecutorOptions {
   throttleEnabled?: boolean;
 }
 
+/**
+ * @internal
+ */
 export class ControlledExecutor<T> {
   private task: (param: T) => Promise<void> | void;
 

package/src/utils/Logger.ts

@@ -4,6 +4,9 @@ export { GlobalLogger, ILogger, ILoggerOpts, ILogHandler, ILogLevel } from 'js-l
 
 const TypedLogger: ILogger = Logger as any;
 
+/**
+ * @public
+ */
 export const LogLevel = {
   TRACE: TypedLogger.TRACE,
   DEBUG: TypedLogger.DEBUG,
@@ -14,6 +17,9 @@ export const LogLevel = {
   OFF: TypedLogger.OFF
 };
 
+/**
+ * @public
+ */
 export interface CreateLoggerOptions {
   logLevel?: ILogLevel;
 }
@@ -25,6 +31,7 @@ export interface CreateLoggerOptions {
  * across all loggers created with `createLogger`. Adjusting settings on this
  * base logger affects all loggers derived from it unless explicitly overridden.
  *
+ * @public
  */
 export function createBaseLogger() {
   return Logger;
@@ -36,6 +43,8 @@ export function createBaseLogger() {
  * Named loggers allow specific modules or areas of your application to have
  * their own logging levels and behaviors. These loggers inherit configuration
  * from the base logger by default but can override settings independently.
+ *
+ * @public
  */
 export function createLogger(name: string, options: CreateLoggerOptions = {}): ILogger {
   const logger = Logger.get(name);

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

package/src/utils/mutex.ts

@@ -1,5 +1,8 @@
 import { Queue } from './queue.js';
 
+/**
+ * @internal
+ */
 export type UnlockFn = () => void;
 
 /**
@@ -178,10 +181,19 @@ export class Mutex {
 
 /**
  * Creates a signal aborting after the set timeout.
+ *
+ * @internal
  */
 export function timeoutSignal(timeout: number): AbortSignal;
+
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined;
 
+/**
+ * @internal
+ */
 export function timeoutSignal(timeout?: number): AbortSignal | undefined {
   if (timeout == null) return;
   if ('timeout' in AbortSignal) return AbortSignal.timeout(timeout);

package/src/utils/parseQuery.ts

@@ -1,10 +1,16 @@
 import type { CompilableQuery } from '../types/types.js';
 
+/**
+ * @internal
+ */
 export interface ParsedQuery {
   sqlStatement: string;
   parameters: any[];
 }
 
+/**
+ * @internal
+ */
 export const parseQuery = <T>(query: string | CompilableQuery<T>, parameters: any[]): ParsedQuery => {
   let sqlStatement: string;
 

package/src/utils/stream_transform.ts

@@ -2,9 +2,11 @@
  * An async iterator that can't be cancelled.
  *
  * To keep data flow simple, we always pass an explicit cancellation token when subscribing to async streams. Once the
- * {@link AbortSignal} aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
+ * `AbortSignal` aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
  * that there's no way to distinguish between streams that have completed normally and streams that have been cancelled,
  * but that is acceptable for our uses of this.
+ *
+ * @internal
  */
 export type SimpleAsyncIterator<T> = Pick<AsyncIterator<T>, 'next'>;