@powersync/common 1.33.2 → 1.34.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -1,5 +1,5 @@
 import { Mutex } from 'async-mutex';
-import Logger, { ILogger } from 'js-logger';
+import { ILogger } from 'js-logger';
 import { DBAdapter, QueryResult, Transaction } from '../db/DBAdapter.js';
 import { SyncStatus } from '../db/crud/SyncStatus.js';
 import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
@@ -84,7 +84,6 @@ export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
 export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
-    logger: Logger.ILogger;
     crudUploadThrottleMs: number;
 };
 export declare const DEFAULT_CRUD_BATCH_LIMIT = 100;
@@ -101,11 +100,6 @@ export declare const DEFAULT_LOCK_TIMEOUT_MS = 120000;
 export declare const isPowerSyncDatabaseOptionsWithSettings: (test: any) => test is PowerSyncDatabaseOptionsWithSettings;
 export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncDBListener> {
     protected options: PowerSyncDatabaseOptions;
-    /**
-     * Transactions should be queued in the DBAdapter, but we also want to prevent
-     * calls to `.execute` while an async transaction is running.
-     */
-    protected static transactionMutex: Mutex;
     /**
      * Returns true if the connection is closed.
      */
@@ -123,6 +117,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected _schema: Schema;
     private _database;
     protected runExclusiveMutex: Mutex;
+    logger: ILogger;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
     constructor(options: PowerSyncDatabaseOptionsWithSettings);
@@ -185,7 +180,6 @@ 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.

package/lib/client/AbstractPowerSyncDatabase.js

@@ -8,7 +8,6 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { throttleTrailing } from '../utils/async.js';
-import { mutexRunExclusive } from '../utils/mutex.js';
 import { ConnectionManager } from './ConnectionManager.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
@@ -27,7 +26,6 @@ export const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
 export const DEFAULT_WATCH_THROTTLE_MS = 30;
 export const DEFAULT_POWERSYNC_DB_OPTIONS = {
     retryDelayMs: 5000,
-    logger: Logger.get('PowerSyncDatabase'),
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_CRUD_BATCH_LIMIT = 100;
@@ -46,11 +44,6 @@ export const isPowerSyncDatabaseOptionsWithSettings = (test) => {
 };
 export class AbstractPowerSyncDatabase extends BaseObserver {
     options;
-    /**
-     * Transactions should be queued in the DBAdapter, but we also want to prevent
-     * calls to `.execute` while an async transaction is running.
-     */
-    static transactionMutex = new Mutex();
     /**
      * Returns true if the connection is closed.
      */
@@ -70,6 +63,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _schema;
     _database;
     runExclusiveMutex;
+    logger;
     constructor(options) {
         super();
         this.options = options;
@@ -89,6 +83,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         else {
             throw new Error('The provided `database` option is invalid.');
         }
+        this.logger = options.logger ?? Logger.get(`PowerSyncDatabase[${this._database.name}]`);
         this.bucketStorageAdapter = this.generateBucketStorageAdapter();
         this.closed = false;
         this.currentStatus = new SyncStatus({});
@@ -268,16 +263,13 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             schema.validate();
         }
         catch (ex) {
-            this.options.logger?.warn('Schema validation failed. Unexpected behaviour could occur', ex);
+            this.logger.warn('Schema validation failed. Unexpected behaviour could occur', ex);
         }
         this._schema = schema;
         await this.database.execute('SELECT powersync_replace_schema(?)', [JSON.stringify(this.schema.toJSON())]);
         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.
@@ -304,7 +296,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Connects to stream of events from the PowerSync instance.
      */
     async connect(connector, options) {
-        return this.connectionManager.connect(connector, options);
+        const resolvedOptions = options ?? {};
+        resolvedOptions.serializedSchema = this.schema.toJSON();
+        return this.connectionManager.connect(connector, resolvedOptions);
     }
     /**
      * Close the sync connection.
@@ -477,8 +471,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @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);
+        return this.writeLock((tx) => tx.execute(sql, parameters));
     }
     /**
      * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
@@ -546,7 +539,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async readLock(callback) {
         await this.waitForReady();
-        return mutexRunExclusive(AbstractPowerSyncDatabase.transactionMutex, () => callback(this.database));
+        return this.database.readLock(callback);
     }
     /**
      * Takes a global lock, without starting a transaction.
@@ -554,10 +547,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      */
     async writeLock(callback) {
         await this.waitForReady();
-        return mutexRunExclusive(AbstractPowerSyncDatabase.transactionMutex, async () => {
-            const res = await callback(this.database);
-            return res;
-        });
+        return this.database.writeLock(callback);
     }
     /**
      * Open a read-only transaction.
@@ -617,7 +607,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @param options Options for configuring watch behavior
      */
     watchWithCallback(sql, parameters, handler, options) {
-        const { onResult, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
+        const { onResult, onError = (e) => this.logger.error(e) } = handler ?? {};
         if (!onResult) {
             throw new Error('onResult is required');
         }
@@ -723,7 +713,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @returns A dispose function to stop watching for changes
      */
     onChangeWithCallback(handler, options) {
-        const { onChange, onError = (e) => this.options.logger?.error(e) } = handler ?? {};
+        const { onChange, onError = (e) => this.logger.error(e) } = handler ?? {};
         if (!onChange) {
             throw new Error('onChange is required');
         }

package/lib/client/ConnectionManager.d.ts

@@ -1,7 +1,7 @@
 import { ILogger } from 'js-logger';
 import { BaseListener, BaseObserver } from '../utils/BaseObserver.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
-import { PowerSyncConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { InternalConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
 /**
  * @internal
  */
@@ -17,12 +17,12 @@ export interface ConnectionManagerSyncImplementationResult {
  * @internal
  */
 export interface ConnectionManagerOptions {
-    createSyncImplementation(connector: PowerSyncBackendConnector, options: PowerSyncConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
+    createSyncImplementation(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
     logger: ILogger;
 }
 type StoredConnectionOptions = {
     connector: PowerSyncBackendConnector;
-    options: PowerSyncConnectionOptions;
+    options: InternalConnectionOptions;
 };
 /**
  * @internal
@@ -66,7 +66,7 @@ export declare class ConnectionManager extends BaseObserver<ConnectionManagerLis
     constructor(options: ConnectionManagerOptions);
     get logger(): ILogger;
     close(): Promise<void>;
-    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<void>;
     protected connectInternal(): Promise<void>;
     /**
      * Close the sync connection.

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

@@ -1,4 +1,3 @@
-import { Mutex } from 'async-mutex';
 import { ILogger } from 'js-logger';
 import { DBAdapter, Transaction } from '../../../db/DBAdapter.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
@@ -8,13 +7,12 @@ import { CrudEntry } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
 export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListener> implements BucketStorageAdapter {
     private db;
-    private mutex;
     private logger;
     tableNames: Set<string>;
     private _hasCompletedSync;
     private updateListener;
     private _clientId?;
-    constructor(db: DBAdapter, mutex: Mutex, logger?: ILogger);
+    constructor(db: DBAdapter, logger?: ILogger);
     init(): Promise<void>;
     dispose(): Promise<void>;
     _getClientId(): Promise<string>;

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

@@ -6,16 +6,14 @@ import { PSInternalTable } from './BucketStorageAdapter.js';
 import { CrudEntry } from './CrudEntry.js';
 export class SqliteBucketStorage extends BaseObserver {
     db;
-    mutex;
     logger;
     tableNames;
     _hasCompletedSync;
     updateListener;
     _clientId;
-    constructor(db, mutex, logger = Logger.get('SqliteBucketStorage')) {
+    constructor(db, logger = Logger.get('SqliteBucketStorage')) {
         super();
         this.db = db;
-        this.mutex = mutex;
         this.logger = logger;
         this._hasCompletedSync = false;
         this.tableNames = new Set();
@@ -66,11 +64,11 @@ export class SqliteBucketStorage extends BaseObserver {
     async saveSyncData(batch, fixedKeyFormat = false) {
         await this.writeTransaction(async (tx) => {
             for (const b of batch.buckets) {
-                const result = await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
+                await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
                     'save',
                     JSON.stringify({ buckets: [b.toJSON(fixedKeyFormat)] })
                 ]);
-                this.logger.debug('saveSyncData', JSON.stringify(result));
+                this.logger.debug(`Saved batch of data for  bucket: ${b.bucket}, operations: ${b.data.length}`);
             }
         });
     }
@@ -86,7 +84,7 @@ export class SqliteBucketStorage extends BaseObserver {
         await this.writeTransaction(async (tx) => {
             await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', ['delete_bucket', bucket]);
         });
-        this.logger.debug('done deleting bucket');
+        this.logger.debug(`Done deleting bucket ${bucket}`);
     }
     async hasCompletedSync() {
         if (this._hasCompletedSync) {
@@ -108,6 +106,12 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
+        if (priority == null) {
+            this.logger.debug(`Validated checksums checkpoint ${checkpoint.last_op_id}`);
+        }
+        else {
+            this.logger.debug(`Validated checksums for partial checkpoint ${checkpoint.last_op_id}, priority ${priority}`);
+        }
         let buckets = checkpoint.buckets;
         if (priority !== undefined) {
             buckets = buckets.filter((b) => hasMatchingPriority(priority, b));
@@ -124,7 +128,6 @@ export class SqliteBucketStorage extends BaseObserver {
         });
         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 };
         }
         return {
@@ -177,7 +180,6 @@ export class SqliteBucketStorage extends BaseObserver {
             JSON.stringify({ ...checkpoint })
         ]);
         const resultItem = rs.rows?.item(0);
-        this.logger.debug('validateChecksums priority, checkpoint, result item', priority, checkpoint, resultItem);
         if (!resultItem) {
             return {
                 checkpointValid: false,
@@ -210,30 +212,26 @@ export class SqliteBucketStorage extends BaseObserver {
         }
         const seqBefore = rs[0]['seq'];
         const opId = await cb();
-        this.logger.debug(`[updateLocalTarget] Updating target to checkpoint ${opId}`);
         return this.writeTransaction(async (tx) => {
             const anyData = await tx.execute('SELECT 1 FROM ps_crud LIMIT 1');
             if (anyData.rows?.length) {
                 // if isNotEmpty
-                this.logger.debug('updateLocalTarget', 'ps crud is not empty');
+                this.logger.debug(`New data uploaded since write checkpoint ${opId} - need new write checkpoint`);
                 return false;
             }
             const rs = await tx.execute("SELECT seq FROM sqlite_sequence WHERE name = 'ps_crud'");
             if (!rs.rows?.length) {
                 // assert isNotEmpty
-                throw new Error('SQlite Sequence should not be empty');
+                throw new Error('SQLite Sequence should not be empty');
             }
             const seqAfter = rs.rows?.item(0)['seq'];
-            this.logger.debug('seqAfter', JSON.stringify(rs.rows?.item(0)));
             if (seqAfter != seqBefore) {
-                this.logger.debug('seqAfter != seqBefore', seqAfter, seqBefore);
+                this.logger.debug(`New data uploaded since write checpoint ${opId} - need new write checkpoint (sequence updated)`);
                 // New crud data may have been uploaded since we got the checkpoint. Abort.
                 return false;
             }
-            const response = await tx.execute("UPDATE ps_buckets SET target_op = CAST(? as INTEGER) WHERE name='$local'", [
-                opId
-            ]);
-            this.logger.debug(['[updateLocalTarget] Response from updating target_op ', JSON.stringify(response)]);
+            this.logger.debug(`Updating target write checkpoint to ${opId}`);
+            await tx.execute("UPDATE ps_buckets SET target_op = CAST(? as INTEGER) WHERE name='$local'", [opId]);
             return true;
         });
     }

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

@@ -3,7 +3,7 @@ import { type fetch } from 'cross-fetch';
 import Logger, { ILogger } from 'js-logger';
 import { DataStream } from '../../../utils/DataStream.js';
 import { PowerSyncCredentials } from '../../connection/PowerSyncCredentials.js';
-import { StreamingSyncLine, StreamingSyncRequest } from './streaming-sync-types.js';
+import { StreamingSyncRequest } from './streaming-sync-types.js';
 export type BSONImplementation = typeof BSON;
 export type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
@@ -120,11 +120,6 @@ export declare abstract class AbstractRemote {
      */
     abstract getBSON(): Promise<BSONImplementation>;
     protected createSocket(url: string): WebSocket;
-    /**
-     * Connects to the sync/stream websocket endpoint and delivers sync lines by decoding the BSON events
-     * sent by the server.
-     */
-    socketStream(options: SocketSyncStreamOptions): Promise<DataStream<StreamingSyncLine>>;
     /**
      * Returns a data stream of sync line data.
      *
@@ -133,10 +128,6 @@ export declare abstract class AbstractRemote {
      * (required for compatibility with older sync services).
      */
     socketStreamRaw<T>(options: SocketSyncStreamOptions, map: (buffer: Uint8Array) => T, bson?: typeof BSON): Promise<DataStream<T>>;
-    /**
-     * Connects to the sync/stream http endpoint, parsing lines as JSON.
-     */
-    postStream(options: SyncStreamOptions): Promise<DataStream<StreamingSyncLine>>;
     /**
      * Connects to the sync/stream http endpoint, mapping and emitting each received string line.
      */

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

@@ -178,14 +178,6 @@ export class AbstractRemote {
     createSocket(url) {
         return new WebSocket(url);
     }
-    /**
-     * Connects to the sync/stream websocket endpoint and delivers sync lines by decoding the BSON events
-     * sent by the server.
-     */
-    async socketStream(options) {
-        const bson = await this.getBSON();
-        return await this.socketStreamRaw(options, (data) => bson.deserialize(data), bson);
-    }
     /**
      * Returns a data stream of sync line data.
      *
@@ -363,14 +355,6 @@ export class AbstractRemote {
         }
         return stream;
     }
-    /**
-     * Connects to the sync/stream http endpoint, parsing lines as JSON.
-     */
-    async postStream(options) {
-        return await this.postStreamRaw(options, (line) => {
-            return JSON.parse(line);
-        });
-    }
     /**
      * Connects to the sync/stream http endpoint, mapping and emitting each received string line.
      */

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

@@ -1,4 +1,4 @@
-import Logger, { ILogger } from 'js-logger';
+import { ILogger } from 'js-logger';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js';
 import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter.js';
@@ -88,7 +88,8 @@ export interface StreamingSyncImplementationListener extends BaseListener {
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
  */
-export interface PowerSyncConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
+export type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, 'serializedSchema'>;
+export interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
 }
 /** @internal */
 export interface BaseConnectionOptions {
@@ -114,6 +115,10 @@ export interface BaseConnectionOptions {
      * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
      */
     params?: Record<string, StreamingSyncRequestParameterType>;
+    /**
+     * The serialized schema - mainly used to forward information about raw tables to the sync client.
+     */
+    serializedSchema?: any;
 }
 /** @internal */
 export interface AdditionalConnectionOptions {
@@ -135,7 +140,7 @@ export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncI
     /**
      * Connects to the sync service
      */
-    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(options?: InternalConnectionOptions): Promise<void>;
     /**
      * Disconnects from the sync services.
      * @throws if not connected or if abort is not controlled internally
@@ -155,7 +160,6 @@ export declare const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 export declare const DEFAULT_RETRY_DELAY_MS = 5000;
 export declare const DEFAULT_STREAMING_SYNC_OPTIONS: {
     retryDelayMs: number;
-    logger: Logger.ILogger;
     crudUploadThrottleMs: number;
 };
 export type RequiredPowerSyncConnectionOptions = Required<BaseConnectionOptions>;
@@ -166,7 +170,8 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected abortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
-    private pendingCrudUpload?;
+    protected logger: ILogger;
+    private isUploadingCrud;
     private notifyCompletedUploads?;
     syncStatus: SyncStatus;
     triggerCrudUpload: () => void;
@@ -176,7 +181,6 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     waitUntilStatusMatches(predicate: (status: SyncStatus) => boolean): Promise<void>;
     get lastSyncedAt(): Date | undefined;
     get isConnected(): boolean;
-    protected get logger(): Logger.ILogger;
     dispose(): Promise<void>;
     abstract obtainLock<T>(lockOptions: LockOptions<T>): Promise<T>;
     hasCompletedSync(): Promise<boolean>;