@powersync/common 1.46.0 → 1.47.0

package/src/attachments/RemoteStorageAdapter.ts

@@ -0,0 +1,30 @@
+import { AttachmentRecord } from './Schema.js';
+
+/**
+ * RemoteStorageAdapter defines the interface for remote storage operations.
+ * Implementations handle uploading, downloading, and deleting files from remote storage.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface RemoteStorageAdapter {
+  /**
+   * Uploads a file to remote storage.
+   * @param fileData The binary content of the file to upload
+   * @param attachment The associated attachment metadata
+   */
+  uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord): Promise<void>;
+
+  /**
+   * Downloads a file from remote storage.
+   * @param attachment The attachment describing the file to download
+   * @returns The binary data of the downloaded file
+   */
+  downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer>;
+
+  /**
+   * Deletes a file from remote storage.
+   * @param attachment The attachment describing the file to delete
+   */
+  deleteFile(attachment: AttachmentRecord): Promise<void>;
+}

package/src/attachments/Schema.ts

@@ -0,0 +1,87 @@
+import { column } from '../db/schema/Column.js';
+import { Table } from '../db/schema/Table.js';
+import { TableV2Options } from '../db/schema/Table.js';
+
+export const ATTACHMENT_TABLE = 'attachments';
+
+/**
+ * AttachmentRecord represents an attachment in the local database.
+ *
+ * @experimental
+ */
+export interface AttachmentRecord {
+  id: string;
+  filename: string;
+  localUri?: string;
+  size?: number;
+  mediaType?: string;
+  timestamp?: number;
+  metaData?: string;
+  hasSynced?: boolean;
+  state: AttachmentState;
+}
+
+/**
+ * Maps a database row to an AttachmentRecord.
+ *
+ * @param row - The database row object
+ * @returns The corresponding AttachmentRecord
+ *
+ * @experimental
+ */
+export function attachmentFromSql(row: any): AttachmentRecord {
+  return {
+    id: row.id,
+    filename: row.filename,
+    localUri: row.local_uri,
+    size: row.size,
+    mediaType: row.media_type,
+    timestamp: row.timestamp,
+    metaData: row.meta_data,
+    hasSynced: row.has_synced === 1,
+    state: row.state
+  };
+}
+
+/**
+ * AttachmentState represents the current synchronization state of an attachment.
+ *
+ * @experimental
+ */
+export enum AttachmentState {
+  QUEUED_UPLOAD = 0, // Attachment to be uploaded
+  QUEUED_DOWNLOAD = 1, // Attachment to be downloaded
+  QUEUED_DELETE = 2, // Attachment to be deleted
+  SYNCED = 3, // Attachment has been synced
+  ARCHIVED = 4 // Attachment has been orphaned, i.e. the associated record has been deleted
+}
+
+export interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {}
+
+/**
+ * AttachmentTable defines the schema for the attachment queue table.
+ *
+ * @internal
+ */
+export class AttachmentTable extends Table {
+  constructor(options?: AttachmentTableOptions) {
+    super(
+      {
+        filename: column.text,
+        local_uri: column.text,
+        timestamp: column.integer,
+        size: column.integer,
+        media_type: column.text,
+        state: column.integer, // Corresponds to AttachmentState
+        has_synced: column.integer,
+        meta_data: column.text
+      },
+      {
+        ...options,
+        viewName: options?.viewName ?? ATTACHMENT_TABLE,
+        localOnly: true,
+        insertOnly: false
+      }
+    );
+  }
+}

package/src/attachments/SyncingService.ts

