@powersync/common 0.0.0-dev-20250210155038 → 0.0.0-dev-20250416114737

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -10,7 +10,7 @@ import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnecto
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
-import { type AdditionalConnectionOptions, type PowerSyncConnectionOptions, StreamingSyncImplementation, StreamingSyncImplementationListener, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -153,9 +153,18 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     waitForReady(): Promise<void>;
     /**
+     * Wait for the first sync operation to complete.
+     *
+     * @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.
      * @returns A promise which will resolve once the first full sync has completed.
      */
-    waitForFirstSync(signal?: AbortSignal): Promise<void>;
+    waitForFirstSync(request?: AbortSignal | {
+        signal?: AbortSignal;
+        priority?: number;
+    }): Promise<void>;
     /**
      * Allows for extended implementations to execute custom initialization
      * logic as part of the total init process
@@ -213,7 +222,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     getUploadQueueStats(includeSize?: boolean): Promise<UploadQueueStats>;
     /**
-     * Get a batch of crud data to upload.
+     * Get a batch of CRUD data to upload.
      *
      * Returns null if there is no data to upload.
      *
@@ -228,6 +237,9 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
+     * @returns A batch of CRUD operations to upload, or null if there are none
      */
     getCrudBatch(limit?: number): Promise<CrudBatch | null>;
     /**
@@ -242,36 +254,71 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      *
      * Unlike {@link 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
      */
     getNextCrudTransaction(): Promise<CrudTransaction | null>;
     /**
      * Get an unique client id for this database.
      *
      * The id is not reset when the database is cleared, only when the database is deleted.
+     *
+     * @returns A unique identifier for the database instance
      */
     getClientId(): Promise<string>;
     private handleCrudCheckpoint;
     /**
-     * Execute a write (INSERT/UPDATE/DELETE) query
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query
      * and optionally return results.
+     *
+     * @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>;
+    /**
+     * 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
+     * @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.
+     */
+    executeRaw(sql: string, parameters?: any[]): Promise<any[][]>;
     /**
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * 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
+     * @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
+     * @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
+     * @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
+     * @returns The first result matching the query
+     * @throws Error if no rows are returned
      */
     get<T>(sql: string, parameters?: any[]): Promise<T>;
     /**
@@ -288,12 +335,22 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     readTransaction<T>(callback: (tx: Transaction) => Promise<T>, lockTimeout?: number): Promise<T>;
     /**
      * Open a read-write transaction.
      * 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
+     * @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>;
     /**
@@ -336,14 +393,34 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
      */
     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.
      * 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
+     * @returns An AsyncIterable that yields QueryResults whenever the data changes
      */
     watchWithAsyncGenerator(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
+    /**
+     * Resolves the list of tables that are used in a SQL query.
+     * If tables are specified in the options, those are used directly.
+     * Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.
+     *
+     * @param sql The SQL query to analyze
+     * @param parameters Optional parameters for the SQL query
+     * @param options Optional watch options that may contain explicit table list
+     * @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}.
@@ -382,7 +459,9 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * Returns dispose function to stop watching.
+     * @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?: SQLWatchOptions): () => void;
     /**
@@ -391,7 +470,10 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * This is preferred over {@link watchWithAsyncGenerator} when multiple queries need to be performed
      * together when data is changed.
      *
-     * Note, do not declare this as `async *onChange` as it will not work in React Native
+     * Note: do not declare this as `async *onChange` as it will not work in React Native.
+     *
+     * @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;

package/lib/client/AbstractPowerSyncDatabase.js

@@ -7,14 +7,14 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { mutexRunExclusive } from '../utils/mutex.js';
-import { throttleTrailing } from '../utils/throttle.js';
+import { throttleTrailing } from '../utils/async.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
+import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
-import { runOnSchemaChange } from './runOnSchemaChange.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -42,6 +42,10 @@ export const DEFAULT_LOCK_TIMEOUT_MS = 120_000; // 2 mins
 export const isPowerSyncDatabaseOptionsWithSettings = (test) => {
     return typeof test == 'object' && isSQLOpenOptions(test.database);
 };
+/**
+ * The priority used by the core extension to indicate that a full sync was completed.
+ */
+const FULL_SYNC_PRIORITY = 2147483647;
 export class AbstractPowerSyncDatabase extends BaseObserver {
     options;
     /**
@@ -127,16 +131,27 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this._isReadyPromise;
     }
     /**
+     * Wait for the first sync operation to complete.
+     *
+     * @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.
      * @returns A promise which will resolve once the first full sync has completed.
      */
-    async waitForFirstSync(signal) {
-        if (this.currentStatus.hasSynced) {
+    async waitForFirstSync(request) {
+        const signal = request instanceof AbortSignal ? request : request?.signal;
+        const priority = request && 'priority' in request ? request.priority : undefined;
+        const statusMatches = priority === undefined
+            ? (status) => status.hasSynced
+            : (status) => status.statusForPriority(priority).hasSynced;
+        if (statusMatches(this.currentStatus)) {
             return;
         }
         return new Promise((resolve) => {
             const dispose = this.registerListener({
                 statusChanged: (status) => {
-                    if (status.hasSynced) {
+                    if (statusMatches(status)) {
                         dispose();
                         resolve();
                     }
@@ -177,19 +192,36 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 .map((n) => parseInt(n));
         }
         catch (e) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.2.0 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
+            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
         }
-        // Validate >=0.2.0 <1.0.0
-        if (versionInts[0] != 0 || versionInts[1] < 2 || versionInts[2] < 0) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.2.0 <1.0.0, got: ${this.sdkVersion}`);
+        // Validate >=0.3.11 <1.0.0
+        if (versionInts[0] != 0 || versionInts[1] < 3 || (versionInts[1] == 3 && versionInts[2] < 11)) {
+            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}`);
         }
     }
     async updateHasSynced() {
-        const result = await this.database.get('SELECT powersync_last_synced_at() as synced_at');
-        const hasSynced = result.synced_at != null;
-        const syncedAt = result.synced_at != null ? new Date(result.synced_at + 'Z') : undefined;
-        if (hasSynced != this.currentStatus.hasSynced) {
-            this.currentStatus = new SyncStatus({ ...this.currentStatus.toJSON(), hasSynced, lastSyncedAt: syncedAt });
+        const result = await this.database.getAll('SELECT priority, last_synced_at FROM ps_sync_state ORDER BY priority DESC');
+        let lastCompleteSync;
+        const priorityStatusEntries = [];
+        for (const { priority, last_synced_at } of result) {
+            const parsedDate = new Date(last_synced_at + 'Z');
+            if (priority == FULL_SYNC_PRIORITY) {
+                // This lowest-possible priority represents a complete sync.
+                lastCompleteSync = parsedDate;
+            }
+            else {
+                priorityStatusEntries.push({ priority, hasSynced: true, lastSyncedAt: parsedDate });
+            }
+        }
+        const hasSynced = lastCompleteSync != null;
+        const updatedStatus = new SyncStatus({
+            ...this.currentStatus.toJSON(),
+            hasSynced,
+            priorityStatusEntries,
+            lastSyncedAt: lastCompleteSync
+        });
+        if (!updatedStatus.isEqual(this.currentStatus)) {
+            this.currentStatus = updatedStatus;
             this.iterateListeners((l) => l.statusChanged?.(this.currentStatus));
         }
     }
@@ -245,7 +277,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const { retryDelayMs, crudUploadThrottleMs } = this.resolvedConnectionOptions(options);
         this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, {
             retryDelayMs,
-            crudUploadThrottleMs,
+            crudUploadThrottleMs
         });
         this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
             statusChanged: (status) => {
@@ -302,12 +334,15 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async close(options = DEFAULT_POWERSYNC_CLOSE_OPTIONS) {
         await this.waitForReady();
+        if (this.closed) {
+            return;
+        }
         const { disconnect } = options;
         if (disconnect) {
             await this.disconnect();
         }
         await this.syncStreamImplementation?.dispose();
-        this.database.close();
+        await this.database.close();
         this.closed = true;
     }
     /**
@@ -328,7 +363,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         });
     }
     /**
-     * Get a batch of crud data to upload.
+     * Get a batch of CRUD data to upload.
      *
      * Returns null if there is no data to upload.
      *
@@ -343,6 +378,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * 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
+     * @returns A batch of CRUD operations to upload, or null if there are none
      */
     async getCrudBatch(limit = DEFAULT_CRUD_BATCH_LIMIT) {
         const result = await this.getAll(`SELECT id, tx_id, data FROM ${PSInternalTable.CRUD} ORDER BY id ASC LIMIT ?`, [limit + 1]);
@@ -370,6 +408,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      *
      * Unlike {@link getCrudBatch}, this only returns data from a single transaction at a time.
      * All data for the transaction is loaded into memory.
+     *
+     * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     async getNextCrudTransaction() {
         return await this.readTransaction(async (tx) => {
@@ -394,6 +434,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Get an unique client id for this database.
      *
      * The id is not reset when the database is cleared, only when the database is deleted.
+     *
+     * @returns A unique identifier for the database instance
      */
     async getClientId() {
         return this.bucketStorageAdapter.getClientId();
@@ -417,17 +459,38 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         });
     }
     /**
-     * Execute a write (INSERT/UPDATE/DELETE) query
+     * Execute a SQL write (INSERT/UPDATE/DELETE) query
      * and optionally return results.
+     *
+     * @param sql The SQL query to execute
+     * @param parameters Optional array of parameters to bind to the query
+     * @returns The query result as an object with structured key-value pairs
      */
     async execute(sql, parameters) {
         await this.waitForReady();
         return this.database.execute(sql, parameters);
     }
+    /**
+     * 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
+     * @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.
+     */
+    async executeRaw(sql, parameters) {
+        await this.waitForReady();
+        return this.database.executeRaw(sql, parameters);
+    }
     /**
      * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
      * 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
+     * @returns The query result
      */
     async executeBatch(sql, parameters) {
         await this.waitForReady();
@@ -435,6 +498,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      *  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
+     * @returns An array of results
      */
     async getAll(sql, parameters) {
         await this.waitForReady();
@@ -442,6 +509,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      * 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
+     * @returns The first result if found, or null if no results are returned
      */
     async getOptional(sql, parameters) {
         await this.waitForReady();
@@ -449,6 +520,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     }
     /**
      * 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
+     * @returns The first result matching the query
+     * @throws Error if no rows are returned
      */
     async get(sql, parameters) {
         await this.waitForReady();
@@ -477,6 +553,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * 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
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     async readTransaction(callback, lockTimeout = DEFAULT_LOCK_TIMEOUT_MS) {
         await this.waitForReady();
@@ -490,6 +571,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Open a read-write transaction.
      * 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
+     * @returns The result of the callback
+     * @throws Error if the lock cannot be obtained within the timeout period
      */
     async writeTransaction(callback, lockTimeout = DEFAULT_LOCK_TIMEOUT_MS) {
         await this.waitForReady();
@@ -514,6 +600,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * 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
      */
     watchWithCallback(sql, parameters, handler, options) {
         const { onResult, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
@@ -554,6 +645,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.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
+     * @returns An AsyncIterable that yields QueryResults whenever the data changes
      */
     watchWithAsyncGenerator(sql, parameters, options) {
         return new EventIterator((eventOptions) => {
@@ -571,6 +667,16 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             });
         });
     }
+    /**
+     * Resolves the list of tables that are used in a SQL query.
+     * If tables are specified in the options, those are used directly.
+     * Otherwise, analyzes the query using EXPLAIN to determine which tables are accessed.
+     *
+     * @param sql The SQL query to analyze
+     * @param parameters Optional parameters for the SQL query
+     * @param options Optional watch options that may contain explicit table list
+     * @returns Array of table names that the query depends on
+     */
     async resolveTables(sql, parameters, options) {
         const resolvedTables = options?.tables ? [...options.tables] : [];
         if (!options?.tables) {
@@ -602,7 +708,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      *
      * Note that the `onChange` callback member of the handler is required.
      *
-     * Returns dispose function to stop watching.
+     * @param handler Callbacks for handling change events and errors
+     * @param options Options for configuring watch behavior
+     * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
         const { onChange, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
@@ -644,7 +752,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * This is preferred over {@link watchWithAsyncGenerator} when multiple queries need to be performed
      * together when data is changed.
      *
-     * Note, do not declare this as `async *onChange` as it will not work in React Native
+     * Note: do not declare this as `async *onChange` as it will not work in React Native.
+     *
+     * @param options Options for configuring watch behavior
+     * @returns An AsyncIterable that yields change events whenever the specified tables change
      */
     onChangeWithAsyncGenerator(options) {
         const resolvedOptions = options ?? {};

package/lib/client/SQLOpenFactory.d.ts

@@ -6,6 +6,9 @@ export interface SQLOpenOptions {
     dbFilename: string;
     /**
      * Directory where the database file is located.
+     *
+     * When set, the directory must exist when the database is opened, it will
+     * not be created automatically.
      */
     dbLocation?: string;
     /**

package/lib/client/sync/bucket/BucketStorageAdapter.d.ts

@@ -2,6 +2,10 @@ import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObser
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, OpId } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
+export interface BucketDescription {
+    name: string;
+    priority: number;
+}
 export interface Checkpoint {
     last_op_id: OpId;
     buckets: BucketChecksum[];
@@ -25,6 +29,7 @@ export interface SyncLocalDatabaseResult {
 }
 export interface BucketChecksum {
     bucket: string;
+    priority?: number;
     /**
      * 32-bit unsigned hash.
      */
@@ -51,7 +56,7 @@ export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
-    syncLocalDatabase(checkpoint: Checkpoint): Promise<{
+    syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<{
         checkpointValid: boolean;
         ready: boolean;
         failures?: any[];

package/lib/client/sync/bucket/SqliteBucketStorage.d.ts

@@ -37,14 +37,14 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
      */
     private deleteBucket;
     hasCompletedSync(): Promise<boolean>;
-    syncLocalDatabase(checkpoint: Checkpoint): Promise<SyncLocalDatabaseResult>;
+    syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<SyncLocalDatabaseResult>;
     /**
      * Atomically update the local state to the current checkpoint.
      *
      * This includes creating new tables, dropping old tables, and copying data over from the oplog.
      */
     private updateObjectsFromBuckets;
-    validateChecksums(checkpoint: Checkpoint): Promise<SyncLocalDatabaseResult>;
+    validateChecksums(checkpoint: Checkpoint, priority: number | undefined): Promise<SyncLocalDatabaseResult>;
     /**
      * Force a compact, for tests.
      */

package/lib/client/sync/bucket/SqliteBucketStorage.js

@@ -106,8 +106,8 @@ export class SqliteBucketStorage extends BaseObserver {
         }
         return completed;
     }
-    async syncLocalDatabase(checkpoint) {
-        const r = await this.validateChecksums(checkpoint);
+    async syncLocalDatabase(checkpoint, priority) {
+        const r = await this.validateChecksums(checkpoint, priority);
         if (!r.checkpointValid) {
             this.logger.error('Checksums failed for', r.checkpointFailures);
             for (const b of r.checkpointFailures ?? []) {
@@ -115,17 +115,21 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        const bucketNames = checkpoint.buckets.map((b) => b.bucket);
+        const buckets = checkpoint.buckets;
+        if (priority !== undefined) {
+            buckets.filter((b) => hasMatchingPriority(priority, b));
+        }
+        const bucketNames = buckets.map((b) => b.bucket);
         await this.writeTransaction(async (tx) => {
             await tx.execute(`UPDATE ps_buckets SET last_op = ? WHERE name IN (SELECT json_each.value FROM json_each(?))`, [
                 checkpoint.last_op_id,
                 JSON.stringify(bucketNames)
             ]);
-            if (checkpoint.write_checkpoint) {
+            if (priority == null && checkpoint.write_checkpoint) {
                 await tx.execute("UPDATE ps_buckets SET last_op = ? WHERE name = '$local'", [checkpoint.write_checkpoint]);
             }
         });
-        const valid = await this.updateObjectsFromBuckets(checkpoint);
+        const valid = await this.updateObjectsFromBuckets(checkpoint, priority);
         if (!valid) {
             this.logger.debug('Not at a consistent checkpoint - cannot update local db');
             return { ready: false, checkpointValid: true };
@@ -141,19 +145,36 @@ export class SqliteBucketStorage extends BaseObserver {
      *
      * This includes creating new tables, dropping old tables, and copying data over from the oplog.
      */
-    async updateObjectsFromBuckets(checkpoint) {
+    async updateObjectsFromBuckets(checkpoint, priority) {
+        let arg = '';
+        if (priority !== undefined) {
+            const affectedBuckets = [];
+            for (const desc of checkpoint.buckets) {
+                if (hasMatchingPriority(priority, desc)) {
+                    affectedBuckets.push(desc.bucket);
+                }
+            }
+            arg = JSON.stringify({ priority, buckets: affectedBuckets });
+        }
         return this.writeTransaction(async (tx) => {
             const { insertId: result } = await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
                 'sync_local',
-                ''
+                arg
             ]);
             return result == 1;
         });
     }
-    async validateChecksums(checkpoint) {
-        const rs = await this.db.execute('SELECT powersync_validate_checkpoint(?) as result', [JSON.stringify(checkpoint)]);
+    async validateChecksums(checkpoint, priority) {
+        if (priority !== undefined) {
+            // Only validate the buckets within the priority we care about
+            const newBuckets = checkpoint.buckets.filter((cs) => hasMatchingPriority(priority, cs));
+            checkpoint = { ...checkpoint, buckets: newBuckets };
+        }
+        const rs = await this.db.execute('SELECT powersync_validate_checkpoint(?) as result', [
+            JSON.stringify({ ...checkpoint })
+        ]);
         const resultItem = rs.rows?.item(0);
-        this.logger.debug('validateChecksums result item', resultItem);
+        this.logger.debug('validateChecksums priority, checkpoint, result item', priority, checkpoint, resultItem);
         if (!resultItem) {
             return {
                 checkpointValid: false,
@@ -304,3 +325,6 @@ export class SqliteBucketStorage extends BaseObserver {
         // No-op for now
     }
 }
+function hasMatchingPriority(priority, bucket) {
+    return bucket.priority != null && bucket.priority <= priority;
+}