@powersync/common 0.0.0-dev-20260630144038 → 0.0.0-dev-20261015114518

package/src/attachments/SyncingService.ts

@@ -1,7 +1,7 @@
 import { LogLevels, PowerSyncLogger } from '../utils/Logger.js';
 import { AttachmentService } from './AttachmentService.js';
+import { AttachmentTransportAdapter } from './AttachmentTransportAdapter.js';
 import { LocalStorageAdapter } from './LocalStorageAdapter.js';
-import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { AttachmentRecord, AttachmentState } from './Schema.js';
 import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 import { AttachmentContext } from './AttachmentContext.js';
@@ -10,60 +10,96 @@ import { AttachmentContext } from './AttachmentContext.js';
  * Orchestrates attachment synchronization between local and remote storage.
  * Handles uploads, downloads, deletions, and state transitions.
  *
+ * Remote operations (upload/download/delete) go through the {@link AttachmentTransportAdapter};
+ * local file operations use the {@link LocalStorageAdapter}.
+ *
  * @internal
  */
 export class SyncingService {
   private attachmentService: AttachmentService;
   private localStorage: LocalStorageAdapter;
-  private remoteStorage: RemoteStorageAdapter;
+  private transport: AttachmentTransportAdapter;
   private logger: PowerSyncLogger;
   private errorHandler?: AttachmentErrorHandler;
 
   constructor(
     attachmentService: AttachmentService,
     localStorage: LocalStorageAdapter,
-    remoteStorage: RemoteStorageAdapter,
+    transport: AttachmentTransportAdapter,
     logger: PowerSyncLogger,
     errorHandler?: AttachmentErrorHandler
   ) {
     this.attachmentService = attachmentService;
     this.localStorage = localStorage;
-    this.remoteStorage = remoteStorage;
+    this.transport = transport;
     this.logger = logger;
     this.errorHandler = errorHandler;
   }
 
   /**
    * Processes attachments based on their state (upload, download, or delete).
-   * All updates are saved in a single batch after processing.
+   *
+   * Each attachment's I/O runs outside the attachment-service mutex, and the row's
+   * state transition is persisted immediately after it completes. This keeps the
+   * mutex available to concurrent `saveFile` / `deleteFile` / watched-attachment
+   * processing while a batch is in flight, and means consumer queries against the
+   * attachments queue see incremental progress instead of one atomic commit at the
+   * end of the batch.
    *
    * @param attachments - Array of attachment records to process
-   * @param context - Attachment context for database operations
-   * @returns Promise that resolves when all attachments have been processed and saved
+   * @param options - Optional controls. Pass `signal` (an `AbortSignal`) to interrupt
+   *                  the batch: it is checked between attachments and, once aborted, the
+   *                  loop exits early — letting `stopSync` stop a running batch within
+   *                  one attachment's processing time.
    */
-  async processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void> {
-    const updatedAttachments: AttachmentRecord[] = [];
+  async processAttachments(
+    attachments: AttachmentRecord[],
+    options?: {
+      signal?: AbortSignal;
+    }
+  ): Promise<void> {
+    const signal = options?.signal;
+    this.logger.log({
+      level: LogLevels.info,
+      message: `Starting processAttachments with ${attachments.length} attachments`
+    });
+
     for (const attachment of attachments) {
-      switch (attachment.state) {
-        case AttachmentState.QUEUED_UPLOAD:
-          const uploaded = await this.uploadAttachment(attachment);
-          updatedAttachments.push(uploaded);
-          break;
-        case AttachmentState.QUEUED_DOWNLOAD:
-          const downloaded = await this.downloadAttachment(attachment);
-          updatedAttachments.push(downloaded);
-          break;
-        case AttachmentState.QUEUED_DELETE:
-          const deleted = await this.deleteAttachment(attachment, context);
-          updatedAttachments.push(deleted);
-          break;
-
-        default:
-          break;
+      if (signal?.aborted) {
+        this.logger.log({
+          level: LogLevels.info,
+          message: 'Sync cancelled; stopping iteration early'
+        });
+        return;
       }
-    }
 
-    await context.saveAttachments(updatedAttachments);
+      try {
+        let updated: AttachmentRecord;
+        switch (attachment.state) {
+          case AttachmentState.QUEUED_UPLOAD:
+            updated = await this.uploadAttachment(attachment);
+            break;
+          case AttachmentState.QUEUED_DOWNLOAD:
+            updated = await this.downloadAttachment(attachment);
+            break;
+          case AttachmentState.QUEUED_DELETE:
+            // `deleteAttachment` needs a context (it removes the row in a
+            // transaction); briefly re-acquire the mutex for just this row.
+            updated = await this.attachmentService.withContext((ctx) => this.deleteAttachment(attachment, ctx));
+            break;
+          default:
+            continue;
+        }
+
+        await this.attachmentService.withContext((ctx) => ctx.saveAttachments([updated]));
+      } catch (error) {
+        this.logger.log({
+          level: LogLevels.warn,
+          message: `Error during sync for ${attachment.id}`,
+          error
+        });
+      }
+    }
   }
 
   /**
@@ -81,8 +117,7 @@ export class SyncingService {
         throw new Error(`No localUri for attachment ${attachment.id}`);
       }
 
-      const fileBlob = await this.localStorage.readFile(attachment.localUri);
-      await this.remoteStorage.uploadFile(fileBlob, attachment);
+      await this.transport.upload({ ...attachment, localUri: attachment.localUri });
 
       return {
         ...attachment,
@@ -104,7 +139,7 @@ export class SyncingService {
 
   /**
    * Downloads an attachment from remote storage to local storage.
-   * Retrieves the file, converts to base64, and saves locally.
+   * The destination `localUri` is assigned here and the transport writes the file to it.
    * On success, marks as SYNCED. On failure, defers to error handler or archives.
    *
    * @param attachment - The attachment record to download
@@ -113,10 +148,8 @@ export class SyncingService {
   async downloadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord> {
     this.logger.log({ level: LogLevels.info, message: `Downloading attachment ${attachment.filename}` });
     try {
-      const fileData = await this.remoteStorage.downloadFile(attachment);
-
       const localUri = this.localStorage.getLocalUri(attachment.filename);
-      await this.localStorage.saveFile(localUri, fileData);
+      await this.transport.download({ ...attachment, localUri });
 
       return {
         ...attachment,
@@ -148,7 +181,7 @@ export class SyncingService {
    */
   async deleteAttachment(attachment: AttachmentRecord, context: AttachmentContext): Promise<AttachmentRecord> {
     try {
-      await this.remoteStorage.deleteFile(attachment);
+      await this.transport.delete(attachment);
       if (attachment.localUri) {
         await this.localStorage.deleteFile(attachment.localUri);
       }

package/src/client/CommonPowerSyncDatabase.ts

@@ -16,13 +16,25 @@ 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';
 
 /**
+ * Options passed to {@link CommonPowerSyncDatabase#disconnectAndClear}.
+ *
  * @public
  */
 export interface DisconnectAndClearOptions {
   /** When set to false, data in local-only tables is preserved. */
   clearLocal?: boolean;
+  /**
+   * A [soft] clear deletes publicly visible tables, but keeps internal copies of data synced in the database.
+   *
+   * This usually means that if {@link CommonPowerSyncDatabase#connect} is later called again with a JWT from the same
+   * user, the first sync is very fast because all internal data is still available. When a different user  logs in, no
+   * old data would be visible at any point. Using soft deletes is recommended where it's not a security issue that old
+   * data could be reconstructed from internal database tables.
+   */
+  soft?: boolean;
 }
 
 /**
@@ -233,6 +245,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.
    *
@@ -343,7 +368,7 @@ export interface CommonPowerSyncDatabase extends BaseObserverInterface<PowerSync
 
   /**
    * Open a read-only transaction.
-   * Read transactions can run concurrently to a write transaction.
+   * When multiple connections are available, read transactions can run concurrently to a write transaction.
    * Changes from any write transaction are not visible to read transactions started before it.
    *
    * @param callback - Function to execute within the transaction

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/connection/PowerSyncCredentials.ts

@@ -4,5 +4,5 @@
 export interface PowerSyncCredentials {
   endpoint: string;
   token: string;
-  expiresAt?: Date;
+  expiresAt?: Date | undefined;
 }

package/src/client/runOnSchemaChange.ts

@@ -9,6 +9,8 @@ export function runOnSchemaChange(
   options?: SQLWatchOptions
 ): void {
   const triggerWatchedQuery = () => {
+    if (options?.signal?.aborted) return;
+
     const abortController = new AbortController();
     let disposeSchemaListener: (() => void) | null = null;
     const stopWatching = () => {

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,20 @@ export interface SyncOptions {
    * milliseconds.
    */
   crudUploadThrottleMs?: number;
+
+  /**
+   * The mode used to request checkpoints from the service (used after uploading local data).
+   */
+  checkpointMode?: CheckpointMode;
+
+  /**
+   * Enables the core extension's diagnostics event stream: detailed per-bucket download stats,
+   * including each bucket's `target_count`, and inferred column types. Off by default.
+   *
+   * The events are internal. No public API exposes them; only PowerSync DevTools reads them, to show
+   * per-bucket totals. See https://docs.powersync.com/tools/devtools-overview.
+   */
+  diagnostics?: boolean;
 }
 
 /**
@@ -75,3 +89,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/db/crud/SyncStatus.ts

@@ -94,7 +94,7 @@ export interface SyncStatus {
   get hasSynced(): boolean | undefined;
 
   /**
-   * All sync streams currently being tracked in teh database.
+   * All sync streams currently being tracked in the database.
    *
    * This returns null when the database is currently being opened and we don't have reliable information about all
    * included streams yet.

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