@powersync/common 1.53.1 → 1.54.0

package/dist/index.d.cts

@@ -2,13 +2,25 @@ import Logger, { ILogger, ILogLevel } from 'js-logger';
 export { GlobalLogger, ILogHandler, ILogLevel, ILogger, ILoggerOpts } from 'js-logger';
 import { fetch } from 'cross-fetch';
 
+/**
+ * @public
+ */
 interface Disposable {
     dispose: () => Promise<void> | void;
 }
+/**
+ * @public
+ */
 type BaseListener = Record<string, ((...event: any) => any) | undefined>;
+/**
+ * @public
+ */
 interface BaseObserverInterface<T extends BaseListener> {
     registerListener(listener: Partial<T>): () => void;
 }
+/**
+ * @internal
+ */
 declare class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
     protected listeners: Set<Partial<T>>;
     constructor();
@@ -32,6 +44,8 @@ declare class BaseObserver<T extends BaseListener = BaseListener> implements Bas
  */
 /**
  * Object returned by SQL Query executions.
+ *
+ * @public
  */
 type QueryResult = {
     /** Represents the auto-generated row id if applicable. */
@@ -51,12 +65,15 @@ type QueryResult = {
         /** The length of the dataset */
         length: number;
         /** A convenience function to acess the index based the row object
-         * @param idx the row index
+         * @param idx - the row index
          * @returns the row structure identified by column names
          */
         item: (idx: number) => any;
     };
 };
