refactor(attachments): update local storage adapter interfaces to support streaming

This commit refines the local storage adapter interfaces by replacing the `LocalStorageAdapter` with `StreamingLocalStorageAdapter` in multiple components, including `ExpoFileSystemStorageAdapter`, `ReactNativeFileSystemStorageAdapter`, and `NodeFileSystemAdapter`. The `AttachmentQueue` and related types have been updated to leverage the new streaming capabilities, ensuring that the `saveFileFromUri` method is only available when a streaming-capable adapter is used. Documentation has been adjusted to reflect these changes.

Author: khawarizmus

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

@@ -1,5 +1,5 @@
 import { decode as decodeBase64 } from 'base64-arraybuffer';
-import type { AttachmentData, LocalStorageAdapter } from '@powersync/common';
+import type { AttachmentData, StreamingLocalStorageAdapter } from '@powersync/common';
 import type { File, Directory } from 'expo-file-system';
 
 /**
@@ -9,7 +9,7 @@ import type { File, Directory } from 'expo-file-system';
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export class ExpoFileSystemStorageAdapter implements LocalStorageAdapter {
+export class ExpoFileSystemStorageAdapter implements StreamingLocalStorageAdapter {
   private File: typeof File;
   private Directory: typeof Directory;
   private storageDir: Directory;

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

@@ -1,5 +1,5 @@
 import { decode as decodeBase64, encode as encodeBase64 } from 'base64-arraybuffer';
-import type { AttachmentData, LocalStorageAdapter } from '@powersync/common';
+import type { AttachmentData, StreamingLocalStorageAdapter } from '@powersync/common';
 
 /**
  * ReactNativeFileSystemStorageAdapter implements LocalStorageAdapter using @dr.pogodin/react-native-fs.
@@ -8,7 +8,7 @@ import type { AttachmentData, LocalStorageAdapter } from '@powersync/common';
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export class ReactNativeFileSystemStorageAdapter implements LocalStorageAdapter {
+export class ReactNativeFileSystemStorageAdapter implements StreamingLocalStorageAdapter {
   private rnfs: typeof import('@dr.pogodin/react-native-fs');
   private storageDirectory: string;
 

packages/common/etc/common.api.md

@@ -80,8 +80,8 @@ export interface AttachmentErrorHandler {
 export function attachmentFromSql(row: any): AttachmentRecord;
 
 // @alpha
-export class AttachmentQueue {
-    constructor(input: AttachmentQueueOptions);
+export class AttachmentQueue<TLocal extends LocalStorageAdapter = LocalStorageAdapter> {
+    constructor(input: AttachmentQueueOptions<TLocal>);
     readonly archivedCacheLimit: number;
     // (undocumented)
     clearQueue(): Promise<void>;
@@ -94,12 +94,12 @@ export class AttachmentQueue {
     // (undocumented)
     expireCache(): Promise<void>;
     generateAttachmentId(): Promise<string>;
-    readonly localStorage: LocalStorageAdapter;
+    readonly localStorage: TLocal;
     readonly logger: PowerSyncLogger;
     saveFile(options: SaveAttachmentOptions & {
         data: AttachmentData;
     }): Promise<AttachmentRecord>;
-    saveFileFromUri(options: SaveAttachmentOptions & {
+    saveFileFromUri(this: AttachmentQueue<StreamingLocalStorageAdapter>, options: SaveAttachmentOptions & {
         localUri: string;
     }): Promise<AttachmentRecord>;
     startSync(): Promise<void>;
@@ -113,7 +113,7 @@ export class AttachmentQueue {
 }
 
 // @alpha
-export type AttachmentQueueOptions = BaseAttachmentQueueOptions & ({
+export type AttachmentQueueOptions<TLocal extends LocalStorageAdapter = LocalStorageAdapter> = BaseAttachmentQueueOptions<TLocal> & ({
     remoteStorage: RemoteStorageAdapter;
     transportAdapter?: never;
 } | {
@@ -177,12 +177,12 @@ export interface AttachmentTransportAdapter {
 }
 
 // @alpha
-export interface BaseAttachmentQueueOptions {
+export interface BaseAttachmentQueueOptions<TLocal extends LocalStorageAdapter = LocalStorageAdapter> {
     archivedCacheLimit?: number;
     db: CommonPowerSyncDatabase;
     downloadAttachments?: boolean;
     errorHandler?: AttachmentErrorHandler;
-    localStorage: LocalStorageAdapter;
+    localStorage: TLocal;
     logger?: PowerSyncLogger;
     syncIntervalMs?: number;
     syncThrottleDuration?: number;
@@ -663,7 +663,6 @@ export interface LocalStorageAdapter {
     getLocalUri(filename: string): string;
     initialize(): Promise<void>;
     makeDir(path: string): Promise<void>;
-    moveFile?(sourceUri: string, targetUri: string): Promise<number>;
     readFile(filePath: string): Promise<ArrayBuffer>;
     rmDir(path: string): Promise<void>;
     saveFile(filePath: string, data: AttachmentData): Promise<number>;
@@ -1015,6 +1014,11 @@ export interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOption
     placeholderData?: RowType[];
 }
 
+// @alpha
+export interface StreamingLocalStorageAdapter extends LocalStorageAdapter {
+    moveFile(sourceUri: string, targetUri: string): Promise<number>;
+}
+
 // Warning: (ae-forgotten-export) The symbol "JSONValue" needs to be exported by the entry point index.d.ts
 //
 // @public (undocumented)

packages/common/src/attachments/AttachmentQueue.ts

@@ -7,7 +7,7 @@ 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 { AttachmentData, LocalStorageAdapter, StreamingLocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js';
 import { SyncingService } from './SyncingService.js';
@@ -20,15 +20,17 @@ import { CommonPowerSyncDatabase } from '../client/CommonPowerSyncDatabase.js';
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export interface BaseAttachmentQueueOptions {
+export interface BaseAttachmentQueueOptions<TLocal extends LocalStorageAdapter = LocalStorageAdapter> {
   /**
    * PowerSync database instance
    */
   db: CommonPowerSyncDatabase;
   /**
-   * 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
    */
