@powersync/common 1.31.1 → 1.33.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -5,6 +5,7 @@ import { SyncStatus } from '../db/crud/SyncStatus.js';
 import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
+import { ConnectionManager } from './ConnectionManager.js';
 import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
@@ -114,13 +115,14 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * Current connection status.
      */
     currentStatus: SyncStatus;
-    syncStreamImplementation?: StreamingSyncImplementation;
     sdkVersion: string;
     protected bucketStorageAdapter: BucketStorageAdapter;
-    private syncStatusListenerDisposer?;
     protected _isReadyPromise: Promise<void>;
+    protected connectionManager: ConnectionManager;
+    get syncStreamImplementation(): StreamingSyncImplementation | null;
     protected _schema: Schema;
     private _database;
+    protected runExclusiveMutex: Mutex;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
     constructor(options: PowerSyncDatabaseOptionsWithSettings);
@@ -190,6 +192,11 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      */
     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>;
     /**
      * Connects to stream of events from the PowerSync instance.
      */

package/lib/client/AbstractPowerSyncDatabase.js

@@ -2,12 +2,14 @@ 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 { ConnectionManager } from './ConnectionManager.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
@@ -15,7 +17,6 @@ import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
-import { FULL_SYNC_PRIORITY } from '../db/crud/SyncProgress.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -59,13 +60,16 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Current connection status.
      */
     currentStatus;
-    syncStreamImplementation;
     sdkVersion;
     bucketStorageAdapter;
-    syncStatusListenerDisposer;
     _isReadyPromise;
+    connectionManager;
+    get syncStreamImplementation() {
+        return this.connectionManager.syncStreamImplementation;
+    }
     _schema;
     _database;
