@powersync/common 2.1.0 → 2.2.1

package/lib/attachments/AttachmentContext.js

@@ -189,8 +189,9 @@ export class AttachmentContext {
           ?
       `, [AttachmentState.ARCHIVED, limit, this.archivedCacheLimit]);
         const archivedAttachments = results.map(attachmentFromSql);
+        // Nothing above the cache limit, so the paginated cleanup in `expireCache` is complete.
         if (archivedAttachments.length === 0)
-            return false;
+            return true;
         await callback?.(archivedAttachments);
         this.logger.log({
             level: LogLevels.info,

package/lib/attachments/AttachmentContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"AttachmentContext.js","sourceRoot":"","sources":["../../src/attachments/AttachmentContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AttachmentContext.js","sourceRoot":"","sources":["../../src/attachments/AttachmentContext.ts"],"names":[],"mappings":"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"}

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.1",
   "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/attachments/AttachmentContext.ts

@@ -231,7 +231,8 @@ export class AttachmentContext {
     );
 
     const archivedAttachments = results.map(attachmentFromSql);
-    if (archivedAttachments.length === 0) return false;
+    // Nothing above the cache limit, so the paginated cleanup in `expireCache` is complete.
+    if (archivedAttachments.length === 0) return true;
 
     await callback?.(archivedAttachments);
     this.logger.log({

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';