@powersync/common 2.1.0 → 2.2.0

package/lib/client/CommonPowerSyncDatabase.d.ts

@@ -16,6 +16,7 @@ import { ArrayQueryDefinition, Query } from './Query.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { Mutex } from '../utils/mutex.js';
 import { QueryResult } from '../db/QueryResult.js';
+import { CheckpointRequest } from './sync/CheckpointRequest.js';
 /**
  * @public
  */
@@ -205,6 +206,18 @@ export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSync
      * @returns A {@link SyncStream} instance that can be subscribed to.
      */
     syncStream(name: string, params?: Record<string, any>): SyncStream;
+    /**
+     * Requests a checkpoint from the PowerSync service.
+     *
+     * The returned request can be awaited (using {@link CheckpointRequest#waitForSync}) to confirm that the local
+     * database has applied server-side changes up to the checkpoint. This method requires an active or connecting sync
+     * client connected with a {@link CheckpointMode} set to `requests` and PowerSync service version 1.24.0 or later.
+     *
+     * It can throw for connection, mode, authentication, or service request failures.
+     *
+     * @alpha
+     */
+    requestCheckpoint(): Promise<CheckpointRequest>;
     /**
      * Close the database, releasing resources.
      *

package/lib/client/connection/PowerSyncBackendConnector.d.ts

@@ -23,4 +23,15 @@ 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/lib/client/sync/CheckpointRequest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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/lib/client/sync/CheckpointRequest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=CheckpointRequest.js.map

package/lib/client/sync/CheckpointRequest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointRequest.js","sourceRoot":"","sources":["../../../src/client/sync/CheckpointRequest.ts"],"names":[],"mappings":""}

package/lib/client/sync/options.d.ts

@@ -40,6 +40,10 @@ export interface SyncOptions {
      * milliseconds.
      */
     crudUploadThrottleMs?: number;
+    /**
+     * The mode used to request checkpoints from the service (used after uploading local data).
+     */
+    checkpointMode?: CheckpointMode;
 }
 /**
  * @public
@@ -63,3 +67,33 @@ export declare 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/lib/client/sync/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/client/sync/options.ts"],"names":[],"mappings":"AAqDA;;GAEG;AACH,MAAM,CAAN,IAAY,0BAGX;AAHD,WAAY,0BAA0B;IACpC,2CAAa,CAAA;IACb,uDAAyB,CAAA;AAC3B,CAAC,EAHW,0BAA0B,KAA1B,0BAA0B,QAGrC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACvB;;;OAGG;IACH,sCAAqB,CAAA;IAErB;;;OAGG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/client/sync/options.ts"],"names":[],"mappings":"AA0DA;;GAEG;AACH,MAAM,CAAN,IAAY,0BAGX;AAHD,WAAY,0BAA0B;IACpC,2CAAa,CAAA;IACb,uDAAyB,CAAA;AAC3B,CAAC,EAHW,0BAA0B,KAA1B,0BAA0B,QAGrC;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,aAYX;AAZD,WAAY,aAAa;IACvB;;;OAGG;IACH,sCAAqB,CAAA;IAErB;;;OAGG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAZW,aAAa,KAAb,aAAa,QAYxB"}

package/lib/index.d.ts

@@ -14,9 +14,10 @@ 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';
 export * from './db/crud/UploadQueueStatus.js';

package/lib/index.js

@@ -14,6 +14,7 @@ export * from './client/SQLOpenFactory.js';
 export * from './client/sync/bucket/CrudBatch.js';
 export { 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 { SyncStreamConnectionMethod, FetchStrategy } from './client/sync/options.js';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAEvD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAmB,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAAe,0BAA0B,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAGlG,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAErC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAGjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAElC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,wCAAwC,CAAC;AAEvD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAmB,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAEL,0BAA0B,EAC1B,aAAa,EAGd,MAAM,0BAA0B,CAAC;AAGlC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AAErC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAGjD,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mBAAmB,CAAC;AAElC,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -32,13 +32,14 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@types/uuid": "^9.0.6",
-    "@microsoft/api-extractor": "^7.58.7"
+    "@microsoft/api-extractor": "^7.59.0"
   },
   "scripts": {
     "build": "tsc -b",
     "build:prod": "tsc -b",
     "clean": "rm -rf lib dist tsconfig.tsbuildinfo",
     "test": "vitest",
-    "test:exports": "attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm"
+    "test:exports": "attw --pack . --ignore-rules no-resolution cjs-resolves-to-esm",
+    "api-diff": "api-extractor run --verbose"
   }
 }

package/src/client/CommonPowerSyncDatabase.ts

@@ -16,6 +16,7 @@ import { ArrayQueryDefinition, Query } from './Query.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { Mutex } from '../utils/mutex.js';
 import { QueryResult } from '../db/QueryResult.js';
+import { CheckpointRequest } from './sync/CheckpointRequest.js';
 
 /**
  * @public
@@ -233,6 +234,19 @@ export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSync
    */
   syncStream(name: string, params?: Record<string, any>): SyncStream;
 
+  /**
+   * Requests a checkpoint from the PowerSync service.
+   *
+   * The returned request can be awaited (using {@link CheckpointRequest#waitForSync}) to confirm that the local
+   * database has applied server-side changes up to the checkpoint. This method requires an active or connecting sync
+   * client connected with a {@link CheckpointMode} set to `requests` and PowerSync service version 1.24.0 or later.
+   *
+   * It can throw for connection, mode, authentication, or service request failures.
+   *
+   * @alpha
+   */
+  requestCheckpoint(): Promise<CheckpointRequest>;
+
   /**
    * Close the database, releasing resources.
    *

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

@@ -15,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';