@@ -0,0 +1,193 @@
+import { ILogger } from '../utils/Logger.js';
+import { AttachmentService } from './AttachmentService.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';
+
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+export class SyncingService {
+  private attachmentService: AttachmentService;
+  private localStorage: LocalStorageAdapter;
+  private remoteStorage: RemoteStorageAdapter;
+  private logger: ILogger;
+  private errorHandler?: AttachmentErrorHandler;
+
+  constructor(
+    attachmentService: AttachmentService,
+    localStorage: LocalStorageAdapter,
+    remoteStorage: RemoteStorageAdapter,
+    logger: ILogger,
+    errorHandler?: AttachmentErrorHandler
+  ) {
+    this.attachmentService = attachmentService;
+    this.localStorage = localStorage;
+    this.remoteStorage = remoteStorage;
+    this.logger = logger;
+    this.errorHandler = errorHandler;
+  }
+
+  /**
+   * Processes attachments based on their state (upload, download, or delete).
+   * All updates are saved in a single batch after processing.
+   *
+   * @param attachments - Array of attachment records to process
+   * @param context - Attachment context for database operations
+   * @returns Promise that resolves when all attachments have been processed and saved
+   */
+  async processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void> {
+    const updatedAttachments: AttachmentRecord[] = [];
+    for (const attachment of attachments) {
+      switch (attachment.state) {
+        case AttachmentState.QUEUED_UPLOAD:
+          const uploaded = await this.uploadAttachment(attachment);
+          updatedAttachments.push(uploaded);
+          break;
+        case AttachmentState.QUEUED_DOWNLOAD:
+          const downloaded = await this.downloadAttachment(attachment);
+          updatedAttachments.push(downloaded);
+          break;
+        case AttachmentState.QUEUED_DELETE:
+          const deleted = await this.deleteAttachment(attachment);
+          updatedAttachments.push(deleted);
+          break;
+
+        default:
+          break;
+      }
+    }
+
+    await context.saveAttachments(updatedAttachments);
+  }
+
+  /**
+   * Uploads an attachment from local storage to remote storage.
+   * On success, marks as SYNCED. On failure, defers to error handler or archives.
+   *
+   * @param attachment - The attachment record to upload
+   * @returns Updated attachment record with new state
+   * @throws Error if the attachment has no localUri
+   */
+  async uploadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord> {
+    this.logger.info(`Uploading attachment ${attachment.filename}`);
+    try {
+      if (attachment.localUri == null) {
+        throw new Error(`No localUri for attachment ${attachment.id}`);
+      }
+
+      const fileBlob = await this.localStorage.readFile(attachment.localUri);
+      await this.remoteStorage.uploadFile(fileBlob, attachment);
+
+      return {
+        ...attachment,
+        state: AttachmentState.SYNCED,
+        hasSynced: true
+      };
+    } catch (error) {
+      const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
+      if (!shouldRetry) {
+        return {
+          ...attachment,
+          state: AttachmentState.ARCHIVED
+        };
+      }
+
+      return attachment;
+    }
+  }
+
+  /**
+   * Downloads an attachment from remote storage to local storage.
+   * Retrieves the file, converts to base64, and saves locally.
+   * On success, marks as SYNCED. On failure, defers to error handler or archives.
+   *
+   * @param attachment - The attachment record to download
+   * @returns Updated attachment record with local URI and new state
+   */
+  async downloadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord> {
+    this.logger.info(`Downloading attachment ${attachment.filename}`);
+    try {
+      const fileData = await this.remoteStorage.downloadFile(attachment);
+
+      const localUri = this.localStorage.getLocalUri(attachment.filename);
+      await this.localStorage.saveFile(localUri, fileData);
+
+      return {
+        ...attachment,
+        state: AttachmentState.SYNCED,
+        localUri: localUri,
+        hasSynced: true
+      };
+    } catch (error) {
+      const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
+      if (!shouldRetry) {
+        return {
+          ...attachment,
+          state: AttachmentState.ARCHIVED
+        };
+      }
+
+      return attachment;
+    }
+  }
+
+  /**
+   * Deletes an attachment from both remote and local storage.
+   * Removes the remote file, local file (if exists), and the attachment record.
+   * On failure, defers to error handler or archives.
+   *
+   * @param attachment - The attachment record to delete
+   * @returns Updated attachment record
+   */
+  async deleteAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord> {
+    try {
+      await this.remoteStorage.deleteFile(attachment);
+      if (attachment.localUri) {
+        await this.localStorage.deleteFile(attachment.localUri);
+      }
+
+      await this.attachmentService.withContext(async (ctx) => {
+        await ctx.deleteAttachment(attachment.id);
+      });
+
+      return {
+        ...attachment,
+        state: AttachmentState.ARCHIVED
+      };
+    } catch (error) {
+      const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
+      if (!shouldRetry) {
+        return {
+          ...attachment,
+          state: AttachmentState.ARCHIVED
+        };
+      }
+
+      return attachment;
+    }
+  }
+
+  /**
+   * Performs cleanup of archived attachments by removing their local files and records.
+   * Errors during local file deletion are logged but do not prevent record deletion.
+   */
+  async deleteArchivedAttachments(context: AttachmentContext): Promise<boolean> {
+    return await context.deleteArchivedAttachments(async (archivedAttachments) => {
+      for (const attachment of archivedAttachments) {
+        if (attachment.localUri) {
+          try {
+            await this.localStorage.deleteFile(attachment.localUri);
+          } catch (error) {
+            this.logger.error('Error deleting local file for archived attachment', error);
+          }
+        }
+      }
+    });
+  }
+}

package/src/attachments/WatchedAttachmentItem.ts

@@ -0,0 +1,19 @@
+/**
+ * WatchedAttachmentItem represents an attachment reference in your application's data model.
+ * Use either filename OR fileExtension (not both).
+ *
+ * @experimental
+ */
+export type WatchedAttachmentItem =
+  | {
+      id: string;
+      filename: string;
+      fileExtension?: never;
+      metaData?: string;
+    }
+  | {
+      id: string;
+      fileExtension: string;
+      filename?: never;
+      metaData?: string;
+    };

package/src/index.ts

@@ -1,3 +1,13 @@
+export * from './attachments/AttachmentContext.js';
+export * from './attachments/AttachmentErrorHandler.js';
+export * from './attachments/AttachmentQueue.js';
+export * from './attachments/AttachmentService.js';
+export * from './attachments/LocalStorageAdapter.js';
+export * from './attachments/RemoteStorageAdapter.js';
+export * from './attachments/Schema.js';
+export * from './attachments/SyncingService.js';
+export * from './attachments/WatchedAttachmentItem.js';
+
 export * from './client/AbstractPowerSyncDatabase.js';
 export * from './client/AbstractPowerSyncOpenFactory.js';
 export { compilableQueryWatch, CompilableQueryWatchHandler } from './client/compilableQueryWatch.js';
@@ -51,6 +61,7 @@ export * from './utils/BaseObserver.js';
 export * from './utils/ControlledExecutor.js';
 export * from './utils/DataStream.js';
 export * from './utils/Logger.js';
+export * from './utils/mutex.js';
 export * from './utils/parseQuery.js';
 
 export * from './types/types.js';

package/src/utils/mutex.ts

@@ -6,7 +6,7 @@ import { Mutex } from 'async-mutex';
 export async function mutexRunExclusive<T>(
   mutex: Mutex,
   callback: () => Promise<T>,
-  options?: { timeoutMs: number }
+  options?: { timeoutMs?: number }
 ): Promise<T> {
   return new Promise((resolve, reject) => {
     const timeout = options?.timeoutMs;