diff --git a/.changeset/silly-emus-burn.md b/.changeset/silly-emus-burn.md new file mode 100644 index 000000000..f4485e960 --- /dev/null +++ b/.changeset/silly-emus-burn.md @@ -0,0 +1,5 @@ +--- +'@powersync/common': minor +--- + +[Attachments] Extracted `AttachmentQueue` constructor options to an options interface named `AttachmentQueueOptions`. diff --git a/packages/common/etc/common.api.md b/packages/common/etc/common.api.md index f2816502d..62ea06fbc 100644 --- a/packages/common/etc/common.api.md +++ b/packages/common/etc/common.api.md @@ -408,20 +408,8 @@ export interface AttachmentErrorHandler { export function attachmentFromSql(row: any): AttachmentRecord; // @alpha -export class AttachmentQueue implements AttachmentQueue { - constructor(input: { - db: AbstractPowerSyncDatabase; - remoteStorage: RemoteStorageAdapter; - localStorage: LocalStorageAdapter; - watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise, signal: AbortSignal) => void; - tableName?: string; - logger?: ILogger; - syncIntervalMs?: number; - syncThrottleDuration?: number; - downloadAttachments?: boolean; - archivedCacheLimit?: number; - errorHandler?: AttachmentErrorHandler; - }); +export class AttachmentQueue { + constructor(input: AttachmentQueueOptions); readonly archivedCacheLimit: number; // (undocumented) clearQueue(): Promise; @@ -455,6 +443,21 @@ export class AttachmentQueue implements AttachmentQueue { withAttachmentContext(callback: (context: AttachmentContext) => Promise): Promise; } +// @alpha +export interface AttachmentQueueOptions { + archivedCacheLimit?: number; + db: AbstractPowerSyncDatabase; + downloadAttachments?: boolean; + errorHandler?: AttachmentErrorHandler; + localStorage: LocalStorageAdapter; + logger?: ILogger; + remoteStorage: RemoteStorageAdapter; + syncIntervalMs?: number; + syncThrottleDuration?: number; + tableName?: string; + watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise, signal: AbortSignal) => void; +} + // @alpha export interface AttachmentRecord { // (undocumented) diff --git a/packages/common/src/attachments/AttachmentQueue.ts b/packages/common/src/attachments/AttachmentQueue.ts index b467ed18c..2184537d3 100644 --- a/packages/common/src/attachments/AttachmentQueue.ts +++ b/packages/common/src/attachments/AttachmentQueue.ts @@ -12,6 +12,58 @@ import { ATTACHMENT_TABLE, AttachmentRecord, AttachmentState } from './Schema.js import { SyncingService } from './SyncingService.js'; import { WatchedAttachmentItem } from './WatchedAttachmentItem.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, 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 * between local and remote storage. @@ -21,7 +73,7 @@ import { WatchedAttachmentItem } from './WatchedAttachmentItem.js'; * @experimental * @alpha This is currently experimental and may change without a major version bump. */ -export class AttachmentQueue implements AttachmentQueue { +export class AttachmentQueue { /** Timer for periodic synchronization operations */ private periodicSyncTimer?: ReturnType; @@ -100,49 +152,7 @@ export class AttachmentQueue implements AttachmentQueue { downloadAttachments = true, archivedCacheLimit = 100, errorHandler - }: { - /** - * 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, 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; - errorHandler?: AttachmentErrorHandler; - }) { + }: AttachmentQueueOptions) { this.db = db; this.remoteStorage = remoteStorage; this.localStorage = localStorage;