@powersync/common 1.53.2 → 1.55.0

package/src/attachments/AttachmentQueue.ts

@@ -1,15 +1,68 @@
 import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
 import { DEFAULT_WATCH_THROTTLE_MS } from '../client/watched/WatchedQuery.js';
 import { DifferentialWatchedQuery } from '../client/watched/processors/DifferentialQueryProcessor.js';
-import { ILogger } from '../utils/Logger.js';
 import { Transaction } from '../db/DBAdapter.js';
+import { ILogger } from '../utils/Logger.js';
+import { AttachmentContext } from './AttachmentContext.js';
+import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
+import { AttachmentService } from './AttachmentService.js';
 import { AttachmentData, LocalStorageAdapter } from './LocalStorageAdapter.js';
 import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
 import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js';
 import { SyncingService } from './SyncingService.js';
 import { WatchedAttachmentItem } from './WatchedAttachmentItem.js';
-import { AttachmentService } from './AttachmentService.js';
-import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
+
+/**
+ * Configuration options for {@link AttachmentQueue}.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface AttachmentQueueOptions {
+  /**
+   * PowerSync database instance
+   */
+  db: AbstractPowerSyncDatabase;
+  /**
+   * Remote storage adapter for upload/download operations
+   */
+  remoteStorage: RemoteStorageAdapter;
+  /**
+   * Local storage adapter for file persistence
+   */
+  localStorage: LocalStorageAdapter;
+  /**
+   * Callback for monitoring attachment changes in your data model
+   */
+  watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
+  /**
+   * Name of the table to store attachment records. Default: 'ps_attachment_queue'
+   */
+  tableName?: string;
+  /**
+   * Logger instance. Defaults to db.logger
+   */
+  logger?: ILogger;
+  /**
+   * Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
+   */
+  syncIntervalMs?: number;
+  /**
+   * Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
+   */
+  syncThrottleDuration?: number;
+  /**
+   * Whether to automatically download remote attachments. Default: true
+   */
+  downloadAttachments?: boolean;
+  /**
+   * Maximum archived attachments before cleanup. Default: 100
+   */
+  archivedCacheLimit?: number;
+
+  /** Handler for upload, download and delete errors */
+  errorHandler?: AttachmentErrorHandler;
+}
 
 /**
  * AttachmentQueue manages the lifecycle and synchronization of attachments
@@ -78,24 +131,14 @@ export class AttachmentQueue {
   /** Cleanup function for status change listener */
   private statusListenerDispose?: () => void;
 
-  private watchActiveAttachments: DifferentialWatchedQuery<AttachmentRecord>;
+  private watchActiveAttachments!: DifferentialWatchedQuery<AttachmentRecord>;
 
-  private watchAttachmentsAbortController: AbortController;
+  private watchAttachmentsAbortController!: AbortController;
 
   /**
    * 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 - Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000
-   * @param options.syncThrottleDuration - Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30
-   * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
-   * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
    */
   constructor({
     db,
@@ -109,19 +152,7 @@ export class AttachmentQueue {
     downloadAttachments = true,
     archivedCacheLimit = 100,
     errorHandler
-  }: {
-    db: AbstractPowerSyncDatabase;
-    remoteStorage: RemoteStorageAdapter;
-    localStorage: LocalStorageAdapter;
-    watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
-    tableName?: string;
-    logger?: ILogger;
-    syncIntervalMs?: number;
-    syncThrottleDuration?: number;
-    downloadAttachments?: boolean;
-    archivedCacheLimit?: number;
-    errorHandler?: AttachmentErrorHandler;
-  }) {
+  }: AttachmentQueueOptions) {
     this.db = db;
     this.remoteStorage = remoteStorage;
     this.localStorage = localStorage;
@@ -228,6 +259,7 @@ export class AttachmentQueue {
               state: AttachmentState.QUEUED_DOWNLOAD,
               hasSynced: false,
               metaData: watchedAttachment.metaData,
+              mediaType: watchedAttachment.mediaType,
               timestamp: new Date().getTime()
             });
             continue;
@@ -321,17 +353,24 @@ export class AttachmentQueue {
     }
   }
 
+  /**
+   * Provides an {@link AttachmentContext} to a callback.
+   *
+   * The callback runs while the attachment queue mutex is held. Do not call
+   * other {@link AttachmentQueue} methods from within the callback, as they may
+   * attempt to acquire the same mutex and block indefinitely.
+   */
+  withAttachmentContext<T>(callback: (context: AttachmentContext) => Promise<T>): Promise<T> {
+    /**
+     * AttachmentService is internal and private in this class.
+     * We only need to expose its locking and context functionality for extending classes.
+     */
+    return this.attachmentService.withContext(callback);
+  }
   /**
    * 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({
@@ -342,11 +381,30 @@ export class AttachmentQueue {
     id,
     updateHook
   }: {
+    /**
+     * The file data as ArrayBuffer, Blob, or base64 string
+     */
     data: AttachmentData;
