@powersync/common 1.27.0 → 1.28.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -155,7 +155,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     /**
      * Wait for the first sync operation to complete.
      *
-     * @argument 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.
@@ -183,6 +183,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Cannot be used while connected - this should only be called before {@link AbstractPowerSyncDatabase.connect}.
      */
     updateSchema(schema: Schema): Promise<void>;
+    get logger(): Logger.ILogger;
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.
@@ -222,7 +223,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.
      *
@@ -237,6 +238,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>;
     /**
@@ -251,37 +255,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>;
     /**
@@ -298,12 +336,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>;
     /**
@@ -346,14 +394,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}.
@@ -392,7 +460,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;
     /**
@@ -401,7 +471,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,7 +7,7 @@ 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';
@@ -133,7 +133,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     /**
      * Wait for the first sync operation to complete.
      *
-     * @argument 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.
@@ -250,6 +250,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.database.refreshSchema();
         this.iterateListeners(async (cb) => cb.schemaChanged?.(schema));
     }
+    get logger() {
+        return this.options.logger;
+    }
     /**
      * Wait for initialization to complete.
      * While initializing is automatic, this helps to catch and report initialization errors.
@@ -260,6 +263,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     // Use the options passed in during connect, or fallback to the options set during database creation or fallback to the default options
     resolvedConnectionOptions(options) {
         return {
+            ...options,
             retryDelayMs: options?.retryDelayMs ?? this.options.retryDelayMs ?? this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS,
             crudUploadThrottleMs: options?.crudUploadThrottleMs ?? this.options.crudUploadThrottleMs ?? DEFAULT_CRUD_UPLOAD_THROTTLE_MS
         };
@@ -274,11 +278,8 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             throw new Error('Cannot connect using a closed client');
         }
-        const { retryDelayMs, crudUploadThrottleMs } = this.resolvedConnectionOptions(options);
-        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, {
-            retryDelayMs,
-            crudUploadThrottleMs
-        });
+        const resolvedConnectOptions = this.resolvedConnectionOptions(options);
+        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, resolvedConnectOptions);
         this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
             statusChanged: (status) => {
                 this.currentStatus = new SyncStatus({
@@ -363,7 +364,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.
      *
@@ -378,6 +379,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]);
@@ -405,6 +409,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) => {
@@ -429,6 +435,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();
@@ -452,13 +460,26 @@ 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);
@@ -467,6 +488,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * 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();
@@ -474,6 +499,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();
@@ -481,6 +510,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();
@@ -488,6 +521,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();
@@ -516,6 +554,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();
@@ -529,6 +572,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();
@@ -553,6 +601,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 ?? {};
@@ -593,6 +646,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) => {
@@ -610,6 +668,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) {
@@ -641,7 +709,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 ?? {};
@@ -683,7 +753,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/sync/stream/AbstractRemote.d.ts

@@ -54,6 +54,13 @@ export type AbstractRemoteOptions = {
      * Binding should be done before passing here.
      */
     fetchImplementation: FetchImplementation | FetchImplementationProvider;
+    /**
+     * Optional options to pass directly to all `fetch` calls.
+     *
+     * This can include fields such as `dispatcher` (e.g. for proxy support),
+     * `cache`, or any other fetch-compatible options.
+     */
+    fetchOptions?: {};
 };
 export declare const DEFAULT_REMOTE_OPTIONS: AbstractRemoteOptions;
 export declare abstract class AbstractRemote {
@@ -84,6 +91,7 @@ export declare abstract class AbstractRemote {
      * Provides a BSON implementation. The import nature of this varies depending on the platform
      */
     abstract getBSON(): Promise<BSONImplementation>;
+    protected createSocket(url: string): WebSocket;
     /**
      * Connects to the sync/stream websocket endpoint
      */

package/lib/client/sync/stream/AbstractRemote.js

@@ -44,7 +44,8 @@ export const DEFAULT_REMOTE_OPTIONS = {
     socketUrlTransformer: (url) => url.replace(/^https?:\/\//, function (match) {
         return match === 'https://' ? 'wss://' : 'ws://';
     }),
-    fetchImplementation: new FetchImplementationProvider()
+    fetchImplementation: new FetchImplementationProvider(),
+    fetchOptions: {}
 };
 export class AbstractRemote {
     connector;
@@ -153,6 +154,9 @@ export class AbstractRemote {
         }
         return res;
     }
+    createSocket(url) {
+        return new WebSocket(url);
+    }
     /**
      * Connects to the sync/stream websocket endpoint
      */
@@ -167,7 +171,8 @@ export class AbstractRemote {
         const userAgent = this.getUserAgent();
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
-                url: this.options.socketUrlTransformer(request.url)
+                url: this.options.socketUrlTransformer(request.url),
+                wsCreator: (url) => this.createSocket(url)
             }),
             setup: {
                 keepAlive: KEEP_ALIVE_MS,
@@ -318,6 +323,7 @@ export class AbstractRemote {
             body: JSON.stringify(data),
             signal: controller.signal,
             cache: 'no-store',
+            ...(this.options.fetchOptions ?? {}),
             ...options.fetchOptions
         }).catch((ex) => {
             if (ex.name == 'AbortError') {

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -116,6 +116,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected abortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
+    private pendingCrudUpload?;
     syncStatus: SyncStatus;
     triggerCrudUpload: () => void;
     constructor(options: AbstractStreamingSyncImplementationOptions);
@@ -137,9 +138,8 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
      */
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
     private collectLocalBucketState;
-    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<{
-        retry?: boolean;
-    }>;
+    protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;
     private delayRetry;
 }