@powersync/common 2.0.0 → 2.2.0

package/src/client/connection/PowerSyncBackendConnector.ts

@@ -25,4 +25,16 @@ export interface PowerSyncBackendConnector {
    * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
    */
   uploadData: (database: CommonPowerSyncDatabase) => Promise<void>;
+
+  /**
+   * Posts a client-generated checkpoint request to the backend and returns the effective checkpoint request state.
+   *
+   * This method is optional. It only needs to be implemented when the selected {@link CheckpointMode} is `requests`
+   * and [asynchronous backend uploads](https://docs.powersync.com/client-sdks/advanced/checkpoint-requests#asynchronous-upload-backends)
+   * are used. In any other case, this method should not be present on backend connectors.
+   *
+   * @param requestId - The client-generated checkpoint request ID (a positive 64-bit integer encoded as a string).
+   * @param clientId - The PowerSync client ID for the current device.
+   */
+  postCheckpointRequest?(clientId: string, requestId: string): Promise<string>;
 }

package/src/client/sync/CheckpointRequest.ts

@@ -0,0 +1,31 @@
+/**
+ * A checkpoint request created by {@link CommonPowerSyncDatabase#requestCheckpoint}.
+ *
+ * Use this value to wait until the local database has applied server-side changes up to the requested checkpoint. This
+ * is useful for explicit refresh flows where the caller wants confirmation that the local view has caught up to the
+ * service.
+ *
+ * Checkpoint requests are backed by request ids tracked in the local database, so they are reusable across disconnect
+ * and reconnect cycles. A wait interrupted by a disconnect throws an error, but the same request can be awaited again
+ * once a new connection is established.
+ *
+ * Requests do not survive {@link CommonPowerSyncDatabase#disconnectAndClear}, instances created before a clear should
+ * be discarded and requested again.
+ *
+ * @alpha
+ */
+export interface CheckpointRequest {
+  /**
+   * Whether this checkpoint request has synced before.
+   */
+  readonly hasSynced: boolean;
+
+  /**
+   * Waits until this checkpoint has been synced locally.
+   *
+   * This method fails on sync errors: If a download or upload error occurs before this checkpoint request has synced,
+   * that error is rethrown here. This makes it easier to observe sync errors when relying on checkpoints. Once sync has
+   * recovered, it is valid to call this method again to await the checkpoint.
+   */
+  waitForSync(options?: { signal?: AbortSignal }): Promise<void>;
+}

package/src/client/sync/options.ts

@@ -49,6 +49,11 @@ export interface SyncOptions {
    * milliseconds.
    */
   crudUploadThrottleMs?: number;
+
+  /**
+   * The mode used to request checkpoints from the service (used after uploading local data).
+   */
+  checkpointMode?: CheckpointMode;
 }
 
 /**
@@ -75,3 +80,33 @@ export enum FetchStrategy {
    */
   Sequential = 'sequential'
 }
+
+/**
+ * The mechanism to request checkpoints from the PowerSync service.
+ *
+ * Checkpoint requests are used after a client uploads local mutations. The PowerSync service later references them in
+ * downloaded data, allowing the SDK to assume that uploaded data has been synced down again.
+ *
+ * There are two ways to send checkpoint requests: A legacy (but default and stable) format supported by all PowerSync
+ * service versions, and a newer (`requests`) method which is only available from PowerSync service version 1.24.0 or
+ * later.
+ *
+ * Note that the requests checkpoint mode is an alpha API.
+ *
+ * @public
+ */
+export type CheckpointMode = 'legacy' | 'requests' | { requests: CheckpointRequestsOptions };
+
+/**
+ * Options associated with a {@link CheckpointMode} when the requests-based checkpoint option is used.
+ *
+ * @public
+ */
+export interface CheckpointRequestsOptions {
+  /**
+   * The delay, in milliseconds, to wait before re-sending a checkpoint request when it hasn't been applied in time.
+   *
+   * The minimum value for this is 10 seconds, lower values will be ignored.
+   */
+  retryDelay: number;
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './attachments/AttachmentContext.js';
 export * from './attachments/AttachmentErrorHandler.js';
 export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentTransportAdapter.js';
 export * from './attachments/LocalStorageAdapter.js';
 export * from './attachments/RemoteStorageAdapter.js';
 export * from './attachments/Schema.js';
@@ -14,9 +15,16 @@ export * from './client/SQLOpenFactory.js';
 export * from './client/sync/bucket/CrudBatch.js';
 export { CrudEntry, OpId, UpdateType } from './client/sync/bucket/CrudEntry.js';
 export * from './client/sync/bucket/CrudTransaction.js';
+export * from './client/sync/CheckpointRequest.js';
 export * from './client/sync/stream/JsonValue.js';
 export * from './client/sync/sync-streams.js';
-export { SyncOptions, SyncStreamConnectionMethod, FetchStrategy } from './client/sync/options.js';
+export {
+  SyncOptions,
+  SyncStreamConnectionMethod,
+  FetchStrategy,
+  CheckpointMode,
+  CheckpointRequestsOptions
+} from './client/sync/options.js';
 
 export { ProgressWithOperations, SyncProgress } from './db/crud/SyncProgress.js';
 export * from './db/crud/SyncStatus.js';