@powersync/common 0.0.0-dev-20250609122429 → 0.0.0-dev-20250625140957

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

@@ -12,6 +12,48 @@ export declare enum SyncStreamConnectionMethod {
     HTTP = "http",
     WEB_SOCKET = "web-socket"
 }
+export declare enum SyncClientImplementation {
+    /**
+     * Decodes and handles sync lines received from the sync service in JavaScript.
+     *
+     * This is the default option.
+     *
+     * @deprecated Don't use {@link SyncClientImplementation.JAVASCRIPT} directly. Instead, use
+     * {@link DEFAULT_SYNC_CLIENT_IMPLEMENTATION} or omit the option. The explicit choice to use
+     * the JavaScript-based sync implementation will be removed from a future version of the SDK.
+     */
+    JAVASCRIPT = "js",
+    /**
+     * This implementation offloads the sync line decoding and handling into the PowerSync
+     * core extension.
+     *
+     * @experimental
+     * While this implementation is more performant than {@link SyncClientImplementation.JAVASCRIPT},
+     * it has seen less real-world testing and is marked as __experimental__ at the moment.
+     *
+     * ## Compatibility warning
+     *
+     * The Rust sync client stores sync data in a format that is slightly different than the one used
+     * by the old {@link JAVASCRIPT} implementation. When adopting the {@link RUST} client on existing
+     * databases, the PowerSync SDK will migrate the format automatically.
+     * Further, the {@link JAVASCRIPT} client in recent versions of the PowerSync JS SDK (starting from
+     * the version introducing {@link RUST} as an option) also supports the new format, so you can switch
+     * back to {@link JAVASCRIPT} later.
+     *
+     * __However__: Upgrading the SDK version, then adopting {@link RUST} as a sync client and later
+     * downgrading the SDK to an older version (necessarily using the JavaScript-based implementation then)
+     * can lead to sync issues.
+     */
+    RUST = "rust"
+}
+/**
+ * The default {@link SyncClientImplementation} to use.
+ *
+ * Please use this field instead of {@link SyncClientImplementation.JAVASCRIPT} directly. A future version
+ * of the PowerSync SDK will enable {@link SyncClientImplementation.RUST} by default and remove the JavaScript
+ * option.
+ */
+export declare const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = SyncClientImplementation.JAVASCRIPT;
 /**
  * Abstract Lock to be implemented by various JS environments
  */
@@ -50,6 +92,14 @@ export interface PowerSyncConnectionOptions extends BaseConnectionOptions, Addit
 }
 /** @internal */
 export interface BaseConnectionOptions {
+    /**
+     * Whether to use a JavaScript implementation to handle received sync lines from the sync
+     * service, or whether this work should be offloaded to the PowerSync core extension.
+     *
+     * This defaults to the JavaScript implementation ({@link SyncClientImplementation.JAVASCRIPT})
+     * since the ({@link SyncClientImplementation.RUST}) implementation is experimental at the moment.
+     */
+    clientImplementation?: SyncClientImplementation;
     /**
      * The connection method to use when streaming updates from
      * the PowerSync backend instance.
@@ -117,6 +167,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
     private pendingCrudUpload?;
+    private notifyCompletedUploads?;
     syncStatus: SyncStatus;
     triggerCrudUpload: () => void;
     constructor(options: AbstractStreamingSyncImplementationOptions);
@@ -138,7 +189,25 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
      */
     streamingSync(signal?: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
     private collectLocalBucketState;
+    /**
+     * Older versions of the JS SDK used to encode subkeys as JSON in {@link OplogEntry.toJSON}.
+     * Because subkeys are always strings, this leads to quotes being added around them in `ps_oplog`.
+     * While this is not a problem as long as it's done consistently, it causes issues when a database
+     * created by the JS SDK is used with other SDKs, or (more likely) when the new Rust sync client
+     * is enabled.
+     *
+     * So, we add a migration from the old key format (with quotes) to the new one (no quotes). The
+     * migration is only triggered when necessary (for now). The function returns whether the new format
+     * should be used, so that the JS SDK is able to write to updated databases.
+     *
+     * @param requireFixedKeyFormat Whether we require the new format or also support the old one.
+     *        The Rust client requires the new subkey format.
+     * @returns Whether the database is now using the new, fixed subkey format.
+     */
+    private requireKeyFormat;
     protected streamingSyncIteration(signal: AbortSignal, options?: PowerSyncConnectionOptions): Promise<void>;
+    private legacyStreamingSyncIteration;
+    private rustSyncIteration;
     private updateSyncStatusForStartingCheckpoint;
     private applyCheckpoint;
     protected updateSyncStatus(options: SyncStatusOptions): void;