Merge pull request #735 from powersync-ja/attachment-package-refactor

Update attachment package

Author: joshuabrink

.changeset/angry-planes-accept.md

@@ -0,0 +1,9 @@
+---
+'@powersync/react-native': minor
+'@powersync/common': minor
+'@powersync/node': minor
+'@powersync/web': minor
+'@powersync/attachments': patch
+---
+
+Deprecated @powersync/attachments in favor of enhanced and consistent attachment functionality built into @powersync/common and platform-specific SDKs

.changeset/new-attachments-react-native.md

@@ -0,0 +1,5 @@
+---
+'@powersync/attachments-storage-react-native': minor
+---
+
+Added new @powersync/attachments-storage-react-native package providing LocalStorageAdapter implementations for React Native environments. Includes ExpoFileSystemStorageAdapter and ReactNativeFileSystemStorageAdapter for device-based attachment file storage.

README.md

@@ -36,7 +36,11 @@ _[PowerSync](https://www.powersync.com) is a sync engine for building local-firs
 
 - [packages/attachments](./packages/attachments/README.md)
 
-  - Attachments helper package for React Native and JavaScript/TypeScript projects.
+  - Attachments helper package for React Native and JavaScript/TypeScript projects (deprecated).
+
+- [packages/attachments-storage-react-native](./packages/attachments-storage-react-native/README.md)
+
+  - React Native file system storage adapters for PowerSync attachments (alpha).
 
 - [packages/kysely-driver](./packages/kysely-driver/README.md)
 
@@ -51,7 +55,7 @@ _[PowerSync](https://www.powersync.com) is a sync engine for building local-firs
   - [OP-SQLite](https://github.com/OP-Engineering/op-sqlite) integration for React Native projects. Alternative to the default usage of [react-native-quick-sqlite](https://github.com/powersync-ja/react-native-quick-sqlite).
 
 - [packages/common](./packages/common/README.md)
-  - Shared package: TypeScript implementation of a PowerSync database connector and streaming sync bucket implementation.
+  - Shared package: TypeScript implementation of a PowerSync database connector, streaming sync bucket implementation and attachment utilities.
 
 ## Demo Apps / Example Projects
 

demos/react-native-supabase-todolist/app/views/todos/edit/[id].tsx

@@ -1,5 +1,4 @@
-import { ATTACHMENT_TABLE, AttachmentRecord } from '@powersync/attachments';
-import { usePowerSync, useQuery } from '@powersync/react-native';
+import { usePowerSync, useQuery, ATTACHMENT_TABLE, attachmentFromSql, AttachmentRecord } from '@powersync/react-native';
 import { CameraCapturedPicture } from 'expo-camera';
 import _ from 'lodash';
 import * as React from 'react';
@@ -12,21 +11,7 @@ import { TODO_TABLE, TodoRecord, LIST_TABLE } from '../../../../library/powersyn
 import { useSystem } from '../../../../library/powersync/system';
 import { TodoItemWidget } from '../../../../library/widgets/TodoItemWidget';
 
-type TodoEntry = TodoRecord & Partial<Omit<AttachmentRecord, 'id'>> & { todo_id: string; attachment_id: string | null };
-
-const toAttachmentRecord = _.memoize((entry: TodoEntry): AttachmentRecord | null => {
-  return entry.attachment_id == null
-    ? null
-    : {
-      id: entry.attachment_id,
-      filename: entry.filename!,
-      state: entry.state!,
-      timestamp: entry.timestamp,
-      local_uri: entry.local_uri,
-      media_type: entry.media_type,
-      size: entry.size
-    };
-});
+type TodoEntry = TodoRecord & { todo_id: string; attachment_id: string | null };
 
 const TodoView: React.FC = () => {
   const system = useSystem();
@@ -61,10 +46,10 @@ const TodoView: React.FC = () => {
     if (completed) {
       const userID = await system.supabaseConnector.userId();
       updatedRecord.completed_at = new Date().toISOString();
-      updatedRecord.completed_by = userID;
+      updatedRecord.completed_by = userID!;
     } else {
-      updatedRecord.completed_at = undefined;
-      updatedRecord.completed_by = undefined;
+      updatedRecord.completed_at = null;
+      updatedRecord.completed_by = null;
     }
     await system.powersync.execute(
       `UPDATE ${TODO_TABLE}
@@ -77,9 +62,13 @@ const TodoView: React.FC = () => {
   };
 
   const savePhoto = async (id: string, data: CameraCapturedPicture) => {
-    if (system.attachmentQueue) {
+    if (system.photoAttachmentQueue) {
       // We are sure the base64 is not null, as we are using the base64 option in the CameraWidget
-      const { id: photoId } = await system.attachmentQueue.savePhoto(data.base64!);
+      const { id: photoId } = await system.photoAttachmentQueue.saveFile({
+        data: data.base64!,
+        fileExtension: 'jpg',
+        mediaType: 'image/jpeg'
+      });
 
       await system.powersync.execute(`UPDATE ${TODO_TABLE} SET photo_id = ? WHERE id = ?`, [photoId, id]);
     }
@@ -99,12 +88,16 @@ const TodoView: React.FC = () => {
   };
 
   const deleteTodo = async (id: string, photoRecord?: AttachmentRecord) => {
-    await system.powersync.writeTransaction(async (tx) => {
-      if (system.attachmentQueue && photoRecord != null) {
-        await system.attachmentQueue.delete(photoRecord, tx);
-      }
-      await tx.execute(`DELETE FROM ${TODO_TABLE} WHERE id = ?`, [id]);
-    });
+    if (system.photoAttachmentQueue && photoRecord != null) {
+      await system.photoAttachmentQueue.deleteFile({
+        id: photoRecord.id,
+        updateHook: async (tx) => {
+          await tx.execute(`DELETE FROM ${TODO_TABLE} WHERE id = ?`, [id]);
+        }
+      });
+    } else {
+      await system.powersync.execute(`DELETE FROM ${TODO_TABLE} WHERE id = ?`, [id]);
+    }
   };
 
   if (isLoading) {
@@ -157,7 +150,7 @@ const TodoView: React.FC = () => {
       <ScrollView style={{ maxHeight: '90%' }}>
         {todos.map((r) => {
           const record = { ...r, id: r.todo_id };
-          const photoRecord = toAttachmentRecord(r);
+          const photoRecord = attachmentFromSql(r);
           return (
             <TodoItemWidget
               key={r.todo_id}

demos/react-native-supabase-todolist/library/powersync/AppSchema.ts

@@ -1,5 +1,5 @@
-import { AttachmentTable } from '@powersync/attachments';
 import { column, Schema, Table } from '@powersync/react-native';
+import { AttachmentTable } from '@powersync/common';
 
 export const LIST_TABLE = 'lists';
 export const TODO_TABLE = 'todos';
@@ -27,9 +27,7 @@ const lists = new Table({
 export const AppSchema = new Schema({
   todos,
   lists,
-  attachments: new AttachmentTable({
-    name: 'attachments',
-  }),
+  attachments: new AttachmentTable(),
 });
 
 export type Database = (typeof AppSchema)['types'];

demos/react-native-supabase-todolist/library/powersync/PhotoAttachmentQueue.ts

@@ -1,32 +1,41 @@
 import '@azure/core-asynciterator-polyfill';
 
-import { createBaseLogger, LogLevel, PowerSyncDatabase, SyncClientImplementation } from '@powersync/react-native';
+import {
+  createBaseLogger,
+  LogLevel,
+  PowerSyncDatabase,
+  SyncClientImplementation,
+  AttachmentQueue,
+  type AttachmentRecord,
+  type WatchedAttachmentItem,
+} from '@powersync/react-native';
+import { ReactNativeFileSystemStorageAdapter } from '@powersync/attachments-storage-react-native';
 import React from 'react';
-import { SupabaseStorageAdapter } from '../storage/SupabaseStorageAdapter';
-
-import { type AttachmentRecord } from '@powersync/attachments';
 import { configureFts } from '../fts/fts_setup';
 import { KVStorage } from '../storage/KVStorage';
+import { SupabaseRemoteStorageAdapter } from '../storage/SupabaseRemoteStorageAdapter';
 import { AppConfig } from '../supabase/AppConfig';
 import { SupabaseConnector } from '../supabase/SupabaseConnector';
-import { AppSchema } from './AppSchema';
-import { PhotoAttachmentQueue } from './PhotoAttachmentQueue';
+import { AppSchema, TODO_TABLE } from './AppSchema';
 
 const logger = createBaseLogger();
 logger.useDefaults();
 logger.setLevel(LogLevel.DEBUG);
 
 export class System {
   kvStorage: KVStorage;
-  storage: SupabaseStorageAdapter;
   supabaseConnector: SupabaseConnector;
   powersync: PowerSyncDatabase;
-  attachmentQueue: PhotoAttachmentQueue | undefined = undefined;
+  photoAttachmentQueue: AttachmentQueue | undefined = undefined;
 
   constructor() {
     this.kvStorage = new KVStorage();
-    this.supabaseConnector = new SupabaseConnector(this);
-    this.storage = this.supabaseConnector.storage;
+    this.supabaseConnector = new SupabaseConnector({
+      kvStorage: this.kvStorage,
+      supabaseUrl: AppConfig.supabaseUrl,
+      supabaseAnonKey: AppConfig.supabaseAnonKey
+    });
+
     this.powersync = new PowerSyncDatabase({
       schema: AppSchema,
       database: {
@@ -50,18 +59,48 @@ export class System {
      */
 
     if (AppConfig.supabaseBucket) {
-      this.attachmentQueue = new PhotoAttachmentQueue({
-        powersync: this.powersync,
-        storage: this.storage,
-        // Use this to handle download errors where you can use the attachment
-        // and/or the exception to decide if you want to retry the download
-        onDownloadError: async (attachment: AttachmentRecord, exception: any) => {
-          if (exception.toString() === 'StorageApiError: Object not found') {
-            return { retry: false };
-          }
+      const localStorage = new ReactNativeFileSystemStorageAdapter();
+      const remoteStorage = new SupabaseRemoteStorageAdapter({
+        client: this.supabaseConnector.client,
+        bucket: AppConfig.supabaseBucket
+      });
+
+      this.photoAttachmentQueue = new AttachmentQueue({
+        db: this.powersync,
+        localStorage,
+        remoteStorage,
+        watchAttachments: async (onUpdate, signal) => {
+          const watcher = this.powersync.watch(
+            `SELECT photo_id as id FROM ${TODO_TABLE} WHERE photo_id IS NOT NULL`,
+            [],
+            {
+              signal
+            }
+          );
 
-          return { retry: true };
-        }
+          for await (const result of watcher) {
+            const attachments: WatchedAttachmentItem[] = (result.rows?._array ?? []).map((row: any) => ({
+              id: row.id,
+              fileExtension: 'jpg'
+            }));
+            await onUpdate(attachments);
+          }
+        },
+        errorHandler: {
+          onDownloadError: async (attachment: AttachmentRecord, error: Error) => {
+            if (error.toString() === 'StorageApiError: Object not found') {
+              return false; // Don't retry
+            }
+            return true; // Retry
+          },
+          onUploadError: async (attachment: AttachmentRecord, error: Error) => {
+            return true; // Retry uploads by default
+          },
+          onDeleteError: async (attachment: AttachmentRecord, error: Error) => {
+            return true; // Retry deletes by default
+          }
+        },
+        logger
       });
     }
   }
@@ -70,8 +109,8 @@ export class System {
     await this.powersync.init();
     await this.powersync.connect(this.supabaseConnector, { clientImplementation: SyncClientImplementation.RUST });
 
-    if (this.attachmentQueue) {
-      await this.attachmentQueue.init();
+    if (this.photoAttachmentQueue) {
+      await this.photoAttachmentQueue.startSync();
     }
 
     // Demo using SQLite Full-Text Search with PowerSync.

demos/react-native-supabase-todolist/library/powersync/system.ts

@@ -0,0 +1,53 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import { AttachmentRecord, RemoteStorageAdapter } from '@powersync/react-native';
+
+export interface SupabaseRemoteStorageAdapterOptions {
+  client: SupabaseClient;
+  bucket: string;
+}
+
+/**
+ * SupabaseRemoteStorageAdapter implements RemoteStorageAdapter for Supabase Storage.
+ * Handles upload, download, and deletion of files from Supabase Storage buckets.
+ */
+export class SupabaseRemoteStorageAdapter implements RemoteStorageAdapter {
+  constructor(private options: SupabaseRemoteStorageAdapterOptions) {}
+
+  async uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord): Promise<void> {
+    const mediaType = attachment.mediaType ?? 'application/octet-stream';
+
+    const { error } = await this.options.client.storage
+      .from(this.options.bucket)
+      .upload(attachment.filename, fileData, { contentType: mediaType });
+
+    if (error) {
+      throw error;
+    }
+  }
+
+  async downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer> {
+    const { data, error } = await this.options.client.storage.from(this.options.bucket).download(attachment.filename);
+
+    if (error) {
+      throw error;
+    }
+
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onloadend = () => {
+        resolve(reader.result as ArrayBuffer);
+      };
+      reader.onerror = reject;
+      reader.readAsArrayBuffer(data);
+    });
+  }
+
+  async deleteFile(attachment: AttachmentRecord): Promise<void> {
+    const { error } = await this.options.client.storage.from(this.options.bucket).remove([attachment.filename]);
+
+    if (error) {
+      console.debug('Failed to delete file from Supabase Storage', error);
+      throw error;
+    }
+  }
+}