@powersync/common 0.0.0-dev-20250423120133 → 0.0.0-dev-20250526133243

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -79,6 +79,10 @@ export interface PowerSyncCloseOptions {
      */
     disconnect?: boolean;
 }
+type StoredConnectionOptions = {
+    connector: PowerSyncBackendConnector;
+    options: PowerSyncConnectionOptions;
+};
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
 export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
@@ -121,6 +125,29 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected _isReadyPromise: Promise<void>;
     protected _schema: Schema;
     private _database;
+    /**
+     * Tracks active connection attempts
+     */
+    protected connectingPromise: Promise<void> | null;
+    /**
+     * Tracks actively instantiating a streaming sync implementation.
+     */
+    protected syncStreamInitPromise: Promise<void> | null;
+    /**
+     * Active disconnect operation. Calling disconnect multiple times
+     * will resolve to the same operation.
+     */
+    protected disconnectingPromise: Promise<void> | null;
+    /**
+     * Tracks the last parameters supplied to `connect` calls.
+     * Calling `connect` multiple times in succession will result in:
+     * - 1 pending connection operation which will be aborted.
+     * - updating the last set of parameters while waiting for the pending
+     *   attempt to be aborted
+     * - internally connecting with the last set of parameters
+     */
+    protected pendingConnectionOptions: StoredConnectionOptions | null;
+    protected connectionMutex: Mutex;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
     constructor(options: PowerSyncDatabaseOptionsWithSettings);
@@ -183,12 +210,19 @@ 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.
      */
     init(): Promise<void>;
     resolvedConnectionOptions(options?: PowerSyncConnectionOptions): RequiredAdditionalConnectionOptions;
+    /**
+     * Locking mechanism for exclusively running critical portions of connect/disconnect operations.
+     * Locking here is mostly only important on web for multiple tab scenarios.
+     */
+    protected runExclusive<T>(callback: () => Promise<T>): Promise<T>;
+    protected connectInternal(): Promise<void>;
     /**
      * Connects to stream of events from the PowerSync instance.
      */
@@ -199,6 +233,8 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Use {@link connect} to connect again.
      */
     disconnect(): Promise<void>;
+    protected disconnectInternal(): Promise<void>;
+    protected performDisconnect(): Promise<void>;
     /**
      *  Disconnect and clear the database.
      *  Use this when logging out.
@@ -483,3 +519,4 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     private executeReadOnly;
 }
+export {};

package/lib/client/AbstractPowerSyncDatabase.js

@@ -2,12 +2,13 @@ import { Mutex } from 'async-mutex';
 import { EventIterator } from 'event-iterator';
 import Logger from 'js-logger';
 import { isBatchedUpdateNotification } from '../db/DBAdapter.js';
+import { FULL_SYNC_PRIORITY } from '../db/crud/SyncProgress.js';
 import { SyncStatus } from '../db/crud/SyncStatus.js';
 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/async.js';
+import { mutexRunExclusive } from '../utils/mutex.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
@@ -42,10 +43,6 @@ 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;
     /**
@@ -69,6 +66,29 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _isReadyPromise;
     _schema;
     _database;
+    /**
+     * Tracks active connection attempts
+     */
+    connectingPromise;
+    /**
+     * Tracks actively instantiating a streaming sync implementation.
+     */
+    syncStreamInitPromise;
+    /**
+     * Active disconnect operation. Calling disconnect multiple times
+     * will resolve to the same operation.
+     */
+    disconnectingPromise;
+    /**
+     * Tracks the last parameters supplied to `connect` calls.
+     * Calling `connect` multiple times in succession will result in:
+     * - 1 pending connection operation which will be aborted.
+     * - updating the last set of parameters while waiting for the pending
+     *   attempt to be aborted
+     * - internally connecting with the last set of parameters
+     */
+    pendingConnectionOptions;
+    connectionMutex;
     constructor(options) {
         super();
         this.options = options;
@@ -95,6 +115,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         this._schema = schema;
         this.ready = false;
         this.sdkVersion = '';
+        this.connectingPromise = null;
+        this.syncStreamInitPromise = null;
+        this.pendingConnectionOptions = null;
+        this.connectionMutex = new Mutex();
         // Start async init
         this._isReadyPromise = this.initialize();
     }