+/**
+ * @public
+ */
 interface DBGetUtils {
     /** Execute a read-only query and return results. */
     getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
@@ -65,6 +82,9 @@ interface DBGetUtils {
     /** Execute a read-only query and return the first result, error if the ResultSet is empty. */
     get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
+/**
+ * @public
+ */
 interface SqlExecutor {
     /** Execute a single write statement. */
     execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
@@ -76,15 +96,22 @@ interface SqlExecutor {
      *
      * Example result:
      *
-     * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+     * ```JavaScript
+     * [ [ '1', 'list 1', '33', 'Post content', '1' ] ]
+     * ```
      *
      * Where as `execute`'s `rows._array` would have been:
      *
-     * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
+     * ```JavaScript
+     * [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]
+     * ```
      */
     executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
     executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
 }
+/**
+ * @public
+ */
 interface LockContext extends SqlExecutor, DBGetUtils {
     /**
      * How the connection has been opened.
@@ -97,7 +124,9 @@ interface LockContext extends SqlExecutor, DBGetUtils {
     connectionType?: 'writer' | 'queryOnly' | 'readOnly';
 }
 /**
- * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ * Implements {@link DBGetUtils} on a {@link SqlExecutor}.
+ *
+ * @internal
  */
 declare function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omit<SqlExecutor, 'executeBatch'>>(Base: TBase): {
     new (...args: any[]): {
@@ -109,6 +138,9 @@ declare function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Om
         executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
     };
 } & TBase;
+/**
+ * @public
+ */
 interface Transaction extends LockContext {
     /** Commit multiple changes to the local DB using the Transaction context. */
     commit: () => Promise<QueryResult>;
@@ -117,27 +149,40 @@ interface Transaction extends LockContext {
 }
 /**
  * Update table operation numbers from SQLite
+ *
+ * @public
  */
 declare enum RowUpdateType {
     SQLITE_INSERT = 18,
     SQLITE_DELETE = 9,
     SQLITE_UPDATE = 23
 }
+/**
+ * @public
+ */
 interface TableUpdateOperation {
     opType: RowUpdateType;
     rowId: number;
 }
 /**
  * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ *
+ * @public
  */
 interface UpdateNotification extends TableUpdateOperation {
     table: string;
 }
+/**
+ * @public
+ */
 interface BatchedUpdateNotification {
     rawUpdates: UpdateNotification[];
     tables: string[];
     groupedUpdates: Record<string, TableUpdateOperation[]>;
 }
+/**
+ * @public
+ */
 interface DBAdapterListener extends BaseListener {
     /**
      * Listener for table updates.
@@ -147,9 +192,15 @@ interface DBAdapterListener extends BaseListener {
      */
     tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
 }
+/**
+ * @public
+ */
 interface DBLockOptions {
     timeoutMs?: number;
 }
+/**
+ * @public
+ */
 interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
     name: string;
     close: () => void | Promise<void>;
@@ -160,13 +211,18 @@ interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
      */
     refreshSchema: () => Promise<void>;
 }
+/**
+ * @public
+ */
 interface DBAdapter extends ConnectionPool, SqlExecutor, DBGetUtils {
     readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
     writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
 }
 /**
- * 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
  */
 declare function DBAdapterDefaultMixin<TBase extends new (...args: any[]) => ConnectionPool>(Base: TBase): {
     new (...args: any[]): {
@@ -189,17 +245,27 @@ declare function DBAdapterDefaultMixin<TBase extends new (...args: any[]) => Con
         registerListener(listener: Partial<DBAdapterListener>): () => void;
     };
 } & TBase;
+/**
+ * @internal
+ */
 declare function isBatchedUpdateNotification(update: BatchedUpdateNotification | UpdateNotification): update is BatchedUpdateNotification;
+/**
+ * @internal
+ */
 declare function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification): string[];
 
 /**
  * 64-bit unsigned integer stored as a string in base-10.
  *
  * Not sortable as a string.
+ *
+ * @public
  */
 type OpId = string;
 /**
  * Type of local change.
+ *
+ * @public
  */
 declare enum UpdateType {
     /** Insert or replace existing row. All non-null columns are included in the data. Generated by INSERT statements. */
@@ -209,6 +275,9 @@ declare enum UpdateType {
     /** Delete existing row. Contains the id. Generated by DELETE statements. */
     DELETE = "DELETE"
 }
+/**
+ * @internal
+ */
 type CrudEntryJSON = {
     id: string;
     data: string;
@@ -229,6 +298,8 @@ type CrudEntryOutputJSON = {
 };
 /**
  * A single client-side change.
+ *
+ * @public
  */
 declare class CrudEntry {
     /**
@@ -289,6 +360,8 @@ declare class CrudEntry {
 
 /**
  * A batch of client-side changes.
+ *
+ * @public
  */
 declare class CrudBatch {
     /**
@@ -318,6 +391,9 @@ declare class CrudBatch {
     complete: (writeCheckpoint?: string) => Promise<void>);
 }
 
+/**
+ * @internal
+ */
 declare enum PSInternalTable {
     DATA = "ps_data",
     CRUD = "ps_crud",
@@ -325,6 +401,9 @@ declare enum PSInternalTable {
     OPLOG = "ps_oplog",
     UNTYPED = "ps_untyped"
 }
+/**
+ * @internal
+ */
 declare enum PowerSyncControlCommand {
     PROCESS_TEXT_LINE = "line_text",
     PROCESS_BSON_LINE = "line_binary",
@@ -338,9 +417,15 @@ declare enum PowerSyncControlCommand {
      */
     CONNECTION_STATE = "connection"
 }
+/**
+ * @internal
+ */
 interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
 }
+/**
+ * @internal
+ */
 interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
     init(): Promise<void>;
     hasMigratedSubkeys(): Promise<boolean>;
@@ -360,6 +445,9 @@ interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListen
     control(op: PowerSyncControlCommand, payload: string | Uint8Array | null): Promise<string>;
 }
 
+/**
+ * @public
+ */
 interface PowerSyncCredentials {
     endpoint: string;
     token: string;
@@ -370,17 +458,28 @@ interface PowerSyncCredentials {
  * An async iterator that can't be cancelled.
  *
  * To keep data flow simple, we always pass an explicit cancellation token when subscribing to async streams. Once the
- * {@link AbortSignal} aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
+ * `AbortSignal` aborts, iterators are supposed to clean up and then emit a final `{done: true}` event. This means
  * that there's no way to distinguish between streams that have completed normally and streams that have been cancelled,
  * but that is acceptable for our uses of this.
+ *
+ * @internal
  */
 type SimpleAsyncIterator<T> = Pick<AsyncIterator<T>, 'next'>;
 
+/**
+ * @internal
+ */
 type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
     invalidateCredentials?: () => void;
 };
+/**
+ * @internal
+ */
 declare const DEFAULT_REMOTE_LOGGER: Logger.ILogger;
+/**
+ * @internal
+ */
 type SyncStreamOptions = {
     path: string;
     data: unknown;
@@ -388,6 +487,9 @@ type SyncStreamOptions = {
     abortSignal: AbortSignal;
     fetchOptions?: Request;
 };
+/**
+ * @public
+ */
 declare enum FetchStrategy {
     /**
      * Queues multiple sync events before processing, reducing round-trips.
@@ -400,19 +502,30 @@ declare enum FetchStrategy {
      */
     Sequential = "sequential"
 }
+/**
+ * @internal
+ */
 type SocketSyncStreamOptions = SyncStreamOptions & {
     fetchStrategy: FetchStrategy;
 };
+/**
+ * @internal
+ */
 type FetchImplementation = typeof fetch;
 /**
  * Class wrapper for providing a fetch implementation.
  * The class wrapper is used to distinguish the fetchImplementation
  * option in [AbstractRemoteOptions] from the general fetch method
  * which is typeof "function"
+ *
+ * @internal
  */
 declare class FetchImplementationProvider {
     getFetch(): FetchImplementation;
 }
+/**
+ * @internal
+ */
 type AbstractRemoteOptions = {
     /**
      * Transforms the PowerSync base URL which might contain
@@ -434,7 +547,13 @@ type AbstractRemoteOptions = {
      */
     fetchOptions?: {};
 };
+/**
+ * @internal
+ */
 declare const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions;
+/**
+ * @internal
+ */
 declare abstract class AbstractRemote {
     protected connector: RemoteConnector;
     protected logger: ILogger;
@@ -519,7 +638,7 @@ declare abstract class AbstractRemote {
      * Posts a `/sync/stream` request.
      *
      * Depending on the `Content-Type` of the response, this returns strings for sync lines or encoded BSON documents as
-     * {@link Uint8Array}s.
+     * `Uint8Array`s.
      */
     fetchStream(options: SyncStreamOptions): Promise<SimpleAsyncIterator<Uint8Array | string>>;
 }
@@ -529,16 +648,29 @@ interface JSONObject {
     [key: string]: JSONValue;
 }
 type JSONArray = JSONValue[];
+/**
+ * @public
+ */
 type StreamingSyncRequestParameterType = JSONValue;
 
+/**
+ * @internal
+ */
 declare enum LockType {
     CRUD = "crud",
     SYNC = "sync"
 }
+/**
+ * @public
+ */
 declare enum SyncStreamConnectionMethod {
     HTTP = "http",
     WEB_SOCKET = "web-socket"
 }
+/**
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
+ */
 declare enum SyncClientImplementation {
     /**
      * This implementation offloads the sync line decoding and handling into the PowerSync
@@ -549,8 +681,8 @@ declare enum SyncClientImplementation {
      * ## Compatibility warning
      *
      * The Rust sync client stores sync data in a format that is slightly different than the one used
-     * by the old JavaScript client. When adopting the {@link RUST} client on existing databases, the PowerSync SDK will
-     * migrate the format automatically.
+     * by the old JavaScript client. When adopting the {@link SyncClientImplementation.RUST} client on existing databases,
+     * the PowerSync SDK will migrate the format automatically.
      *
      * SDK versions supporting both the JavaScript and the Rust client support both formats with the JavaScript client
      * implementaiton. However, downgrading to an SDK version that only supports the JavaScript client would not be
@@ -560,16 +692,24 @@ declare enum SyncClientImplementation {
 }
 /**
  * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
+ *
+ * @deprecated Deprecated since {@link SyncClientImplementation.RUST} is the only option.
+ * @public
  */
 declare const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.RUST;
 /**
  * Abstract Lock to be implemented by various JS environments
+ *
+ * @internal
  */
 interface LockOptions<T> {
     callback: () => Promise<T>;
     type: LockType;
     signal?: AbortSignal;
 }
+/**
+ * @internal
+ */
 interface AbstractStreamingSyncImplementationOptions extends RequiredAdditionalConnectionOptions {
     adapter: BucketStorageAdapter;
     subscriptions: SubscribedStream[];
@@ -582,6 +722,9 @@ interface AbstractStreamingSyncImplementationOptions extends RequiredAdditionalC
     logger?: ILogger;
     remote: AbstractRemote;
 }
+/**
+ * @internal
+ */
 interface StreamingSyncImplementationListener extends BaseListener {
     /**
      * Triggered whenever a status update has been attempted to be made or
@@ -596,11 +739,16 @@ interface StreamingSyncImplementationListener extends BaseListener {
 /**
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
+ *
+ * @public
  */
 type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, 'serializedSchema'>;
+/**
+ * @internal
+ */
 interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
 }
-/** @internal */
+/** @public */
 interface BaseConnectionOptions {
     /**
      * A set of metadata to be included in service logs.
@@ -653,6 +801,9 @@ interface AdditionalConnectionOptions {
 interface RequiredAdditionalConnectionOptions extends Required<AdditionalConnectionOptions> {
     subscriptions: SubscribedStream[];
 }
+/**
+ * @internal
+ */
 interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
     /**
      * Connects to the sync service
@@ -673,33 +824,53 @@ interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyn
     updateSubscriptions(subscriptions: SubscribedStream[]): void;
     markConnectionMayHaveChanged(): void;
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
+/**
+ * @internal
+ */
 declare const DEFAULT_RETRY_DELAY_MS = 5000;
+/**
+ * @internal
+ */
 declare const DEFAULT_STREAMING_SYNC_OPTIONS: {
     retryDelayMs: number;
     crudUploadThrottleMs: number;
 };
+/**
+ * @internal
+ */
 type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
+/**
+ * @internal
+ */
 declare const DEFAULT_STREAM_CONNECTION_OPTIONS: RequiredPowerSyncConnectionOptions;
+/**
+ * @internal
+ */
 type SubscribedStream = {
     name: string;
     params: Record<string, any> | null;
 };
+/**
+ * @internal
+ */
 declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener> implements StreamingSyncImplementation {
     protected options: AbstractStreamingSyncImplementationOptions;
     protected abortController: AbortController | null;
-    protected uploadAbortController: AbortController | undefined;
     protected crudUpdateListener?: () => void;
-    protected streamingSyncPromise?: Promise<void>;
+    protected streamingSyncPromise?: Promise<[void, void]>;
     protected logger: ILogger;
     private activeStreams;
     private connectionMayHaveChanged;
-    private isUploadingCrud;
+    private crudUploadNotifier;
     private notifyCompletedUploads?;
     private handleActiveStreamsChange?;
     syncStatus: SyncStatus;
-    triggerCrudUpload: () => void;
     constructor(options: AbstractStreamingSyncImplementationOptions);
+    triggerCrudUpload(): void;
     waitForReady(): Promise<void>;
     waitForStatus(status: SyncStatusOptions): Promise<void>;
     waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
@@ -708,16 +879,14 @@ declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<
     dispose(): Promise<void>;
     abstract obtainLock<T>(lockOptions: LockOptions<T>): Promise<T>;
     getWriteCheckpoint(): Promise<string>;
-    protected _uploadAllCrud(): Promise<void>;
+    private crudUploadLoop;
+    private _uploadAllCrud;
     connect(options?: PowerSyncConnectionOptions): Promise<void>;
     disconnect(): Promise<void>;
-    /**
-     * @deprecated use [connect instead]
-     */
-    streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private streamingSync;
     markConnectionMayHaveChanged(): void;
     /**
-     * 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
@@ -727,7 +896,7 @@ declare abstract class AbstractStreamingSyncImplementation extends BaseObserver<
      * 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.
      */
@@ -765,7 +934,10 @@ interface BucketProgress {
 }
 
 /**
- * A description of a sync stream, consisting of its {@link name} and the {@link parameters} used when subscribing.
+ * A description of a sync stream, consisting of its {@link SyncStreamDescription.name} and the
+ * {@link SyncStreamDescription.parameters} used when subscribing.
+ *
+ * @public
  */
 interface SyncStreamDescription {
     /**
@@ -783,6 +955,8 @@ interface SyncStreamDescription {
  * Information about a subscribed sync stream.
  *
  * This includes the {@link SyncStreamDescription}, along with information about the current sync status.
+ *
+ * @public
  */
 interface SyncSubscriptionDescription extends SyncStreamDescription {
     active: boolean;
@@ -790,15 +964,17 @@ interface SyncSubscriptionDescription extends SyncStreamDescription {
      * Whether this stream subscription is included by default, regardless of whether the stream has explicitly been
      * subscribed to or not.
      *
-     * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-     * happens when a default stream was subscribed explicitly.
+     * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+     * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+     * default stream was subscribed explicitly.
      */
     isDefault: boolean;
     /**
      * Whether this stream has been subscribed to explicitly.
      *
-     * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-     * happens when a default stream was subscribed explicitly.
+     * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+     * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+     * default stream was subscribed explicitly.
      */
     hasExplicitSubscription: boolean;
     /**
@@ -811,10 +987,13 @@ interface SyncSubscriptionDescription extends SyncStreamDescription {
      */
     hasSynced: boolean;
     /**
-     * If {@link hasSynced} is true, the last time data from this stream has been synced.
+     * If {@link SyncSubscriptionDescription.hasSynced} is true, the last time data from this stream has been synced.
      */
     lastSyncedAt: Date | null;
 }
+/**
+ * @public
+ */
 interface SyncStreamSubscribeOptions {
     /**
      * A "time to live" for this stream subscription, in seconds.
@@ -834,6 +1013,8 @@ interface SyncStreamSubscribeOptions {
  * A handle to a {@link SyncStreamDescription} that allows subscribing to the stream.
  *
  * To obtain an instance of {@link SyncStream}, call {@link AbstractPowerSyncDatabase.syncStream}.
+ *
+ * @public
  */
 interface SyncStream extends SyncStreamDescription {
     /**
@@ -842,7 +1023,7 @@ interface SyncStream extends SyncStreamDescription {
      * You should keep a reference to the returned {@link SyncStreamSubscription} object along as you need data for that
      * stream. As soon as {@link SyncStreamSubscription.unsubscribe} is called for all subscriptions on this stream
      * (including subscriptions created on other tabs), the {@link SyncStreamSubscribeOptions.ttl} starts ticking and will
-     * eventually evict the stream (unless {@link subscribe} is called again).
+     * eventually evict the stream (unless {@link SyncStream.subscribe} is called again).
      */
     subscribe(options?: SyncStreamSubscribeOptions): Promise<SyncStreamSubscription>;
     /**
@@ -852,6 +1033,9 @@ interface SyncStream extends SyncStreamDescription {
      */
     unsubscribeAll(): Promise<void>;
 }
+/**
+ * @public
+ */
 interface SyncStreamSubscription extends SyncStreamDescription {
     /**
      * A promise that resolves once data from in this sync stream has been synced and applied.
@@ -870,6 +1054,8 @@ type InternalProgressInformation = Record<string, BucketProgress>;
  *
  * To obtain these values, use {@link SyncProgress}, available through
  * {@link SyncStatus#downloadProgress}.
+ *
+ * @public
  */
 interface ProgressWithOperations {
     /**
@@ -882,7 +1068,8 @@ interface ProgressWithOperations {
      */
     downloadedOperations: number;
     /**
-     * Relative progress, as {@link downloadedOperations} of {@link totalOperations}.
+     * Relative progress, as {@link ProgressWithOperations.downloadedOperations} of
+     * {@link ProgressWithOperations.totalOperations}.
      *
      * This will be a number between `0.0` and `1.0` (inclusive).
      *
@@ -911,6 +1098,8 @@ interface ProgressWithOperations {
  *
  * Also note that data is downloaded in bulk, which means that individual counters are unlikely
  * to be updated one-by-one.
+ *
+ * @public
  */
 declare class SyncProgress implements ProgressWithOperations {
     protected internal: InternalProgressInformation;
@@ -927,6 +1116,9 @@ declare class SyncProgress implements ProgressWithOperations {
     untilPriority(priority: number): ProgressWithOperations;
 }
 
+/**
+ * @public
+ */
 type SyncDataFlowStatus = Partial<{
     downloading: boolean;
     uploading: boolean;
@@ -944,16 +1136,25 @@ type SyncDataFlowStatus = Partial<{
     /**
      * Internal information about how far we are downloading operations in buckets.
      *
-     * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
+     * @internal Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
      */
     downloadProgress: InternalProgressInformation | null;
+    /**
+     * @internal
+     */
     internalStreamSubscriptions: CoreStreamSubscription[] | null;
 }>;
+/**
+ * @public
+ */
 interface SyncPriorityStatus {
     priority: number;
     lastSyncedAt?: Date;
     hasSynced?: boolean;
 }
+/**
+ * @internal
+ */
 type SyncStatusOptions = {
     connected?: boolean;
     connecting?: boolean;
@@ -966,6 +1167,9 @@ type SyncStatusOptions = {
      */
     clientImplementation?: SyncClientImplementation;
 };
+/**
+ * @public
+ */
 declare class SyncStatus {
     protected options: SyncStatusOptions;
     constructor(options: SyncStatusOptions);
@@ -974,64 +1178,45 @@ declare 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(): SyncClientImplementation | undefined;
     /**
      * 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(): boolean;
     /**
      * 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(): boolean;
     /**
      * 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(): Date | undefined;
     /**
      * 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(): boolean | undefined;
     /**
      * 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(): Partial<{
-        downloading: boolean;
-        uploading: boolean;
-        /**
-         * Error during downloading (including connecting).
-         *
-         * Cleared on the next successful data download.
-         */
-        downloadError?: Error;
-        /**
-         * Error during uploading.
-         * Cleared on the next successful upload.
-         */
-        uploadError?: Error;
-        /**
-         * Internal information about how far we are downloading operations in buckets.
-         *
-         * Please use the {@link SyncStatus#downloadProgress} property to track sync progress.
-         */
-        downloadProgress: InternalProgressInformation | null;
-        internalStreamSubscriptions: CoreStreamSubscription[] | null;
-    }>;
+    get dataFlowStatus(): SyncDataFlowStatus;
     /**
      * All sync streams currently being tracked in teh database.
      *
@@ -1040,13 +1225,13 @@ declare class SyncStatus {
      */
     get syncStreams(): SyncStreamStatus[] | undefined;
     /**
-     * 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: SyncStreamDescription): SyncStreamStatus | undefined;
     /**
      * 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(): SyncPriorityStatus[];
@@ -1073,29 +1258,29 @@ declare 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: number): SyncPriorityStatus;
     /**
      * 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: SyncStatus): boolean;
     /**
      * 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(): string;
     /**
      * 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(): SyncStatusOptions;
     /**
@@ -1111,6 +1296,8 @@ declare class SyncStatus {
 }
 /**
  * Information about a sync stream subscription.
+ *
+ * @public
  */
 interface SyncStreamStatus {
     progress: ProgressWithOperations | null;
@@ -1118,6 +1305,9 @@ interface SyncStreamStatus {
     priority: number | null;
 }
 
+/**
+ * @public
+ */
 declare class UploadQueueStats {
     /**
      * Number of records in the upload queue.
@@ -1139,26 +1329,54 @@ declare class UploadQueueStats {
     toString(): string;
 }
 
+/**
+ * @see https://www.sqlite.org/lang_expr.html#castexpr
+ * @public
+ */
 declare enum ColumnType {
     TEXT = "TEXT",
     INTEGER = "INTEGER",
     REAL = "REAL"
 }
+/**
+ * @public
+ */
 interface ColumnOptions {
     name: string;
     type?: ColumnType;
 }
+/**
+ * @public
+ */
 type BaseColumnType<T extends number | string | null> = {
     type: ColumnType;
 };
+/**
+ * @public
+ */
 type ColumnsType = Record<string, BaseColumnType<any>>;
+/**
+ * @public
+ */
 type ExtractColumnValueType<T extends BaseColumnType<any>> = T extends BaseColumnType<infer R> ? R : unknown;
+/**
+ * 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
+ */
 declare const MAX_AMOUNT_OF_COLUMNS = 1999;
+/**
+ * @public
+ */
 declare const column: {
     text: BaseColumnType<string | null>;
     integer: BaseColumnType<number | null>;
     real: BaseColumnType<number | null>;
 };
+/**
+ * @public
+ */
 declare class Column {
     protected options: ColumnOptions;
     constructor(options: ColumnOptions);
@@ -1170,11 +1388,20 @@ declare class Column {
     };
 }
 
+/**
+ * @public
+ */
 interface IndexColumnOptions {
     name: string;
     ascending?: boolean;
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_INDEX_COLUMN_OPTIONS: Partial<IndexColumnOptions>;
+/**
+ * @public
+ */
 declare class IndexedColumn {
     protected options: IndexColumnOptions;
     static createAscending(column: string): IndexedColumn;
@@ -1188,11 +1415,20 @@ declare class IndexedColumn {
     };
 }
 
+/**
+ * @public
+ */
 interface IndexOptions {
     name: string;
     columns?: IndexedColumn[];
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_INDEX_OPTIONS: Partial<IndexOptions>;
+/**
+ * @public
+ */
 declare class Index {
     protected options: IndexOptions;
     static createAscending(options: IndexOptions, columnNames: string[]): Index;
@@ -1213,12 +1449,16 @@ declare class Index {
   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
 */
 declare class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {
 }
 
 /**
  * Options that apply both to JSON-based tables and raw tables.
+ *
+ * @public
  */
 interface TableOrRawTableOptions {
     localOnly?: boolean;
@@ -1234,6 +1474,8 @@ interface SharedTableOptions extends TableOrRawTableOptions {
  *
  * Including old values may be helpful for some backend connector implementations, which is
  * why it can be enabled on per-table or per-columm basis.
+ *
+ * @public
  */
 interface TrackPreviousOptions {
     /** When defined, a list of column names for which old values should be tracked. */
@@ -1241,6 +1483,9 @@ interface TrackPreviousOptions {
     /** When enabled, only include values that have actually been changed by an update. */
     onlyWhenChanged?: boolean;
 }
+/**
+ * @public
+ */
 interface TableOptions extends SharedTableOptions {
     /**
      * The synced table name, matching sync rules
@@ -1249,15 +1494,27 @@ interface TableOptions extends SharedTableOptions {
     columns: Column[];
     indexes?: Index[];
 }
+/**
+ * @public
+ */
 type RowType<T extends TableV2<any>> = {
     [K in keyof T['columnMap']]: ExtractColumnValueType<T['columnMap'][K]>;
 } & {
     id: string;
 };
+/**
+ * @public
+ */
 type IndexShorthand = Record<string, string[]>;
+/**
+ * @public
+ */
 interface TableV2Options extends SharedTableOptions {
     indexes?: IndexShorthand;
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_TABLE_OPTIONS: {
     indexes: never[];
     insertOnly: boolean;
@@ -1266,7 +1523,13 @@ declare const DEFAULT_TABLE_OPTIONS: {
     trackMetadata: boolean;
     ignoreEmptyUpdates: boolean;
 };
+/**
+ * @internal
+ */
 declare const InvalidSQLCharacters: RegExp;
+/**
+ * @public
+ */
 declare class Table<Columns extends ColumnsType = ColumnsType> {
     protected options: TableOptions;
     protected _mappedColumns: Columns;
@@ -1287,9 +1550,8 @@ declare class Table<Columns extends ColumnsType = ColumnsType> {
      * 1. New constructor: Using a Columns object and an optional TableV2Options object
      * 2. Deprecated constructor: Using a TableOptions object (will be removed in the next major release)
      *
-     * @constructor
-     * @param {Columns | TableOptions} optionsOrColumns - Either a Columns object (for V2 syntax) or a TableOptions object (for V1 syntax)
-     * @param {TableV2Options} [v2Options] - Optional configuration options for V2 syntax
+     * @param columns - Either a Columns object (for V2 syntax) or a TableOptions object (for V1 syntax)
+     * @param options - Optional configuration options for V2 syntax
      *
      * @example
      * ```javascript
@@ -1383,8 +1645,10 @@ declare class Table<Columns extends ColumnsType = ColumnsType> {
  * using client-side table and column constraints.
  *
  * To collect local writes to raw tables with PowerSync, custom triggers are required. See
- * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables} for details and an example on
  * using raw tables.
+ *
+ * @public
  */
 type RawTableType = RawTableTypeWithStatements | InferredRawTableType;
 interface RawTableTypeWithStatements {
@@ -1440,12 +1704,16 @@ interface InferredRawTableType extends Partial<RawTableTypeWithStatements> {
  * `{Column: 'name'}`.
  * The `"Rest"` parameter gets resolved to a JSON object covering all values from the synced row that haven't been
  * covered by a `Column` parameter.
+ *
+ * @public
  */
 type PendingStatementParameter = 'Id' | {
     Column: string;
 } | 'Rest';
 /**
  * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
+ *
+ * @public
  */
 type PendingStatement = {
     sql: string;
@@ -1467,11 +1735,16 @@ type RawTable<T extends RawTableType = RawTableType> = T & {
 };
 
 type SchemaType = Record<string, Table<any>>;
+/**
+ * @public
+ */
 type SchemaTableType<S extends SchemaType> = {
     [K in keyof S]: RowType<S[K]>;
 };
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
+ *
+ * @public
  */
 declare class Schema<S extends SchemaType = SchemaType> {
     readonly types: SchemaTableType<S>;
@@ -1485,7 +1758,7 @@ declare class Schema<S extends SchemaType = SchemaType> {
      * 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: Record<string, RawTableType>): void;
     validate(): void;
@@ -1523,6 +1796,9 @@ declare class Schema<S extends SchemaType = SchemaType> {
     static rawTableToJson(table: RawTable): unknown;
 }
 
+/**
+ * @public
+ */
 interface PowerSyncBackendConnector {
     /** Allows the PowerSync client to retrieve an authentication token from your backend
      * which is used to authenticate against the PowerSync service.
@@ -1564,6 +1840,9 @@ interface ConnectionManagerSyncImplementationResult {
 interface CreateSyncImplementationOptions extends AdditionalConnectionOptions {
     subscriptions: SubscribedStream[];
 }
+/**
+ * @internal
+ */
 interface InternalSubscriptionAdapter {
     firstStatusMatching(predicate: (status: SyncStatus) => any, abort?: AbortSignal): Promise<void>;
     resolveOfflineSyncStatus(): Promise<void>;
@@ -1635,7 +1914,7 @@ declare class ConnectionManager extends BaseObserver<ConnectionManagerListener>
     /**
      * Close the sync connection.
      *
-     * Use {@link connect} to connect again.
+     * Use {@link ConnectionManager.connect} to connect again.
      */
     disconnect(): Promise<void>;
     protected disconnectInternal(): Promise<void>;
@@ -1655,12 +1934,16 @@ declare class ConnectionManager extends BaseObserver<ConnectionManagerListener>
  * A basic comparator for incrementally watched queries. This performs a single comparison which
  * determines if the result set has changed. The {@link WatchedQuery} will only emit the new result
  * if a change has been detected.
+ *
+ * @public
  */
 interface WatchedQueryComparator<Data> {
     checkEquality: (current: Data, previous: Data) => boolean;
 }
 /**
  * Options for {@link ArrayComparator}
+ *
+ * @public
  */
 type ArrayComparatorOptions<ItemType> = {
     /**
@@ -1671,6 +1954,8 @@ type ArrayComparatorOptions<ItemType> = {
 /**
  * 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
  */
 declare class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemType[]> {
     protected options: ArrayComparatorOptions<ItemType>;
@@ -1679,13 +1964,21 @@ declare class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemTy
 }
 /**
  * Watched query comparator that always reports changed result sets.
+ *
+ * @public
  */
 declare const FalsyComparator: WatchedQueryComparator<unknown>;
 
+/**
+ * @public
+ */
 interface CompilableQuery<T> {
     execute(): Promise<T[]>;
     compile(): CompiledQuery;
 }
+/**
+ * @public
+ */
 interface CompiledQuery {
     readonly sql: string;
     readonly parameters: ReadonlyArray<unknown>;
@@ -1722,6 +2015,8 @@ declare class MetaBaseObserver<Listener extends BaseListener> extends BaseObserv
 
 /**
  * State for {@link WatchedQuery} instances.
+ *
+ * @public
  */
 interface WatchedQueryState<Data> {
     /**
@@ -1749,6 +2044,8 @@ interface WatchedQueryState<Data> {
 }
 /**
  * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ *
+ * @public
  */
 interface WatchExecuteOptions {
     sql: string;
@@ -1756,13 +2053,16 @@ interface WatchExecuteOptions {
     db: AbstractPowerSyncDatabase;
 }
 /**
- * Similar to {@link CompatibleQuery}, except the `execute` method
- * does not enforce an Array result type.
+ *
+ * @public
  */
 interface WatchCompatibleQuery<ResultType> {
     execute(options: WatchExecuteOptions): Promise<ResultType>;
     compile(): CompiledQuery;
 }
+/**
+ * @public
+ */
 interface WatchedQueryOptions {
     /** The minimum interval between queries. */
     throttleMs?: number;
@@ -1779,6 +2079,9 @@ interface WatchedQueryOptions {
      */
     triggerOnTables?: string[];
 }
+/**
+ * @public
+ */
 declare enum WatchedQueryListenerEvent {
     ON_DATA = "onData",
     ON_ERROR = "onError",
@@ -1786,6 +2089,9 @@ declare enum WatchedQueryListenerEvent {
     SETTINGS_WILL_UPDATE = "settingsWillUpdate",
     CLOSED = "closed"
 }
+/**
+ * @public
+ */
 interface WatchedQueryListener<Data> extends BaseListener {
     [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
     [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
@@ -1793,8 +2099,17 @@ interface WatchedQueryListener<Data> extends BaseListener {
     [WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?: () => void;
     [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_WATCH_THROTTLE_MS = 30;
+/**
+ * @internal
+ */
 declare const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions;
+/**
+ * @public
+ */
 interface WatchedQuery<Data = unknown, Settings extends WatchedQueryOptions = WatchedQueryOptions, Listener extends WatchedQueryListener<Data> = WatchedQueryListener<Data>> extends MetaBaseObserverInterface<Listener> {
     /**
      * Current state of the watched query.
@@ -1863,7 +2178,7 @@ declare abstract class AbstractQueryProcessor<Data = unknown[], Settings extends
     updateSettings(settings: Settings): Promise<void>;
     /**
      * This method is used to link a query to the subscribers of this listener class.
-     * This method should perform actual query watching and report results via {@link updateState} method.
+     * This method should perform actual query watching and report results via {@link AbstractQueryProcessor.updateState} method.
      */
     protected abstract linkQuery(options: LinkQueryOptions<Data>): Promise<void>;
     protected updateState(update: Partial<MutableWatchedQueryState<Data>>): Promise<void>;
@@ -1885,6 +2200,8 @@ declare abstract class AbstractQueryProcessor<Data = unknown[], Settings extends
 /**
  * Represents an updated row in a differential watched query.
  * It contains both the current and previous state of the row.
+ *
+ * @public
  */
 interface WatchedQueryRowDifferential<RowType> {
     readonly current: RowType;
@@ -1893,6 +2210,8 @@ interface WatchedQueryRowDifferential<RowType> {
 /**
  * Represents the result of a watched query that has been diffed.
  * {@link DifferentialWatchedQueryState#diff} is of the {@link WatchedQueryDifferential} form.
+ *
+ * @public
  */
 interface WatchedQueryDifferential<RowType> {
     readonly added: ReadonlyArray<Readonly<RowType>>;
@@ -1917,6 +2236,8 @@ interface WatchedQueryDifferential<RowType> {
 }
 /**
  * Row comparator for differentially watched queries which keys and compares items in the result set.
+ *
+ * @public
  */
 interface DifferentialWatchedQueryComparator<RowType> {
     /**
@@ -1930,6 +2251,8 @@ interface DifferentialWatchedQueryComparator<RowType> {
 }
 /**
  * Options for building a differential watched query with the {@link Query} builder.
+ *
+ * @public
  */
 interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOptions {
     /**
@@ -1946,6 +2269,8 @@ interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOptions {
 }
 /**
  * Settings for differential incremental watched queries using.
+ *
+ * @public
  */
 interface DifferentialWatchedQuerySettings<RowType> extends DifferentialWatchedQueryOptions<RowType> {
     /**
@@ -1953,9 +2278,15 @@ interface DifferentialWatchedQuerySettings<RowType> extends DifferentialWatchedQ
      */
     query: WatchCompatibleQuery<RowType[]>;
 }
+/**
+ * @public
+ */
 interface DifferentialWatchedQueryListener<RowType> extends WatchedQueryListener<ReadonlyArray<Readonly<RowType>>> {
     onDiff?: (diff: WatchedQueryDifferential<RowType>) => void | Promise<void>;
 }
+/**
+ * @public
+ */
 type DifferentialWatchedQuery<RowType> = WatchedQuery<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>, DifferentialWatchedQueryListener<RowType>>;
 /**
  * @internal
@@ -1970,6 +2301,8 @@ type DataHashMap<RowType> = Map<string, {
 /**
  * An empty differential result set.
  * This is used as the initial state for differential incrementally watched queries.
+ *
+ * @internal
  */
 declare const EMPTY_DIFFERENTIAL: {
     added: never[];
@@ -1982,6 +2315,8 @@ declare 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
  */
 declare const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any>;
 /**
@@ -2003,12 +2338,16 @@ declare class DifferentialQueryProcessor<RowType> extends AbstractQueryProcessor
 
 /**
  * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
+ *
+ * @public
  */
 interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
     query: WatchCompatibleQuery<DataType>;
 }
 /**
  * {@link WatchedQuery} returned from {@link Query#watch}.
+ *
+ * @public
  */
 type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
 /**
@@ -2034,11 +2373,15 @@ declare class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data,
 
 /**
  * Query parameters for {@link ArrayQueryDefinition#parameters}
+ *
+ * @public
  */
 type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
 /**
  * Options for building a query with {@link AbstractPowerSyncDatabase#query}.
  * This query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+ *
+ * @public
  */
 interface ArrayQueryDefinition<RowType = unknown> {
     sql: string;
@@ -2057,6 +2400,8 @@ interface ArrayQueryDefinition<RowType = unknown> {
 }
 /**
  * Options for {@link Query#watch}.
+ *
+ * @public
  */
 interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOptions {
     /**
@@ -2081,6 +2426,9 @@ interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOptions {
      */
     placeholderData?: RowType[];
 }
+/**
+ * @public
+ */
 interface Query<RowType> {
     /**
      * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
@@ -2126,6 +2474,9 @@ interface Query<RowType> {
     differentialWatch(options?: DifferentialWatchedQueryOptions<RowType>): DifferentialWatchedQuery<RowType>;
 }
 
+/**
+ * @public
+ */
 interface SQLOpenOptions {
     /**
      * Filename for the database.
@@ -2149,6 +2500,9 @@ interface SQLOpenOptions {
      */
     debugMode?: boolean;
 }
+/**
+ * @public
+ */
 interface SQLOpenFactory {
     /**
      * Opens a connection adapter to a SQLite DB
@@ -2157,17 +2511,26 @@ interface SQLOpenFactory {
 }
 /**
  * Tests if the input is a {@link SQLOpenOptions}
+ *
+ * @internal
  */
 declare const isSQLOpenOptions: (test: any) => test is SQLOpenOptions;
 /**
  * Tests if input is a {@link SQLOpenFactory}
+ *
+ * @internal
  */
 declare const isSQLOpenFactory: (test: any) => test is SQLOpenFactory;
 /**
  * Tests if input is a {@link DBAdapter}
+ *
+ * @internal
  */
 declare const isDBAdapter: (test: any) => test is DBAdapter;
 
+/**
+ * @public
+ */
 declare class CrudTransaction extends CrudBatch {
     /**
      * List of client-side changes.
@@ -2198,7 +2561,8 @@ declare class CrudTransaction extends CrudBatch {
 
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
- * @experimental
+ *
+ * @experimental @alpha
  */
 declare enum DiffTriggerOperation {
     INSERT = "INSERT",
@@ -2206,7 +2570,7 @@ declare enum DiffTriggerOperation {
     DELETE = "DELETE"
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the base record structure for all diff records.
  *
@@ -2235,7 +2599,7 @@ interface BaseTriggerDiffRecord<TOperationId extends string | number = number> {
     timestamp: string;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite UPDATE operation.
  * This record contains the new value and optionally the previous value.
  * Values are stored as JSON strings.
@@ -2252,7 +2616,7 @@ interface TriggerDiffUpdateRecord<TOperationId extends string | number = number>
     previous_value: string;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite INSERT operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -2264,7 +2628,7 @@ interface TriggerDiffInsertRecord<TOperationId extends string | number = number>
     value: string;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite DELETE operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -2276,7 +2640,7 @@ interface TriggerDiffDeleteRecord<TOperationId extends string | number = number>
     value: string;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the record structure for all diff records.
  *
@@ -2301,7 +2665,7 @@ interface TriggerDiffDeleteRecord<TOperationId extends string | number = number>
  */
 type TriggerDiffRecord<TOperationId extends string | number = number> = TriggerDiffUpdateRecord<TOperationId> | TriggerDiffInsertRecord<TOperationId> | TriggerDiffDeleteRecord<TOperationId>;
 /**
- * @experimental
+ * @experimental @alpha
  * Querying the DIFF table directly with {@link TriggerDiffHandlerContext#withExtractedDiff} will return records
  * with the tracked columns extracted from the JSON value.
  * This type represents the structure of such records.
@@ -2329,7 +2693,7 @@ type ExtractedTriggerDiffRecord<T, TOperationId extends string | number = number
     __previous_value?: string;
 };
 /**
- * @experimental
+ * @experimental @alpha
  * Hooks used in the creation of a table diff trigger.
  */
 interface TriggerCreationHooks {
@@ -2385,7 +2749,7 @@ interface BaseCreateDiffTriggerOptions {
     useStorage?: boolean;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerManager#createDiffTrigger}.
  */
 interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
@@ -2402,19 +2766,19 @@ interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
     setupContext?: LockContext;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerRemoveCallback}.
  */
 interface TriggerRemoveCallbackOptions {
     context?: LockContext;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Callback to drop a trigger after it has been created.
  */
 type TriggerRemoveCallback = (options?: TriggerRemoveCallbackOptions) => Promise<void>;
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerDiffHandlerContext#withDiff}.
  */
 interface WithDiffOptions {
@@ -2428,7 +2792,7 @@ interface WithDiffOptions {
     castOperationIdAsText?: boolean;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Context for the `onChange` handler provided to {@link TriggerManager#trackTableDiff}.
  */
 interface TriggerDiffHandlerContext extends LockContext {
@@ -2483,7 +2847,7 @@ interface TriggerDiffHandlerContext extends LockContext {
      * Allows querying the database with access to the table containing diff records.
      * The diff table is accessible via the `DIFF` accessor.
      *
-     * This is similar to {@link withDiff} but extracts the row columns from the tracked JSON value. The diff operation
+     * This is similar to {@link TriggerDiffHandlerContext#withDiff} but extracts the row columns from the tracked JSON value. The diff operation
      * data is aliased as `__` columns to avoid column conflicts.
      *
      * For {@link DiffTriggerOperation#DELETE} operations the previous_value columns are extracted for convenience.
@@ -2514,7 +2878,7 @@ interface TriggerDiffHandlerContext extends LockContext {
     withExtractedDiff: <T = any>(query: string, params?: ReadonlyArray<Readonly<any>>) => Promise<T[]>;
 }
 /**
- * @experimental
+ * @experimental @alpha
  * Options for tracking changes to a table with {@link TriggerManager#trackTableDiff}.
  */
 interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
@@ -2525,13 +2889,13 @@ interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
      */
     onChange: (context: TriggerDiffHandlerContext) => Promise<void>;
     /**
-     * The minimum interval, in milliseconds, between {@link onChange} invocations.
+     * The minimum interval, in milliseconds, between {@link TrackDiffOptions.onChange} invocations.
      *  @default {@link DEFAULT_WATCH_THROTTLE_MS}
      */
     throttleMs?: number;
 }
 /**
- * @experimental
+ * @experimental @alpha
  */
 interface TriggerManager {
     /**
@@ -2579,7 +2943,7 @@ interface TriggerManager {
     /**
      * @experimental
      * Tracks changes for a table. Triggering a provided handler on changes.
-     * Uses {@link createDiffTrigger} internally to create a temporary destination table.
+     * Uses {@link TriggerManager.createDiffTrigger} internally to create a temporary destination table.
      *
      * @returns A callback to cleanup the trigger and stop tracking changes.
      *
@@ -2685,7 +3049,7 @@ declare class TriggerManagerImpl implements TriggerManager {
     protected isDisposed: boolean;
     constructor(options: TriggerManagerImplOptions);
     protected get db(): AbstractPowerSyncDatabase;
-    protected getUUID(): Promise<string>;
+    protected getUUID(ctx?: LockContext): Promise<string>;
     protected removeTriggers(tx: LockContext, triggerIds: string[]): Promise<void>;
     dispose(): void;
     /**
@@ -2701,6 +3065,9 @@ declare class TriggerManagerImpl implements TriggerManager {
     trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback>;
 }
 
+/**
+ * @internal
+ */
 type UnlockFn = () => void;
 /**
  * An asynchronous semaphore implementation with associated items per lease.
@@ -2747,23 +3114,38 @@ declare class Mutex {
 }
 /**
  * Creates a signal aborting after the set timeout.
+ *
+ * @internal
  */
 declare function timeoutSignal(timeout: number): AbortSignal;
+/**
+ * @internal
+ */
 declare function timeoutSignal(timeout?: number): AbortSignal | undefined;
 
+/**
+ * @public
+ */
 interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
 }
+/**
+ * @public
+ */
 interface BasePowerSyncDatabaseOptions extends AdditionalConnectionOptions {
     /** Schema used for the local database. */
     schema: Schema;
     /**
-     * @deprecated Use {@link retryDelayMs} instead as this will be removed in future releases.
+     * @deprecated Use {@link AdditionalConnectionOptions.retryDelayMs} instead as this will be removed in future
+     * releases.
      */
     retryDelay?: number;
     logger?: ILogger;
 }
+/**
+ * @public
+ */
 interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
     /**
      * Source for a SQLite database connection.
@@ -2774,22 +3156,35 @@ interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
      */
     database: DBAdapter | SQLOpenFactory | SQLOpenOptions;
 }
+/**
+ * @public
+ */
 interface PowerSyncDatabaseOptionsWithDBAdapter extends BasePowerSyncDatabaseOptions {
     database: DBAdapter;
 }
+/**
+ * @public
+ */
 interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDatabaseOptions {
     database: SQLOpenFactory;
 }
+/**
+ * @public
+ */
 interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
     database: SQLOpenOptions;
 }
+/**
+ * @public
+ */
 interface SQLOnChangeOptions {
     signal?: AbortSignal;
     tables?: string[];
     /** The minimum interval between queries. */
     throttleMs?: number;
     /**
-     * @deprecated All tables specified in {@link tables} will be watched, including PowerSync tables with prefixes.
+     * @deprecated All tables specified in {@link SQLOnChangeOptions.tables} will be watched, including PowerSync tables
+     * with prefixes.
      *
      * Allows for watching any SQL table
      * by not removing PowerSync table name prefixes
@@ -2800,6 +3195,9 @@ interface SQLOnChangeOptions {
      */
     triggerImmediate?: boolean;
 }
+/**
+ * @public
+ */
 interface SQLWatchOptions extends SQLOnChangeOptions {
     /**
      * Optional comparator which will be used to compare the results of the query.
@@ -2807,23 +3205,38 @@ interface SQLWatchOptions extends SQLOnChangeOptions {
      */
     comparator?: WatchedQueryComparator<QueryResult>;
 }
+/**
+ * @public
+ */
 interface WatchOnChangeEvent {
     changedTables: string[];
 }
+/**
+ * @public
+ */
 interface WatchHandler {
     onResult: (results: QueryResult) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * @public
+ */
 interface WatchOnChangeHandler {
     onChange: (event: WatchOnChangeEvent) => Promise<void> | void;
     onError?: (error: Error) => void;
 }
+/**
+ * @public
+ */
 interface PowerSyncDBListener extends StreamingSyncImplementationListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
     closing: () => Promise<void> | void;
     closed: () => Promise<void> | void;
 }
+/**
+ * @public
+ */
 interface PowerSyncCloseOptions {
     /**
      * Disconnect the sync stream client if connected.
@@ -2832,16 +3245,27 @@ interface PowerSyncCloseOptions {
      */
     disconnect?: boolean;
 }
+/**
+ * @internal
+ */
 declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
+/**
+ * @internal
+ */
 declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
     crudUploadThrottleMs: number;
 };
+/**
+ * @internal
+ */
 declare 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
  */
 declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
 /**
@@ -2849,6 +3273,9 @@ declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
  * @internal
  */
 declare const isPowerSyncDatabaseOptionsWithSettings: (test: any) => test is PowerSyncDatabaseOptionsWithSettings;
+/**
+ * @public
+ */
 declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
     protected options: PowerSyncDatabaseOptions;
     /**
@@ -2927,7 +3354,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     /**
      * 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.
@@ -2982,7 +3409,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     /**
      * Close the sync connection.
      *
-     * Use {@link connect} to connect again.
+     * Use {@link AbstractPowerSyncDatabase.connect} to connect again.
      */
     disconnect(): Promise<void>;
     /**
@@ -2997,8 +3424,8 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     /**
      * 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.
      */
@@ -3026,14 +3453,14 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
      */
     getCrudBatch(limit?: number): Promise<CrudBatch | null>;
@@ -3047,7 +3474,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
@@ -3059,7 +3486,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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.
      *
@@ -3102,8 +3529,8 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
      */
     execute(sql: string, parameters?: any[]): Promise<QueryResult>;
@@ -3111,8 +3538,8 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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.
      */
@@ -3122,53 +3549,53 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
      */
     executeBatch(sql: string, parameters?: any[][]): Promise<QueryResult>;
     /**
      *  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
      */
     getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
     /**
      * 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
      */
     getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
     /**
      * 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
      */
     get<T>(sql: string, parameters?: any[]): Promise<T>;
     /**
      * 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.
      */
-    readLock<T>(callback: (db: DBAdapter) => Promise<T>): Promise<T>;
+    readLock<T>(callback: (db: LockContext) => Promise<T>): Promise<T>;
     /**
      * 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.
      */
-    writeLock<T>(callback: (db: DBAdapter) => Promise<T>): Promise<T>;
+    writeLock<T>(callback: (db: LockContext) => Promise<T>): Promise<T>;
     /**
      * Open a read-only transaction.
      * 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
      */
@@ -3178,15 +3605,15 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
      */
     writeTransaction<T>(callback: (tx: Transaction) => Promise<T>, lockTimeout?: number): Promise<T>;
     /**
-     * This version of `watch` uses {@link AsyncGenerator}, for documentation see {@link watchWithAsyncGenerator}.
-     * Can be overloaded to use a callback handler instead, for documentation see {@link watchWithCallback}.
+     * This version of `watch` uses `AsyncGenerator`, for documentation see {@link AbstractPowerSyncDatabase.watchWithAsyncGenerator}.
+     * Can be overloaded to use a callback handler instead, for documentation see {@link AbstractPowerSyncDatabase.watchWithCallback}.
      *
      * @example
      * ```javascript
@@ -3202,7 +3629,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      */
     watch(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
     /**
-     * See {@link watchWithCallback}.
+     * See {@link AbstractPowerSyncDatabase.watchWithCallback}.
      *
      * @example
      * ```javascript
@@ -3256,25 +3683,25 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     customQuery<RowType>(query: WatchCompatibleQuery<RowType[]>): Query<RowType>;
     /**
      * 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: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
     /**
      * 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: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
@@ -3283,15 +3710,15 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * 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
      */
     resolveTables(sql: string, parameters?: any[], options?: SQLWatchOptions): Promise<string[]>;
     /**
-     * This version of `onChange` uses {@link AsyncGenerator}, for documentation see {@link onChangeWithAsyncGenerator}.
-     * Can be overloaded to use a callback handler instead, for documentation see {@link onChangeWithCallback}.
+     * This version of `onChange` uses `AsyncGenerator`, for documentation see {@link AbstractPowerSyncDatabase.onChangeWithAsyncGenerator}.
+     * Can be overloaded to use a callback handler instead, for documentation see {@link AbstractPowerSyncDatabase.onChangeWithCallback}.
      *
      * @example
      * ```javascript
@@ -3304,7 +3731,7 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      */
     onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
-     * See {@link onChangeWithCallback}.
+     * See {@link AbstractPowerSyncDatabase.onChangeWithCallback}.
      *
      * @example
      * ```javascript
@@ -3321,36 +3748,36 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     /**
      * 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?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
     /**
      * 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?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
     private handleTableChanges;
     private processTableUpdates;
-    /**
-     * @ignore
-     */
     private executeReadOnly;
 }
 
+/**
+ * @public
+ */
 declare const LogLevel: {
     TRACE: Logger.ILogLevel;
     DEBUG: Logger.ILogLevel;
@@ -3360,6 +3787,9 @@ declare const LogLevel: {
     ERROR: Logger.ILogLevel;
     OFF: Logger.ILogLevel;
 };
+/**
+ * @public
+ */
 interface CreateLoggerOptions {
     logLevel?: ILogLevel;
 }
@@ -3370,6 +3800,7 @@ interface CreateLoggerOptions {
  * across all loggers created with `createLogger`. Adjusting settings on this
  * base logger affects all loggers derived from it unless explicitly overridden.
  *
+ * @public
  */
 declare function createBaseLogger(): typeof Logger;
 /**
@@ -3378,14 +3809,21 @@ declare function createBaseLogger(): typeof Logger;
  * 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
  */
 declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;
 
+/**
+ * The default name of the local table storing attachment data.
+ *
+ * @alpha
+ */
 declare const ATTACHMENT_TABLE = "attachments";
 /**
  * AttachmentRecord represents an attachment in the local database.
  *
- * @experimental
+ * @alpha
  */
 interface AttachmentRecord {
     id: string;
@@ -3404,13 +3842,13 @@ interface AttachmentRecord {
  * @param row - The database row object
  * @returns The corresponding AttachmentRecord
  *
- * @experimental
+ * @alpha
  */
 declare function attachmentFromSql(row: any): AttachmentRecord;
 /**
  * AttachmentState represents the current synchronization state of an attachment.
  *
- * @experimental
+ * @alpha
  */
 declare enum AttachmentState {
     QUEUED_UPLOAD = 0,// Attachment to be uploaded
@@ -3419,12 +3857,15 @@ declare enum AttachmentState {
     SYNCED = 3,// Attachment has been synced
     ARCHIVED = 4
 }
+/**
+ * @alpha
+ */
 interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {
 }
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
- * @internal
+ * @alpha
  */
 declare class AttachmentTable extends Table {
     constructor(options?: AttachmentTableOptions);
@@ -3436,17 +3877,18 @@ declare class AttachmentTable extends Table {
  * Provides methods to query, insert, update, and delete attachment records with
  * proper transaction management through PowerSync.
  *
- * @internal
+ * @experimental
+ * @alpha
  */
 declare class AttachmentContext {
     /** PowerSync database instance for executing queries */
-    db: AbstractPowerSyncDatabase;
+    readonly db: AbstractPowerSyncDatabase;
     /** Name of the database table storing attachment records */
-    tableName: string;
+    readonly tableName: string;
     /** Logger instance for diagnostic information */
-    logger: ILogger;
+    readonly logger: ILogger;
     /** Maximum number of archived attachments to keep before cleanup */
-    archivedCacheLimit: number;
+    readonly archivedCacheLimit: number;
     /**
      * Creates a new AttachmentContext instance.
      *
@@ -3523,28 +3965,34 @@ declare class AttachmentContext {
 interface AttachmentErrorHandler {
     /**
      * Handles a download error for a specific attachment.
-     * @param attachment The attachment that failed to download
-     * @param error The error encountered during the download
+     * @param attachment - The attachment that failed to download
+     * @param error - The error encountered during the download
      * @returns `true` to retry the operation, `false` to archive the attachment
      */
     onDownloadError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
     /**
      * Handles an upload error for a specific attachment.
-     * @param attachment The attachment that failed to upload
-     * @param error The error encountered during the upload
+     * @param attachment - The attachment that failed to upload
+     * @param error - The error encountered during the upload
      * @returns `true` to retry the operation, `false` to archive the attachment
      */
     onUploadError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
     /**
      * Handles a delete error for a specific attachment.
-     * @param attachment The attachment that failed to delete
-     * @param error The error encountered during the delete
+     * @param attachment - The attachment that failed to delete
+     * @param error - The error encountered during the delete
      * @returns `true` to retry the operation, `false` to archive the attachment
      */
     onDeleteError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
 }
 
+/**
+ * @alpha
+ */
 type AttachmentData = ArrayBuffer | string;
+/**
+ * @alpha
+ */
 declare enum EncodingType {
     UTF8 = "utf8",
     Base64 = "base64"
@@ -3559,36 +4007,36 @@ declare enum EncodingType {
 interface LocalStorageAdapter {
     /**
      * Saves data to a local file.
-     * @param filePath Path where the file will be stored
-     * @param data Data to store (ArrayBuffer, Blob, or string)
+     * @param filePath - Path where the file will be stored
+     * @param data - Data to store (ArrayBuffer, Blob, or string)
      * @returns Number of bytes written
      */
     saveFile(filePath: string, data: AttachmentData): Promise<number>;
     /**
      * Retrieves file data as an ArrayBuffer.
-     * @param filePath Path where the file is stored
+     * @param filePath - Path where the file is stored
      * @returns ArrayBuffer containing the file data
      */
     readFile(filePath: string): Promise<ArrayBuffer>;
     /**
      * Deletes the file at the given path.
-     * @param filePath Path where the file is stored
+     * @param filePath - Path where the file is stored
      */
     deleteFile(filePath: string): Promise<void>;
     /**
      * Checks if a file exists at the given path.
-     * @param filePath Path where the file is stored
+     * @param filePath - Path where the file is stored
      * @returns True if the file exists, false otherwise
      */
     fileExists(filePath: string): Promise<boolean>;
     /**
      * Creates a directory at the specified path.
-     * @param path The full path to the directory
+     * @param path - The full path to the directory
      */
     makeDir(path: string): Promise<void>;
     /**
      * Removes a directory at the specified path.
-     * @param path The full path to the directory
+     * @param path - The full path to the directory
      */
     rmDir(path: string): Promise<void>;
     /**
@@ -3601,7 +4049,7 @@ interface LocalStorageAdapter {
     clear(): Promise<void>;
     /**
      * Returns the file path for the provided filename in the storage directory.
-     * @param filename The filename to get the path for
+     * @param filename - The filename to get the path for
      * @returns The full file path
      */
     getLocalUri(filename: string): string;
@@ -3617,19 +4065,19 @@ interface LocalStorageAdapter {
 interface RemoteStorageAdapter {
     /**
      * Uploads a file to remote storage.
-     * @param fileData The binary content of the file to upload
-     * @param attachment The associated attachment metadata
+     * @param fileData - The binary content of the file to upload
+     * @param attachment - The associated attachment metadata
      */
     uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord): Promise<void>;
     /**
      * Downloads a file from remote storage.
-     * @param attachment The attachment describing the file to download
+     * @param attachment - The attachment describing the file to download
      * @returns The binary data of the downloaded file
      */
     downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer>;
     /**
      * Deletes a file from remote storage.
-     * @param attachment The attachment describing the file to delete
+     * @param attachment - The attachment describing the file to delete
      */
     deleteFile(attachment: AttachmentRecord): Promise<void>;
 }
@@ -3638,18 +4086,20 @@ interface RemoteStorageAdapter {
  * WatchedAttachmentItem represents an attachment reference in your application's data model.
  * Use either filename OR fileExtension (not both).
  *
- * @experimental
+ * @alpha
  */
 type WatchedAttachmentItem = {
     id: string;
     filename: string;
     fileExtension?: never;
     metaData?: string;
+    mediaType?: string;
 } | {
     id: string;
     fileExtension: string;
     filename?: never;
     metaData?: string;
+    mediaType?: string;
 };
 
 /**
@@ -3661,7 +4111,7 @@ type WatchedAttachmentItem = {
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-declare class AttachmentQueue {
+declare class AttachmentQueue implements AttachmentQueue {
     /** Timer for periodic synchronization operations */
     private periodicSyncTimer?;
     /** Service for synchronizing attachments between local and remote storage */
@@ -3708,27 +4158,47 @@ declare 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, syncIntervalMs, syncThrottleDuration, downloadAttachments, archivedCacheLimit, errorHandler }: {
+        /**
+         * PowerSync database instance
+         */
         db: AbstractPowerSyncDatabase;
+        /**
+         * Remote storage adapter for upload/download operations
+         */
         remoteStorage: RemoteStorageAdapter;
+        /**
+         * Local storage adapter for file persistence
+         */
         localStorage: LocalStorageAdapter;
+        /**
+         * Callback for monitoring attachment changes in your data model
+         */
         watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
+        /**
+         * Name of the table to store attachment records. Default: 'ps_attachment_queue'
+         */
         tableName?: string;
+        /**
+         * Logger instance. Defaults to db.logger
+         */
         logger?: ILogger;
+        /**
+         * Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
+         */
         syncIntervalMs?: number;
+        /**
+         * Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
+         */
         syncThrottleDuration?: number;
+        /**
+         * Whether to automatically download remote attachments. Default: true
+         */
         downloadAttachments?: boolean;
+        /**
+         * Maximum archived attachments before cleanup. Default: 100
+         */
         archivedCacheLimit?: number;
         errorHandler?: AttachmentErrorHandler;
     });
@@ -3762,25 +4232,45 @@ declare class AttachmentQueue {
      * Clears the periodic sync timer and closes all active attachment watchers.
      */
     stopSync(): Promise<void>;
+    /**
+     * 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<T>(callback: (context: AttachmentContext) => Promise<T>): Promise<T>;
     /**
      * 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
      */
     saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }: {
+        /**
+         * The file data as ArrayBuffer, Blob, or base64 string
+         */
         data: AttachmentData;
+        /**
+         * File extension (e.g., 'jpg', 'pdf')
+         */
         fileExtension: string;
+        /**
+         * MIME type of the file (e.g., 'image/jpeg')
+         */
         mediaType?: string;
+        /**
+         * Optional metadata to associate with the attachment
+         */
         metaData?: string;
+        /**
+         * Optional custom ID. If not provided, a UUID will be generated
+         */
         id?: string;
+        /**
+         * Optional callback to execute additional database operations within the same transaction as the attachment
+         * creation.
+         */
         updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
     }): Promise<AttachmentRecord>;
     deleteFile({ id, updateHook }: {
@@ -3882,10 +4372,16 @@ declare class SyncingService {
     deleteArchivedAttachments(context: AttachmentContext): Promise<boolean>;
 }
 
+/**
+ * @internal
+ */
 interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions>, SQLOpenOptions {
     /** Schema used for the local database. */
     schema: Schema;
 }
+/**
+ * @internal
+ */
 declare abstract class AbstractPowerSyncDatabaseOpenFactory {
     protected options: PowerSyncOpenFactoryOptions;
     constructor(options: PowerSyncOpenFactoryOptions);
@@ -3901,16 +4397,31 @@ declare abstract class AbstractPowerSyncDatabaseOpenFactory {
     getInstance(): AbstractPowerSyncDatabase;
 }
 
+/**
+ * @public
+ */
 interface CompilableQueryWatchHandler<T> {
     onResult: (results: T[]) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * @public
+ */
 declare function compilableQueryWatch<T>(db: AbstractPowerSyncDatabase, query: CompilableQuery<T>, handler: CompilableQueryWatchHandler<T>, options?: SQLWatchOptions): void;
 
+/**
+ * @internal
+ */
 declare const MAX_OP_ID = "9223372036854775807";
 
+/**
+ * @internal
+ */
 declare function runOnSchemaChange(callback: (signal: AbortSignal) => void, db: AbstractPowerSyncDatabase, options?: SQLWatchOptions): void;
 
+/**
+ * @internal
+ */
 declare class SqliteBucketStorage extends BaseObserver<BucketStorageListener> implements BucketStorageAdapter {
     private db;
     private logger;
@@ -3944,6 +4455,8 @@ declare class SqliteBucketStorage extends BaseObserver<BucketStorageListener> im
  * 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
  */
 declare class ConnectionClosedError extends Error {
     static NAME: string;
@@ -3960,6 +4473,8 @@ declare const MEMORY_TRIGGER_CLAIM_MANAGER: TriggerClaimManager;
 /**
  * Helper function for sanitizing UUID input strings.
  * Typically used with {@link sanitizeSQL}.
+ *
+ * @alpha
  */
 declare function sanitizeUUID(uuid: string): string;
 /**
@@ -3989,11 +4504,15 @@ declare function sanitizeUUID(uuid: string): string;
  * // Incorrect:
  * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
  * ```
+ *
+ * @alpha
  */
 declare function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string;
 
 /**
  * Options for {@link GetAllQuery}.
+ *
+ * @public
  */
 type GetAllQueryOptions<RowType = unknown> = {
     sql: string;
@@ -4012,6 +4531,8 @@ type GetAllQueryOptions<RowType = unknown> = {
 };
 /**
  * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ *
+ * @public
  */
 declare class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
     protected options: GetAllQueryOptions<RowType>;
@@ -4026,12 +4547,17 @@ declare class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<Row
  * 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
  */
 declare class AbortOperation extends Error {
     protected reason: string;
     constructor(reason: string);
 }
 
+/**
+ * @internal
+ */
 interface ControlledExecutorOptions {
     /**
      * If throttling is enabled, it ensures only one task runs at a time,
@@ -4040,6 +4566,9 @@ interface ControlledExecutorOptions {
      */
     throttleEnabled?: boolean;
 }
+/**
+ * @internal
+ */
 declare class ControlledExecutor<T> {
     private task;
     /**
@@ -4058,10 +4587,16 @@ declare class ControlledExecutor<T> {
     private execute;
 }
 
+/**
+ * @internal
+ */
 interface ParsedQuery {
     sqlStatement: string;
     parameters: any[];
 }
+/**
+ * @internal
+ */
 declare const parseQuery: <T>(query: string | CompilableQuery<T>, parameters: any[]) => ParsedQuery;
 
 export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DBAdapterDefaultMixin, DBGetUtilsDefaultMixin, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, Mutex, OnChangeQueryProcessor, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, Semaphore, SqliteBucketStorage, SyncClientImplementation, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID, timeoutSignal };