feat(attachments): add delete functionality to AttachmentTransportAdapter

Enhance AttachmentTransportAdapter to support file deletion operations.
This includes updates to ExpoFileSystemTransportAdapter and ReactNativeFSTransportAdapter
to implement the new deleteFile method. Additionally, adjustments were made to
AttachmentQueue and BufferedAttachmentTransport to integrate the delete functionality
into the attachment synchronization process.

Author: khawarizmus

packages/attachments-storage-react-native/src/ExpoFileSystemTransportAdapter.ts

@@ -1,4 +1,4 @@
-import type { AttachmentTransportAdapter, LocatedAttachmentRecord } from '@powersync/common';
+import type { AttachmentRecord, AttachmentTransportAdapter, LocatedAttachmentRecord } from '@powersync/common';
 
 /**
  * Describes the HTTP request used to upload a file's bytes to remote storage.
@@ -44,6 +44,11 @@ export interface ExpoFileSystemTransportAdapterOptions {
   resolveUpload: (attachment: LocatedAttachmentRecord) => Promise<ExpoUploadRequest> | ExpoUploadRequest;
   /** Resolves the download request (e.g. a presigned URL) for an attachment. */
   resolveDownload: (attachment: LocatedAttachmentRecord) => Promise<ExpoDownloadRequest> | ExpoDownloadRequest;
+  /**
+   * Deletes the attachment's file from remote storage (e.g. a storage SDK call or a
+   * `DELETE` request). Delete is a plain remote operation, not a file transfer.
+   */
+  deleteFile: (attachment: AttachmentRecord) => Promise<void>;
 }
 
 type ExpoUploadResult = { status: number; body?: string };