+    runExclusiveMutex;
     constructor(options) {
         super();
         this.options = options;
@@ -92,7 +96,31 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         this._schema = schema;
         this.ready = false;
         this.sdkVersion = '';
+        this.runExclusiveMutex = new Mutex();
         // Start async init
+        this.connectionManager = new ConnectionManager({
+            createSyncImplementation: async (connector, options) => {
+                await this.waitForReady();
+                return this.runExclusive(async () => {
+                    const sync = this.generateSyncStreamImplementation(connector, this.resolvedConnectionOptions(options));
+                    const onDispose = sync.registerListener({
+                        statusChanged: (status) => {
+                            this.currentStatus = new SyncStatus({
+                                ...status.toJSON(),
+                                hasSynced: this.currentStatus?.hasSynced || !!status.lastSyncedAt
+                            });
+                            this.iterateListeners((cb) => cb.statusChanged?.(this.currentStatus));
+                        }
+                    });
+                    await sync.waitForReady();
+                    return {
+                        sync,
+                        onDispose
+                    };
+                });
+            },
+            logger: this.logger
+        });
         this._isReadyPromise = this.initialize();
     }
     /**
@@ -265,30 +293,18 @@ 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.runExclusiveMutex.runExclusive(callback);
+    }
     /**
      * Connects to stream of events from the PowerSync instance.
      */
     async connect(connector, 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');
-        }
-        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));
-            }
-        });
-        await this.syncStreamImplementation.waitForReady();
-        this.syncStreamImplementation.triggerCrudUpload();
-        await this.syncStreamImplementation.connect(options);
+        return this.connectionManager.connect(connector, options);
     }
     /**
      * Close the sync connection.
@@ -296,11 +312,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Use {@link connect} to connect again.
      */
     async disconnect() {
-        await this.waitForReady();
-        await this.syncStreamImplementation?.disconnect();
-        this.syncStatusListenerDisposer?.();
-        await this.syncStreamImplementation?.dispose();
-        this.syncStreamImplementation = undefined;
+        return this.connectionManager.disconnect();
     }
     /**
      *  Disconnect and clear the database.
@@ -339,7 +351,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (disconnect) {
             await this.disconnect();
         }
-        await this.syncStreamImplementation?.dispose();
+        await this.connectionManager.close();
         await this.database.close();
         this.closed = true;
     }

package/lib/client/ConnectionManager.d.ts

@@ -0,0 +1,80 @@
+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';
+/**
+ * @internal
+ */
+export interface ConnectionManagerSyncImplementationResult {
+    sync: StreamingSyncImplementation;
+    /**
+     * Additional cleanup function which is called after the sync stream implementation
+     * is disposed.
+     */
+    onDispose: () => Promise<void> | void;
+}
+/**
+ * @internal
+ */
+export interface ConnectionManagerOptions {
+    createSyncImplementation(connector: PowerSyncBackendConnector, options: PowerSyncConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
+    logger: ILogger;
+}
+type StoredConnectionOptions = {
+    connector: PowerSyncBackendConnector;
+    options: PowerSyncConnectionOptions;
+};
+/**
+ * @internal
+ */
+export interface ConnectionManagerListener extends BaseListener {
+    syncStreamCreated: (sync: StreamingSyncImplementation) => void;
+}
+/**
+ * @internal
+ */
+export declare class ConnectionManager extends BaseObserver<ConnectionManagerListener> {
+    protected options: ConnectionManagerOptions;
+    /**
+     * 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;
+    syncStreamImplementation: StreamingSyncImplementation | null;
+    /**
+     * Additional cleanup function which is called after the sync stream implementation
+     * is disposed.
+     */
+    protected syncDisposer: (() => Promise<void> | void) | null;
+    constructor(options: ConnectionManagerOptions);
+    get logger(): ILogger;
+    close(): Promise<void>;
+    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
+    protected connectInternal(): Promise<void>;
+    /**
+     * Close the sync connection.
+     *
+     * Use {@link connect} to connect again.
+     */
+    disconnect(): Promise<void>;
+    protected disconnectInternal(): Promise<void>;
+    protected performDisconnect(): Promise<void>;
+}
+export {};

package/lib/client/ConnectionManager.js

@@ -0,0 +1,175 @@
+import { BaseObserver } from '../utils/BaseObserver.js';
+/**
+ * @internal
+ */
+export class ConnectionManager extends BaseObserver {
+    options;
+    /**
+     * 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;
+    syncStreamImplementation;
+    /**
+     * Additional cleanup function which is called after the sync stream implementation
+     * is disposed.
+     */
+    syncDisposer;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.connectingPromise = null;
+        this.syncStreamInitPromise = null;
+        this.disconnectingPromise = null;
+        this.pendingConnectionOptions = null;
+        this.syncStreamImplementation = null;
+        this.syncDisposer = null;
+    }
+    get logger() {
+        return this.options.logger;
+    }
+    async close() {
+        await this.syncStreamImplementation?.dispose();
+        await this.syncDisposer?.();
+    }
+    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 ?? {}
+        };
+        // 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.
+        // We should also disconnect if we have already completed a connection attempt.
+        if (!hadPendingOptions || this.syncStreamImplementation) {
+            await this.disconnectInternal();
+        }
+        // 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()
+                    .catch(() => { })
+                    .finally(checkConnection);
+                return this.connectingPromise;
+            }
+            else {
+                // Clear the connecting promise, done.
+                this.connectingPromise = null;
+                return;
+            }
+        };
+        this.connectingPromise ??= this.connectInternal()
+            .catch(() => { })
+            .finally(checkConnection);
+        return this.connectingPromise;
+    }
+    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 = new Promise(async (resolve, reject) => {
+            try {
+                if (!this.pendingConnectionOptions) {
+                    this.logger.debug('No pending connection options found, not creating sync stream implementation');
+                    // A disconnect could have cleared this.
+                    resolve();
+                    return;
+                }
+                if (this.disconnectingPromise) {
+                    resolve();
+                    return;
+                }
+                const { connector, options } = this.pendingConnectionOptions;
+                appliedOptions = options;
+                this.pendingConnectionOptions = null;
+                const { sync, onDispose } = await this.options.createSyncImplementation(connector, options);
+                this.iterateListeners((l) => l.syncStreamCreated?.(sync));
+                this.syncStreamImplementation = sync;
+                this.syncDisposer = onDispose;
+                await this.syncStreamImplementation.waitForReady();
+                resolve();
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        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.logger.debug('Attempting to connect to PowerSync instance');
+        await this.syncStreamImplementation?.connect(appliedOptions);
+        this.syncStreamImplementation?.triggerCrudUpload();
+    }
+    /**
+     * Close the sync connection.
+     *
+     * Use {@link connect} to connect again.
+     */
+    async disconnect() {
+        // 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;
+        }
+        this.disconnectingPromise = this.performDisconnect();
+        await this.disconnectingPromise;
+        this.disconnectingPromise = null;
+    }
+    async performDisconnect() {
+        // 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;
+        // Keep reference to the sync stream implementation and disposer
+        // The class members will be cleared before we trigger the disconnect
+        // to prevent any further calls to the sync stream implementation.
+        const sync = this.syncStreamImplementation;
+        this.syncStreamImplementation = null;
+        const disposer = this.syncDisposer;
+        this.syncDisposer = null;
+        await sync?.disconnect();
+        await sync?.dispose();
+        await disposer?.();
+    }
+}

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

@@ -51,17 +51,27 @@ export declare enum PSInternalTable {
     OPLOG = "ps_oplog",
     UNTYPED = "ps_untyped"
 }
