@powersync/common 1.53.1 → 1.54.0

package/dist/bundle.node.cjs

@@ -3,7 +3,10 @@
 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 +22,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 +59,15 @@ class Column {
     }
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_INDEX_COLUMN_OPTIONS = {
     ascending: true
 };
+/**
+ * @public
+ */
 class IndexedColumn {
     options;
     static createAscending(column) {
@@ -75,9 +94,15 @@ class IndexedColumn {
     }
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_INDEX_OPTIONS = {
     columns: []
 };
+/**
+ * @public
+ */
 class Index {
     options;
     static createAscending(options, columnNames) {
@@ -119,6 +144,9 @@ function encodeTableOptions(options) {
     };
 }
 
+/**
+ * @internal
+ */
 const DEFAULT_TABLE_OPTIONS = {
     indexes: [],
     insertOnly: false,
@@ -127,7 +155,13 @@ const DEFAULT_TABLE_OPTIONS = {
     trackMetadata: false,
     ignoreEmptyUpdates: false
 };
+/**
+ * @internal
+ */
 const InvalidSQLCharacters = /["'%,.#\s[\]]/;
+/**
+ * @public
+ */
 class Table {
     options;
     _mappedColumns;
@@ -318,6 +352,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 +364,7 @@ const ATTACHMENT_TABLE = 'attachments';
  * @param row - The database row object
  * @returns The corresponding AttachmentRecord
  *
- * @experimental
+ * @alpha
  */
 function attachmentFromSql(row) {
     return {
@@ -343,7 +382,7 @@ function attachmentFromSql(row) {
 /**
  * AttachmentState represents the current synchronization state of an attachment.
  *
- * @experimental
+ * @alpha
  */
 exports.AttachmentState = void 0;
 (function (AttachmentState) {
@@ -356,7 +395,7 @@ exports.AttachmentState = void 0;
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
- * @internal
+ * @alpha
  */
 class AttachmentTable extends Table {
     constructor(options) {
@@ -384,7 +423,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 +646,9 @@ class AttachmentContext {
     }
 }
 
+/**
+ * @public
+ */
 exports.WatchedQueryListenerEvent = void 0;
 (function (WatchedQueryListenerEvent) {
     WatchedQueryListenerEvent["ON_DATA"] = "onData";
@@ -614,176 +657,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 +854,9 @@ class Mutex {
         }
     }
 }
+/**
+ * @internal
+ */
 function timeoutSignal(timeout) {
     if (timeout == null)
         return;
@@ -997,36 +885,200 @@ class AttachmentService {
         this.context = new AttachmentContext(db, tableName, logger, archivedCacheLimit);
     }
     /**
-     * Creates a differential watch query for active attachments requiring synchronization.
-     * @returns Watch query that emits changes for queued uploads, downloads, and deletes
+     * Creates a differential watch query for active attachments requiring synchronization.
+     * @returns Watch query that emits changes for queued uploads, downloads, and deletes
+     */
+    watchActiveAttachments({ throttleMs } = {}) {
+        this.logger.info('Watching active attachments...');
+        const watch = this.db
+            .query({
+            sql: /* sql */ `
+          SELECT
+            *
+          FROM
+            ${this.tableName}
+          WHERE
+            state = ?
+            OR state = ?
+            OR state = ?
+          ORDER BY
+            timestamp ASC
+        `,
+            parameters: [exports.AttachmentState.QUEUED_UPLOAD, exports.AttachmentState.QUEUED_DOWNLOAD, exports.AttachmentState.QUEUED_DELETE]
+        })
+            .differentialWatch({ throttleMs });
+        return watch;
+    }
+    /**
+     * Executes a callback with exclusive access to the attachment context.
+     */
+    async withContext(callback) {
+        return this.mutex.runExclusive(async () => {
+            return callback(this.context);
+        });
+    }
+}
+
+/**
+ * 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
      */
-    watchActiveAttachments({ throttleMs } = {}) {
-        this.logger.info('Watching active attachments...');
-        const watch = this.db
-            .query({
-            sql: /* sql */ `
-          SELECT
-            *
-          FROM
-            ${this.tableName}
-          WHERE
-            state = ?
-            OR state = ?
-            OR state = ?
-          ORDER BY
-            timestamp ASC
-        `,
-            parameters: [exports.AttachmentState.QUEUED_UPLOAD, exports.AttachmentState.QUEUED_DOWNLOAD, exports.AttachmentState.QUEUED_DELETE]
-        })
-            .differentialWatch({ throttleMs });
-        return watch;
+    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;
+        }
     }
     /**
-     * Executes a callback with exclusive access to the attachment context.
+     * 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 withContext(callback) {
-        return this.mutex.runExclusive(async () => {
-            return callback(this.context);
+    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);
+                    }
+                }
+            }
         });
     }
 }
@@ -1087,16 +1139,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 +1227,7 @@ class AttachmentQueue {
                             state: exports.AttachmentState.QUEUED_DOWNLOAD,
                             hasSynced: false,
                             metaData: watchedAttachment.metaData,
+                            mediaType: watchedAttachment.mediaType,
                             timestamp: new Date().getTime()
                         });
                         continue;
@@ -1272,17 +1315,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 +1445,9 @@ class AttachmentQueue {
     }
 }
 
+/**
+ * @alpha
+ */
 exports.EncodingType = void 0;
 (function (EncodingType) {
     EncodingType["UTF8"] = "utf8";
@@ -1703,7 +1756,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 +1802,8 @@ function DBGetUtilsDefaultMixin(Base) {
 }
 /**
  * Update table operation numbers from SQLite
+ *
+ * @public
  */
 exports.RowUpdateType = void 0;
 (function (RowUpdateType) {
@@ -1755,8 +1812,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 +1903,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 +1939,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 +1979,9 @@ class SyncProgress {
     }
 }
 
+/**
+ * @public
+ */
 class SyncStatus {
     options;
     constructor(options) {
@@ -1922,6 +1992,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 +2001,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 +2009,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 +2018,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 +2026,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 +2035,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 +2063,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 +2073,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 +2108,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 +2130,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 +2154,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 +2163,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 +2229,9 @@ class SyncStreamStatusView {
     }
 }
 
+/**
+ * @public
+ */
 class UploadQueueStats {
     count;
     size;
@@ -2182,6 +2257,9 @@ class UploadQueueStats {
     }
 }
 
+/**
+ * @internal
+ */
 class BaseObserver {
     listeners = new Set();
     constructor() { }
@@ -2209,6 +2287,9 @@ class BaseObserver {
     }
 }
 
+/**
+ * @internal
+ */
 class ControlledExecutor {
     task;
     /**
@@ -2278,30 +2359,44 @@ function throttleTrailing(func, wait) {
         }
     };
 }
-/**
- * Throttle a function to be called at most once every "wait" milliseconds,
- * on the leading and trailing edge.
- *
- * Roughly equivalent to lodash/throttle with {leading: true, trailing: true}
- */
-function throttleLeadingTrailing(func, wait) {
-    let timeoutId = null;
-    let lastCallTime = 0;
-    const invokeFunction = () => {
-        func();
-        lastCallTime = Date.now();
-        timeoutId = null;
-    };
-    return function () {
-        const now = Date.now();
-        const timeToWait = wait - (now - lastCallTime);
-        if (timeToWait <= 0) {
-            // Leading edge: Call the function immediately if enough time has passed
-            invokeFunction();
-        }
-        else if (!timeoutId) {
-            // Set a timeout for the trailing edge if not already set
-            timeoutId = setTimeout(invokeFunction, timeToWait);
+function asyncNotifier() {
+    let waitingConsumer = null;
+    let hasPendingNotification = false;
+    return {
+        notify() {
+            if (waitingConsumer != null) {
+                waitingConsumer();
+                waitingConsumer = null;
+            }
+            else {
+                hasPendingNotification = true;
+            }
+        },
+        waitForNotification(signal) {
+            return new Promise((resolve) => {
+                if (waitingConsumer != null) {
+                    throw new Error('Illegal call to waitForNotification, already has a waiter.');
+                }
+                if (signal.aborted) {
+                    resolve();
+                }
+                else if (hasPendingNotification) {
+                    resolve();
+                    hasPendingNotification = false;
+                }
+                else {
+                    function complete() {
+                        signal.removeEventListener('abort', onAbort);
+                        resolve();
+                    }
+                    function onAbort() {
+                        waitingConsumer = null;
+                        resolve();
+                    }
+                    waitingConsumer = complete;
+                    signal.addEventListener('abort', onAbort);
+                }
+            });
         }
     };
 }
@@ -2462,7 +2557,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
@@ -2602,6 +2697,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;
@@ -2629,6 +2726,8 @@ class ArrayComparator {
 }
 /**
  * Watched query comparator that always reports changed result sets.
+ *
+ * @public
  */
 const FalsyComparator = {
     checkEquality: () => false // Default comparator that always returns false
@@ -2836,6 +2935,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: [],
@@ -2848,6 +2949,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) => {
@@ -3128,6 +3231,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.
@@ -3135,17 +3240,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";
@@ -3154,6 +3266,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";
@@ -3171,6 +3286,8 @@ exports.PowerSyncControlCommand = void 0;
 
 /**
  * A batch of client-side changes.
+ *
+ * @public
  */
 class CrudBatch {
     crud;
@@ -3197,6 +3314,8 @@ class CrudBatch {
 
 /**
  * Type of local change.
+ *
+ * @public
  */
 exports.UpdateType = void 0;
 (function (UpdateType) {
@@ -3209,6 +3328,8 @@ exports.UpdateType = void 0;
 })(exports.UpdateType || (exports.UpdateType = {}));
 /**
  * A single client-side change.
+ *
+ * @public
  */
 class CrudEntry {
     /**
@@ -3305,6 +3426,9 @@ class CrudEntry {
     }
 }
 
+/**
+ * @public
+ */
 class CrudTransaction extends CrudBatch {
     crud;
     complete;
@@ -3333,6 +3457,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;
@@ -8132,7 +8258,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.53.1";
+var version = "1.54.0";
 var PACKAGE = {
 	version: version};
 
@@ -8262,7 +8388,8 @@ class WebsocketClientTransport {
                 removeListeners();
                 resolve(new WebsocketDuplexConnectionExports.WebsocketDuplexConnection(websocket, new distExports.Deserializer(), multiplexerDemultiplexerFactory));
             };
-            const errorListener = (ev) => {
+            const errorListener = (event) => {
+                const ev = event;
                 removeListeners();
                 // We add a default error in that case.
                 if (ev.error != null) {
@@ -8505,7 +8632,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) {
     /**
@@ -8524,12 +8657,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://';
@@ -8537,6 +8675,9 @@ const DEFAULT_REMOTE_OPTIONS = {
     fetchImplementation: new FetchImplementationProvider(),
     fetchOptions: {}
 };
+/**
+ * @internal
+ */
 class AbstractRemote {
     connector;
     logger;
@@ -8946,7 +9087,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);
@@ -8988,16 +9129,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) {
     /**
@@ -9009,8 +9160,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
@@ -9020,14 +9171,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,
@@ -9037,22 +9203,21 @@ const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     serializedSchema: undefined,
     includeDefaultStreams: true
 };
+/**
+ * @internal
+ */
 class AbstractStreamingSyncImplementation extends BaseObserver {
     options;
     abortController;
-    // In rare cases, mostly for tests, uploads can be triggered without being properly connected.
-    // This allows ensuring that all upload processes can be aborted.
-    uploadAbortController;
     crudUpdateListener;
     streamingSyncPromise;
     logger;
     activeStreams;
     connectionMayHaveChanged = false;
-    isUploadingCrud = false;
+    crudUploadNotifier = asyncNotifier();
     notifyCompletedUploads;
     handleActiveStreamsChange;
     syncStatus;
-    triggerCrudUpload;
     constructor(options) {
         super();
         this.options = options;
@@ -9068,16 +9233,9 @@ class AbstractStreamingSyncImplementation extends BaseObserver {
             }
         });
         this.abortController = null;
-        this.triggerCrudUpload = throttleLeadingTrailing(() => {
-            if (!this.syncStatus.connected || this.isUploadingCrud) {
-                return;
-            }
-            this.isUploadingCrud = true;
-            this._uploadAllCrud().finally(() => {
-                this.notifyCompletedUploads?.();
-                this.isUploadingCrud = false;
-            });
-        }, this.options.crudUploadThrottleMs);
+    }
+    triggerCrudUpload() {
+        this.crudUploadNotifier.notify();
     }
     async waitForReady() { }
     waitForStatus(status) {
@@ -9125,7 +9283,6 @@ class AbstractStreamingSyncImplementation extends BaseObserver {
         super.dispose();
         this.crudUpdateListener?.();
         this.crudUpdateListener = undefined;
-        this.uploadAbortController?.abort();
     }
     async getWriteCheckpoint() {
         const clientId = await this.options.adapter.getClientId();
@@ -9135,7 +9292,17 @@ class AbstractStreamingSyncImplementation extends BaseObserver {
         this.logger.debug(`Created write checkpoint: ${checkpoint}`);
         return checkpoint;
     }
-    async _uploadAllCrud() {
+    async crudUploadLoop(signal) {
+        while (!signal.aborted) {
+            await Promise.all([
+                // Start the initial CRUD upload on connect. Then, keep polling until we're done.
+                this._uploadAllCrud(signal),
+                this.delayRetry(signal, this.options.crudUploadThrottleMs)
+            ]);
+            await this.crudUploadNotifier.waitForNotification(signal);
+        }
+    }
+    async _uploadAllCrud(signal) {
         return this.obtainLock({
             type: exports.LockType.CRUD,
             callback: async () => {
@@ -9143,12 +9310,7 @@ class AbstractStreamingSyncImplementation extends BaseObserver {
                  * Keep track of the first item in the CRUD queue for the last `uploadCrud` iteration.
                  */
                 let checkedCrudItem;
-                const controller = new AbortController();
-                this.uploadAbortController = controller;
-                this.abortController?.signal.addEventListener('abort', () => {
-                    controller.abort();
-                }, { once: true });
-                while (!controller.signal.aborted) {
+                while (!signal.aborted) {
                     try {
                         /**
                          * This is the first item in the FIFO CRUD queue.
@@ -9178,7 +9340,10 @@ The next upload iteration will be delayed.`);
                         else {
                             // Uploading is completed
                             const neededUpdate = await this.options.adapter.updateLocalTarget(() => this.getWriteCheckpoint());
-                            if (neededUpdate == false && checkedCrudItem != null) {
+                            if (neededUpdate) {
+                                this.notifyCompletedUploads?.();
+                            }
+                            else if (checkedCrudItem != null) {
                                 // Only log this if there was something to upload
                                 this.logger.debug('Upload complete, no write checkpoint needed.');
                             }
@@ -9193,7 +9358,7 @@ The next upload iteration will be delayed.`);
                                 uploadError: ex
                             }
                         });
-                        await this.delayRetry(controller.signal);
+                        await this.delayRetry(signal);
                         if (!this.isConnected) {
                             // Exit the upload loop if the sync stream is no longer connected
                             break;
@@ -9208,7 +9373,6 @@ The next upload iteration will be delayed.`);
                         });
                     }
                 }
-                this.uploadAbortController = undefined;
             }
         });
     }
@@ -9218,7 +9382,10 @@ The next upload iteration will be delayed.`);
         }
         const controller = new AbortController();
         this.abortController = controller;
-        this.streamingSyncPromise = this.streamingSync(this.abortController.signal, options);
+        this.streamingSyncPromise = Promise.all([
+            this.crudUploadLoop(controller.signal).catch((ex) => this.logger.error('Error in crud upload loop', ex)),
+            this.streamingSync(controller.signal, options)
+        ]);
         // Return a promise that resolves when the connection status is updated to indicate that we're connected.
         return new Promise((resolve) => {
             const disposer = this.registerListener({
@@ -9256,14 +9423,7 @@ The next upload iteration will be delayed.`);
         this.abortController = null;
         this.updateSyncStatus({ connected: false, connecting: false });
     }
-    /**
-     * @deprecated use [connect instead]
-     */
     async streamingSync(signal, options) {
-        if (!signal) {
-            this.abortController = new AbortController();
-            signal = this.abortController.signal;
-        }
         /**
          * Listen for CRUD updates and trigger upstream uploads
          */
@@ -9369,7 +9529,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
@@ -9379,7 +9539,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.
      */
@@ -9637,14 +9797,13 @@ The next upload iteration will be delayed.`);
         // trigger this for all updates
         this.iterateListeners((cb) => cb.statusUpdated?.(options));
     }
-    async delayRetry(signal) {
+    async delayRetry(signal, delay = this.options.retryDelayMs) {
         return new Promise((resolve) => {
             if (signal?.aborted) {
                 // If the signal is already aborted, resolve immediately
                 resolve();
                 return;
             }
-            const { retryDelayMs } = this.options;
             let timeoutId;
             const endDelay = () => {
                 resolve();
@@ -9655,7 +9814,7 @@ The next upload iteration will be delayed.`);
                 signal?.removeEventListener('abort', endDelay);
             };
             signal?.addEventListener('abort', endDelay, { once: true });
-            timeoutId = setTimeout(endDelay, retryDelayMs);
+            timeoutId = setTimeout(endDelay, delay);
         });
     }
     updateSubscriptions(subscriptions) {
@@ -9687,7 +9846,8 @@ const MEMORY_TRIGGER_CLAIM_MANAGER = {
 
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
- * @experimental
+ *
+ * @experimental @alpha
  */
 exports.DiffTriggerOperation = void 0;
 (function (DiffTriggerOperation) {
@@ -9749,8 +9909,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
     `);
@@ -9863,7 +10023,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.
@@ -10103,18 +10263,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
 /**
@@ -10124,6 +10295,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;
     /**
@@ -10281,7 +10455,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.
@@ -10436,7 +10610,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();
@@ -10463,8 +10637,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.
      */
@@ -10522,14 +10696,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) {
@@ -10556,7 +10730,7 @@ 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
@@ -10571,7 +10745,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.
      *
@@ -10665,8 +10839,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) {
@@ -10676,8 +10850,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.
      */
@@ -10690,8 +10864,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) {
@@ -10701,8 +10875,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) {
@@ -10712,8 +10886,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) {
@@ -10723,8 +10897,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
      */
@@ -10734,7 +10908,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();
@@ -10742,7 +10916,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();
@@ -10753,8 +10927,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
      */
@@ -10771,8 +10945,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
      */
@@ -10849,15 +11023,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 ?? {};
@@ -10870,7 +11044,7 @@ SELECT * FROM crud_entries;
         const watchedQuery = new OnChangeQueryProcessor({
             db: this,
             comparator,
-            placeholderData: null,
+            placeholderData: null, // FIXME
             watchOptions: {
                 query: {
                     compile: () => ({
@@ -10903,12 +11077,12 @@ 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) {
@@ -10932,9 +11106,9 @@ SELECT * FROM crud_entries;
      * 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) {
@@ -10963,13 +11137,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) {
@@ -11012,12 +11186,12 @@ 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.
+     * This is preferred over {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator} when multiple queries need to be
+     * performed together when data is changed.
      *
      * Note: do not declare this as `async *onChange` as it will not work in React Native.
      *
-     * @param options Options for configuring watch behavior
+     * @param options - Options for configuring watch behavior
      * @returns An AsyncIterable that yields change events whenever the specified tables change
      */
     onChangeWithAsyncGenerator(options) {
@@ -11055,15 +11229,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) {
@@ -11088,6 +11262,9 @@ class AbstractPowerSyncDatabaseOpenFactory {
     }
 }
 
+/**
+ * @internal
+ */
 function runOnSchemaChange(callback, db, options) {
     const triggerWatchedQuery = () => {
         const abortController = new AbortController();
@@ -11112,6 +11289,9 @@ function runOnSchemaChange(callback, db, options) {
     triggerWatchedQuery();
 }
 
+/**
+ * @public
+ */
 function compilableQueryWatch(db, query, handler, options) {
     const { onResult, onError = (e) => { } } = handler ?? {};
     if (!onResult) {
@@ -11149,8 +11329,14 @@ function compilableQueryWatch(db, query, handler, options) {
     runOnSchemaChange(watchQuery, db, options);
 }
 
+/**
+ * @internal
+ */
 const MAX_OP_ID = '9223372036854775807';
 
+/**
+ * @internal
+ */
 class SqliteBucketStorage extends BaseObserver {
     db;
     logger;
@@ -11311,6 +11497,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';
@@ -11330,6 +11518,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 {
     /*
@@ -11366,7 +11556,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)) {
@@ -11412,6 +11602,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 {
 }
@@ -11422,6 +11614,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;
@@ -11458,6 +11652,8 @@ function sanitizeUUID(uuid) {
  * // Incorrect:
  * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
  * ```
+ *
+ * @alpha
  */
 function sanitizeSQL(strings, ...values) {
     let result = '';
@@ -11487,6 +11683,8 @@ function sanitizeSQL(strings, ...values) {
 
 /**
  * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ *
+ * @public
  */
 class GetAllQuery {
     options;
@@ -11511,6 +11709,9 @@ class GetAllQuery {
 }
 
 const TypedLogger = Logger;
+/**
+ * @public
+ */
 const LogLevel = {
     TRACE: TypedLogger.TRACE,
     DEBUG: TypedLogger.DEBUG,
@@ -11527,6 +11728,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;
@@ -11537,6 +11739,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);
@@ -11546,6 +11750,9 @@ function createLogger(name, options = {}) {
     return logger;
 }
 
+/**
+ * @internal
+ */
 const parseQuery = (query, parameters) => {
     let sqlStatement;
     if (typeof query == 'string') {