@powersync/common 0.0.0-dev-20250715111940 → 0.0.0-dev-20250728083821

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;
@@ -118,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);
@@ -180,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

@@ -26,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;
@@ -64,6 +63,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _schema;
     _database;
     runExclusiveMutex;
+    logger;
     constructor(options) {
         super();
         this.options = options;
@@ -83,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({});
@@ -262,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.
@@ -609,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');
         }
@@ -715,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/sync/bucket/SqliteBucketStorage.js

@@ -64,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}`);
             }
         });
     }
@@ -84,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) {
@@ -106,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));
@@ -122,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 {
@@ -175,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,
@@ -208,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.js

@@ -204,6 +204,22 @@ export class AbstractRemote {
         // headers with websockets on web. The browser userAgent is however added
         // automatically as a header.
         const userAgent = this.getUserAgent();
+        const stream = new DataStream({
+            logger: this.logger,
+            pressure: {
+                lowWaterMark: SYNC_QUEUE_REQUEST_LOW_WATER
+            },
+            mapLine: map
+        });
+        // Handle upstream abort
+        if (options.abortSignal?.aborted) {
+            throw new AbortOperation('Connection request aborted');
+        }
+        else {
+            options.abortSignal?.addEventListener('abort', () => {
+                stream.close();
+            }, { once: true });
+        }
         let keepAliveTimeout;
         const resetTimeout = () => {
             clearTimeout(keepAliveTimeout);
@@ -213,12 +229,22 @@ export class AbstractRemote {
             }, SOCKET_TIMEOUT_MS);
         };
         resetTimeout();
+        // Typescript complains about this being `never` if it's not assigned here.
+        // This is assigned in `wsCreator`.
+        let disposeSocketConnectionTimeout = () => { };
         const url = this.options.socketUrlTransformer(request.url);
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url,
                 wsCreator: (url) => {
                     const socket = this.createSocket(url);
+                    disposeSocketConnectionTimeout = stream.registerListener({
+                        closed: () => {
+                            // Allow closing the underlying WebSocket if the stream was closed before the
+                            // RSocket connect completed. This should effectively abort the request.
+                            socket.close();
+                        }
+                    });
                     socket.addEventListener('message', (event) => {
                         resetTimeout();
                     });
@@ -242,20 +268,18 @@ export class AbstractRemote {
         let rsocket;
         try {
             rsocket = await connector.connect();
+            // The connection is established, we no longer need to monitor the initial timeout
+            disposeSocketConnectionTimeout();
         }
         catch (ex) {
             this.logger.error(`Failed to connect WebSocket`, ex);
             clearTimeout(keepAliveTimeout);
+            if (!stream.closed) {
+                await stream.close();
+            }
             throw ex;
         }
         resetTimeout();
-        const stream = new DataStream({
-            logger: this.logger,
-            pressure: {
-                lowWaterMark: SYNC_QUEUE_REQUEST_LOW_WATER
-            },
-            mapLine: map
-        });
         let socketIsClosed = false;
         const closeSocket = () => {
             clearTimeout(keepAliveTimeout);
@@ -341,18 +365,6 @@ export class AbstractRemote {
                 l();
             }
         });
-        /**
-         * Handle abort operations here.
-         * Unfortunately cannot insert them into the connection.
-         */
-        if (options.abortSignal?.aborted) {
-            stream.close();
-        }
-        else {
-            options.abortSignal?.addEventListener('abort', () => {
-                stream.close();
-            });
-        }
         return stream;
     }
     /**

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';
@@ -160,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>;
@@ -171,6 +170,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected abortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
+    protected logger: ILogger;
     private isUploadingCrud;
     private notifyCompletedUploads?;
     syncStatus: SyncStatus;
@@ -181,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>;

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

@@ -65,7 +65,6 @@ export const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 export const DEFAULT_RETRY_DELAY_MS = 5000;
 export const DEFAULT_STREAMING_SYNC_OPTIONS = {
     retryDelayMs: DEFAULT_RETRY_DELAY_MS,
-    logger: Logger.get('PowerSyncStream'),
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
 };
 export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
@@ -86,6 +85,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     abortController;
     crudUpdateListener;
     streamingSyncPromise;
+    logger;
     isUploadingCrud = false;
     notifyCompletedUploads;
     syncStatus;
@@ -93,6 +93,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     constructor(options) {
         super();
         this.options = { ...DEFAULT_STREAMING_SYNC_OPTIONS, ...options };
+        this.logger = options.logger ?? Logger.get('PowerSyncStream');
         this.syncStatus = new SyncStatus({
             connected: false,
             connecting: false,
@@ -156,9 +157,6 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     get isConnected() {
         return this.syncStatus.connected;
     }
-    get logger() {
-        return this.options.logger;
-    }
     async dispose() {
         this.crudUpdateListener?.();
         this.crudUpdateListener = undefined;
@@ -170,7 +168,9 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         const clientId = await this.options.adapter.getClientId();
         let path = `/write-checkpoint2.json?client_id=${clientId}`;
         const response = await this.options.remote.get(path);
-        return response['data']['write_checkpoint'];
+        const checkpoint = response['data']['write_checkpoint'];
+        this.logger.debug(`Created write checkpoint: ${checkpoint}`);
+        return checkpoint;
     }
     async _uploadAllCrud() {
         return this.obtainLock({
@@ -209,7 +209,11 @@ The next upload iteration will be delayed.`);
                         }
                         else {
                             // Uploading is completed
-                            await this.options.adapter.updateLocalTarget(() => this.getWriteCheckpoint());
+                            const neededUpdate = await this.options.adapter.updateLocalTarget(() => this.getWriteCheckpoint());
+                            if (neededUpdate == false && checkedCrudItem != null) {
+                                // Only log this if there was something to upload
+                                this.logger.debug('Upload complete, no write checkpoint needed.');
+                            }
                             break;
                         }
                     }
