@powersync/common 1.53.2 → 1.55.0

package/dist/bundle.node.cjs

@@ -1,9 +1,11 @@
 'use strict';
 
-var eventIterator = require('event-iterator');
 var node_buffer = require('node:buffer');
 
-// https://www.sqlite.org/lang_expr.html#castexpr
+/**
+ * @see https://www.sqlite.org/lang_expr.html#castexpr
+ * @public
+ */
 exports.ColumnType = void 0;
 (function (ColumnType) {
     ColumnType["TEXT"] = "TEXT";
@@ -19,14 +21,24 @@ const integer = {
 const real = {
     type: exports.ColumnType.REAL
 };
-// powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
-// In earlier versions this was limited to 63.
+/**
+ * powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
+ * In earlier versions this was limited to 63.
+ *
+ * @internal
+ */
 const MAX_AMOUNT_OF_COLUMNS = 1999;
+/**
+ * @public
+ */
 const column = {
     text,
     integer,
     real
 };
+/**
+ * @public
+ */
 class Column {
     options;
     constructor(options) {
@@ -46,9 +58,15 @@ class Column {
     }
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_INDEX_COLUMN_OPTIONS = {
     ascending: true
 };
+/**
+ * @public
+ */
 class IndexedColumn {
     options;
     static createAscending(column) {
@@ -75,9 +93,15 @@ class IndexedColumn {
     }
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_INDEX_OPTIONS = {
     columns: []
 };
+/**
+ * @public
+ */
 class Index {
     options;
     static createAscending(options, columnNames) {
@@ -119,6 +143,9 @@ function encodeTableOptions(options) {
     };
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_TABLE_OPTIONS = {
     indexes: [],
     insertOnly: false,
@@ -127,7 +154,13 @@ const DEFAULT_TABLE_OPTIONS = {
     trackMetadata: false,
     ignoreEmptyUpdates: false
 };
+/**
+ * @internal
+ */
 const InvalidSQLCharacters = /["'%,.#\s[\]]/;
+/**
+ * @public
+ */
 class Table {
     options;
     _mappedColumns;
@@ -318,6 +351,11 @@ class Table {
     }
 }
 
+/**
+ * The default name of the local table storing attachment data.
+ *
+ * @alpha
+ */
 const ATTACHMENT_TABLE = 'attachments';
 /**
  * Maps a database row to an AttachmentRecord.
@@ -325,7 +363,7 @@ const ATTACHMENT_TABLE = 'attachments';
  * @param row - The database row object
  * @returns The corresponding AttachmentRecord
  *
- * @experimental
+ * @alpha
  */
 function attachmentFromSql(row) {
     return {
@@ -343,7 +381,7 @@ function attachmentFromSql(row) {
 /**
  * AttachmentState represents the current synchronization state of an attachment.
  *
- * @experimental
+ * @alpha
  */
 exports.AttachmentState = void 0;
 (function (AttachmentState) {
@@ -356,7 +394,7 @@ exports.AttachmentState = void 0;
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
- * @internal
+ * @alpha
  */
 class AttachmentTable extends Table {
     constructor(options) {
@@ -384,7 +422,8 @@ class AttachmentTable extends Table {
  * Provides methods to query, insert, update, and delete attachment records with
  * proper transaction management through PowerSync.
  *
- * @internal
+ * @experimental
+ * @alpha
  */
 class AttachmentContext {
     /** PowerSync database instance for executing queries */
@@ -606,6 +645,9 @@ class AttachmentContext {
     }
 }
 
+/**
+ * @public
+ */
 exports.WatchedQueryListenerEvent = void 0;
 (function (WatchedQueryListenerEvent) {
     WatchedQueryListenerEvent["ON_DATA"] = "onData";
@@ -614,176 +656,18 @@ exports.WatchedQueryListenerEvent = void 0;
     WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
     WatchedQueryListenerEvent["CLOSED"] = "closed";
 })(exports.WatchedQueryListenerEvent || (exports.WatchedQueryListenerEvent = {}));
+/**
+ * @internal
+ */
 const DEFAULT_WATCH_THROTTLE_MS = 30;
+/**
+ * @internal
+ */
 const DEFAULT_WATCH_QUERY_OPTIONS = {
     throttleMs: DEFAULT_WATCH_THROTTLE_MS,
     reportFetching: true
 };
 
-/**
- * Orchestrates attachment synchronization between local and remote storage.
- * Handles uploads, downloads, deletions, and state transitions.
- *
- * @internal
- */
-class SyncingService {
-    attachmentService;
-    localStorage;
-    remoteStorage;
-    logger;
-    errorHandler;
-    constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
-        this.attachmentService = attachmentService;
-        this.localStorage = localStorage;
-        this.remoteStorage = remoteStorage;
-        this.logger = logger;
-        this.errorHandler = errorHandler;
-    }
-    /**
-     * Processes attachments based on their state (upload, download, or delete).
-     * All updates are saved in a single batch after processing.
-     *
-     * @param attachments - Array of attachment records to process
-     * @param context - Attachment context for database operations
-     * @returns Promise that resolves when all attachments have been processed and saved
-     */
-    async processAttachments(attachments, context) {
-        const updatedAttachments = [];
-        for (const attachment of attachments) {
-            switch (attachment.state) {
-                case exports.AttachmentState.QUEUED_UPLOAD:
-                    const uploaded = await this.uploadAttachment(attachment);
-                    updatedAttachments.push(uploaded);
-                    break;
-                case exports.AttachmentState.QUEUED_DOWNLOAD:
-                    const downloaded = await this.downloadAttachment(attachment);
-                    updatedAttachments.push(downloaded);
-                    break;
-                case exports.AttachmentState.QUEUED_DELETE:
-                    const deleted = await this.deleteAttachment(attachment, context);
-                    updatedAttachments.push(deleted);
-                    break;
-            }
-        }
-        await context.saveAttachments(updatedAttachments);
-    }
-    /**
-     * Uploads an attachment from local storage to remote storage.
-     * On success, marks as SYNCED. On failure, defers to error handler or archives.
-     *
-     * @param attachment - The attachment record to upload
-     * @returns Updated attachment record with new state
-     * @throws Error if the attachment has no localUri
-     */
-    async uploadAttachment(attachment) {
-        this.logger.info(`Uploading attachment ${attachment.filename}`);
-        try {
-            if (attachment.localUri == null) {
-                throw new Error(`No localUri for attachment ${attachment.id}`);
-            }
-            const fileBlob = await this.localStorage.readFile(attachment.localUri);
-            await this.remoteStorage.uploadFile(fileBlob, attachment);
-            return {
-                ...attachment,
-                state: exports.AttachmentState.SYNCED,
-                hasSynced: true
-            };
-        }
-        catch (error) {
-            const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
-            if (!shouldRetry) {
-                return {
-                    ...attachment,
-                    state: exports.AttachmentState.ARCHIVED
-                };
-            }
-            return attachment;
-        }
-    }
-    /**
-     * Downloads an attachment from remote storage to local storage.
-     * Retrieves the file, converts to base64, and saves locally.
-     * On success, marks as SYNCED. On failure, defers to error handler or archives.
-     *
-     * @param attachment - The attachment record to download
-     * @returns Updated attachment record with local URI and new state
-     */
-    async downloadAttachment(attachment) {
-        this.logger.info(`Downloading attachment ${attachment.filename}`);
-        try {
-            const fileData = await this.remoteStorage.downloadFile(attachment);
-            const localUri = this.localStorage.getLocalUri(attachment.filename);
-            await this.localStorage.saveFile(localUri, fileData);
-            return {
-                ...attachment,
-                state: exports.AttachmentState.SYNCED,
-                localUri: localUri,
-                hasSynced: true
-            };
-        }
-        catch (error) {
-            const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
-            if (!shouldRetry) {
-                return {
-                    ...attachment,
-                    state: exports.AttachmentState.ARCHIVED
-                };
-            }
-            return attachment;
-        }
-    }
-    /**
-     * Deletes an attachment from both remote and local storage.
-     * Removes the remote file, local file (if exists), and the attachment record.
-     * On failure, defers to error handler or archives.
-     *
-     * @param attachment - The attachment record to delete
-     * @param context - Attachment context for database operations
-     * @returns Updated attachment record
-     */
-    async deleteAttachment(attachment, context) {
-        try {
-            await this.remoteStorage.deleteFile(attachment);
-            if (attachment.localUri) {
-                await this.localStorage.deleteFile(attachment.localUri);
-            }
-            await context.deleteAttachment(attachment.id);
-            return {
-                ...attachment,
-                state: exports.AttachmentState.ARCHIVED
-            };
-        }
-        catch (error) {
-            const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
-            if (!shouldRetry) {
-                return {
-                    ...attachment,
-                    state: exports.AttachmentState.ARCHIVED
-                };
-            }
-            return attachment;
-        }
-    }
-    /**
-     * Performs cleanup of archived attachments by removing their local files and records.
-     * Errors during local file deletion are logged but do not prevent record deletion.
-     */
-    async deleteArchivedAttachments(context) {
-        return await context.deleteArchivedAttachments(async (archivedAttachments) => {
-            for (const attachment of archivedAttachments) {
-                if (attachment.localUri) {
-                    try {
-                        await this.localStorage.deleteFile(attachment.localUri);
-                    }
-                    catch (error) {
-                        this.logger.error('Error deleting local file for archived attachment', error);
-                    }
-                }
-            }
-        });
-    }
-}
-
 /**
  * A simple fixed-capacity queue implementation.
  *
@@ -969,6 +853,9 @@ class Mutex {
         }
     }
 }
+/**
+ * @internal
+ */
 function timeoutSignal(timeout) {
     if (timeout == null)
         return;
@@ -1031,6 +918,170 @@ class AttachmentService {
     }
 }
 
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+class SyncingService {
+    attachmentService;
+    localStorage;
+    remoteStorage;
+    logger;
+    errorHandler;
+    constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
+        this.attachmentService = attachmentService;
+        this.localStorage = localStorage;
+        this.remoteStorage = remoteStorage;
+        this.logger = logger;
+        this.errorHandler = errorHandler;
+    }
+    /**
+     * Processes attachments based on their state (upload, download, or delete).
+     * All updates are saved in a single batch after processing.
+     *
+     * @param attachments - Array of attachment records to process
+     * @param context - Attachment context for database operations
+     * @returns Promise that resolves when all attachments have been processed and saved
+     */
+    async processAttachments(attachments, context) {
+        const updatedAttachments = [];
+        for (const attachment of attachments) {
+            switch (attachment.state) {
+                case exports.AttachmentState.QUEUED_UPLOAD:
+                    const uploaded = await this.uploadAttachment(attachment);
+                    updatedAttachments.push(uploaded);
+                    break;
+                case exports.AttachmentState.QUEUED_DOWNLOAD:
+                    const downloaded = await this.downloadAttachment(attachment);
+                    updatedAttachments.push(downloaded);
+                    break;
+                case exports.AttachmentState.QUEUED_DELETE:
+                    const deleted = await this.deleteAttachment(attachment, context);
+                    updatedAttachments.push(deleted);
+                    break;
+            }
+        }
+        await context.saveAttachments(updatedAttachments);
+    }
+    /**
+     * Uploads an attachment from local storage to remote storage.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to upload
+     * @returns Updated attachment record with new state
+     * @throws Error if the attachment has no localUri
+     */
+    async uploadAttachment(attachment) {
+        this.logger.info(`Uploading attachment ${attachment.filename}`);
+        try {
+            if (attachment.localUri == null) {
+                throw new Error(`No localUri for attachment ${attachment.id}`);
+            }
+            const fileBlob = await this.localStorage.readFile(attachment.localUri);
+            await this.remoteStorage.uploadFile(fileBlob, attachment);
+            return {
+                ...attachment,
+                state: exports.AttachmentState.SYNCED,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Downloads an attachment from remote storage to local storage.
+     * Retrieves the file, converts to base64, and saves locally.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to download
+     * @returns Updated attachment record with local URI and new state
+     */
+    async downloadAttachment(attachment) {
+        this.logger.info(`Downloading attachment ${attachment.filename}`);
+        try {
+            const fileData = await this.remoteStorage.downloadFile(attachment);
+            const localUri = this.localStorage.getLocalUri(attachment.filename);
+            await this.localStorage.saveFile(localUri, fileData);
+            return {
+                ...attachment,
+                state: exports.AttachmentState.SYNCED,
+                localUri: localUri,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Deletes an attachment from both remote and local storage.
+     * Removes the remote file, local file (if exists), and the attachment record.
+     * On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to delete
+     * @param context - Attachment context for database operations
+     * @returns Updated attachment record
+     */
+    async deleteAttachment(attachment, context) {
+        try {
+            await this.remoteStorage.deleteFile(attachment);
+            if (attachment.localUri) {
+                await this.localStorage.deleteFile(attachment.localUri);
+            }
+            await context.deleteAttachment(attachment.id);
+            return {
+                ...attachment,
+                state: exports.AttachmentState.ARCHIVED
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Performs cleanup of archived attachments by removing their local files and records.
+     * Errors during local file deletion are logged but do not prevent record deletion.
+     */
+    async deleteArchivedAttachments(context) {
+        return await context.deleteArchivedAttachments(async (archivedAttachments) => {
+            for (const attachment of archivedAttachments) {
+                if (attachment.localUri) {
+                    try {
+                        await this.localStorage.deleteFile(attachment.localUri);
+                    }
+                    catch (error) {
+                        this.logger.error('Error deleting local file for archived attachment', error);
+                    }
+                }
+            }
+        });
+    }
+}
+
 /**
  * AttachmentQueue manages the lifecycle and synchronization of attachments
  * between local and remote storage.
@@ -1087,16 +1138,6 @@ class AttachmentQueue {
      * Creates a new AttachmentQueue instance.
      *
      * @param options - Configuration options
-     * @param options.db - PowerSync database instance
-     * @param options.remoteStorage - Remote storage adapter for upload/download operations
-     * @param options.localStorage - Local storage adapter for file persistence
-     * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
-     * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
-     * @param options.logger - Logger instance. Defaults to db.logger
-     * @param options.syncIntervalMs - Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
-     * @param options.syncThrottleDuration - Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
-     * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
-     * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
      */
     constructor({ db, localStorage, remoteStorage, watchAttachments, logger, tableName = ATTACHMENT_TABLE, syncIntervalMs = 30 * 1000, syncThrottleDuration = DEFAULT_WATCH_THROTTLE_MS, downloadAttachments = true, archivedCacheLimit = 100, errorHandler }) {
         this.db = db;
@@ -1185,6 +1226,7 @@ class AttachmentQueue {
                             state: exports.AttachmentState.QUEUED_DOWNLOAD,
                             hasSynced: false,
                             metaData: watchedAttachment.metaData,
+                            mediaType: watchedAttachment.mediaType,
                             timestamp: new Date().getTime()
                         });
                         continue;
@@ -1272,17 +1314,24 @@ class AttachmentQueue {
             this.statusListenerDispose = undefined;
         }
     }
+    /**
+     * Provides an {@link AttachmentContext} to a callback.
+     *
+     * The callback runs while the attachment queue mutex is held. Do not call
+     * other {@link AttachmentQueue} methods from within the callback, as they may
+     * attempt to acquire the same mutex and block indefinitely.
+     */
+    withAttachmentContext(callback) {
+        /**
+         * AttachmentService is internal and private in this class.
+         * We only need to expose its locking and context functionality for extending classes.
+         */
+        return this.attachmentService.withContext(callback);
+    }
     /**
      * Saves a file to local storage and queues it for upload to remote storage.
      *
      * @param options - File save options
-     * @param options.data - The file data as ArrayBuffer, Blob, or base64 string
-     * @param options.fileExtension - File extension (e.g., 'jpg', 'pdf')
-     * @param options.mediaType - MIME type of the file (e.g., 'image/jpeg')
-     * @param options.metaData - Optional metadata to associate with the attachment
-     * @param options.id - Optional custom ID. If not provided, a UUID will be generated
-     * @param options.updateHook - Optional callback to execute additional database operations
-     *                             within the same transaction as the attachment creation
      * @returns Promise resolving to the created attachment record
      */
     async saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }) {
@@ -1395,6 +1444,9 @@ class AttachmentQueue {
     }
 }
 
+/**
+ * @alpha
+ */
 exports.EncodingType = void 0;
 (function (EncodingType) {
     EncodingType["UTF8"] = "utf8";
@@ -1703,7 +1755,9 @@ var Logger = /*@__PURE__*/getDefaultExportFromCjs(loggerExports);
  * different SQLite DB implementations.
  */
 /**
- * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ * Implements {@link DBGetUtils} on a {@link SqlExecutor}.
+ *
+ * @internal
  */
 function DBGetUtilsDefaultMixin(Base) {
     return class extends Base {
@@ -1747,6 +1801,8 @@ function DBGetUtilsDefaultMixin(Base) {
 }
 /**
  * Update table operation numbers from SQLite
+ *
+ * @public
  */
 exports.RowUpdateType = void 0;
 (function (RowUpdateType) {
@@ -1755,8 +1811,10 @@ exports.RowUpdateType = void 0;
     RowUpdateType[RowUpdateType["SQLITE_UPDATE"] = 23] = "SQLITE_UPDATE";
 })(exports.RowUpdateType || (exports.RowUpdateType = {}));
 /**
- * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool.readLock} and
- * {@link ConnectionPool.writeLock}.
+ * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool#readLock} and
+ * {@link ConnectionPool#writeLock}.
+ *
+ * @internal
  */
 function DBAdapterDefaultMixin(Base) {
     return class extends Base {
@@ -1844,9 +1902,15 @@ class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction)
         }
     }
 }
+/**
+ * @internal
+ */
 function isBatchedUpdateNotification(update) {
     return 'tables' in update;
 }
+/**
+ * @internal
+ */
 function extractTableUpdates(update) {
     return isBatchedUpdateNotification(update) ? update.tables : [update.table];
 }
@@ -1874,6 +1938,8 @@ const FULL_SYNC_PRIORITY = 2147483647;
  *
  * Also note that data is downloaded in bulk, which means that individual counters are unlikely
  * to be updated one-by-one.
+ *
+ * @public
  */
 class SyncProgress {
     internal;
@@ -1912,6 +1978,9 @@ class SyncProgress {
     }
 }
 
+/**
+ * @public
+ */
 class SyncStatus {
     options;
     constructor(options) {
@@ -1922,6 +1991,8 @@ class SyncStatus {
      * implementation).
      *
      * This information is only available after a connection has been requested.
+     *
+     * @deprecated This always returns the Rust client (the only option).
      */
     get clientImplementation() {
         return this.options.clientImplementation;
@@ -1929,7 +2000,7 @@ class SyncStatus {
     /**
      * Indicates if the client is currently connected to the PowerSync service.
      *
-     * @returns {boolean} True if connected, false otherwise. Defaults to false if not specified.
+     * @returns True if connected, false otherwise. Defaults to false if not specified.
      */
     get connected() {
         return this.options.connected ?? false;
@@ -1937,7 +2008,7 @@ class SyncStatus {
     /**
      * Indicates if the client is in the process of establishing a connection to the PowerSync service.
      *
-     * @returns {boolean} True if connecting, false otherwise. Defaults to false if not specified.
+     * @returns True if connecting, false otherwise. Defaults to false if not specified.
      */
     get connecting() {
         return this.options.connecting ?? false;
@@ -1946,7 +2017,7 @@ class SyncStatus {
      * Time that a last sync has fully completed, if any.
      * This timestamp is reset to null after a restart of the PowerSync service.
      *
-     * @returns {Date | undefined} The timestamp of the last successful sync, or undefined if no sync has completed.
+     * @returns The timestamp of the last successful sync, or undefined if no sync has completed.
      */
     get lastSyncedAt() {
         return this.options.lastSyncedAt;
@@ -1954,7 +2025,7 @@ class SyncStatus {
     /**
      * Indicates whether there has been at least one full sync completed since initialization.
      *
-     * @returns {boolean | undefined} True if at least one sync has completed, false if no sync has completed,
+     * @returns True if at least one sync has completed, false if no sync has completed,
      * or undefined when the state is still being loaded from the database.
      */
     get hasSynced() {
@@ -1963,10 +2034,10 @@ class SyncStatus {
     /**
      * Provides the current data flow status regarding uploads and downloads.
      *
-     * @returns {SyncDataFlowStatus} An object containing:
+     * @returns An object containing:
      * - downloading: True if actively downloading changes (only when connected is also true)
      * - uploading: True if actively uploading changes
-     * Defaults to {downloading: false, uploading: false} if not specified.
+     * Defaults to `{downloading: false, uploading: false}` if not specified.
      */
     get dataFlowStatus() {
         return (this.options.dataFlow ?? {
@@ -1991,7 +2062,7 @@ class SyncStatus {
         return this.options.dataFlow?.internalStreamSubscriptions?.map((core) => new SyncStreamStatusView(this, core));
     }
     /**
-     * If the `stream` appears in {@link syncStreams}, returns the current status for that stream.
+     * If the `stream` appears in {@link SyncStatus.syncStreams}, returns the current status for that stream.
      */
     forStream(stream) {
         const asJson = JSON.stringify(stream.parameters);
@@ -2001,7 +2072,7 @@ class SyncStatus {
     /**
      * Provides sync status information for all bucket priorities, sorted by priority (highest first).
      *
-     * @returns {SyncPriorityStatus[]} An array of status entries for different sync priority levels,
+     * @returns An array of status entries for different sync priority levels,
      * sorted with highest priorities (lower numbers) first.
      */
     get priorityStatusEntries() {
@@ -2036,8 +2107,8 @@ class SyncStatus {
      * For example, if PowerSync just finished synchronizing buckets in priority level 3, calling this method
      * with a priority of 1 may return information for priority level 3.
      *
-     * @param {number} priority The bucket priority for which the status should be reported
-     * @returns {SyncPriorityStatus} Status information for the requested priority level or the next higher level with available status
+     * @param priority - The bucket priority for which the status should be reported
+     * @returns Status information for the requested priority level or the next higher level with available status
      */
     statusForPriority(priority) {
         // priorityStatusEntries are sorted by ascending priorities (so higher numbers to lower numbers).
@@ -2058,8 +2129,8 @@ class SyncStatus {
      * Compares this SyncStatus instance with another to determine if they are equal.
      * Equality is determined by comparing the serialized JSON representation of both instances.
      *
-     * @param {SyncStatus} status The SyncStatus instance to compare against
-     * @returns {boolean} True if the instances are considered equal, false otherwise
+     * @param status - The SyncStatus instance to compare against
+     * @returns True if the instances are considered equal, false otherwise
      */
     isEqual(status) {
         /**
@@ -2082,7 +2153,7 @@ class SyncStatus {
      * Creates a human-readable string representation of the current sync status.
      * Includes information about connection state, sync completion, and data flow.
      *
-     * @returns {string} A string representation of the sync status
+     * @returns A string representation of the sync status
      */
     getMessage() {
         const dataFlow = this.dataFlowStatus;
@@ -2091,7 +2162,7 @@ class SyncStatus {
     /**
      * Serializes the SyncStatus instance to a plain object.
      *
-     * @returns {SyncStatusOptions} A plain object representation of the sync status
+     * @returns A plain object representation of the sync status
      */
     toJSON() {
         return {
@@ -2157,6 +2228,9 @@ class SyncStreamStatusView {
     }
 }
 
+/**
+ * @public
+ */
 class UploadQueueStats {
     count;
     size;
@@ -2182,6 +2256,9 @@ class UploadQueueStats {
     }
 }
 
+/**
+ * @internal
+ */
 class BaseObserver {
     listeners = new Set();
     constructor() { }
@@ -2209,6 +2286,9 @@ class BaseObserver {
     }
 }
 
+/**
+ * @internal
+ */
 class ControlledExecutor {
     task;
     /**
@@ -2260,6 +2340,210 @@ class ControlledExecutor {
     }
 }
 
+/**
+ * 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.
+ */
+const symbolAsyncIterator = Symbol.asyncIterator ?? Symbol.for('Symbol.asyncIterator');
+
+const doneResult = { done: true, value: undefined };
+function valueResult(value) {
+    return { done: false, value };
+}
+/**
+ * Expands a source async iterator by allowing to inject events asynchronously.
+ *
+ * The resulting iterator will emit all events from its source. Additionally though, events can be injected. These
+ * events are dropped once the main iterator completes, but are otherwise forwarded.
+ *
+ * The iterator completes when its source completes, and it supports backpressure by only calling `next()` on the source
+ * in response to a `next()` call from downstream if no pending injected events can be dispatched.
+ */
+function injectable(source) {
+    let sourceIsDone = false;
+    let waiter = undefined; // An active, waiting next() call.
+    // A pending upstream event that couldn't be dispatched because inject() has been called before it was resolved.
+    let pendingSourceEvent = null;
+    let sourceFetchInFlight = false;
+    let pendingInjectedEvents = [];
+    const consumeWaiter = () => {
+        const pending = waiter;
+        waiter = undefined;
+        return pending;
+    };
+    const fetchFromSource = () => {
+        const resolveWaiter = (propagate) => {
+            sourceFetchInFlight = false;
+            const active = consumeWaiter();
+            if (active) {
+                propagate(active);
+            }
+            else {
+                pendingSourceEvent = propagate;
+            }
+        };
+        sourceFetchInFlight = true;
+        const nextFromSource = source.next();
+        nextFromSource.then((value) => {
+            sourceIsDone = value.done == true;
+            resolveWaiter((w) => w.resolve(value));
+        }, (error) => {
+            resolveWaiter((w) => w.reject(error));
+        });
+    };
+    return {
+        next: () => {
+            return new Promise((resolve, reject) => {
+                // First priority: Dispatch ready upstream events.
+                if (sourceIsDone) {
+                    return resolve(doneResult);
+                }
+                if (pendingSourceEvent) {
+                    pendingSourceEvent({ resolve, reject });
+                    pendingSourceEvent = null;
+                    return;
+                }
+                // Second priority: Dispatch injected events
+                if (pendingInjectedEvents.length) {
+                    return resolve(valueResult(pendingInjectedEvents.shift()));
+                }
+                // Nothing pending? Fetch from source
+                waiter = { resolve, reject };
+                if (!sourceFetchInFlight) {
+                    fetchFromSource();
+                }
+            });
+        },
+        inject: (event) => {
+            const pending = consumeWaiter();
+            if (pending != null) {
+                pending.resolve(valueResult(event));
+            }
+            else {
+                pendingInjectedEvents.push(event);
+            }
+        }
+    };
+}
+/**
+ * Splits a byte stream at line endings, emitting each line as a string.
+ */
+function extractJsonLines(source, decoder) {
+    let buffer = '';
+    const pendingLines = [];
+    let isFinalEvent = false;
+    return {
+        next: async () => {
+            while (true) {
+                if (isFinalEvent) {
+                    return doneResult;
+                }
+                {
+                    const first = pendingLines.shift();
+                    if (first) {
+                        return { done: false, value: first };
+                    }
+                }
+                const { done, value } = await source.next();
+                if (done) {
+                    const remaining = buffer.trim();
+                    if (remaining.length != 0) {
+                        isFinalEvent = true;
+                        return { done: false, value: remaining };
+                    }
+                    return doneResult;
+                }
+                const data = decoder.decode(value, { stream: true });
+                buffer += data;
+                const lines = buffer.split('\n');
+                for (let i = 0; i < lines.length - 1; i++) {
+                    const l = lines[i].trim();
+                    if (l.length > 0) {
+                        pendingLines.push(l);
+                    }
+                }
+                buffer = lines[lines.length - 1];
+            }
+        }
+    };
+}
+/**
+ * Splits a concatenated stream of BSON objects by emitting individual objects.
+ */
+function extractBsonObjects(source) {
+    // Fully read but not emitted yet.
+    const completedObjects = [];
+    // Whether source has returned { done: true }. We do the same once completed objects have been emitted.
+    let isDone = false;
+    const lengthBuffer = new DataView(new ArrayBuffer(4));
+    let objectBody = null;
+    // If we're parsing the length field, a number between 1 and 4 (inclusive) describing remaining bytes in the header.
+    // If we're consuming a document, the bytes remaining.
+    let remainingLength = 4;
+    return {
+        async next() {
+            while (true) {
+                // Before fetching new data from upstream, return completed objects.
+                if (completedObjects.length) {
+                    return valueResult(completedObjects.shift());
+                }
+                if (isDone) {
+                    return doneResult;
+                }
+                const upstreamEvent = await source.next();
+                if (upstreamEvent.done) {
+                    isDone = true;
+                    if (objectBody || remainingLength != 4) {
+                        throw new Error('illegal end of stream in BSON object');
+                    }
+                    return doneResult;
+                }
+                const chunk = upstreamEvent.value;
+                for (let i = 0; i < chunk.length;) {
+                    const availableInData = chunk.length - i;
+                    if (objectBody) {
+                        // We're in the middle of reading a BSON document.
+                        const bytesToRead = Math.min(availableInData, remainingLength);
+                        const copySource = new Uint8Array(chunk.buffer, chunk.byteOffset + i, bytesToRead);
+                        objectBody.set(copySource, objectBody.length - remainingLength);
+                        i += bytesToRead;
+                        remainingLength -= bytesToRead;
+                        if (remainingLength == 0) {
+                            completedObjects.push(objectBody);
+                            // Prepare to read another document, starting with its length
+                            objectBody = null;
+                            remainingLength = 4;
+                        }
+                    }
+                    else {
+                        // Copy up to 4 bytes into lengthBuffer, depending on how many we still need.
+                        const bytesToRead = Math.min(availableInData, remainingLength);
+                        for (let j = 0; j < bytesToRead; j++) {
+                            lengthBuffer.setUint8(4 - remainingLength + j, chunk[i + j]);
+                        }
+                        i += bytesToRead;
+                        remainingLength -= bytesToRead;
+                        if (remainingLength == 0) {
+                            // Transition from reading length header to reading document. Subtracting 4 because the length of the
+                            // header is included in length.
+                            const length = lengthBuffer.getInt32(0, true /* little endian */);
+                            remainingLength = length - 4;
+                            if (remainingLength < 1) {
+                                throw new Error(`invalid length for bson: ${length}`);
+                            }
+                            objectBody = new Uint8Array(length);
+                            new DataView(objectBody.buffer).setInt32(0, length, true);
+                        }
+                    }
+                }
+            }
+        }
+    };
+}
+
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.
@@ -2279,45 +2563,128 @@ function throttleTrailing(func, wait) {
     };
 }
 function asyncNotifier() {
-    let waitingConsumer = null;
-    let hasPendingNotification = false;
+    const queue = new EventQueue();
     return {
         notify() {
-            if (waitingConsumer != null) {
-                waitingConsumer();
-                waitingConsumer = null;
-            }
+            if (queue.countOutstandingEvents > 0) ;
             else {
-                hasPendingNotification = true;
+                queue.notify();
             }
         },
         waitForNotification(signal) {
-            return new Promise((resolve) => {
-                if (waitingConsumer != null) {
-                    throw new Error('Illegal call to waitForNotification, already has a waiter.');
-                }
-                if (signal.aborted) {
-                    resolve();
+            return queue.waitForEvent(signal);
+        }
+    };
+}
+class EventQueue {
+    options;
+    waitingConsumer;
+    outstandingEvents;
+    constructor(options = {}) {
+        this.options = options;
+        this.outstandingEvents = [];
+    }
+    /**
+     * The amount of buffered events not yet dispatched to listeners.
+     */
+    get countOutstandingEvents() {
+        return this.outstandingEvents.length;
+    }
+    notifyInner(dispatch) {
+        const existing = this.waitingConsumer;
+        this.waitingConsumer = undefined;
+        const dispatchAndNotifyListeners = (waiter) => {
+            dispatch(waiter);
+            this.options.eventDelivered?.();
+        };
+        if (existing) {
+            dispatchAndNotifyListeners(existing);
+        }
+        else {
+            this.outstandingEvents.push(dispatchAndNotifyListeners);
+        }
+    }
+    notify(value) {
+        this.notifyInner((l) => l.resolve(value));
+    }
+    notifyError(error) {
+        this.notifyInner((l) => l.reject(error));
+    }
+    waitForEvent(signal) {
+        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 = {
+                resolve: (value) => {
+                    complete();
+                    resolve(value);
+                },
+                reject: (error) => {
+                    complete();
+                    reject(error);
                 }
-                else if (hasPendingNotification) {
-                    resolve();
-                    hasPendingNotification = false;
+            };
+            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);
+            }
+        });
+    }
+    /**
+     * 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(run, abort) {
+        return {
+            [symbolAsyncIterator]: () => {
+                const queue = new EventQueue();
+                const controller = new AbortController();
+                function dispose() {
+                    controller.abort();
+                    abort?.removeEventListener('abort', dispose);
                 }
-                else {
-                    function complete() {
-                        signal.removeEventListener('abort', onAbort);
-                        resolve();
+                if (abort) {
+                    if (abort.aborted) {
+                        controller.abort();
                     }
-                    function onAbort() {
-                        waitingConsumer = null;
-                        resolve();
+                    else {
+                        abort.addEventListener('abort', dispose);
                     }
-                    waitingConsumer = complete;
-                    signal.addEventListener('abort', onAbort);
                 }
-            });
-        }
-    };
+                run(queue, controller.signal);
+                return {
+                    async next() {
+                        const event = await queue.waitForEvent(controller.signal);
+                        return event == null ? doneResult : valueResult(event);
+                    },
+                    async return() {
+                        dispose();
+                        return doneResult;
+                    }
+                };
+            }
+        };
+    }
 }
 
 /**
@@ -2476,7 +2843,7 @@ class ConnectionManager extends BaseObserver {
     /**
      * Close the sync connection.
      *
-     * Use {@link connect} to connect again.
+     * Use {@link ConnectionManager.connect} to connect again.
      */
     async disconnect() {
         // This will help abort pending connects
@@ -2616,6 +2983,8 @@ const _finalizer = 'FinalizationRegistry' in globalThis
 /**
  * An efficient comparator for {@link WatchedQuery} created with {@link Query#watch}. This has the ability to determine if a query
  * result has changes without necessarily processing all items in the result.
+ *
+ * @public
  */
 class ArrayComparator {
     options;
@@ -2643,6 +3012,8 @@ class ArrayComparator {
 }
 /**
  * Watched query comparator that always reports changed result sets.
+ *
+ * @public
  */
 const FalsyComparator = {
     checkEquality: () => false // Default comparator that always returns false
@@ -2850,6 +3221,8 @@ class AbstractQueryProcessor extends MetaBaseObserver {
 /**
  * An empty differential result set.
  * This is used as the initial state for differential incrementally watched queries.
+ *
+ * @internal
  */
 const EMPTY_DIFFERENTIAL = {
     added: [],
@@ -2862,6 +3235,8 @@ const EMPTY_DIFFERENTIAL = {
  * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
  * It keys items by their `id` property if available, alternatively it uses JSON stringification
  * of the entire item for the key and comparison.
+ *
+ * @internal
  */
 const DEFAULT_ROW_COMPARATOR = {
     keyBy: (item) => {
@@ -3142,6 +3517,8 @@ class CustomQuery {
 
 /**
  * Tests if the input is a {@link SQLOpenOptions}
+ *
+ * @internal
  */
 const isSQLOpenOptions = (test) => {
     // typeof null is `object`, but you cannot use the `in` operator on `null.
@@ -3149,17 +3526,24 @@ const isSQLOpenOptions = (test) => {
 };
 /**
  * Tests if input is a {@link SQLOpenFactory}
+ *
+ * @internal
  */
 const isSQLOpenFactory = (test) => {
     return typeof test?.openDB == 'function';
 };
 /**
  * Tests if input is a {@link DBAdapter}
+ *
+ * @internal
  */
 const isDBAdapter = (test) => {
     return typeof test?.writeTransaction == 'function';
 };
 
+/**
+ * @internal
+ */
 exports.PSInternalTable = void 0;
 (function (PSInternalTable) {
     PSInternalTable["DATA"] = "ps_data";
@@ -3168,6 +3552,9 @@ exports.PSInternalTable = void 0;
     PSInternalTable["OPLOG"] = "ps_oplog";
     PSInternalTable["UNTYPED"] = "ps_untyped";
 })(exports.PSInternalTable || (exports.PSInternalTable = {}));
+/**
+ * @internal
+ */
 exports.PowerSyncControlCommand = void 0;
 (function (PowerSyncControlCommand) {
     PowerSyncControlCommand["PROCESS_TEXT_LINE"] = "line_text";
@@ -3185,6 +3572,8 @@ exports.PowerSyncControlCommand = void 0;
 
 /**
  * A batch of client-side changes.
+ *
+ * @public
  */
 class CrudBatch {
     crud;
@@ -3211,6 +3600,8 @@ class CrudBatch {
 
 /**
  * Type of local change.
+ *
+ * @public
  */
 exports.UpdateType = void 0;
 (function (UpdateType) {
@@ -3223,6 +3614,8 @@ exports.UpdateType = void 0;
 })(exports.UpdateType || (exports.UpdateType = {}));
 /**
  * A single client-side change.
+ *
+ * @public
  */
 class CrudEntry {
     /**
@@ -3319,6 +3712,9 @@ class CrudEntry {
     }
 }
 
+/**
+ * @public
+ */
 class CrudTransaction extends CrudBatch {
     crud;
     complete;
@@ -3347,6 +3743,8 @@ class CrudTransaction extends CrudBatch {
  * 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
  */
 class AbortOperation extends Error {
     reason;
@@ -8146,7 +8544,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.53.2";
+var version = "1.55.0";
 var PACKAGE = {
 	version: version};
 
@@ -8222,289 +8620,95 @@ function requireWebsocketDuplexConnection () {
 	        get: function () {
 	            return this.done ? 0 : 1;
 	        },
-	        enumerable: false,
-	        configurable: true
-	    });
-	    WebsocketDuplexConnection.prototype.close = function (error) {
-	        if (this.done) {
-	            _super.prototype.close.call(this, error);
-	            return;
-	        }
-	        this.websocket.removeEventListener("close", this.handleClosed);
-	        this.websocket.removeEventListener("error", this.handleError);
-	        this.websocket.removeEventListener("message", this.handleMessage);
-	        this.websocket.close();
-	        delete this.websocket;
-	        _super.prototype.close.call(this, error);
-	    };
-	    WebsocketDuplexConnection.prototype.send = function (frame) {
-	        if (this.done) {
-	            return;
-	        }
-	        var buffer = (0, rsocket_core_1.serializeFrame)(frame);
-	        this.websocket.send(buffer);
-	    };
-	    return WebsocketDuplexConnection;
-	}(rsocket_core_1.Deferred));
-	WebsocketDuplexConnection.WebsocketDuplexConnection = WebsocketDuplexConnection$1;
-	
-	return WebsocketDuplexConnection;
-}
-
-var WebsocketDuplexConnectionExports = requireWebsocketDuplexConnection();
-
-/**
- * Adapted from rsocket-websocket-client
- * https://github.com/rsocket/rsocket-js/blob/e224cf379e747c4f1ddc4f2fa111854626cc8575/packages/rsocket-websocket-client/src/WebsocketClientTransport.ts#L17
- * This adds additional error handling for React Native iOS.
- * This particularly adds a close listener to handle cases where the WebSocket
- * connection closes immediately after opening without emitting an error.
- */
-class WebsocketClientTransport {
-    url;
-    factory;
-    constructor(options) {
-        this.url = options.url;
-        this.factory = options.wsCreator ?? ((url) => new WebSocket(url));
-    }
-    connect(multiplexerDemultiplexerFactory) {
-        return new Promise((resolve, reject) => {
-            const websocket = this.factory(this.url);
-            websocket.binaryType = 'arraybuffer';
-            let removeListeners;
-            const openListener = () => {
-                removeListeners();
-                resolve(new WebsocketDuplexConnectionExports.WebsocketDuplexConnection(websocket, new distExports.Deserializer(), multiplexerDemultiplexerFactory));
-            };
-            const errorListener = (ev) => {
-                removeListeners();
-                // We add a default error in that case.
-                if (ev.error != null) {
-                    // undici typically provides an error object
-                    reject(ev.error);
-                }
-                else if (ev.message != null) {
-                    // React Native typically does not provide an error object, but does provide a message
-                    reject(new Error(`Failed to create websocket connection: ${ev.message}`));
-                }
-                else {
-                    // Browsers often provide no details at all
-                    reject(new Error(`Failed to create websocket connection to ${this.url}`));
-                }
-            };
-            /**
-             * In some cases, such as React Native iOS, the WebSocket connection may close immediately after opening
-             * without and error. In such cases, we need to handle the close event to reject the promise.
-             */
-            const closeListener = () => {
-                removeListeners();
-                reject(new Error('WebSocket connection closed while opening'));
-            };
-            removeListeners = () => {
-                websocket.removeEventListener('open', openListener);
-                websocket.removeEventListener('error', errorListener);
-                websocket.removeEventListener('close', closeListener);
-            };
-            websocket.addEventListener('open', openListener);
-            websocket.addEventListener('error', errorListener);
-            websocket.addEventListener('close', closeListener);
-        });
-    }
-}
-
-const doneResult = { done: true, value: undefined };
-function valueResult(value) {
-    return { done: false, value };
-}
-/**
- * Expands a source async iterator by allowing to inject events asynchronously.
- *
- * The resulting iterator will emit all events from its source. Additionally though, events can be injected. These
- * events are dropped once the main iterator completes, but are otherwise forwarded.
- *
- * The iterator completes when its source completes, and it supports backpressure by only calling `next()` on the source
- * in response to a `next()` call from downstream if no pending injected events can be dispatched.
- */
-function injectable(source) {
-    let sourceIsDone = false;
-    let waiter = undefined; // An active, waiting next() call.
-    // A pending upstream event that couldn't be dispatched because inject() has been called before it was resolved.
-    let pendingSourceEvent = null;
-    let sourceFetchInFlight = false;
-    let pendingInjectedEvents = [];
-    const consumeWaiter = () => {
-        const pending = waiter;
-        waiter = undefined;
-        return pending;
-    };
-    const fetchFromSource = () => {
-        const resolveWaiter = (propagate) => {
-            sourceFetchInFlight = false;
-            const active = consumeWaiter();
-            if (active) {
-                propagate(active);
-            }
-            else {
-                pendingSourceEvent = propagate;
-            }
-        };
-        sourceFetchInFlight = true;
-        const nextFromSource = source.next();
-        nextFromSource.then((value) => {
-            sourceIsDone = value.done == true;
-            resolveWaiter((w) => w.resolve(value));
-        }, (error) => {
-            resolveWaiter((w) => w.reject(error));
-        });
-    };
-    return {
-        next: () => {
-            return new Promise((resolve, reject) => {
-                // First priority: Dispatch ready upstream events.
-                if (sourceIsDone) {
-                    return resolve(doneResult);
-                }
-                if (pendingSourceEvent) {
-                    pendingSourceEvent({ resolve, reject });
-                    pendingSourceEvent = null;
-                    return;
-                }
-                // Second priority: Dispatch injected events
-                if (pendingInjectedEvents.length) {
-                    return resolve(valueResult(pendingInjectedEvents.shift()));
-                }
-                // Nothing pending? Fetch from source
-                waiter = { resolve, reject };
-                if (!sourceFetchInFlight) {
-                    fetchFromSource();
-                }
-            });
-        },
-        inject: (event) => {
-            const pending = consumeWaiter();
-            if (pending != null) {
-                pending.resolve(valueResult(event));
-            }
-            else {
-                pendingInjectedEvents.push(event);
-            }
-        }
-    };
-}
-/**
- * Splits a byte stream at line endings, emitting each line as a string.
- */
-function extractJsonLines(source, decoder) {
-    let buffer = '';
-    const pendingLines = [];
-    let isFinalEvent = false;
-    return {
-        next: async () => {
-            while (true) {
-                if (isFinalEvent) {
-                    return doneResult;
-                }
-                {
-                    const first = pendingLines.shift();
-                    if (first) {
-                        return { done: false, value: first };
-                    }
-                }
-                const { done, value } = await source.next();
-                if (done) {
-                    const remaining = buffer.trim();
-                    if (remaining.length != 0) {
-                        isFinalEvent = true;
-                        return { done: false, value: remaining };
-                    }
-                    return doneResult;
-                }
-                const data = decoder.decode(value, { stream: true });
-                buffer += data;
-                const lines = buffer.split('\n');
-                for (let i = 0; i < lines.length - 1; i++) {
-                    const l = lines[i].trim();
-                    if (l.length > 0) {
-                        pendingLines.push(l);
-                    }
-                }
-                buffer = lines[lines.length - 1];
-            }
-        }
-    };
+	        enumerable: false,
+	        configurable: true
+	    });
+	    WebsocketDuplexConnection.prototype.close = function (error) {
+	        if (this.done) {
+	            _super.prototype.close.call(this, error);
+	            return;
+	        }
+	        this.websocket.removeEventListener("close", this.handleClosed);
+	        this.websocket.removeEventListener("error", this.handleError);
+	        this.websocket.removeEventListener("message", this.handleMessage);
+	        this.websocket.close();
+	        delete this.websocket;
+	        _super.prototype.close.call(this, error);
+	    };
+	    WebsocketDuplexConnection.prototype.send = function (frame) {
+	        if (this.done) {
+	            return;
+	        }
+	        var buffer = (0, rsocket_core_1.serializeFrame)(frame);
+	        this.websocket.send(buffer);
+	    };
+	    return WebsocketDuplexConnection;
+	}(rsocket_core_1.Deferred));
+	WebsocketDuplexConnection.WebsocketDuplexConnection = WebsocketDuplexConnection$1;
+	
+	return WebsocketDuplexConnection;
 }
+
+var WebsocketDuplexConnectionExports = requireWebsocketDuplexConnection();
+
 /**
- * Splits a concatenated stream of BSON objects by emitting individual objects.
+ * Adapted from rsocket-websocket-client
+ * https://github.com/rsocket/rsocket-js/blob/e224cf379e747c4f1ddc4f2fa111854626cc8575/packages/rsocket-websocket-client/src/WebsocketClientTransport.ts#L17
+ * This adds additional error handling for React Native iOS.
+ * This particularly adds a close listener to handle cases where the WebSocket
+ * connection closes immediately after opening without emitting an error.
  */
-function extractBsonObjects(source) {
-    // Fully read but not emitted yet.
-    const completedObjects = [];
-    // Whether source has returned { done: true }. We do the same once completed objects have been emitted.
-    let isDone = false;
-    const lengthBuffer = new DataView(new ArrayBuffer(4));
-    let objectBody = null;
-    // If we're parsing the length field, a number between 1 and 4 (inclusive) describing remaining bytes in the header.
-    // If we're consuming a document, the bytes remaining.
-    let remainingLength = 4;
-    return {
-        async next() {
-            while (true) {
-                // Before fetching new data from upstream, return completed objects.
-                if (completedObjects.length) {
-                    return valueResult(completedObjects.shift());
-                }
-                if (isDone) {
-                    return doneResult;
+class WebsocketClientTransport {
+    url;
+    factory;
+    constructor(options) {
+        this.url = options.url;
+        this.factory = options.wsCreator ?? ((url) => new WebSocket(url));
+    }
+    connect(multiplexerDemultiplexerFactory) {
+        return new Promise((resolve, reject) => {
+            const websocket = this.factory(this.url);
+            websocket.binaryType = 'arraybuffer';
+            let removeListeners;
+            const openListener = () => {
+                removeListeners();
+                resolve(new WebsocketDuplexConnectionExports.WebsocketDuplexConnection(websocket, new distExports.Deserializer(), multiplexerDemultiplexerFactory));
+            };
+            const errorListener = (event) => {
+                const ev = event;
+                removeListeners();
+                // We add a default error in that case.
+                if (ev.error != null) {
+                    // undici typically provides an error object
+                    reject(ev.error);
                 }
-                const upstreamEvent = await source.next();
-                if (upstreamEvent.done) {
-                    isDone = true;
-                    if (objectBody || remainingLength != 4) {
-                        throw new Error('illegal end of stream in BSON object');
-                    }
-                    return doneResult;
+                else if (ev.message != null) {
+                    // React Native typically does not provide an error object, but does provide a message
+                    reject(new Error(`Failed to create websocket connection: ${ev.message}`));
                 }
-                const chunk = upstreamEvent.value;
-                for (let i = 0; i < chunk.length;) {
-                    const availableInData = chunk.length - i;
-                    if (objectBody) {
-                        // We're in the middle of reading a BSON document.
-                        const bytesToRead = Math.min(availableInData, remainingLength);
-                        const copySource = new Uint8Array(chunk.buffer, chunk.byteOffset + i, bytesToRead);
-                        objectBody.set(copySource, objectBody.length - remainingLength);
-                        i += bytesToRead;
-                        remainingLength -= bytesToRead;
-                        if (remainingLength == 0) {
-                            completedObjects.push(objectBody);
-                            // Prepare to read another document, starting with its length
-                            objectBody = null;
-                            remainingLength = 4;
-                        }
-                    }
-                    else {
-                        // Copy up to 4 bytes into lengthBuffer, depending on how many we still need.
-                        const bytesToRead = Math.min(availableInData, remainingLength);
-                        for (let j = 0; j < bytesToRead; j++) {
-                            lengthBuffer.setUint8(4 - remainingLength + j, chunk[i + j]);
-                        }
-                        i += bytesToRead;
-                        remainingLength -= bytesToRead;
-                        if (remainingLength == 0) {
-                            // Transition from reading length header to reading document. Subtracting 4 because the length of the
-                            // header is included in length.
-                            const length = lengthBuffer.getInt32(0, true /* little endian */);
-                            remainingLength = length - 4;
-                            if (remainingLength < 1) {
-                                throw new Error(`invalid length for bson: ${length}`);
-                            }
-                            objectBody = new Uint8Array(length);
-                            new DataView(objectBody.buffer).setInt32(0, length, true);
-                        }
-                    }
+                else {
+                    // Browsers often provide no details at all
+                    reject(new Error(`Failed to create websocket connection to ${this.url}`));
                 }
-            }
-        }
-    };
+            };
+            /**
+             * In some cases, such as React Native iOS, the WebSocket connection may close immediately after opening
+             * without and error. In such cases, we need to handle the close event to reject the promise.
+             */
+            const closeListener = () => {
+                removeListeners();
+                reject(new Error('WebSocket connection closed while opening'));
+            };
+            removeListeners = () => {
+                websocket.removeEventListener('open', openListener);
+                websocket.removeEventListener('error', errorListener);
+                websocket.removeEventListener('close', closeListener);
+            };
+            websocket.addEventListener('open', openListener);
+            websocket.addEventListener('error', errorListener);
+            websocket.addEventListener('close', closeListener);
+        });
+    }
 }
 
 const POWERSYNC_TRAILING_SLASH_MATCH = /\/+$/;
@@ -8519,7 +8723,13 @@ const SOCKET_TIMEOUT_MS = 30_000;
 // If there is a backlog of messages (for example on slow connections), keepalive messages could be delayed
 // significantly. Therefore this is longer than the socket timeout.
 const KEEP_ALIVE_LIFETIME_MS = 90_000;
+/**
+ * @internal
+ */
 const DEFAULT_REMOTE_LOGGER = Logger.get('PowerSyncRemote');
+/**
+ * @public
+ */
 exports.FetchStrategy = void 0;
 (function (FetchStrategy) {
     /**
@@ -8538,12 +8748,17 @@ exports.FetchStrategy = void 0;
  * The class wrapper is used to distinguish the fetchImplementation
  * option in [AbstractRemoteOptions] from the general fetch method
  * which is typeof "function"
+ *
+ * @internal
  */
 class FetchImplementationProvider {
     getFetch() {
         throw new Error('Unspecified fetch implementation');
     }
 }
+/**
+ * @internal
+ */
 const DEFAULT_REMOTE_OPTIONS = {
     socketUrlTransformer: (url) => url.replace(/^https?:\/\//, function (match) {
         return match === 'https://' ? 'wss://' : 'ws://';
@@ -8551,6 +8766,9 @@ const DEFAULT_REMOTE_OPTIONS = {
     fetchImplementation: new FetchImplementationProvider(),
     fetchOptions: {}
 };
+/**
+ * @internal
+ */
 class AbstractRemote {
     connector;
     logger;
@@ -8711,8 +8929,19 @@ class AbstractRemote {
         let pendingSocket = null;
         let keepAliveTimeout;
         let rsocket = null;
-        let queue = null;
+        let paused = false;
+        const queue = new EventQueue({
+            eventDelivered: () => {
+                if (queue.countOutstandingEvents <= SYNC_QUEUE_REQUEST_LOW_WATER) {
+                    paused = false;
+                    requestMore();
+                }
+            }
+        });
         let didClose = false;
+        let connectionEstablished = false;
+        let pendingEventsCount = syncQueueRequestSize;
+        let res = null;
         const abortRequest = () => {
             if (didClose) {
                 return;
@@ -8725,10 +8954,23 @@ class AbstractRemote {
             if (rsocket) {
                 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) {
+            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');
@@ -8783,25 +9025,19 @@ class AbstractRemote {
         // Helps to prevent double close scenarios
         rsocket.onClose(() => (rsocket = null));
         return await new Promise((resolve, reject) => {
-            let connectionEstablished = false;
-            let pendingEventsCount = syncQueueRequestSize;
-            let paused = false;
-            let res = null;
-            function requestMore() {
-                const delta = syncQueueRequestSize - pendingEventsCount;
-                if (!paused && delta > 0) {
-                    res?.request(delta);
-                    pendingEventsCount = syncQueueRequestSize;
+            const queueAsIterator = {
+                next: async () => {
+                    if (didClose)
+                        return doneResult;
+                    const notification = await queue.waitForEvent(options.abortSignal);
+                    if (didClose) {
+                        return doneResult;
+                    }
+                    else {
+                        return valueResult(notification);
+                    }
                 }
-            }
-            const events = new eventIterator.EventIterator((q) => {
-                queue = q;
-                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]();
+            };
             res = rsocket.requestStream({
                 data: toBuffer(options.data),
                 metadata: toBuffer({
@@ -8837,11 +9073,11 @@ 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
                     pendingEventsCount--;
@@ -8960,7 +9196,7 @@ 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) {
         const { isBson, stream } = await this.fetchStreamRaw(options);
@@ -9002,16 +9238,26 @@ function isInterruptingInstruction(instruction) {
     return 'EstablishSyncStream' in instruction || 'CloseSyncStream' in instruction;
 }
 
+/**
+ * @internal
+ */
 exports.LockType = void 0;
 (function (LockType) {
     LockType["CRUD"] = "crud";
     LockType["SYNC"] = "sync";
 })(exports.LockType || (exports.LockType = {}));
+/**
+ * @public
+ */
 exports.SyncStreamConnectionMethod = void 0;
 (function (SyncStreamConnectionMethod) {
     SyncStreamConnectionMethod["HTTP"] = "http";
     SyncStreamConnectionMethod["WEB_SOCKET"] = "web-socket";
 })(exports.SyncStreamConnectionMethod || (exports.SyncStreamConnectionMethod = {}));
+/**
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
+ */
 exports.SyncClientImplementation = void 0;
 (function (SyncClientImplementation) {
     /**
@@ -9023,8 +9269,8 @@ exports.SyncClientImplementation = void 0;
      * ## 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
@@ -9034,14 +9280,29 @@ exports.SyncClientImplementation = void 0;
 })(exports.SyncClientImplementation || (exports.SyncClientImplementation = {}));
 /**
  * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
+ *
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
  */
 const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = exports.SyncClientImplementation.RUST;
+/**
+ * @internal
+ */
 const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
+/**
+ * @internal
+ */
 const DEFAULT_RETRY_DELAY_MS = 5000;
+/**
+ * @internal
+ */
 const DEFAULT_STREAMING_SYNC_OPTIONS = {
     retryDelayMs: DEFAULT_RETRY_DELAY_MS,
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
+/**
+ * @internal
+ */
 const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     appMetadata: {},
     connectionMethod: exports.SyncStreamConnectionMethod.WEB_SOCKET,
@@ -9051,6 +9312,9 @@ const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     serializedSchema: undefined,
     includeDefaultStreams: true
 };
+/**
+ * @internal
+ */
 class AbstractStreamingSyncImplementation extends BaseObserver {
     options;
     abortController;
@@ -9374,7 +9638,7 @@ The next upload iteration will be delayed.`);
         this.handleActiveStreamsChange?.();
     }
     /**
-     * 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
@@ -9384,7 +9648,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.
      */
@@ -9691,7 +9955,8 @@ const MEMORY_TRIGGER_CLAIM_MANAGER = {
 
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
- * @experimental
+ *
+ * @experimental @alpha
  */
 exports.DiffTriggerOperation = void 0;
 (function (DiffTriggerOperation) {
@@ -9753,8 +10018,8 @@ class TriggerManagerImpl {
     get db() {
         return this.options.db;
     }
-    async getUUID() {
-        const { id: uuid } = await this.db.get(/* sql */ `
+    async getUUID(ctx) {
+        const { id: uuid } = await (ctx ?? this.db).get(/* sql */ `
       SELECT
         uuid () as id
     `);
@@ -9867,7 +10132,7 @@ class TriggerManagerImpl {
         const replicatedColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
         const internalSource = sourceDefinition.internalName;
         const triggerIds = [];
-        const id = await this.getUUID();
+        const id = await this.getUUID(setupContext);
         const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
         /**
          * We default to replicating all columns if no columns array is provided.
@@ -10107,18 +10372,29 @@ const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
 };
+/**
+ * @internal
+ */
 const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
     disconnect: true
 };
+/**
+ * @internal
+ */
 const DEFAULT_POWERSYNC_DB_OPTIONS = {
     retryDelayMs: 5000,
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
+/**
+ * @internal
+ */
 const DEFAULT_CRUD_BATCH_LIMIT = 100;
 /**
  * Requesting nested or recursive locks can block the application in some circumstances.
  * This default lock timeout will act as a failsafe to throw an error if a lock cannot
  * be obtained.
+ *
+ * @internal
  */
 const DEFAULT_LOCK_TIMEOUT_MS = 120_000; // 2 mins
 /**
@@ -10128,6 +10404,9 @@ const DEFAULT_LOCK_TIMEOUT_MS = 120_000; // 2 mins
 const isPowerSyncDatabaseOptionsWithSettings = (test) => {
     return typeof test == 'object' && isSQLOpenOptions(test.database);
 };
+/**
+ * @public
+ */
 class AbstractPowerSyncDatabase extends BaseObserver {
     options;
     /**
@@ -10285,7 +10564,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     /**
      * Wait for the first sync operation to complete.
      *
-     * @param request Either an abort signal (after which the promise will complete regardless of
+     * @param request - Either an abort signal (after which the promise will complete regardless of
      * whether a full sync was completed) or an object providing an abort signal and a priority target.
      * When a priority target is set, the promise may complete when all buckets with the given (or higher)
      * priorities have been synchronized. This can be earlier than a complete sync.
@@ -10440,7 +10719,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     /**
      * Close the sync connection.
      *
-     * Use {@link connect} to connect again.
+     * Use {@link AbstractPowerSyncDatabase.connect} to connect again.
      */
     async disconnect() {
         return this.connectionManager.disconnect();
@@ -10467,8 +10746,8 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     /**
      * Create a sync stream to query its status or to subscribe to it.
      *
-     * @param name The name of the stream to subscribe to.
-     * @param params Optional parameters for the stream subscription.
+     * @param name - The name of the stream to subscribe to.
+     * @param params - Optional parameters for the stream subscription.
      * @returns A {@link SyncStream} instance that can be subscribed to.
      * @experimental Sync streams are currently in alpha.
      */
@@ -10526,14 +10805,14 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      * Once the data have been successfully uploaded, call {@link CrudBatch.complete} before
      * requesting the next batch.
      *
-     * Use {@link limit} to specify the maximum number of updates to return in a single
+     * Use the `limit` parameter to specify the maximum number of updates to return in a single
      * batch.
      *
      * This method does include transaction ids in the result, but does not group
      * data by transaction. One batch may contain data from multiple transactions,
      * and a single transaction may be split over multiple batches.
      *
-     * @param limit Maximum number of CRUD entries to include in the batch
+     * @param limit - Maximum number of CRUD entries to include in the batch
      * @returns A batch of CRUD operations to upload, or null if there are none
      */
     async getCrudBatch(limit = DEFAULT_CRUD_BATCH_LIMIT) {
@@ -10560,13 +10839,13 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      * Once the data have been successfully uploaded, call {@link CrudTransaction.complete} before
      * requesting the next transaction.
      *
-     * Unlike {@link getCrudBatch}, this only returns data from a single transaction at a time.
+     * Unlike {@link AbstractPowerSyncDatabase.getCrudBatch}, this only returns data from a single transaction at a time.
      * All data for the transaction is loaded into memory.
      *
      * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     async getNextCrudTransaction() {
-        const iterator = this.getCrudTransactions()[Symbol.asyncIterator]();
+        const iterator = this.getCrudTransactions()[symbolAsyncIterator]();
         return (await iterator.next()).value;
     }
     /**
@@ -10575,7 +10854,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      * This is typically used from the {@link PowerSyncBackendConnector.uploadData} callback. Each entry emitted by the
      * returned iterator is a full transaction containing all local writes made while that transaction was active.
      *
-     * Unlike {@link getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
+     * Unlike {@link AbstractPowerSyncDatabase.getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
      * {@link CrudTransaction.complete}d yet, this iterator can be used to receive multiple transactions. Calling
      * {@link CrudTransaction.complete} will mark that and all prior transactions emitted by the iterator as completed.
      *
@@ -10602,7 +10881,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      */
     getCrudTransactions() {
         return {
-            [Symbol.asyncIterator]: () => {
+            [symbolAsyncIterator]: () => {
                 let lastCrudItemId = -1;
                 const sql = `
 WITH RECURSIVE crud_entries AS (
@@ -10669,8 +10948,8 @@ SELECT * FROM crud_entries;
      * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
      * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
      * @returns The query result as an object with structured key-value pairs
      */
     async execute(sql, parameters) {
@@ -10680,8 +10959,8 @@ SELECT * FROM crud_entries;
      * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
      * This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
      * @returns The raw query result from the underlying database as a nested array of raw values, where each row is
      * represented as an array of column values without field names.
      */
@@ -10694,8 +10973,8 @@ SELECT * FROM crud_entries;
      * and optionally return results.
      * This is faster than executing separately with each parameter set.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
      * @returns The query result
      */
     async executeBatch(sql, parameters) {
@@ -10705,8 +10984,8 @@ SELECT * FROM crud_entries;
     /**
      *  Execute a read-only query and return results.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
      * @returns An array of results
      */
     async getAll(sql, parameters) {
@@ -10716,8 +10995,8 @@ SELECT * FROM crud_entries;
     /**
      * Execute a read-only query and return the first result, or null if the ResultSet is empty.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
      * @returns The first result if found, or null if no results are returned
      */
     async getOptional(sql, parameters) {
@@ -10727,8 +11006,8 @@ SELECT * FROM crud_entries;
     /**
      * Execute a read-only query and return the first result, error if the ResultSet is empty.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
      * @returns The first result matching the query
      * @throws Error if no rows are returned
      */
@@ -10738,7 +11017,7 @@ SELECT * FROM crud_entries;
     }
     /**
      * Takes a read lock, without starting a transaction.
-     * In most cases, {@link readTransaction} should be used instead.
+     * In most cases, {@link AbstractPowerSyncDatabase.readTransaction} should be used instead.
      */
     async readLock(callback) {
         await this.waitForReady();
@@ -10746,7 +11025,7 @@ SELECT * FROM crud_entries;
     }
     /**
      * Takes a global lock, without starting a transaction.
-     * In most cases, {@link writeTransaction} should be used instead.
+     * In most cases, {@link AbstractPowerSyncDatabase.writeTransaction} should be used instead.
      */
     async writeLock(callback) {
         await this.waitForReady();
@@ -10757,8 +11036,8 @@ SELECT * FROM crud_entries;
      * Read transactions can run concurrently to a write transaction.
      * Changes from any write transaction are not visible to read transactions started before it.
      *
-     * @param callback Function to execute within the transaction
-     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @param callback - Function to execute within the transaction
+     * @param lockTimeout - Time in milliseconds to wait for a lock before throwing an error
      * @returns The result of the callback
      * @throws Error if the lock cannot be obtained within the timeout period
      */
@@ -10775,8 +11054,8 @@ SELECT * FROM crud_entries;
      * This takes a global lock - only one write transaction can execute against the database at a time.
      * Statements within the transaction must be done on the provided {@link Transaction} interface.
      *
-     * @param callback Function to execute within the transaction
-     * @param lockTimeout Time in milliseconds to wait for a lock before throwing an error
+     * @param callback - Function to execute within the transaction
+     * @param lockTimeout - Time in milliseconds to wait for a lock before throwing an error
      * @returns The result of the callback
      * @throws Error if the lock cannot be obtained within the timeout period
      */
@@ -10853,15 +11132,15 @@ SELECT * FROM crud_entries;
     }
     /**
      * Execute a read query every time the source tables are modified.
-     * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
+     * Use {@link SQLOnChangeOptions.throttleMs} to specify the minimum interval between queries.
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
-     * @param handler Callbacks for handling results and errors
-     * @param options Options for configuring watch behavior
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
+     * @param handler - Callbacks for handling results and errors
+     * @param options - Options for configuring watch behavior
      */
     watchWithCallback(sql, parameters, handler, options) {
         const { onResult, onError = (e) => this.logger.error(e) } = handler ?? {};
@@ -10874,7 +11153,7 @@ SELECT * FROM crud_entries;
         const watchedQuery = new OnChangeQueryProcessor({
             db: this,
             comparator,
-            placeholderData: null,
+            placeholderData: null, // FIXME
             watchOptions: {
                 query: {
                     compile: () => ({
@@ -10907,38 +11186,35 @@ SELECT * FROM crud_entries;
     }
     /**
      * Execute a read query every time the source tables are modified.
-     * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
+     * Use {@link SQLOnChangeOptions.throttleMs} to specify the minimum interval between queries.
      * Source tables are automatically detected using `EXPLAIN QUERY PLAN`.
      *
-     * @param sql The SQL query to execute
-     * @param parameters Optional array of parameters to bind to the query
-     * @param options Options for configuring watch behavior
+     * @param sql - The SQL query to execute
+     * @param parameters - Optional array of parameters to bind to the query
+     * @param options - Options for configuring watch behavior
      * @returns An AsyncIterable that yields QueryResults whenever the data changes
      */
     watchWithAsyncGenerator(sql, parameters, options) {
-        return new eventIterator.EventIterator((eventOptions) => {
+        return EventQueue.queueBasedAsyncIterable((queue, abort) => {
             const handler = {
                 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);
     }
     /**
      * Resolves the list of tables that are used in a SQL query.
      * If tables are specified in the options, those are used directly.
      * Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.
      *
-     * @param sql The SQL query to analyze
-     * @param parameters Optional parameters for the SQL query
-     * @param options Optional watch options that may contain explicit table list
+     * @param sql - The SQL query to analyze
+     * @param parameters - Optional parameters for the SQL query
+     * @param options - Optional watch options that may contain explicit table list
      * @returns Array of table names that the query depends on
      */
     async resolveTables(sql, parameters, options) {
@@ -10967,13 +11243,13 @@ SELECT * FROM crud_entries;
     /**
      * Invoke the provided callback on any changes to any of the specified tables.
      *
-     * This is preferred over {@link watchWithCallback} when multiple queries need to be performed
+     * This is preferred over {@link AbstractPowerSyncDatabase.watchWithCallback} when multiple queries need to be performed
      * together when data is changed.
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * @param handler Callbacks for handling change events and errors
-     * @param options Options for configuring watch behavior
+     * @param handler - Callbacks for handling change events and errors
+     * @param options - Options for configuring watch behavior
      * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
@@ -11016,31 +11292,26 @@ SELECT * FROM crud_entries;
     /**
      * Create a Stream of changes to any of the specified tables.
      *
-     * This is preferred over {@link 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.
+     * This is preferred over {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator} when multiple queries need to be
+     * performed together when data is changed.
      *
-     * @param options Options for configuring watch behavior
+     * @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) {
-        const resolvedOptions = options ?? {};
-        return new eventIterator.EventIterator((eventOptions) => {
-            const dispose = this.onChangeWithCallback({
+        return EventQueue.queueBasedAsyncIterable((queue, abort) => {
+            this.onChangeWithCallback({
                 onChange: (event) => {
-                    eventOptions.push(event);
+                    queue.notify(event);
                 },
                 onError: (error) => {
-                    eventOptions.fail(error);
+                    queue.notifyError(error);
                 }
-            }, options);
-            resolvedOptions.signal?.addEventListener('abort', () => {
-                eventOptions.stop();
-                // Maybe fail?
-            });
-            return () => dispose();
-        });
+            }, { ...options, signal: abort });
+            // Note: We don't have to track the dispose function returned by onChangeWithCallback, it cleans up
+            // after the abort signal completes.
+        }, options?.signal);
     }
     handleTableChanges(changedTables, watchedTables, onDetectedChanges) {
         if (changedTables.size > 0) {
@@ -11059,15 +11330,15 @@ SELECT * FROM crud_entries;
             changedTables.add(table);
         }
     }
-    /**
-     * @ignore
-     */
     async executeReadOnly(sql, params) {
         await this.waitForReady();
         return this.database.readLock((tx) => tx.execute(sql, params));
     }
 }
 
+/**
+ * @internal
+ */
 class AbstractPowerSyncDatabaseOpenFactory {
     options;
     constructor(options) {
@@ -11092,6 +11363,9 @@ class AbstractPowerSyncDatabaseOpenFactory {
     }
 }
 
+/**
+ * @internal
+ */
 function runOnSchemaChange(callback, db, options) {
     const triggerWatchedQuery = () => {
         const abortController = new AbortController();
@@ -11116,6 +11390,9 @@ function runOnSchemaChange(callback, db, options) {
     triggerWatchedQuery();
 }
 
+/**
+ * @public
+ */
 function compilableQueryWatch(db, query, handler, options) {
     const { onResult, onError = (e) => { } } = handler ?? {};
     if (!onResult) {
@@ -11153,8 +11430,14 @@ function compilableQueryWatch(db, query, handler, options) {
     runOnSchemaChange(watchQuery, db, options);
 }
 
+/**
+ * @internal
+ */
 const MAX_OP_ID = '9223372036854775807';
 
+/**
+ * @internal
+ */
 class SqliteBucketStorage extends BaseObserver {
     db;
     logger;
@@ -11315,6 +11598,8 @@ class SqliteBucketStorage extends BaseObserver {
  * Thrown when an underlying database connection is closed.
  * This is particularly relevant when worker connections are marked as closed while
  * operations are still in progress.
+ *
+ * @internal
  */
 class ConnectionClosedError extends Error {
     static NAME = 'ConnectionClosedError';
@@ -11334,6 +11619,8 @@ class ConnectionClosedError extends Error {
 
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
+ *
+ * @public
  */
 class Schema {
     /*
@@ -11370,7 +11657,7 @@ class Schema {
      * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
      * using client-side table and column constraints.
      *
-     * @param tables An object of (table name, raw table definition) entries.
+     * @param tables - An object of (table name, raw table definition) entries.
      */
     withRawTables(tables) {
         for (const [name, rawTableDefinition] of Object.entries(tables)) {
@@ -11416,6 +11703,8 @@ class Schema {
   Generate a new table from the columns and indexes
   @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
   This will be removed in the next major release.
+
+  @public
 */
 class TableV2 extends Table {
 }
@@ -11426,6 +11715,8 @@ function sanitizeString(input) {
 /**
  * Helper function for sanitizing UUID input strings.
  * Typically used with {@link sanitizeSQL}.
+ *
+ * @alpha
  */
 function sanitizeUUID(uuid) {
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -11462,6 +11753,8 @@ function sanitizeUUID(uuid) {
  * // Incorrect:
  * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
  * ```
+ *
+ * @alpha
  */
 function sanitizeSQL(strings, ...values) {
     let result = '';
@@ -11491,6 +11784,8 @@ function sanitizeSQL(strings, ...values) {
 
 /**
  * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ *
+ * @public
  */
 class GetAllQuery {
     options;
@@ -11515,6 +11810,9 @@ class GetAllQuery {
 }
 
 const TypedLogger = Logger;
+/**
+ * @public
+ */
 const LogLevel = {
     TRACE: TypedLogger.TRACE,
     DEBUG: TypedLogger.DEBUG,
@@ -11531,6 +11829,7 @@ const LogLevel = {
  * across all loggers created with `createLogger`. Adjusting settings on this
  * base logger affects all loggers derived from it unless explicitly overridden.
  *
+ * @public
  */
 function createBaseLogger() {
     return Logger;
@@ -11541,6 +11840,8 @@ 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
  */
 function createLogger(name, options = {}) {
     const logger = Logger.get(name);
@@ -11550,6 +11851,9 @@ function createLogger(name, options = {}) {
     return logger;
 }
 
+/**
+ * @internal
+ */
 const parseQuery = (query, parameters) => {
     let sqlStatement;
     if (typeof query == 'string') {