+export declare enum PowerSyncControlCommand {
+    PROCESS_TEXT_LINE = "line_text",
+    PROCESS_BSON_LINE = "line_binary",
+    STOP = "stop",
+    START = "start",
+    NOTIFY_TOKEN_REFRESHED = "refreshed_token",
+    NOTIFY_CRUD_UPLOAD_COMPLETED = "completed_upload"
+}
 export interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
 }
 export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener>, Disposable {
     init(): Promise<void>;
-    saveSyncData(batch: SyncDataBatch): Promise<void>;
+    saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
     getBucketOperationProgress(): Promise<BucketOperationProgress>;
+    hasMigratedSubkeys(): Promise<boolean>;
+    migrateToFixedSubkeys(): Promise<void>;
     syncLocalDatabase(checkpoint: Checkpoint, priority?: number): Promise<{
         checkpointValid: boolean;
         ready: boolean;
@@ -85,4 +95,8 @@ export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener
      * Get an unique client id.
      */
     getClientId(): Promise<string>;
+    /**
+     * Invokes the `powersync_control` function for the sync client.
+     */
+    control(op: PowerSyncControlCommand, payload: string | ArrayBuffer | null): Promise<string>;
 }

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

@@ -6,3 +6,12 @@ export var PSInternalTable;
     PSInternalTable["OPLOG"] = "ps_oplog";
     PSInternalTable["UNTYPED"] = "ps_untyped";
 })(PSInternalTable || (PSInternalTable = {}));
+export var PowerSyncControlCommand;
+(function (PowerSyncControlCommand) {
+    PowerSyncControlCommand["PROCESS_TEXT_LINE"] = "line_text";
+    PowerSyncControlCommand["PROCESS_BSON_LINE"] = "line_binary";
+    PowerSyncControlCommand["STOP"] = "stop";
+    PowerSyncControlCommand["START"] = "start";
+    PowerSyncControlCommand["NOTIFY_TOKEN_REFRESHED"] = "refreshed_token";
+    PowerSyncControlCommand["NOTIFY_CRUD_UPLOAD_COMPLETED"] = "completed_upload";
+})(PowerSyncControlCommand || (PowerSyncControlCommand = {}));

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

@@ -30,6 +30,8 @@ type CrudEntryOutputJSON = {
     id: string;
     tx_id?: number;
     data?: Record<string, any>;
+    old?: Record<string, any>;
+    metadata?: string;
 };
 /**
  * A single client-side change.

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

@@ -74,7 +74,9 @@ export class CrudEntry {
             type: this.table,
             id: this.id,
             tx_id: this.transactionId,
-            data: this.opData
+            data: this.opData,
+            old: this.previousValues,
+            metadata: this.metadata
         };
     }
     equals(entry) {
@@ -93,6 +95,15 @@ export class CrudEntry {
      * Generates an array for use in deep comparison operations
      */
     toComparisonArray() {
-        return [this.transactionId, this.clientId, this.op, this.table, this.id, this.opData];
+        return [
+            this.transactionId,
+            this.clientId,
+            this.op,
+            this.table,
+            this.id,
+            this.opData,
+            this.previousValues,
+            this.metadata
+        ];
     }
 }

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

@@ -7,17 +7,17 @@ export interface OplogEntryJSON {
     object_type?: string;
     op_id: string;
     op: OpTypeJSON;
-    subkey?: string | object;
+    subkey?: string;
 }
 export declare class OplogEntry {
     op_id: OpId;
     op: OpType;
     checksum: number;
-    subkey: string;
+    subkey?: string | undefined;
     object_type?: string | undefined;
     object_id?: string | undefined;
     data?: string | undefined;
     static fromRow(row: OplogEntryJSON): OplogEntry;
-    constructor(op_id: OpId, op: OpType, checksum: number, subkey: string, object_type?: string | undefined, object_id?: string | undefined, data?: string | undefined);
-    toJSON(): OplogEntryJSON;
+    constructor(op_id: OpId, op: OpType, checksum: number, subkey?: string | undefined, object_type?: string | undefined, object_id?: string | undefined, data?: string | undefined);
+    toJSON(fixedKeyEncoding?: boolean): OplogEntryJSON;
 }

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