@@ -435,6 +439,10 @@ The next upload iteration will be delayed.`);
         });
     }
     async legacyStreamingSyncIteration(signal, resolvedOptions) {
+        const rawTables = resolvedOptions.serializedSchema?.raw_tables;
+        if (rawTables != null && rawTables.length) {
+            this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
+        }
         this.logger.debug('Streaming sync iteration started');
         this.options.adapter.startSession();
         let [req, bucketMap] = await this.collectLocalBucketState();
@@ -882,17 +890,17 @@ The next upload iteration will be delayed.`);
     async applyCheckpoint(checkpoint) {
         let result = await this.options.adapter.syncLocalDatabase(checkpoint);
         if (!result.checkpointValid) {
-            this.logger.debug('Checksum mismatch in checkpoint, will reconnect');
+            this.logger.debug(`Checksum mismatch in checkpoint ${checkpoint.last_op_id}, will reconnect`);
             // This means checksums failed. Start again with a new checkpoint.
             // TODO: better back-off
             await new Promise((resolve) => setTimeout(resolve, 50));
             return { applied: false, endIteration: true };
         }
         else if (!result.ready) {
-            this.logger.debug('Could not apply checkpoint due to local data. We will retry applying the checkpoint after that upload is completed.');
+            this.logger.debug(`Could not apply checkpoint ${checkpoint.last_op_id} due to local data. We will retry applying the checkpoint after that upload is completed.`);
             return { applied: false, endIteration: false };
         }
-        this.logger.debug('validated checkpoint', checkpoint);
+        this.logger.debug(`Applied checkpoint ${checkpoint.last_op_id}`, checkpoint);
         this.updateSyncStatus({
             connected: true,
             lastSyncedAt: new Date(),

package/lib/db/schema/RawTable.d.ts

@@ -37,6 +37,10 @@ export type PendingStatement = {
  * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
  * using client-side table and column constraints.
  *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
  * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
  *
  * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or

package/lib/db/schema/RawTable.js

@@ -4,6 +4,10 @@
  * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
  * using client-side table and column constraints.
  *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
  * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
  *
  * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "0.0.0-dev-20250715111940",
+  "version": "0.0.0-dev-20250728083821",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"