@powersync/common 1.53.1 → 1.54.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -1,5 +1,5 @@
 import { ILogger } from 'js-logger';
-import { DBAdapter, QueryResult, Transaction } from '../db/DBAdapter.js';
+import { DBAdapter, LockContext, QueryResult, Transaction } from '../db/DBAdapter.js';
 import { SyncStatus } from '../db/crud/SyncStatus.js';
 import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
@@ -18,19 +18,29 @@ import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
 import { Mutex } from '../utils/mutex.js';
+/**
+ * @public
+ */
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
 }
+/**
+ * @public
+ */
 export 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
+ */
 export interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
     /**
      * Source for a SQLite database connection.
@@ -41,22 +51,35 @@ export interface PowerSyncDatabaseOptions extends BasePowerSyncDatabaseOptions {
      */
     database: DBAdapter | SQLOpenFactory | SQLOpenOptions;
 }
+/**
+ * @public
+ */
 export interface PowerSyncDatabaseOptionsWithDBAdapter extends BasePowerSyncDatabaseOptions {
     database: DBAdapter;
 }
+/**
+ * @public
+ */
 export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDatabaseOptions {
     database: SQLOpenFactory;
 }
+/**
+ * @public
+ */
 export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
     database: SQLOpenOptions;
 }
+/**
+ * @public
+ */
 export 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
@@ -67,6 +90,9 @@ export interface SQLOnChangeOptions {
      */
     triggerImmediate?: boolean;
 }
+/**
+ * @public
+ */
 export interface SQLWatchOptions extends SQLOnChangeOptions {
     /**
      * Optional comparator which will be used to compare the results of the query.
@@ -74,23 +100,38 @@ export interface SQLWatchOptions extends SQLOnChangeOptions {
      */
     comparator?: WatchedQueryComparator<QueryResult>;
 }
+/**
+ * @public
+ */
 export interface WatchOnChangeEvent {
     changedTables: string[];
 }
+/**
+ * @public
+ */
 export interface WatchHandler {
     onResult: (results: QueryResult) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * @public
+ */
 export interface WatchOnChangeHandler {
     onChange: (event: WatchOnChangeEvent) => Promise<void> | void;
     onError?: (error: Error) => void;
 }
+/**
+ * @public
+ */
 export interface PowerSyncDBListener extends StreamingSyncImplementationListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
     closing: () => Promise<void> | void;
     closed: () => Promise<void> | void;
 }
+/**
+ * @public
+ */
 export interface PowerSyncCloseOptions {
     /**
      * Disconnect the sync stream client if connected.
@@ -99,16 +140,27 @@ export interface PowerSyncCloseOptions {
      */
     disconnect?: boolean;
 }
+/**
+ * @internal
+ */
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
+/**
+ * @internal
+ */
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
     crudUploadThrottleMs: number;
 };
+/**
+ * @internal
+ */
 export 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
  */
 export declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
 /**
@@ -116,6 +168,9 @@ export declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
  * @internal
  */
 export declare const isPowerSyncDatabaseOptionsWithSettings: (test: any) => test is PowerSyncDatabaseOptionsWithSettings;
+/**
+ * @public
+ */
 export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
     protected options: PowerSyncDatabaseOptions;
     /**
@@ -194,7 +249,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * 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.
@@ -249,7 +304,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * Close the sync connection.
      *
-     * Use {@link connect} to connect again.
+     * Use {@link AbstractPowerSyncDatabase.connect} to connect again.
      */
     disconnect(): Promise<void>;
     /**
@@ -264,8 +319,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * 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.
      */
@@ -293,14 +348,14 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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>;
@@ -314,7 +369,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
@@ -326,7 +381,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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.
      *
@@ -369,8 +424,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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>;
@@ -378,8 +433,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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.
      */
@@ -389,53 +444,53 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
      */
@@ -445,15 +500,15 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
@@ -469,7 +524,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     watch(sql: string, parameters?: any[], options?: SQLWatchOptions): AsyncIterable<QueryResult>;
     /**
-     * See {@link watchWithCallback}.
+     * See {@link AbstractPowerSyncDatabase.watchWithCallback}.
      *
      * @example
      * ```javascript
@@ -523,25 +578,25 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     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>;
@@ -550,15 +605,15 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * 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
@@ -571,7 +626,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
-     * See {@link onChangeWithCallback}.
+     * See {@link AbstractPowerSyncDatabase.onChangeWithCallback}.
      *
      * @example
      * ```javascript
@@ -588,32 +643,29 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * 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;
 }