@@ -77,11 +79,12 @@ export interface BaseAttachmentQueueOptions {
  * @experimental
  * @alpha This is currently experimental and may change without a major version bump.
  */
-export type AttachmentQueueOptions = BaseAttachmentQueueOptions &
-  (
-    | { remoteStorage: RemoteStorageAdapter; transportAdapter?: never }
-    | { transportAdapter: AttachmentTransportAdapter; remoteStorage?: never }
-  );
+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}.
@@ -116,15 +119,15 @@ type AttachmentSource = { kind: 'data'; data: AttachmentData } | { kind: 'uri';
  * @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>;
 
   /** Service for synchronizing attachments between local and remote storage */
   private readonly syncingService: SyncingService;
 
   /** Adapter for local file storage operations */
-  readonly localStorage: LocalStorageAdapter;
+  readonly localStorage: TLocal;
 
   /**
    * Callback function to watch for changes in attachment references in your data model.
@@ -208,7 +211,7 @@ export class AttachmentQueue {
     downloadAttachments = true,
     archivedCacheLimit = 100,
     errorHandler
-  }: AttachmentQueueOptions) {
+  }: AttachmentQueueOptions<TLocal>) {
     this.db = db;
     this.syncLoopMutex = db.createMutex();
     this.localStorage = localStorage;
@@ -470,10 +473,13 @@ export class AttachmentQueue {
     if (source.kind === 'data') {
       size = await this.localStorage.saveFile(localUri, source.data);
     } else {
-      if (!this.localStorage.moveFile) {
+      // 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 this.localStorage.moveFile(source.localUri, localUri);
+      size = await localStorage.moveFile(source.localUri, localUri);
     }
 
     const attachment: AttachmentRecord = {
@@ -516,11 +522,16 @@ export class AttachmentQueue {
    * (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
-   * @throws Error if the local storage adapter does not support moving files
    */
-  async saveFileFromUri(options: SaveAttachmentOptions & { localUri: string }): Promise<AttachmentRecord> {
+  async saveFileFromUri(
+    this: AttachmentQueue<StreamingLocalStorageAdapter>,
+    options: SaveAttachmentOptions & { localUri: string }
+  ): Promise<AttachmentRecord> {
     return this.createUploadAttachment(options, { kind: 'uri', localUri: options.localUri });
   }
 

packages/common/src/attachments/LocalStorageAdapter.ts

@@ -34,20 +34,6 @@ export interface LocalStorageAdapter {
    */
   readFile(filePath: string): Promise<ArrayBuffer>;
 
-  /**
-   * Moves a file into managed storage without loading it into memory.
-   * Used by {@link AttachmentQueue.saveFileFromUri} to register a file that already
-   * exists on disk. 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.
-   *
-   * Optional: adapters that cannot move files natively may omit this, in which case
-   * {@link AttachmentQueue.saveFileFromUri} is unavailable.
-   * @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>;
-
   /**
    * Deletes the file at the given path.
    * @param filePath - Path where the file is stored
@@ -90,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>;
+}

packages/node/src/attachments/NodeFileSystemAdapter.ts

@@ -1,12 +1,12 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
-import { AttachmentData, EncodingType, LocalStorageAdapter } from '@powersync/common';
+import { AttachmentData, EncodingType, StreamingLocalStorageAdapter } from '@powersync/common';
 
 /**
  * NodeFileSystemAdapter implements LocalStorageAdapter using Node.js filesystem.
  * Suitable for Node.js environments and Electron applications.
  */
-export class NodeFileSystemAdapter implements LocalStorageAdapter {
+export class NodeFileSystemAdapter implements StreamingLocalStorageAdapter {
   constructor(private storageDirectory: string = './user_data') {}
 
   async initialize(): Promise<void> {

packages/react-native/android/.gitignore

@@ -1 +1,2 @@
-build/
+build/
+.gradle/