@powersync/common 2.0.0 → 2.2.0

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

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

@@ -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';
@@ -13,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,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.0.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/attachments/AttachmentQueue.ts

@@ -5,7 +5,9 @@ import { Transaction } from '../db/DBAdapter.js';
 import { AttachmentContext } from './AttachmentContext.js';
 import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 import { AttachmentService } from './AttachmentService.js';
-import { AttachmentData, LocalStorageAdapter } from './LocalStorageAdapter.js';
+import { AttachmentTransportAdapter } from './AttachmentTransportAdapter.js';
+import { BufferedAttachmentTransport } from './BufferedAttachmentTransport.js';
+import { AttachmentData, LocalStorageAdapter, StreamingLocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js';
 import { SyncingService } from './SyncingService.js';
@@ -13,24 +15,22 @@ import { WatchedAttachmentItem } from './WatchedAttachmentItem.js';
 import { CommonPowerSyncDatabase } from '../client/CommonPowerSyncDatabase.js';
 
 /**
- * Configuration options for {@link AttachmentQueue}.
+ * Fields common to every {@link AttachmentQueueOptions} variant.
  *
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export interface AttachmentQueueOptions {
+export interface BaseAttachmentQueueOptions<TLocal extends LocalStorageAdapter = LocalStorageAdapter> {
   /**
    * PowerSync database instance
    */
   db: CommonPowerSyncDatabase;
   /**
-   * Remote storage adapter for upload/download operations
-   */
-  remoteStorage: RemoteStorageAdapter;
-  /**
-   * Local storage adapter for file persistence
+   * Local storage adapter for file persistence. Its type determines whether
+   * {@link AttachmentQueue.saveFileFromUri} is available (a
+   * {@link StreamingLocalStorageAdapter} enables it).
    */
-  localStorage: LocalStorageAdapter;
+  localStorage: TLocal;
   /**
    * Callback for monitoring attachment changes in your data model
    */
@@ -64,6 +64,52 @@ export interface AttachmentQueueOptions {
   errorHandler?: AttachmentErrorHandler;
 }
 
+/**
+ * Configuration options for {@link AttachmentQueue}.
+ *
+ * Provide **exactly one** remote mechanism:
+ * - `remoteStorage` — a {@link RemoteStorageAdapter}, wrapped in the default
+ *   default buffered transport that delegates upload/download/delete to it.
+ * - `transportAdapter` — an {@link AttachmentTransportAdapter} that owns all remote
+ *   operations directly (e.g. a native file-URI implementation for buffer-free
+ *   transfer of large files). No `remoteStorage` is needed in this case.
+ *
+ * Supplying both, or neither, is a type error.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export type AttachmentQueueOptions<TLocal extends LocalStorageAdapter = LocalStorageAdapter> =
+  BaseAttachmentQueueOptions<TLocal> &
+    (
+      | { remoteStorage: RemoteStorageAdapter; transportAdapter?: never }
+      | { transportAdapter: AttachmentTransportAdapter; remoteStorage?: never }
+    );
+
+/**
+ * Fields shared by {@link AttachmentQueue.saveFile} and {@link AttachmentQueue.saveFileFromUri}.
+ *
+ * @alpha
+ */
+export interface SaveAttachmentOptions {
+  /** File extension (e.g., 'jpg', 'pdf') */
+  fileExtension: string;
+  /** MIME type of the file (e.g., 'image/jpeg') */
+  mediaType?: string;
+  /** Optional metadata to associate with the attachment */
+  metaData?: string;
+  /** Optional custom ID. If not provided, a UUID will be generated */
+  id?: string;
+  /**
+   * Optional callback to execute additional database operations within the same transaction as the
+   * attachment creation.
+   */
+  updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
+}
+
+/** How the file bytes reach managed storage when creating an upload attachment. */
+type AttachmentSource = { kind: 'data'; data: AttachmentData } | { kind: 'uri'; localUri: string };
+
 /**
  * AttachmentQueue manages the lifecycle and synchronization of attachments
  * between local and remote storage.
@@ -73,7 +119,7 @@ export interface AttachmentQueueOptions {
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export class AttachmentQueue {
+export class AttachmentQueue<TLocal extends LocalStorageAdapter = LocalStorageAdapter> {
   /** Timer for periodic synchronization operations */
   private periodicSyncTimer?: ReturnType<typeof setInterval>;
 
@@ -81,10 +127,7 @@ export class AttachmentQueue {
   private readonly syncingService: SyncingService;
 
   /** Adapter for local file storage operations */
-  readonly localStorage: LocalStorageAdapter;
-
-  /** Adapter for remote file storage operations */
-  readonly remoteStorage: RemoteStorageAdapter;
+  readonly localStorage: TLocal;
 
   /**
    * Callback function to watch for changes in attachment references in your data model.
@@ -159,6 +202,7 @@ export class AttachmentQueue {
     db,
     localStorage,
     remoteStorage,
+    transportAdapter,
     watchAttachments,
     logger,
     tableName = ATTACHMENT_TABLE,
@@ -167,10 +211,9 @@ export class AttachmentQueue {
     downloadAttachments = true,
     archivedCacheLimit = 100,
     errorHandler
-  }: AttachmentQueueOptions) {
+  }: AttachmentQueueOptions<TLocal>) {
     this.db = db;
     this.syncLoopMutex = db.createMutex();
-    this.remoteStorage = remoteStorage;
     this.localStorage = localStorage;
     this.watchAttachments = watchAttachments;
     this.tableName = tableName;
@@ -180,10 +223,13 @@ export class AttachmentQueue {
     this.downloadAttachments = downloadAttachments;
     this.logger = logger ?? db.logger;
     this.attachmentService = new AttachmentService(db, this.logger, tableName, archivedCacheLimit);
+
+    const transport = transportAdapter ?? new BufferedAttachmentTransport(localStorage, remoteStorage!);
+
     this.syncingService = new SyncingService(
       this.attachmentService,
       localStorage,
-      remoteStorage,
+      transport,
       this.logger,
       errorHandler
     );
@@ -408,49 +454,30 @@ export class AttachmentQueue {
     return this.attachmentService.withContext(callback);
   }
   /**
-   * Saves a file to local storage and queues it for upload to remote storage.
-   *
-   * @param options - File save options
-   * @returns Promise resolving to the created attachment record
+   * Creates a `QUEUED_UPLOAD` attachment record, placing the file at the managed
+   * `localUri` from the given `source`, and persists the record
+   * alongside the caller's `updateHook` in a single transaction.
    */
-  async saveFile({
-    data,
-    fileExtension,
-    mediaType,
-    metaData,
-    id,
-    updateHook
-  }: {
-    /**
-     * The file data as ArrayBuffer, Blob, or base64 string
-     */
-    data: AttachmentData;
-    /**
-     * File extension (e.g., 'jpg', 'pdf')
-     */
-    fileExtension: string;
-    /**
-     * MIME type of the file (e.g., 'image/jpeg')
-     */
-    mediaType?: string;
-    /**
-     * Optional metadata to associate with the attachment
-     */
-    metaData?: string;
-    /**
-     * Optional custom ID. If not provided, a UUID will be generated
-     */
-    id?: string;
-    /**
-     * Optional callback to execute additional database operations within the same transaction as the attachment
-     * creation.
-     */
-    updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
-  }): Promise<AttachmentRecord> {
+  private async createUploadAttachment(
+    { fileExtension, mediaType, metaData, id, updateHook }: SaveAttachmentOptions,
+    source: AttachmentSource
+  ): Promise<AttachmentRecord> {
     const resolvedId = id ?? (await this.generateAttachmentId());
     const filename = `${resolvedId}.${fileExtension}`;
     const localUri = this.localStorage.getLocalUri(filename);
-    const size = await this.localStorage.saveFile(localUri, data);
+
+    let size: number;
+    if (source.kind === 'data') {
+      size = await this.localStorage.saveFile(localUri, source.data);
+    } else {
+      // saveFileFromUri is only exposed for streaming-capable local adapters; guard at
+      // runtime too for plain-JS callers.
+      const localStorage = this.localStorage as Partial<StreamingLocalStorageAdapter>;
+      if (!localStorage.moveFile) {
+        throw new Error('The configured local storage adapter does not support moveFile, required by saveFileFromUri.');
+      }
+      size = await localStorage.moveFile(source.localUri, localUri);
+    }
 
     const attachment: AttachmentRecord = {
       id: resolvedId,
@@ -474,6 +501,37 @@ export class AttachmentQueue {
     return attachment;
   }
 
+  /**
+   * Saves in-memory file data to local storage and queues it for upload.
+   *
+   * @param options - File data plus {@link SaveAttachmentOptions}
+   * @returns Promise resolving to the created attachment record
+   */
+  async saveFile(options: SaveAttachmentOptions & { data: AttachmentData }): Promise<AttachmentRecord> {
+    return this.createUploadAttachment(options, { kind: 'data', data: options.data });
+  }
+
+  /**
+   * Registers a file that already exists on disk and queues it for upload, moving it
+   * into managed storage without loading it into memory.
+   *
+   * Prefer this over {@link AttachmentQueue.saveFile} for large, app-originated files
+   * (recordings, videos): it avoids reading the file into an `ArrayBuffer` just to write
+   * it back to disk. Requires the local storage adapter to implement `moveFile`.
+   *
+   * Only available when the queue is configured with a {@link StreamingLocalStorageAdapter}
+   * (one that implements `moveFile`).
+   *
+   * @param options - The existing file's `localUri` plus {@link SaveAttachmentOptions}
+   * @returns Promise resolving to the created attachment record
+   */
+  async saveFileFromUri(
+    this: AttachmentQueue<StreamingLocalStorageAdapter>,
+    options: SaveAttachmentOptions & { localUri: string }
+  ): Promise<AttachmentRecord> {
+    return this.createUploadAttachment(options, { kind: 'uri', localUri: options.localUri });
+  }
+
   async deleteFile({
     id,
     updateHook

package/src/attachments/AttachmentTransportAdapter.ts

@@ -0,0 +1,49 @@
+import { AttachmentRecord } from './Schema.js';
+
+/**
+ * An {@link AttachmentRecord} that is guaranteed to have a `localUri`.
+ *
+ * The syncing service assigns `localUri` before invoking a transport download,
+ * so implementations always receive both the metadata and the destination path.
+ *
+ * @alpha
+ */
+export type LocatedAttachmentRecord = AttachmentRecord & { localUri: string };
+
+/**
+ * AttachmentTransportAdapter owns all remote-side operations for an attachment —
+ * transfer (upload/download) and delete — as single operations.
+ *
+ * A transport owns the entire transfer, letting implementations pick the most
+ * efficient mechanism available (buffer, stream, or a platform-native file-URI
+ * upload/download API). On platforms like React Native this allows large files to
+ * be transferred without ever materializing them in the JS heap.
+ *
+ * The default transport composes the local and remote storage adapters. Provide a custom transport (via
+ * `AttachmentQueue`'s `transportAdapter` option) to own the whole remote side; in
+ * that case a separate `remoteStorage` is not required.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface AttachmentTransportAdapter {
+  /**
+   * Uploads the attachment's local file to remote storage.
+   * @param attachment - The attachment to upload. `localUri` points at the source file.
+   */
+  upload(attachment: LocatedAttachmentRecord): Promise<void>;
+
+  /**
+   * Downloads the remote file into `attachment.localUri`.
+   * @param attachment - The attachment to download. `localUri` is the destination path,
+   *                      assigned by the syncing service before this call.
+   */
+  download(attachment: LocatedAttachmentRecord): Promise<void>;
+
+  /**
+   * Deletes the attachment's file from remote storage. Local file removal is handled
+   * separately by the syncing service.
+   * @param attachment - The attachment to delete.
+   */
+  delete(attachment: AttachmentRecord): Promise<void>;
+}

package/src/attachments/BufferedAttachmentTransport.ts

@@ -0,0 +1,37 @@
+import { AttachmentTransportAdapter, LocatedAttachmentRecord } from './AttachmentTransportAdapter.js';
+import { LocalStorageAdapter } from './LocalStorageAdapter.js';
+import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
+import { AttachmentRecord } from './Schema.js';
+
+/**
+ * Default {@link AttachmentTransportAdapter}, composing the local and remote
+ * storage adapters.
+ *
+ * The full file body is materialized as an `ArrayBuffer` in JS memory between the
+ * two adapter calls. This is fine for small files but can cause memory pressure on
+ * large ones — environments that support native transfer should provide a custom
+ * transport instead.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export class BufferedAttachmentTransport implements AttachmentTransportAdapter {
+  constructor(
+    private localStorage: LocalStorageAdapter,
+    private remoteStorage: RemoteStorageAdapter
+  ) {}
+
+  async upload(attachment: LocatedAttachmentRecord): Promise<void> {
+    const fileData = await this.localStorage.readFile(attachment.localUri);
+    await this.remoteStorage.uploadFile(fileData, attachment);
+  }
+
+  async download(attachment: LocatedAttachmentRecord): Promise<void> {
+    const fileData = await this.remoteStorage.downloadFile(attachment);
+    await this.localStorage.saveFile(attachment.localUri, fileData);
+  }
+
+  async delete(attachment: AttachmentRecord): Promise<void> {
+    await this.remoteStorage.deleteFile(attachment);
+  }
+}

package/src/attachments/LocalStorageAdapter.ts

@@ -76,3 +76,23 @@ export interface LocalStorageAdapter {
    */
   getLocalUri(filename: string): string;
 }
+
+/**
+ * A {@link LocalStorageAdapter} that can relocate a file into managed storage without
+ * loading it into memory. Required for {@link AttachmentQueue.saveFileFromUri}; only
+ * queues configured with a streaming-capable local adapter expose that method.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface StreamingLocalStorageAdapter extends LocalStorageAdapter {
+  /**
+   * Moves a file into managed storage without loading it into memory.
+   * Overwrites any existing file at the target. When source and target are the same
+   * path, this is a no-op that just reports the size.
+   * @param sourceUri - Path of the existing file
+   * @param targetUri - Destination path within managed storage
+   * @returns Number of bytes in the moved file
+   */
+  moveFile(sourceUri: string, targetUri: string): Promise<number>;
+}

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,25 +10,28 @@ 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;
   }
@@ -114,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,
@@ -137,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
@@ -146,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,
@@ -181,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,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.
    *
@@ -343,7 +357,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