@@ -8,7 +8,7 @@ export class OplogEntry {
     object_id;
     data;
     static fromRow(row) {
-        return new OplogEntry(row.op_id, OpType.fromJSON(row.op), row.checksum, typeof row.subkey == 'string' ? row.subkey : JSON.stringify(row.subkey), row.object_type, row.object_id, row.data);
+        return new OplogEntry(row.op_id, OpType.fromJSON(row.op), row.checksum, row.subkey, row.object_type, row.object_id, row.data);
     }
     constructor(op_id, op, checksum, subkey, object_type, object_id, data) {
         this.op_id = op_id;
@@ -19,7 +19,7 @@ export class OplogEntry {
         this.object_id = object_id;
         this.data = data;
     }
-    toJSON() {
+    toJSON(fixedKeyEncoding = false) {
         return {
             op_id: this.op_id,
             op: this.op.toJSON(),
@@ -27,7 +27,9 @@ export class OplogEntry {
             object_id: this.object_id,
             checksum: this.checksum,
             data: this.data,
-            subkey: JSON.stringify(this.subkey)
+            // Older versions of the JS SDK used to always JSON.stringify here. That has always been wrong,
+            // but we need to migrate gradually to not break existing databases.
+            subkey: fixedKeyEncoding ? this.subkey : JSON.stringify(this.subkey)
         };
     }
 }

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 { BucketOperationProgress, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
+import { BucketOperationProgress, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, PowerSyncControlCommand, SyncLocalDatabaseResult } from './BucketStorageAdapter.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -31,7 +31,7 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
     startSession(): void;
     getBucketStates(): Promise<BucketState[]>;
     getBucketOperationProgress(): Promise<BucketOperationProgress>;
-    saveSyncData(batch: SyncDataBatch): Promise<void>;
+    saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;
     /**
      * Mark a bucket for deletion.
@@ -68,4 +68,8 @@ export declare class SqliteBucketStorage extends BaseObserver<BucketStorageListe
      * Set a target checkpoint.
      */
     setTargetCheckpoint(checkpoint: Checkpoint): Promise<void>;
+    control(op: PowerSyncControlCommand, payload: string | ArrayBuffer | null): Promise<string>;
+    hasMigratedSubkeys(): Promise<boolean>;
+    migrateToFixedSubkeys(): Promise<void>;
+    static _subkeyMigrationKey: string;
 }

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

@@ -70,13 +70,13 @@ export class SqliteBucketStorage extends BaseObserver {
         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) {
+    async saveSyncData(batch, fixedKeyFormat = false) {
         await this.writeTransaction(async (tx) => {
             let count = 0;
             for (const b of batch.buckets) {
                 const result = await tx.execute('INSERT INTO powersync_operations(op, data) VALUES(?, ?)', [
                     'save',
-                    JSON.stringify({ buckets: [b.toJSON()] })
+                    JSON.stringify({ buckets: [b.toJSON(fixedKeyFormat)] })
                 ]);
                 this.logger.debug('saveSyncData', JSON.stringify(result));
                 count += b.data.length;
@@ -339,6 +339,28 @@ export class SqliteBucketStorage extends BaseObserver {
     async setTargetCheckpoint(checkpoint) {
         // No-op for now
     }
+    async control(op, payload) {
+        return await this.writeTransaction(async (tx) => {
+            const [[raw]] = await tx.executeRaw('SELECT powersync_control(?, ?)', [op, payload]);
+            return raw;
+        });
+    }
+    async hasMigratedSubkeys() {
+        const { r } = await this.db.get('SELECT EXISTS(SELECT * FROM ps_kv WHERE key = ?) as r', [
+            SqliteBucketStorage._subkeyMigrationKey
+        ]);
+        return r != 0;
+    }
+    async migrateToFixedSubkeys() {
+        await this.writeTransaction(async (tx) => {
+            await tx.execute('UPDATE ps_oplog SET key = powersync_remove_duplicate_key_encoding(key);');
+            await tx.execute('INSERT OR REPLACE INTO ps_kv (key, value) VALUES (?, ?);', [
+                SqliteBucketStorage._subkeyMigrationKey,
+                '1'
+            ]);
+        });
+    }
+    static _subkeyMigrationKey = 'powersync_js_migrated_subkeys';
 }
 function hasMatchingPriority(priority, bucket) {
     return bucket.priority != null && bucket.priority <= priority;

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

@@ -36,5 +36,5 @@ export declare class SyncDataBucket {
      * Use this for the next request.
      */
     next_after?: OpId | undefined);
-    toJSON(): SyncDataBucketJSON;
+    toJSON(fixedKeyEncoding?: boolean): SyncDataBucketJSON;
 }

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

@@ -27,13 +27,13 @@ export class SyncDataBucket {
         this.after = after;
         this.next_after = next_after;
     }
-    toJSON() {
+    toJSON(fixedKeyEncoding = false) {
         return {
             bucket: this.bucket,
             has_more: this.has_more,
             after: this.after,
             next_after: this.next_after,
-            data: this.data.map((entry) => entry.toJSON())
+            data: this.data.map((entry) => entry.toJSON(fixedKeyEncoding))
         };
     }
 }