+    /**
+     * 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> {
     const resolvedId = id ?? (await this.generateAttachmentId());

package/src/attachments/LocalStorageAdapter.ts

@@ -1,5 +1,11 @@
+/**
+ * @alpha
+ */
 export type AttachmentData = ArrayBuffer | string;
 
+/**
+ * @alpha
+ */
 export enum EncodingType {
   UTF8 = 'utf8',
   Base64 = 'base64'
@@ -15,41 +21,41 @@ export enum EncodingType {
 export interface LocalStorageAdapter {
   /**
    * Saves data to a local file.
-   * @param filePath Path where the file will be stored
-   * @param data Data to store (ArrayBuffer, Blob, or string)
+   * @param filePath - Path where the file will be stored
+   * @param data - Data to store (ArrayBuffer, Blob, or string)
    * @returns Number of bytes written
    */
   saveFile(filePath: string, data: AttachmentData): Promise<number>;
 
   /**
    * Retrieves file data as an ArrayBuffer.
-   * @param filePath Path where the file is stored
+   * @param filePath - Path where the file is stored
    * @returns ArrayBuffer containing the file data
    */
   readFile(filePath: string): Promise<ArrayBuffer>;
 
   /**
    * Deletes the file at the given path.
-   * @param filePath Path where the file is stored
+   * @param filePath - Path where the file is stored
    */
   deleteFile(filePath: string): Promise<void>;
 
   /**
    * Checks if a file exists at the given path.
-   * @param filePath Path where the file is stored
+   * @param filePath - Path where the file is stored
    * @returns True if the file exists, false otherwise
    */
   fileExists(filePath: string): Promise<boolean>;
 
   /**
    * Creates a directory at the specified path.
-   * @param path The full path to the directory
+   * @param path - The full path to the directory
    */
   makeDir(path: string): Promise<void>;
 
   /**
    * Removes a directory at the specified path.
-   * @param path The full path to the directory
+   * @param path - The full path to the directory
    */
   rmDir(path: string): Promise<void>;
 
@@ -65,7 +71,7 @@ export interface LocalStorageAdapter {
 
   /**
    * Returns the file path for the provided filename in the storage directory.
-   * @param filename The filename to get the path for
+   * @param filename - The filename to get the path for
    * @returns The full file path
    */
   getLocalUri(filename: string): string;

package/src/attachments/README.md

@@ -427,10 +427,12 @@ type WatchedAttachmentItem = {
   id: string;
   fileExtension: string;  // e.g., 'jpg', 'pdf'
   metaData?: string;
+  mediaType?: string;     // e.g., 'image/jpeg'
 } | {
   id: string;
   filename: string;       // e.g., 'document.pdf'
   metaData?: string;
+  mediaType?: string;     // e.g., 'application/pdf'
 };
 ```
 

package/src/attachments/RemoteStorageAdapter.ts

@@ -10,21 +10,21 @@ import { AttachmentRecord } from './Schema.js';
 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
+   * @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
+   * @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
+   * @param attachment - The attachment describing the file to delete
    */
   deleteFile(attachment: AttachmentRecord): Promise<void>;
 }

package/src/attachments/Schema.ts

@@ -2,12 +2,17 @@ import { column } from '../db/schema/Column.js';
 import { Table } from '../db/schema/Table.js';
 import { TableV2Options } from '../db/schema/Table.js';
 
+/**
+ * The default name of the local table storing attachment data.
+ *
+ * @alpha
+ */
 export const ATTACHMENT_TABLE = 'attachments';
 
 /**
  * AttachmentRecord represents an attachment in the local database.
  *
- * @experimental
+ * @alpha
  */
 export interface AttachmentRecord {
   id: string;
@@ -27,7 +32,7 @@ export interface AttachmentRecord {
  * @param row - The database row object
  * @returns The corresponding AttachmentRecord
  *
- * @experimental
+ * @alpha
  */
 export function attachmentFromSql(row: any): AttachmentRecord {
   return {
@@ -46,7 +51,7 @@ export function attachmentFromSql(row: any): AttachmentRecord {
 /**
  * AttachmentState represents the current synchronization state of an attachment.
  *
- * @experimental
+ * @alpha
  */
 export enum AttachmentState {
   QUEUED_UPLOAD = 0, // Attachment to be uploaded
@@ -56,12 +61,15 @@ export enum AttachmentState {
   ARCHIVED = 4 // Attachment has been orphaned, i.e. the associated record has been deleted
 }
 
+/**
+ * @alpha
+ */
 export interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {}
 
 /**
  * AttachmentTable defines the schema for the attachment queue table.
  *
- * @internal
+ * @alpha
  */
 export class AttachmentTable extends Table {
   constructor(options?: AttachmentTableOptions) {

package/src/attachments/WatchedAttachmentItem.ts

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