@@ -250,6 +274,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.
@@ -265,30 +292,100 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             crudUploadThrottleMs: options?.crudUploadThrottleMs ?? this.options.crudUploadThrottleMs ?? DEFAULT_CRUD_UPLOAD_THROTTLE_MS
         };
     }
+    /**
+     * Locking mechanism for exclusively running critical portions of connect/disconnect operations.
+     * Locking here is mostly only important on web for multiple tab scenarios.
+     */
+    runExclusive(callback) {
+        return this.connectionMutex.runExclusive(callback);
+    }
+    async connectInternal() {
+        let appliedOptions = null;
+        // This method ensures a disconnect before any connection attempt
+        await this.disconnectInternal();
+        /**
+         * This portion creates a sync implementation which can be racy when disconnecting or
+         * if multiple tabs on web are in use.
+         * This is protected in an exclusive lock.
+         * The promise tracks the creation which is used to synchronize disconnect attempts.
+         */
+        this.syncStreamInitPromise = this.runExclusive(async () => {
+            if (this.closed) {
+                throw new Error('Cannot connect using a closed client');
+            }
+            // Always await this if present since we will be populating a new sync implementation shortly
+            await this.disconnectingPromise;
+            if (!this.pendingConnectionOptions) {
+                // A disconnect could have cleared this.
+                return;
+            }
+            // get pending options and clear it in order for other connect attempts to queue other options
+            const { connector, options } = this.pendingConnectionOptions;
+            appliedOptions = options;
+            this.pendingConnectionOptions = null;
+            this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, this.resolvedConnectionOptions(options));
+            this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
+                statusChanged: (status) => {
+                    this.currentStatus = new SyncStatus({
+                        ...status.toJSON(),
+                        hasSynced: this.currentStatus?.hasSynced || !!status.lastSyncedAt
+                    });
+                    this.iterateListeners((cb) => cb.statusChanged?.(this.currentStatus));
+                }
+            });
+            await this.syncStreamImplementation.waitForReady();
+        });
+        await this.syncStreamInitPromise;
+        this.syncStreamInitPromise = null;
+        if (!appliedOptions) {
+            // A disconnect could have cleared the options which did not create a syncStreamImplementation
+            return;
+        }
+        // It might be possible that a disconnect triggered between the last check
+        // and this point. Awaiting here allows the sync stream to be cleared if disconnected.
+        await this.disconnectingPromise;
+        this.syncStreamImplementation?.triggerCrudUpload();
+        this.options.logger?.debug('Attempting to connect to PowerSync instance');
+        await this.syncStreamImplementation?.connect(appliedOptions);
+    }
     /**
      * Connects to stream of events from the PowerSync instance.
      */
     async connect(connector, options) {
+        // Keep track if there were pending operations before this call
+        const hadPendingOptions = !!this.pendingConnectionOptions;
+        // Update pending options to the latest values
+        this.pendingConnectionOptions = {
+            connector,
+            options: options ?? {}
+        };
         await this.waitForReady();
-        // close connection if one is open
-        await this.disconnect();
-        if (this.closed) {
-            throw new Error('Cannot connect using a closed client');
+        // Disconnecting here provides aborting in progress connection attempts.
+        // The connectInternal method will clear pending options once it starts connecting (with the options).
+        // We only need to trigger a disconnect here if we have already reached the point of connecting.
+        // If we do already have pending options, a disconnect has already been performed.
+        // The connectInternal method also does a sanity disconnect to prevent straggler connections.
+        if (!hadPendingOptions) {
+            await this.disconnectInternal();
         }
-        const resolvedConnectOptions = this.resolvedConnectionOptions(options);
-        this.syncStreamImplementation = this.generateSyncStreamImplementation(connector, resolvedConnectOptions);
-        this.syncStatusListenerDisposer = this.syncStreamImplementation.registerListener({
-            statusChanged: (status) => {
-                this.currentStatus = new SyncStatus({
-                    ...status.toJSON(),
-                    hasSynced: this.currentStatus?.hasSynced || !!status.lastSyncedAt
-                });
-                this.iterateListeners((cb) => cb.statusChanged?.(this.currentStatus));
+        // Triggers a connect which checks if pending options are available after the connect completes.
+        // The completion can be for a successful, unsuccessful or aborted connection attempt.
+        // If pending options are available another connection will be triggered.
+        const checkConnection = async () => {
+            if (this.pendingConnectionOptions) {
+                // Pending options have been placed while connecting.
+                // Need to reconnect.
+                this.connectingPromise = this.connectInternal().finally(checkConnection);
+                return this.connectingPromise;
             }
-        });
-        await this.syncStreamImplementation.waitForReady();
-        this.syncStreamImplementation.triggerCrudUpload();
-        await this.syncStreamImplementation.connect(options);
+            else {
+                // Clear the connecting promise, done.
+                this.connectingPromise = null;
+                return;
+            }
+        };
+        this.connectingPromise ??= this.connectInternal().finally(checkConnection);
+        return this.connectingPromise;
     }
     /**
      * Close the sync connection.
@@ -297,6 +394,23 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async disconnect() {
         await this.waitForReady();
+        // This will help abort pending connects
+        this.pendingConnectionOptions = null;
+        await this.disconnectInternal();
+    }
+    async disconnectInternal() {
+        if (this.disconnectingPromise) {
+            // A disconnect is already in progress
+            return this.disconnectingPromise;
+        }
+        // Wait if a sync stream implementation is being created before closing it
+        // (syncStreamImplementation must be assigned before we can properly dispose it)
+        await this.syncStreamInitPromise;
+        this.disconnectingPromise = this.performDisconnect();
+        await this.disconnectingPromise;
+        this.disconnectingPromise = null;
+    }
+    async performDisconnect() {
         await this.syncStreamImplementation?.disconnect();
         this.syncStatusListenerDisposer?.();
         await this.syncStreamImplementation?.dispose();

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

@@ -27,6 +27,11 @@ export interface SyncLocalDatabaseResult {
     checkpointValid: boolean;
     checkpointFailures?: string[];
 }
+export type SavedProgress = {
+    atLast: number;
+    sinceLast: number;
+};
+export type BucketOperationProgress = Record<string, SavedProgress>;
 export interface BucketChecksum {
     bucket: string;
     priority?: number;
@@ -56,6 +61,7 @@ export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
+    getBucketOperationProgress(): Promise<BucketOperationProgress>;
     syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<{
         checkpointValid: boolean;
         ready: boolean;

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

@@ -51,6 +51,11 @@ export declare class CrudEntry {
      * Data associated with the change.
      */
     opData?: Record<string, any>;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues?: Record<string, any>;
     /**
      * Table that contained the change.
      */
@@ -59,8 +64,15 @@ export declare class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId?: number;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata?: string;
     static fromRow(dbRow: CrudEntryJSON): CrudEntry;
-    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>);
+    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>, previousValues?: Record<string, any>, metadata?: string);
     /**
      * Converts the change to JSON format.
      */

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

