Improve comments

Author: joshuabrink

packages/attachments/src/AttachmentContext.ts

@@ -1,18 +1,43 @@
 import { AbstractPowerSyncDatabase, ILogger, Transaction } from '@powersync/common';
 import { AttachmentRecord, AttachmentState, attachmentFromSql } from './Schema.js';
 
+/**
+ * AttachmentContext provides database operations for managing attachment records.
+ * 
+ * Provides methods to query, insert, update, and delete attachment records with
+ * proper transaction management through PowerSync.
+ */
 export class AttachmentContext {
+  /** PowerSync database instance for executing queries */
   db: AbstractPowerSyncDatabase;
+  
+  /** Name of the database table storing attachment records */
   tableName: string;
+  
+  /** Logger instance for diagnostic information */
   logger: ILogger;
 
+  /**
+   * Creates a new AttachmentContext instance.
+   * 
+   * @param db - PowerSync database instance
+   * @param tableName - Name of the table storing attachment records. Default: 'attachments'
+   * @param logger - Logger instance for diagnostic output
+   */
   constructor(db: AbstractPowerSyncDatabase, tableName: string = 'attachments', logger: ILogger) {
     this.db = db;
     this.tableName = tableName;
     this.logger = logger;
   }
 
-  async getActiveAttachments(): Promise<any[]> {
+  /**
+   * Retrieves all active attachments that require synchronization.
+   * Active attachments include those queued for upload, download, or delete.
+   * Results are ordered by timestamp in ascending order.
+   * 
+   * @returns Promise resolving to an array of active attachment records
+   */
+  async getActiveAttachments(): Promise<AttachmentRecord[]> {
     const attachments = await this.db.getAll(
       /* sql */
       `
@@ -33,6 +58,14 @@ export class AttachmentContext {
     return attachments.map(attachmentFromSql);
   }
 
+  /**
+   * Retrieves all archived attachments.
+   * 
+   * Archived attachments are no longer referenced but haven't been permanently deleted.
+   * These are candidates for cleanup operations to free up storage space.
+   * 
+   * @returns Promise resolving to an array of archived attachment records
+   */
   async getArchivedAttachments(): Promise<AttachmentRecord[]> {
     const attachments = await this.db.getAll(
       /* sql */
@@ -52,6 +85,12 @@ export class AttachmentContext {
     return attachments.map(attachmentFromSql);
   }
 
+  /**
+   * Retrieves all attachment records regardless of state.
+   * Results are ordered by timestamp in ascending order.
+   * 
+   * @returns Promise resolving to an array of all attachment records
+   */
   async getAttachments(): Promise<AttachmentRecord[]> {
     const attachments = await this.db.getAll(
       /* sql */
@@ -69,6 +108,15 @@ export class AttachmentContext {
     return attachments.map(attachmentFromSql);
   }
 
+  /**
+   * Inserts or updates an attachment record within an existing transaction.
+   * 
+   * Performs an upsert operation (INSERT OR REPLACE). Must be called within
+   * an active database transaction context.
+   * 
+   * @param attachment - The attachment record to upsert
+   * @param context - Active database transaction context
+   */
   upsertAttachment(attachment: AttachmentRecord, context: Transaction): void {
     context.execute(
       /* sql */
@@ -102,6 +150,15 @@ export class AttachmentContext {
     );
   }
 
+  /**
+   * Permanently deletes an attachment record from the database.
+   * 
+   * This operation removes the attachment record but does not delete
+   * the associated local or remote files. File deletion should be handled
+   * separately through the appropriate storage adapters.
+   * 
+   * @param attachmentId - Unique identifier of the attachment to delete
+   */
   async deleteAttachment(attachmentId: string): Promise<void> {
     await this.db.writeTransaction((tx) =>
       tx.execute(
@@ -116,6 +173,14 @@ export class AttachmentContext {
     );
   }
 
+  /**
+   * Saves multiple attachment records in a single transaction.
+   * 
+   * All updates are saved in a single batch after processing.
+   * If the attachments array is empty, no database operations are performed.
+   * 
+   * @param attachments - Array of attachment records to save
+   */
   async saveAttachments(attachments: AttachmentRecord[]): Promise<void> {
     if (attachments.length === 0) {
       return;

packages/attachments/src/AttachmentQueue.ts

@@ -1,4 +1,4 @@
-import { AbstractPowerSyncDatabase, ILogger } from '@powersync/common';
+import { AbstractPowerSyncDatabase, ILogger, Transaction } from '@powersync/common';
 import { AttachmentContext } from './AttachmentContext.js';
 import { LocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
@@ -7,20 +7,68 @@ import { SyncingService } from './SyncingService.js';
 import { WatchedAttachmentItem } from './WatchedAttachmentItem.js';
 import { AttachmentService } from './AttachmentService.js';
 
+/**
+ * AttachmentQueue manages the lifecycle and synchronization of attachments
+ * between local and remote storage.
+ * 
+ * Provides automatic synchronization, upload/download queuing, attachment monitoring,
+ * verification and repair of local files, and cleanup of archived attachments.
+ */
 export class AttachmentQueue {
+  /** Timer for periodic synchronization operations */
   periodicSyncTimer?: ReturnType<typeof setInterval>;
+  
+  /** Context for managing attachment records in the database */
   context: AttachmentContext;
+  
+  /** Service for synchronizing attachments between local and remote storage */
   syncingService: SyncingService;
+  
+  /** Adapter for local file storage operations */
   localStorage: LocalStorageAdapter;
+  
+  /** Adapter for remote file storage operations */
   remoteStorage: RemoteStorageAdapter;
+  
+  /** @deprecated Directory path for storing attachments  */
   attachmentsDirectory?: string;
+  
+  /** Name of the database table storing attachment records */
   tableName?: string;
+  
+  /** Logger instance for diagnostic information */
   logger?: ILogger;
+  
+  /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+  syncIntervalMs: number = 30 * 1000;
+  
+  /** Duration in milliseconds to throttle sync operations */
   syncThrottleDuration: number;
+  
+  /** Whether to automatically download remote attachments. Default: true */
   downloadAttachments: boolean = true;
+  
+  /** Maximum number of archived attachments to keep before cleanup. Default: 100 */
   archivedCacheLimit: number;
+  
+  /** Service for managing attachment-related database operations */
   attachmentService: AttachmentService;
 
+  /**
+   * Creates a new AttachmentQueue instance.
+   * 
+   * @param options - Configuration options
+   * @param options.db - PowerSync database instance
+   * @param options.remoteStorage - Remote storage adapter for upload/download operations
+   * @param options.localStorage - Local storage adapter for file persistence
+   * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
+   * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
+   * @param options.logger - Logger instance. Defaults to db.logger
+   * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
+   * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
+   * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
+   * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
+   */
   constructor({
     db,
     localStorage,
@@ -57,8 +105,30 @@ export class AttachmentQueue {
     this.archivedCacheLimit = archivedCacheLimit;
   }
 
+  /**
+   * Callback function to watch for changes in attachment references in your data model.
+   * 
+   * This method should be implemented to monitor changes in your application's
+   * data that reference attachments. When attachments are added, removed, or modified,
+   * this callback should trigger the onUpdate function with the current set of attachments.
+   * 
+   * @param onUpdate - Callback to invoke when attachment references change
+   * @throws Error indicating this method must be implemented by the user
+   */
+  watchAttachments(onUpdate: (attachement: WatchedAttachmentItem[]) => Promise<void>): void {
+    throw new Error('watchAttachments should be implemented by the user of AttachmentQueue');
   }
 
+  /**
+   * Starts the attachment synchronization process.
+   * 
+   * This method:
+   * - Stops any existing sync operations
+   * - Sets up periodic synchronization based on syncIntervalMs
+   * - Registers listeners for active attachment changes
+   * - Processes watched attachments to queue uploads/downloads
+   * - Handles state transitions for archived and new attachments
+   */
   async startSync(): Promise<void> {
     await this.stopSync();
 
@@ -156,20 +226,43 @@ export class AttachmentQueue {
     });
   }
 
-  // Sync storage with all active attachments
+  /**
+   * Synchronizes all active attachments between local and remote storage.
+   * 
+   * This is called automatically at regular intervals when sync is started,
+   * but can also be called manually to trigger an immediate sync.
+   */
   async syncStorage(): Promise<void> {
     const activeAttachments = await this.context.getActiveAttachments();
     await this.localStorage.initialize();
     await this.syncingService.processAttachments(activeAttachments);
     await this.syncingService.deleteArchivedAttachments();
   }
 
+  /**
+   * Stops the attachment synchronization process.
+   * 
+   * Clears the periodic sync timer and closes all active attachment watchers.
+   */
   async stopSync(): Promise<void> {
     clearInterval(this.periodicSyncTimer);
     this.periodicSyncTimer = undefined;
     await this.attachmentService.watchActiveAttachments().close();
   }
 
+  /**
+   * Saves a file to local storage and queues it for upload to remote storage.
+   * 
+   * @param options - File save options
+   * @param options.data - The file data as ArrayBuffer, Blob, or base64 string
+   * @param options.fileExtension - File extension (e.g., 'jpg', 'pdf')
+   * @param options.mediaType - MIME type of the file (e.g., 'image/jpeg')
+   * @param options.metaData - Optional metadata to associate with the attachment
+   * @param options.id - Optional custom ID. If not provided, a UUID will be generated
+   * @param options.updateHook - Optional callback to execute additional database operations
+   *                             within the same transaction as the attachment creation
+   * @returns Promise resolving to the created attachment record
+   */
   async saveFile({
     data,
     fileExtension,
@@ -178,6 +271,7 @@ export class AttachmentQueue {
     id,
     updateHook
   }: {
+    // TODO: create a dedicated type for data
     data: ArrayBuffer | Blob | string;
     fileExtension: string;
     mediaType?: string;
@@ -210,6 +304,14 @@ export class AttachmentQueue {
     return attachment;
   }
 
+  /**
+   * Verifies the integrity of all attachment records and repairs inconsistencies.
+   * 
+   * This method checks each attachment record against the local filesystem and:
+   * - Updates localUri if the file exists at a different path
+   * - Archives attachments with missing local files that haven't been uploaded
+   * - Requeues synced attachments for download if their local files are missing
+   */
   verifyAttachments = async (): Promise<void> => {
     const attachments = await this.context.getAttachments();
     const updates: AttachmentRecord[] = [];

packages/attachments/src/LocalStorageAdapter.ts

@@ -3,19 +3,23 @@ export enum EncodingType {
   Base64 = 'base64'
 }
 
+/**
+ * LocalStorageAdapter defines the interface for local file storage operations.
+ * Implementations handle file I/O, directory management, and storage initialization.
+ */
 export interface LocalStorageAdapter {
   /**
-   * Saves buffer data to a local file.
+   * Saves data to a local file.
    * @param filePath Path where the file will be stored
-   * @param data Data string to store
+   * @param data Data to store (ArrayBuffer, Blob, or string)
    * @returns Number of bytes written
    */
   saveFile(filePath: string, data: ArrayBuffer | Blob | string): Promise<number>;
 
   /**
-   * Retrieves an ArrayBuffer with the file data from the given path.
+   * Retrieves file data as an ArrayBuffer.
    * @param filePath Path where the file is stored
-   * @returns ArrayBuffer with the file data
+   * @returns ArrayBuffer containing the file data
    */
   readFile(filePath: string): Promise<ArrayBuffer>;
 
@@ -35,14 +39,12 @@ export interface LocalStorageAdapter {
   /**
    * Creates a directory at the specified path.
    * @param path The full path to the directory
-   * @throws PowerSyncAttachmentError if creation fails
    */
   makeDir(path: string): Promise<void>;
 
   /**
    * Removes a directory at the specified path.
    * @param path The full path to the directory
-   * @throws PowerSyncAttachmentError if removal fails
    */
   rmDir(path: string): Promise<void>;
 
@@ -57,7 +59,7 @@ export interface LocalStorageAdapter {
   clear(): Promise<void>;
 
   /**
-   * Returns the file path of the provided filename in the user storage directory.
+   * Returns the file path for the provided filename in the storage directory.
    * @param filename The filename to get the path for
    * @returns The full file path
    */

packages/attachments/src/RemoteStorageAdapter.ts

@@ -1,27 +1,27 @@
 import { AttachmentRecord } from "./Schema.js";
 
+/**
+ * RemoteStorageAdapter defines the interface for remote storage operations.
+ * Implementations handle uploading, downloading, and deleting files from remote storage.
+ */
 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 describing the file.
-     * @throws An error if the upload fails.
+     * @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.
-     * @throws An error if the download fails or the file is not found.
+     * @param attachment The attachment describing the file to download
+     * @returns The binary data of the downloaded file
      */
-    downloadFile(attachment: AttachmentRecord): Promise<Blob>;
+    downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer>;
+    
     /**
      * Deletes a file from remote storage.
-     *
-     * @param attachment The `Attachment` describing the file to delete.
-     * @throws An error if the deletion fails or the file does not exist.
+     * @param attachment The attachment describing the file to delete
      */
     deleteFile(attachment: AttachmentRecord): Promise<void>;
 }