feat(attachments): streaming transport + saveFileFromUri

Model attachment byte-transfer as a single operation via AttachmentTransportAdapter,
with a default BufferedAttachmentTransport that composes the existing local/remote
adapters. Add AttachmentQueue.saveFileFromUri and an optional
LocalStorageAdapter.moveFile for buffer-free registration of files already on disk,
a native Expo ExpoFileSystemTransportAdapter, and moveFile in the Node and React
Native local adapters.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: khawarizmus

.changeset/attachment-streaming-transport.md

@@ -0,0 +1,7 @@
+---
+'@powersync/common': minor
+'@powersync/attachments-storage-react-native': minor
+'@powersync/node': minor
+---
+
+Add a streaming attachment transport (`AttachmentTransportAdapter` with a default `BufferedAttachmentTransport`, plus a native Expo `ExpoFileSystemTransportAdapter`) and `AttachmentQueue.saveFileFromUri`, so large files can be uploaded and downloaded without being buffered in JS memory.

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

@@ -81,6 +81,17 @@ To use the Expo File System attachment adapter please install expo-file-system (
     return buffer;
   }
 
+  async moveFile(sourceUri: string, targetUri: string): Promise<number> {
+    if (sourceUri !== targetUri) {
+      const target = new this.File(targetUri);
+      if (target.exists) {
+        target.delete();
+      }
+      new this.File(sourceUri).move(target);
+    }
+    return new this.File(targetUri).size ?? 0;
+  }
+
   async deleteFile(filePath: string): Promise<void> {
     try {
       const file = new this.File(filePath);

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

@@ -0,0 +1,140 @@
+import type { AttachmentTransportAdapter, LocatedAttachmentRecord } from '@powersync/common';
+
+/**
+ * Describes the HTTP request used to upload a file's bytes to remote storage.
+ * Typically points at a presigned URL.
+ */
+export interface ExpoUploadRequest {
+  /** Destination URL (e.g. a presigned upload URL). */
+  url: string;
+  /** HTTP method. Defaults to `PUT`. */
+  httpMethod?: 'POST' | 'PUT' | 'PATCH';
+  /** Additional request headers. */
+  headers?: Record<string, string>;
+  /**
+   * Upload encoding, matching Expo's `FileSystemUploadType`
+   * (`0` = binary content, `1` = multipart). Defaults to binary content.
+   */
+  uploadType?: number;
+  /** Form field name, used only for multipart uploads. */
+  fieldName?: string;
+  /** MIME type of the file. Defaults to the attachment's `mediaType`. */
+  mimeType?: string;
+}
+
+/**
+ * Describes the HTTP request used to download a file's bytes from remote storage.
+ * Typically points at a presigned URL.
+ */
+export interface ExpoDownloadRequest {
+  /** Source URL (e.g. a presigned download URL). */
+  url: string;
+  /** Additional request headers. */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Configuration for {@link ExpoFileSystemTransportAdapter}.
+ *
+ * The resolvers map an attachment to the request that transfers its bytes, keeping
+ * the transport agnostic of the remote storage backend (S3, Supabase, etc.).
+ */
+export interface ExpoFileSystemTransportAdapterOptions {
+  /** Resolves the upload request (e.g. a presigned URL) for an attachment. */
+  resolveUpload: (attachment: LocatedAttachmentRecord) => Promise<ExpoUploadRequest> | ExpoUploadRequest;
+  /** Resolves the download request (e.g. a presigned URL) for an attachment. */
+  resolveDownload: (attachment: LocatedAttachmentRecord) => Promise<ExpoDownloadRequest> | ExpoDownloadRequest;
+}
+
+type ExpoUploadResult = { status: number; body?: string };
+type ExpoDownloadResult = { status: number; uri: string };
+
+interface ExpoFileSystemLegacy {
+  uploadAsync(url: string, fileUri: string, options?: Record<string, unknown>): Promise<ExpoUploadResult>;
+  downloadAsync(uri: string, fileUri: string, options?: Record<string, unknown>): Promise<ExpoDownloadResult>;
+  FileSystemUploadType?: { BINARY_CONTENT: number; MULTIPART: number };
+}
+
+/** Upload encodings, mirroring Expo's `FileSystemUploadType`. */
+const UPLOAD_TYPE_BINARY_CONTENT = 0;
+
+/**
+ * ExpoFileSystemTransportAdapter transfers attachment bytes directly between a local
+ * file URI and remote storage using Expo's native `uploadAsync` / `downloadAsync`.
+ *
+ * The bytes never enter the JS heap, so large files can be transferred without the
+ * memory pressure of the buffer-based transport. Requires `expo-file-system` (its
+ * `uploadAsync` / `downloadAsync` functions, available via `expo-file-system/legacy`
+ * on SDK 54+).
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export class ExpoFileSystemTransportAdapter implements AttachmentTransportAdapter {
+  private fs: ExpoFileSystemLegacy;
+
+  constructor(private options: ExpoFileSystemTransportAdapterOptions) {
+    // `uploadAsync` / `downloadAsync` live in `expo-file-system/legacy` on SDK 54+,
+    // and in the main module on older SDKs. Metro only bundles static `require`
+    // string literals, so each candidate is required explicitly.
+    let resolved: ExpoFileSystemLegacy | undefined;
+    try {
+      const legacy = require('expo-file-system/legacy');
+      if (typeof legacy?.uploadAsync === 'function' && typeof legacy?.downloadAsync === 'function') {
+        resolved = legacy;
+      }
+    } catch {
+      // `/legacy` subpath not available on this SDK; fall back to the main module.
+    }
+    if (!resolved) {
+      try {
+        const main = require('expo-file-system');
+        if (typeof main?.uploadAsync === 'function' && typeof main?.downloadAsync === 'function') {
+          resolved = main;
+        }
+      } catch {
+        // expo-file-system not installed.
+      }
+    }
+
+    if (!resolved) {
+      throw new Error(`Could not resolve expo-file-system's uploadAsync/downloadAsync.
+To use the Expo File System transport please install expo-file-system.`);
+    }
+
+    this.fs = resolved;
+  }
+
+  async upload(attachment: LocatedAttachmentRecord): Promise<void> {
+    const request = await this.options.resolveUpload(attachment);
+    const binaryContent = this.fs.FileSystemUploadType?.BINARY_CONTENT ?? UPLOAD_TYPE_BINARY_CONTENT;
+
+    const result = await this.fs.uploadAsync(request.url, attachment.localUri, {
+      httpMethod: request.httpMethod ?? 'PUT',
+      uploadType: request.uploadType ?? binaryContent,
+      headers: request.headers,
+      fieldName: request.fieldName,
+      mimeType: request.mimeType ?? attachment.mediaType
+    });
+
+    if (!this.isOk(result.status)) {
+      throw new Error(`Upload for ${attachment.id} failed with status ${result.status}: ${result.body ?? ''}`);
+    }
+  }
+
+  async download(attachment: LocatedAttachmentRecord): Promise<void> {
+    const request = await this.options.resolveDownload(attachment);
+
+    const result = await this.fs.downloadAsync(request.url, attachment.localUri, {
+      headers: request.headers
+    });
+
+    if (!this.isOk(result.status)) {
+      throw new Error(`Download for ${attachment.id} failed with status ${result.status}`);
+    }
+  }
+
+  private isOk(status: number): boolean {
+    return status >= 200 && status < 300;
+  }
+}

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

@@ -71,6 +71,17 @@ To use the React Native File System attachment adapter please install @dr.pogodi
     return decodeBase64(content);
   }
 
+  async moveFile(sourceUri: string, targetUri: string): Promise<number> {
+    if (sourceUri !== targetUri) {
+      if (await this.rnfs.exists(targetUri)) {
+        await this.rnfs.unlink(targetUri);
+      }
+      await this.rnfs.moveFile(sourceUri, targetUri);
+    }
+    const stat = await this.rnfs.stat(targetUri);
+    return Number(stat.size);
+  }
+
   async deleteFile(filePath: string): Promise<void> {
     try {
       await this.rnfs.unlink(filePath);

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

@@ -1,2 +1,3 @@
 export * from './ExpoFileSystemStorageAdapter.js';
+export * from './ExpoFileSystemTransportAdapter.js';
 export * from './ReactNativeFileSystemStorageAdapter.js';

packages/common/src/attachments/AttachmentQueue.ts

@@ -5,6 +5,8 @@ import { Transaction } from '../db/DBAdapter.js';
 import { AttachmentContext } from './AttachmentContext.js';
 import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
 import { AttachmentService } from './AttachmentService.js';
+import { AttachmentTransportAdapter } from './AttachmentTransportAdapter.js';
+import { BufferedAttachmentTransport } from './BufferedAttachmentTransport.js';
 import { AttachmentData, LocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js';
@@ -31,6 +33,13 @@ export interface AttachmentQueueOptions {
    * Local storage adapter for file persistence
    */
   localStorage: LocalStorageAdapter;
+  /**
+   * Transport responsible for moving attachment bytes between local and remote storage.
+   * 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.
+   */
+  transportAdapter?: AttachmentTransportAdapter;
   /**
    * Callback for monitoring attachment changes in your data model
    */
@@ -159,6 +168,7 @@ export class AttachmentQueue {
     db,
     localStorage,
     remoteStorage,
+    transportAdapter,
     watchAttachments,
     logger,
     tableName = ATTACHMENT_TABLE,
@@ -184,6 +194,7 @@ export class AttachmentQueue {
       this.attachmentService,
       localStorage,
       remoteStorage,
+      transportAdapter ?? new BufferedAttachmentTransport(localStorage, remoteStorage),
       this.logger,
       errorHandler
     );
@@ -474,6 +485,83 @@ export class AttachmentQueue {
     return attachment;
   }
 
+  /**
+   * 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 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`.
+   *
+   * @param options - File registration options
+   * @returns Promise resolving to the created attachment record
+   * @throws Error if the local storage adapter does not support moving files
+   */
+  async saveFileFromUri({
+    localUri,
+    fileExtension,
+    mediaType,
+    metaData,
+    id,
+    updateHook
+  }: {
+    /**
+     * Path to the existing file on disk
+     */
+    localUri: string;
+    /**
+     * 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> {
+    if (!this.localStorage.moveFile) {
+      throw new Error('The configured local storage adapter does not support moveFile, required by saveFileFromUri.');
+    }
+
+    const resolvedId = id ?? (await this.generateAttachmentId());
+    const filename = `${resolvedId}.${fileExtension}`;
+    const targetUri = this.localStorage.getLocalUri(filename);
+    const size = await this.localStorage.moveFile(localUri, targetUri);
+
+    const attachment: AttachmentRecord = {
+      id: resolvedId,
+      filename,
+      mediaType,
+      localUri: targetUri,
+      state: AttachmentState.QUEUED_UPLOAD,
+      hasSynced: false,
+      size,
+      timestamp: new Date().getTime(),
+      metaData
+    };
+
+    await this.attachmentService.withContext(async (ctx) => {
+      await ctx.db.writeTransaction(async (tx) => {
+        await updateHook?.(tx, attachment);
+        await ctx.upsertAttachment(attachment, tx);
+      });
+    });
+
+    return attachment;
+  }
+
   async deleteFile({
     id,
     updateHook

packages/common/src/attachments/AttachmentTransportAdapter.ts

@@ -0,0 +1,39 @@
+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.
+ */
+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.
+ *
+ * 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.
+ *
+ * @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>;
+}

packages/common/src/attachments/BufferedAttachmentTransport.ts

@@ -0,0 +1,32 @@
+import { AttachmentTransportAdapter, LocatedAttachmentRecord } from './AttachmentTransportAdapter.js';
+import { LocalStorageAdapter } from './LocalStorageAdapter.js';
+import { RemoteStorageAdapter } from './RemoteStorageAdapter.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);
+  }
+}