@powersync/common 1.53.2 → 1.55.0

package/src/client/SQLOpenFactory.ts

@@ -1,5 +1,8 @@
 import { DBAdapter } from '../db/DBAdapter.js';
 
+/**
+ * @public
+ */
 export interface SQLOpenOptions {
   /**
    * Filename for the database.
@@ -25,6 +28,9 @@ export interface SQLOpenOptions {
   debugMode?: boolean;
 }
 
+/**
+ * @public
+ */
 export interface SQLOpenFactory {
   /**
    * Opens a connection adapter to a SQLite DB
@@ -34,6 +40,8 @@ export interface SQLOpenFactory {
 
 /**
  * Tests if the input is a {@link SQLOpenOptions}
+ *
+ * @internal
  */
 export const isSQLOpenOptions = (test: any): test is SQLOpenOptions => {
   // typeof null is `object`, but you cannot use the `in` operator on `null.
@@ -42,6 +50,8 @@ export const isSQLOpenOptions = (test: any): test is SQLOpenOptions => {
 
 /**
  * Tests if input is a {@link SQLOpenFactory}
+ *
+ * @internal
  */
 export const isSQLOpenFactory = (test: any): test is SQLOpenFactory => {
   return typeof test?.openDB == 'function';
@@ -49,6 +59,8 @@ export const isSQLOpenFactory = (test: any): test is SQLOpenFactory => {
 
 /**
  * Tests if input is a {@link DBAdapter}
+ *
+ * @internal
  */
 export const isDBAdapter = (test: any): test is DBAdapter => {
   return typeof test?.writeTransaction == 'function';

package/src/client/compilableQueryWatch.ts

@@ -2,11 +2,17 @@ import { CompilableQuery } from './../types/types.js';
 import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
 
+/**
+ * @public
+ */
 export interface CompilableQueryWatchHandler<T> {
   onResult: (results: T[]) => void;
   onError?: (error: Error) => void;
 }
 
+/**
+ * @public
+ */
 export function compilableQueryWatch<T>(
   db: AbstractPowerSyncDatabase,
   query: CompilableQuery<T>,

package/src/client/connection/PowerSyncBackendConnector.ts

@@ -1,6 +1,9 @@
 import { PowerSyncCredentials } from './PowerSyncCredentials.js';
 import type { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
 
+/**
+ * @public
+ */
 export interface PowerSyncBackendConnector {
   /** Allows the PowerSync client to retrieve an authentication token from your backend
    * which is used to authenticate against the PowerSync service.

package/src/client/connection/PowerSyncCredentials.ts

@@ -1,3 +1,6 @@
+/**
+ * @public
+ */
 export interface PowerSyncCredentials {
   endpoint: string;
   token: string;

package/src/client/constants.ts

@@ -1 +1,4 @@
+/**
+ * @internal
+ */
 export const MAX_OP_ID = '9223372036854775807';

package/src/client/runOnSchemaChange.ts

@@ -1,5 +1,8 @@
 import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
 
+/**
+ * @internal
+ */
 export function runOnSchemaChange(
   callback: (signal: AbortSignal) => void,
   db: AbstractPowerSyncDatabase,

package/src/client/sync/bucket/BucketStorageAdapter.ts

@@ -2,6 +2,9 @@ import { BaseListener, BaseObserverInterface, Disposable } from '../../../utils/
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 
+/**
+ * @internal
+ */
 export enum PSInternalTable {
   DATA = 'ps_data',
   CRUD = 'ps_crud',
@@ -10,6 +13,9 @@ export enum PSInternalTable {
   UNTYPED = 'ps_untyped'
 }
 
+/**
+ * @internal
+ */
 export enum PowerSyncControlCommand {
   PROCESS_TEXT_LINE = 'line_text',
   PROCESS_BSON_LINE = 'line_binary',
@@ -24,10 +30,16 @@ export enum PowerSyncControlCommand {
   CONNECTION_STATE = 'connection'
 }
 
+/**
+ * @internal
+ */
 export interface BucketStorageListener extends BaseListener {
   crudUpdate: () => void;
 }
 
+/**
+ * @internal
+ */
 export interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
   init(): Promise<void>;
 

package/src/client/sync/bucket/CrudBatch.ts

@@ -2,6 +2,8 @@ import { CrudEntry } from './CrudEntry.js';
 
 /**
  * A batch of client-side changes.
+ *
+ * @public
  */
 export class CrudBatch {
   constructor(

package/src/client/sync/bucket/CrudEntry.ts

@@ -2,11 +2,15 @@
  * 64-bit unsigned integer stored as a string in base-10.
  *
  * Not sortable as a string.
+ *
+ * @public
  */
 export type OpId = string;
 
 /**
  * Type of local change.
+ *
+ * @public
  */
 export enum UpdateType {
   /** Insert or replace existing row. All non-null columns are included in the data. Generated by INSERT statements. */
@@ -17,6 +21,9 @@ export enum UpdateType {
   DELETE = 'DELETE'
 }
 
+/**
+ * @internal
+ */
 export type CrudEntryJSON = {
   id: string;
   data: string;
@@ -48,6 +55,8 @@ type CrudEntryOutputJSON = {
 
 /**
  * A single client-side change.
+ *
+ * @public
  */
 export class CrudEntry {
   /**

package/src/client/sync/bucket/CrudTransaction.ts

@@ -1,6 +1,9 @@
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 
+/**
+ * @public
+ */
 export class CrudTransaction extends CrudBatch {
   constructor(
     /**

package/src/client/sync/bucket/SqliteBucketStorage.ts

@@ -11,6 +11,9 @@ import {
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, CrudEntryJSON } from './CrudEntry.js';
 
+/**
+ * @internal
+ */
 export class SqliteBucketStorage extends BaseObserver<BucketStorageListener> implements BucketStorageAdapter {
   public tableNames: Set<string>;
   private updateListener: () => void;

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

@@ -9,11 +9,14 @@ 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
+ */
 export type RemoteConnector = {
   fetchCredentials: () => Promise<PowerSyncCredentials | null>;
   invalidateCredentials?: () => void;
@@ -36,8 +39,14 @@ const SOCKET_TIMEOUT_MS = 30_000;
 // significantly. Therefore this is longer than the socket timeout.
 const KEEP_ALIVE_LIFETIME_MS = 90_000;
 
+/**
+ * @internal
+ */
 export const DEFAULT_REMOTE_LOGGER = Logger.get('PowerSyncRemote');
 
+/**
+ * @internal
+ */
 export type SyncStreamOptions = {
   path: string;
   data: unknown;
@@ -46,6 +55,9 @@ export type SyncStreamOptions = {
   fetchOptions?: Request;
 };
 
+/**
+ * @public
+ */
 export enum FetchStrategy {
   /**
    * Queues multiple sync events before processing, reducing round-trips.
@@ -60,10 +72,16 @@ export enum FetchStrategy {
   Sequential = 'sequential'
 }
 
+/**
+ * @internal
+ */
 export type SocketSyncStreamOptions = SyncStreamOptions & {
   fetchStrategy: FetchStrategy;
 };
 
+/**
+ * @internal
+ */
 export type FetchImplementation = typeof fetch;
 
 /**
@@ -71,6 +89,8 @@ export type FetchImplementation = typeof fetch;
  * The class wrapper is used to distinguish the fetchImplementation
  * option in [AbstractRemoteOptions] from the general fetch method
  * which is typeof "function"
+ *
+ * @internal
  */
 export class FetchImplementationProvider {
   getFetch(): FetchImplementation {
@@ -78,6 +98,9 @@ export class FetchImplementationProvider {
   }
 }
 
+/**
+ * @internal
+ */
 export type AbstractRemoteOptions = {
   /**
    * Transforms the PowerSync base URL which might contain
@@ -102,6 +125,9 @@ export type AbstractRemoteOptions = {
   fetchOptions?: {};
 };
 
+/**
+ * @internal
+ */
 export const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions = {
   socketUrlTransformer: (url) =>
     url.replace(/^https?:\/\//, function (match) {
@@ -111,6 +137,9 @@ export const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions = {
   fetchOptions: {}
 };
 
+/**
+ * @internal
+ */
 export abstract class AbstractRemote {
   protected credentials: PowerSyncCredentials | null = null;
   protected options: AbstractRemoteOptions;
@@ -300,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) {
@@ -319,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');
@@ -384,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(
         {
@@ -447,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
@@ -589,7 +631,7 @@ export abstract class AbstractRemote {
    * Posts a `/sync/stream` request.
    *
    * Depending on the `Content-Type` of the response, this returns strings for sync lines or encoded BSON documents as
-   * {@link Uint8Array}s.
+   * `Uint8Array`s.
    */
   async fetchStream(options: SyncStreamOptions): Promise<SimpleAsyncIterator<Uint8Array | string>> {
     const { isBson, stream } = await this.fetchStreamRaw(options);

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

@@ -22,16 +22,26 @@ import {
 import { asyncNotifier } from '../../../utils/async.js';
 import { StreamingSyncRequestParameterType } from './JsonValue.js';
 
+/**
+ * @internal
+ */
 export enum LockType {
   CRUD = 'crud',
   SYNC = 'sync'
 }
 
+/**
+ * @public
+ */
 export enum SyncStreamConnectionMethod {
   HTTP = 'http',
   WEB_SOCKET = 'web-socket'
 }
 
+/**
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
+ */
 export enum SyncClientImplementation {
   /**
    * This implementation offloads the sync line decoding and handling into the PowerSync
@@ -42,8 +52,8 @@ export enum SyncClientImplementation {
    * ## Compatibility warning
    *
    * The Rust sync client stores sync data in a format that is slightly different than the one used
-   * by the old JavaScript client. When adopting the {@link RUST} client on existing databases, the PowerSync SDK will
-   * migrate the format automatically.
+   * by the old JavaScript client. When adopting the {@link SyncClientImplementation.RUST} client on existing databases,
+   * the PowerSync SDK will migrate the format automatically.
    *
    * SDK versions supporting both the JavaScript and the Rust client support both formats with the JavaScript client
    * implementaiton. However, downgrading to an SDK version that only supports the JavaScript client would not be
@@ -54,11 +64,16 @@ export enum SyncClientImplementation {
 
 /**
  * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
+ *
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
  */
 export const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.RUST;
 
 /**
  * Abstract Lock to be implemented by various JS environments
+ *
+ * @internal
  */
 export interface LockOptions<T> {
   callback: () => Promise<T>;
@@ -66,6 +81,9 @@ export interface LockOptions<T> {
   signal?: AbortSignal;
 }
 
+/**
+ * @internal
+ */
 export interface AbstractStreamingSyncImplementationOptions extends RequiredAdditionalConnectionOptions {
   adapter: BucketStorageAdapter;
   subscriptions: SubscribedStream[];
@@ -79,6 +97,9 @@ export interface AbstractStreamingSyncImplementationOptions extends RequiredAddi
   remote: AbstractRemote;
 }
 
+/**
+ * @internal
+ */
 export interface StreamingSyncImplementationListener extends BaseListener {
   /**
    * Triggered whenever a status update has been attempted to be made or
@@ -94,12 +115,17 @@ export interface StreamingSyncImplementationListener extends BaseListener {
 /**
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
+ *
+ * @public
  */
 export type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, 'serializedSchema'>;
 
+/**
+ * @internal
+ */
 export interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {}
 
-/** @internal */
+/** @public */
 export interface BaseConnectionOptions {
   /**
    * A set of metadata to be included in service logs.
@@ -161,6 +187,9 @@ export interface RequiredAdditionalConnectionOptions extends Required<Additional
   subscriptions: SubscribedStream[];
 }
 
+/**
+ * @internal
+ */
 export interface StreamingSyncImplementation
   extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
   /**
@@ -183,16 +212,31 @@ export interface StreamingSyncImplementation
   markConnectionMayHaveChanged(): void;
 }
 
+/**
+ * @internal
+ */
 export const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
+/**
+ * @internal
+ */
 export const DEFAULT_RETRY_DELAY_MS = 5000;
 
+/**
+ * @internal
+ */
 export const DEFAULT_STREAMING_SYNC_OPTIONS = {
   retryDelayMs: DEFAULT_RETRY_DELAY_MS,
   crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 
+/**
+ * @internal
+ */
 export type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
 
+/**
+ * @internal
+ */
 export const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions = {
   appMetadata: {},
   connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
@@ -203,11 +247,17 @@ export const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptio
   includeDefaultStreams: true
 };
 
+/**
+ * @internal
+ */
 export type SubscribedStream = {
   name: string;
   params: Record<string, any> | null;
 };
 
+/**
+ * @internal
+ */
 export abstract class AbstractStreamingSyncImplementation
   extends BaseObserver<StreamingSyncImplementationListener>
   implements StreamingSyncImplementation
@@ -570,7 +620,7 @@ The next upload iteration will be delayed.`);
   }
 
   /**
-   * Older versions of the JS SDK used to encode subkeys as JSON in {@link OplogEntry.toJSON}.
+   * Older versions of the JS SDK used to encode subkeys as JSON in `OplogEntry.toJSON`.
    * Because subkeys are always strings, this leads to quotes being added around them in `ps_oplog`.
    * While this is not a problem as long as it's done consistently, it causes issues when a database
    * created by the JS SDK is used with other SDKs, or (more likely) when the new Rust sync client
@@ -580,7 +630,7 @@ The next upload iteration will be delayed.`);
    * migration is only triggered when necessary (for now). The function returns whether the new format
    * should be used, so that the JS SDK is able to write to updated databases.
    *
-   * @param requireFixedKeyFormat Whether we require the new format or also support the old one.
+   * @param requireFixedKeyFormat - Whether we require the new format or also support the old one.
    *        The Rust client requires the new subkey format.
    * @returns Whether the database is now using the new, fixed subkey format.
    */

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

@@ -5,4 +5,7 @@ interface JSONObject {
 }
 type JSONArray = JSONValue[];
 
+/**
+ * @public
+ */
 export type StreamingSyncRequestParameterType = JSONValue;

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

@@ -42,7 +42,9 @@ export class WebsocketClientTransport implements ClientTransport {
         resolve(new WebsocketDuplexConnection(websocket, new Deserializer(), multiplexerDemultiplexerFactory));
       };
 
-      const errorListener = (ev: ErrorEvent) => {
+      const errorListener = (event: Event) => {
+        const ev = event as ErrorEvent;
+
         removeListeners();
         // We add a default error in that case.
         if (ev.error != null) {

package/src/client/sync/sync-streams.ts

@@ -1,7 +1,8 @@
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
-
 /**
- * A description of a sync stream, consisting of its {@link name} and the {@link parameters} used when subscribing.
+ * A description of a sync stream, consisting of its {@link SyncStreamDescription.name} and the
+ * {@link SyncStreamDescription.parameters} used when subscribing.
+ *
+ * @public
  */
 export interface SyncStreamDescription {
   /**
@@ -21,6 +22,8 @@ export interface SyncStreamDescription {
  * Information about a subscribed sync stream.
  *
  * This includes the {@link SyncStreamDescription}, along with information about the current sync status.
+ *
+ * @public
  */
 export interface SyncSubscriptionDescription extends SyncStreamDescription {
   active: boolean;
@@ -28,15 +31,17 @@ export interface SyncSubscriptionDescription extends SyncStreamDescription {
    * Whether this stream subscription is included by default, regardless of whether the stream has explicitly been
    * subscribed to or not.
    *
-   * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-   * happens when a default stream was subscribed explicitly.
+   * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+   * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+   * default stream was subscribed explicitly.
    */
   isDefault: boolean;
   /**
    * Whether this stream has been subscribed to explicitly.
    *
-   * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-   * happens when a default stream was subscribed explicitly.
+   * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+   * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+   * default stream was subscribed explicitly.
    */
   hasExplicitSubscription: boolean;
   /**
@@ -49,11 +54,14 @@ export interface SyncSubscriptionDescription extends SyncStreamDescription {
    */
   hasSynced: boolean;
   /**
-   * If {@link hasSynced} is true, the last time data from this stream has been synced.
+   * If {@link SyncSubscriptionDescription.hasSynced} is true, the last time data from this stream has been synced.
    */
   lastSyncedAt: Date | null;
 }
 
+/**
+ * @public
+ */
 export interface SyncStreamSubscribeOptions {
   /**
    * A "time to live" for this stream subscription, in seconds.
@@ -74,6 +82,8 @@ export interface SyncStreamSubscribeOptions {
  * A handle to a {@link SyncStreamDescription} that allows subscribing to the stream.
  *
  * To obtain an instance of {@link SyncStream}, call {@link AbstractPowerSyncDatabase.syncStream}.
+ *
+ * @public
  */
 export interface SyncStream extends SyncStreamDescription {
   /**
@@ -82,7 +92,7 @@ export interface SyncStream extends SyncStreamDescription {
    * You should keep a reference to the returned {@link SyncStreamSubscription} object along as you need data for that
    * stream. As soon as {@link SyncStreamSubscription.unsubscribe} is called for all subscriptions on this stream
    * (including subscriptions created on other tabs), the {@link SyncStreamSubscribeOptions.ttl} starts ticking and will
-   * eventually evict the stream (unless {@link subscribe} is called again).
+   * eventually evict the stream (unless {@link SyncStream.subscribe} is called again).
    */
   subscribe(options?: SyncStreamSubscribeOptions): Promise<SyncStreamSubscription>;
 
@@ -94,6 +104,9 @@ export interface SyncStream extends SyncStreamDescription {
   unsubscribeAll(): Promise<void>;
 }
 
+/**
+ * @public
+ */
 export interface SyncStreamSubscription extends SyncStreamDescription {
   /**
    * A promise that resolves once data from in this sync stream has been synced and applied.