refactor(attachments): streamline AttachmentQueue and transport adapter interfaces

This commit refines the AttachmentQueue and transport adapter interfaces by consolidating configuration options and enhancing type safety. The `AttachmentQueueOptions` now requires either a `remoteStorage` or a `transportAdapter`, ensuring clarity in usage. Additionally, the `saveFile` and `saveFileFromUri` methods have been updated to utilize a unified `SaveAttachmentOptions` type, improving consistency across attachment operations. Documentation in the README.md has also been updated to reflect these changes.

Author: khawarizmus

packages/attachments-storage-react-native/README.md

@@ -85,7 +85,9 @@ const localStorage = new ExpoFileSystemStorageAdapter('/custom/path/to/attachmen
 
 ## Streaming transport adapters
 
-A transport adapter owns **all** remote operations (`upload` / `download` / `delete`) and transfers bytes natively — the file never enters the JS heap. When a `transportAdapter` is provided it fully replaces `remoteStorage` (which is no longer required); implement remote delete via the `deleteFile` callback.
+A transport adapter owns **all** remote operations (`upload` / `download` / `delete`) and transfers bytes natively — the file never enters the JS heap. Implement remote delete via the `deleteFile` callback.
+
+The queue takes **exactly one** remote mechanism: either `remoteStorage` or `transportAdapter`. A `transportAdapter` replaces `remoteStorage` entirely, so none is needed alongside it.
 
 Both transports are backend-agnostic: you supply resolver callbacks that map an attachment to a request (typically a presigned URL from your backend).
 

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

@@ -51,6 +51,7 @@ export interface ExpoFileSystemTransportAdapterOptions {
   deleteFile: (attachment: AttachmentRecord) => Promise<void>;
 }
 
+/** The `expo-file-system` legacy API surface this adapter resolves and uses at runtime. */
 type ExpoUploadResult = { status: number; body?: string };
 type ExpoDownloadResult = { status: number; uri: string };
 

packages/common/etc/common.api.md

@@ -96,22 +96,11 @@ export class AttachmentQueue {
     generateAttachmentId(): Promise<string>;
     readonly localStorage: LocalStorageAdapter;
     readonly logger: PowerSyncLogger;
-    readonly remoteStorage?: RemoteStorageAdapter;
-    saveFile(input: {
+    saveFile(options: SaveAttachmentOptions & {
         data: AttachmentData;
-        fileExtension: string;
-        mediaType?: string;
-        metaData?: string;
-        id?: string;
-        updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
     }): Promise<AttachmentRecord>;
-    saveFileFromUri(input: {
+    saveFileFromUri(options: SaveAttachmentOptions & {
         localUri: string;
-        fileExtension: string;
-        mediaType?: string;
-        metaData?: string;
-        id?: string;
-        updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
     }): Promise<AttachmentRecord>;
     startSync(): Promise<void>;
     stopSync(): Promise<void>;
@@ -124,20 +113,13 @@ export class AttachmentQueue {
 }
 
 // @alpha
-export interface AttachmentQueueOptions {
-    archivedCacheLimit?: number;
-    db: CommonPowerSyncDatabase;
-    downloadAttachments?: boolean;
-    errorHandler?: AttachmentErrorHandler;
-    localStorage: LocalStorageAdapter;
-    logger?: PowerSyncLogger;
-    remoteStorage?: RemoteStorageAdapter;
-    syncIntervalMs?: number;
-    syncThrottleDuration?: number;
-    tableName?: string;
-    transportAdapter?: AttachmentTransportAdapter;
-    watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
-}
+export type AttachmentQueueOptions = BaseAttachmentQueueOptions & ({
+    remoteStorage: RemoteStorageAdapter;
+    transportAdapter?: never;
+} | {
+    transportAdapter: AttachmentTransportAdapter;
+    remoteStorage?: never;
+});
 
 // @alpha
 export interface AttachmentRecord {
@@ -194,6 +176,20 @@ export interface AttachmentTransportAdapter {
     upload(attachment: LocatedAttachmentRecord): Promise<void>;
 }
 
+// @alpha
+export interface BaseAttachmentQueueOptions {
+    archivedCacheLimit?: number;
+    db: CommonPowerSyncDatabase;
+    downloadAttachments?: boolean;
+    errorHandler?: AttachmentErrorHandler;
+    localStorage: LocalStorageAdapter;
+    logger?: PowerSyncLogger;
+    syncIntervalMs?: number;
+    syncThrottleDuration?: number;
+    tableName?: string;
+    watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
+}
+
 // @public (undocumented)
 export type BaseColumnType<T extends number | string | null> = {
     type: ColumnType;
@@ -258,17 +254,6 @@ export interface BatchedUpdateNotification {
     tables: string[];
 }
 
-// @alpha
-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>;
-}
-
 // @public (undocumented)
 export class Column {
     constructor(options: ColumnOptions);
@@ -944,6 +929,15 @@ export function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): st
 // @alpha
 export function sanitizeUUID(uuid: string): string;
 
+// @alpha
+export interface SaveAttachmentOptions {
+    fileExtension: string;
+    id?: string;
+    mediaType?: string;
+    metaData?: string;
+    updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
+}
+
 // Warning: (ae-forgotten-export) The symbol "SchemaType" needs to be exported by the entry point index.d.ts
 //
 // @public