@@ -30,6 +30,11 @@ export class CrudEntry {
      * Data associated with the change.
      */
     opData;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues;
     /**
      * Table that contained the change.
      */
@@ -38,17 +43,26 @@ export class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata;
     static fromRow(dbRow) {
         const data = JSON.parse(dbRow.data);
-        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data);
+        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data, data.old, data.metadata);
     }
-    constructor(clientId, op, table, id, transactionId, opData) {
+    constructor(clientId, op, table, id, transactionId, opData, previousValues, metadata) {
         this.clientId = clientId;
         this.id = id;
         this.op = op;
         this.opData = opData;
         this.table = table;
         this.transactionId = transactionId;
+        this.previousValues = previousValues;
+        this.metadata = metadata;
     }
     /**
      * Converts the change to JSON format.

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

@@ -2,7 +2,7 @@ import { Mutex } from 'async-mutex';
 import { ILogger } from 'js-logger';
 import { DBAdapter, Transaction } from '../../../db/DBAdapter.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
-import { BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
+import { BucketOperationProgress, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -30,6 +30,7 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
      */
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
+    getBucketOperationProgress(): Promise<BucketOperationProgress>;
     saveSyncData(batch: SyncDataBatch): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;
     /**

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

@@ -66,6 +66,10 @@ export class SqliteBucketStorage extends BaseObserver {
         const result = await this.db.getAll("SELECT name as bucket, cast(last_op as TEXT) as op_id FROM ps_buckets WHERE pending_delete = 0 AND name != '$local'");
         return result;
     }
+    async getBucketOperationProgress() {
+        const rows = await this.db.getAll('SELECT name, count_at_last, count_since_last FROM ps_buckets');
+        return Object.fromEntries(rows.map((r) => [r.name, { atLast: r.count_at_last, sinceLast: r.count_since_last }]));
+    }
     async saveSyncData(batch) {
         await this.writeTransaction(async (tx) => {
             let count = 0;
@@ -115,9 +119,9 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        const buckets = checkpoint.buckets;
+        let buckets = checkpoint.buckets;
         if (priority !== undefined) {
-            buckets.filter((b) => hasMatchingPriority(priority, b));
+            buckets = buckets.filter((b) => hasMatchingPriority(priority, b));
         }
         const bucketNames = buckets.map((b) => b.bucket);
         await this.writeTransaction(async (tx) => {
@@ -161,7 +165,18 @@ export class SqliteBucketStorage extends BaseObserver {
                 'sync_local',
                 arg
             ]);
-            return result == 1;
+            if (result == 1) {
+                if (priority == null) {
+                    const bucketToCount = Object.fromEntries(checkpoint.buckets.map((b) => [b.bucket, b.count]));
+                    // The two parameters could be replaced with one, but: https://github.com/powersync-ja/better-sqlite3/pull/6
+                    const jsonBucketCount = JSON.stringify(bucketToCount);
+                    await tx.execute("UPDATE ps_buckets SET count_since_last = 0, count_at_last = ?->name WHERE name != '$local' AND ?->name IS NOT NULL", [jsonBucketCount, jsonBucketCount]);
+                }
+                return true;
+            }
+            else {
+                return false;
+            }
         });
     }
     async validateChecksums(checkpoint, priority) {

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

@@ -7,6 +7,7 @@ import { StreamingSyncLine, StreamingSyncRequest } from './streaming-sync-types.
 export type BSONImplementation = typeof BSON;
 export type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
+    invalidateCredentials?: () => void;
 };
 export declare const DEFAULT_REMOTE_LOGGER: Logger.ILogger;
 export type SyncStreamOptions = {
@@ -74,7 +75,35 @@ export declare abstract class AbstractRemote {
      * which can be called to perform fetch requests
      */
     get fetch(): FetchImplementation;
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     getCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    prefetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    fetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials(): void;
     getUserAgent(): string;
     protected buildRequest(path: string): Promise<{
         url: string;

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

@@ -8,8 +8,6 @@ import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { DataStream } from '../../../utils/DataStream.js';
 const POWERSYNC_TRAILING_SLASH_MATCH = /\/+$/;
 const POWERSYNC_JS_VERSION = PACKAGE.version;
-// Refresh at least 30 sec before it expires
-const REFRESH_CREDENTIALS_SAFETY_PERIOD_MS = 30_000;
 const SYNC_QUEUE_REQUEST_LOW_WATER = 5;
 // Keep alive message is sent every period
 const KEEP_ALIVE_MS = 20_000;
@@ -70,17 +68,52 @@ export class AbstractRemote {
             ? fetchImplementation.getFetch()
             : fetchImplementation;
     }
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     async getCredentials() {
-        const { expiresAt } = this.credentials ?? {};
-        if (expiresAt && expiresAt > new Date(new Date().valueOf() + REFRESH_CREDENTIALS_SAFETY_PERIOD_MS)) {
+        if (this.credentials) {
             return this.credentials;
         }
-        this.credentials = await this.connector.fetchCredentials();
-        if (this.credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
-            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${this.credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
-        }
+        return this.prefetchCredentials();
+    }
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    async prefetchCredentials() {
+        this.credentials = await this.fetchCredentials();
         return this.credentials;
     }
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    async fetchCredentials() {
+        const credentials = await this.connector.fetchCredentials();
+        if (credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
+            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
+        }
+        return credentials;
+    }
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials() {
+        this.credentials = null;
+        this.connector.invalidateCredentials?.();
+    }
     getUserAgent() {
         return `powersync-js/${POWERSYNC_JS_VERSION}`;
     }
@@ -114,6 +147,9 @@ export class AbstractRemote {
             },
             body: JSON.stringify(data)
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when posting to ${path}: ${await res.text()}}`);
         }
@@ -128,6 +164,9 @@ export class AbstractRemote {
                 ...request.headers
             }
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when getting from ${path}: ${await res.text()}}`);
         }
@@ -145,6 +184,9 @@ export class AbstractRemote {
             this.logger.error(`Caught ex when POST streaming to ${path}`, ex);
             throw ex;
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             const text = await res.text();
             this.logger.error(`Could not POST streaming to ${path} - ${res.status} - ${res.statusText}: ${text}`);
@@ -169,10 +211,18 @@ export class AbstractRemote {
         // headers with websockets on web. The browser userAgent is however added
         // automatically as a header.
         const userAgent = this.getUserAgent();
+        let socketCreationError;
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url: this.options.socketUrlTransformer(request.url),
-                wsCreator: (url) => this.createSocket(url)
+                wsCreator: (url) => {
+                    const s = this.createSocket(url);
+                    s.addEventListener('error', (e) => {
+                        socketCreationError = new Error('Failed to create connection to websocket: ', e.target.url ?? '');
+                        this.logger.warn('Socket error', e);
+                    });
+                    return s;
+                }
             }),
             setup: {
                 keepAlive: KEEP_ALIVE_MS,
@@ -197,7 +247,7 @@ export class AbstractRemote {
              * On React native the connection exception can be `undefined` this causes issues
              * with detecting the exception inside async-mutex
              */
-            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex)}`);
+            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex ?? socketCreationError)}`);
         }
         const stream = new DataStream({
             logger: this.logger,
@@ -233,6 +283,17 @@ export class AbstractRemote {
             }, syncQueueRequestSize, // The initial N amount
             {
                 onError: (e) => {
+                    if (e.message.includes('PSYNC_')) {
+                        if (e.message.includes('PSYNC_S21')) {
+                            this.invalidateCredentials();
+                        }
+                    }
+                    else {
+                        // Possible that connection is with an older service, always invalidate to be safe
+                        if (e.message !== 'Closed. ') {
+                            this.invalidateCredentials();
+                        }
+                    }
                     // Don't log closed as an error
                     if (e.message !== 'Closed. ') {
                         this.logger.error(e);

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

@@ -139,6 +139,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
     private collectLocalBucketState;
     protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private updateSyncStatusForStartingCheckpoint;
     private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;
     private delayRetry;