@@ -134,6 +139,10 @@ To use the Expo File System transport please install expo-file-system.`);
     }
   }
 
+  async delete(attachment: AttachmentRecord): Promise<void> {
+    await this.options.deleteFile(attachment);
+  }
+
   private isOk(status: number): boolean {
     return status >= 200 && status < 300;
   }

packages/attachments-storage-react-native/src/ReactNativeFSTransportAdapter.ts

@@ -1,4 +1,4 @@
-import type { AttachmentTransportAdapter, LocatedAttachmentRecord } from '@powersync/common';
+import type { AttachmentRecord, AttachmentTransportAdapter, LocatedAttachmentRecord } from '@powersync/common';
 
 /**
  * Describes the HTTP request used to upload a file's bytes to remote storage.
@@ -44,6 +44,11 @@ export interface ReactNativeFSTransportAdapterOptions {
   resolveDownload: (
     attachment: LocatedAttachmentRecord
   ) => Promise<ReactNativeFSDownloadRequest> | ReactNativeFSDownloadRequest;
+  /**
+   * Deletes the attachment's file from remote storage (e.g. a storage SDK call or a
+   * `DELETE` request). Delete is a plain remote operation, not a file transfer.
+   */
+  deleteFile: (attachment: AttachmentRecord) => Promise<void>;
 }
 
 /**
@@ -112,6 +117,10 @@ To use the React Native File System transport please install @dr.pogodin/react-n
     }
   }
 
+  async delete(attachment: AttachmentRecord): Promise<void> {
+    await this.options.deleteFile(attachment);
+  }
+
   /** react-native-fs expects plain filesystem paths, not `file://` URIs. */
   private toPath(uri: string): string {
     return uri.startsWith('file://') ? uri.slice('file://'.length) : uri;

packages/common/etc/common.api.md

@@ -96,7 +96,7 @@ export class AttachmentQueue {
     generateAttachmentId(): Promise<string>;
     readonly localStorage: LocalStorageAdapter;
     readonly logger: PowerSyncLogger;
-    readonly remoteStorage: RemoteStorageAdapter;
+    readonly remoteStorage?: RemoteStorageAdapter;
     saveFile(input: {
         data: AttachmentData;
         fileExtension: string;
@@ -131,7 +131,7 @@ export interface AttachmentQueueOptions {
     errorHandler?: AttachmentErrorHandler;
     localStorage: LocalStorageAdapter;
     logger?: PowerSyncLogger;
-    remoteStorage: RemoteStorageAdapter;
+    remoteStorage?: RemoteStorageAdapter;
     syncIntervalMs?: number;
     syncThrottleDuration?: number;
     tableName?: string;
@@ -189,6 +189,7 @@ export type AttachmentTableRecord = RowType<AttachmentTable>;
 
 // @alpha
 export interface AttachmentTransportAdapter {
+    delete(attachment: AttachmentRecord): Promise<void>;
     download(attachment: LocatedAttachmentRecord): Promise<void>;
     upload(attachment: LocatedAttachmentRecord): Promise<void>;
 }
@@ -261,6 +262,8 @@ export interface BatchedUpdateNotification {
 export class BufferedAttachmentTransport implements AttachmentTransportAdapter {
     constructor(localStorage: LocalStorageAdapter, remoteStorage: RemoteStorageAdapter);
     // (undocumented)
+    delete(attachment: AttachmentRecord): Promise<void>;
+    // (undocumented)
     download(attachment: LocatedAttachmentRecord): Promise<void>;
     // (undocumented)
     upload(attachment: LocatedAttachmentRecord): Promise<void>;

packages/common/src/attachments/AttachmentQueue.ts

@@ -26,18 +26,29 @@ export interface AttachmentQueueOptions {
    */
   db: CommonPowerSyncDatabase;
   /**
-   * Remote storage adapter for upload/download operations
+   * Remote storage adapter for upload/download/delete operations. Used to build the
+   * default {@link BufferedAttachmentTransport}, which delegates all three operations
+   * to it.
+   *
+   * Required unless a {@link AttachmentQueueOptions.transportAdapter} is provided. If
+   * both are provided, `transportAdapter` takes precedence and `remoteStorage` is
+   * completely unused.
    */
-  remoteStorage: RemoteStorageAdapter;
+  remoteStorage?: RemoteStorageAdapter;
   /**
    * Local storage adapter for file persistence
    */
   localStorage: LocalStorageAdapter;
   /**
-   * Transport responsible for moving attachment bytes between local and remote storage.
+   * Transport responsible for all remote attachment operations (upload/download/delete).
+   *
    * Defaults to a {@link BufferedAttachmentTransport} composed from `localStorage` and
    * `remoteStorage`. Provide a custom transport (e.g. a native file-URI implementation)
    * to transfer large files without materializing them in JS memory.
+   *
+   * When provided, the transport handles **all** remote operations directly and does
+   * not use `remoteStorage` — any `remoteStorage` passed alongside it is ignored, so
+   * implement delete on the transport itself.
    */
   transportAdapter?: AttachmentTransportAdapter;
   /**
@@ -92,8 +103,8 @@ export class AttachmentQueue {
   /** Adapter for local file storage operations */
   readonly localStorage: LocalStorageAdapter;
 
-  /** Adapter for remote file storage operations */
-  readonly remoteStorage: RemoteStorageAdapter;
+  /** Adapter for remote file storage operations. Undefined when a custom `transportAdapter` is used. */
+  readonly remoteStorage?: RemoteStorageAdapter;
 
   /**
    * Callback function to watch for changes in attachment references in your data model.
@@ -190,11 +201,16 @@ export class AttachmentQueue {
     this.downloadAttachments = downloadAttachments;
     this.logger = logger ?? db.logger;
     this.attachmentService = new AttachmentService(db, this.logger, tableName, archivedCacheLimit);
+
+    if (!transportAdapter && !remoteStorage) {
+      throw new Error('AttachmentQueue requires either a `remoteStorage` or a `transportAdapter`.');
+    }
+    const transport = transportAdapter ?? new BufferedAttachmentTransport(localStorage, remoteStorage!);
+
     this.syncingService = new SyncingService(
       this.attachmentService,
       localStorage,
-      remoteStorage,
-      transportAdapter ?? new BufferedAttachmentTransport(localStorage, remoteStorage),
+      transport,
       this.logger,
       errorHandler
     );

packages/common/src/attachments/AttachmentTransportAdapter.ts

@@ -11,16 +11,18 @@ import { AttachmentRecord } from './Schema.js';
 export type LocatedAttachmentRecord = AttachmentRecord & { localUri: string };
 
 /**
- * AttachmentTransportAdapter models the movement of an attachment's bytes between
- * local storage and remote storage as a single operation.
+ * 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.
  *
  * {@link BufferedAttachmentTransport} is the default, composing the local and
- * remote storage adapters.
+ * 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.
@@ -38,4 +40,11 @@ export interface AttachmentTransportAdapter {
    *                      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>;
 }

packages/common/src/attachments/BufferedAttachmentTransport.ts

@@ -1,6 +1,7 @@
 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
@@ -29,4 +30,8 @@ export class BufferedAttachmentTransport implements AttachmentTransportAdapter {
     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);
+  }
 }

packages/common/src/attachments/SyncingService.ts

@@ -2,7 +2,6 @@ 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';
@@ -11,27 +10,27 @@ 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;
@@ -182,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);
       }

packages/node/tests/attachments.test.ts

@@ -796,7 +796,8 @@ describe('attachment queue - transport', () => {
     const transportUpload = vi.fn().mockResolvedValue(undefined);
     const transportAdapter: AttachmentTransportAdapter = {
       upload: transportUpload,
-      download: vi.fn().mockResolvedValue(undefined)
+      download: vi.fn().mockResolvedValue(undefined),
+      delete: vi.fn().mockResolvedValue(undefined)
     };
 
     const q = new AttachmentQueue({
@@ -841,7 +842,8 @@ describe('attachment queue - transport', () => {
     });
     const transportAdapter: AttachmentTransportAdapter = {
       upload: vi.fn().mockResolvedValue(undefined),
-      download: transportDownload
+      download: transportDownload,
+      delete: vi.fn().mockResolvedValue(undefined)
     };
 
     const q = new AttachmentQueue({
@@ -878,6 +880,75 @@ describe('attachment queue - transport', () => {
     const record = attachments.find((r) => r.id === id)!;
     expect(await mockLocalStorage.fileExists(record.localUri!)).toBe(true);
   });
+
+  // A custom transport replaces remoteStorage for ALL remote operations. Upload and
+  // download are covered by the two tests above; this covers the delete slice.
+  it('delete goes through the custom transport (not remoteStorage)', async () => {
+    const transportDelete = vi.fn().mockResolvedValue(undefined);
+    const transportAdapter: AttachmentTransportAdapter = {
+      upload: vi.fn().mockResolvedValue(undefined),
+      download: vi.fn(async (attachment: AttachmentRecord & { localUri: string }) => {
+        await mockLocalStorage.saveFile(attachment.localUri, createMockJpegBuffer());
+      }),
+      delete: transportDelete
+    };
+
+    const q = new AttachmentQueue({
+      db,
+      watchAttachments,
+      remoteStorage: mockRemoteStorage,
+      localStorage: mockLocalStorage,
+      transportAdapter,
+      syncIntervalMs: INTERVAL_MILLISECONDS,
+      archivedCacheLimit: 0
+    });
+    onTestFinished(() => q.stopSync());
+
+    await q.startSync();
+
+    const id = await q.generateAttachmentId();
+    await db.execute('INSERT INTO users (id, name, email, photo_id) VALUES (uuid(), ?, ?, ?)', [
+      'deleter',
+      'deleter@example.com',
+      id
+    ]);
+    await waitForMatchCondition(
+      () => watchAttachmentsTable(),
+      (results) => results.some((r) => r.id === id && r.state === AttachmentState.SYNCED),
+      5
+    );
+
+    await q.deleteFile({
+      id,
+      updateHook: async (tx) => {
+        await tx.execute('UPDATE users SET photo_id = NULL WHERE photo_id = ?', [id]);
+      }
+    });
+
+    await waitForMatchCondition(
+      () => watchAttachmentsTable(),
+      (results) => !results.some((r) => r.id === id),
+      5
+    );
+
+    // With a custom transport present, it owns delete; the passed-alongside
+    // remoteStorage.deleteFile is not used.
+    expect(transportDelete).toHaveBeenCalled();
+    expect(mockDeleteFile).not.toHaveBeenCalled();
+  });
+
+  it('throws when neither remoteStorage nor transportAdapter is provided', () => {
+    expect(
+      () =>
+        new AttachmentQueue({
+          db,
+          watchAttachments,
+          localStorage: mockLocalStorage,
+          syncIntervalMs: INTERVAL_MILLISECONDS,
+          archivedCacheLimit: 0
+        })
+    ).toThrow(/remoteStorage/);
+  });
 });
 
 describe('attachment queue - saveFileFromUri', () => {