AttachmentQueue
Experimental Alpha
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.
This is currently experimental and may change without a major version bump.
Constructors
new AttachmentQueue()
new AttachmentQueue(options): AttachmentQueue
Alpha
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { archivedCacheLimit: number; db: AbstractPowerSyncDatabase; downloadAttachments: boolean; errorHandler: AttachmentErrorHandler; localStorage: LocalStorageAdapter; logger: ILogger; remoteStorage: RemoteStorageAdapter; syncIntervalMs: number; syncThrottleDuration: number; tableName: string; watchAttachments: (onUpdate, signal) => void; } | Configuration options |
options.archivedCacheLimit? | number | Maximum archived attachments before cleanup. Default: 100 |
options.db | AbstractPowerSyncDatabase | PowerSync database instance |
options.downloadAttachments? | boolean | Whether to automatically download remote attachments. Default: true |
options.errorHandler? | AttachmentErrorHandler | - |
options.localStorage | LocalStorageAdapter | Local storage adapter for file persistence |
options.logger? | ILogger | Logger instance. Defaults to db.logger |
options.remoteStorage | RemoteStorageAdapter | Remote storage adapter for upload/download operations |
options.syncIntervalMs? | number | Periodic polling interval in milliseconds for retrying failed uploads/downloads. Default: 30000 |
options.syncThrottleDuration? | number | Throttle duration in milliseconds for the reactive watch query that detects attachment changes. Prevents rapid-fire syncs during bulk changes. Default: 30 |
options.tableName? | string | Name of the table to store attachment records. Default: 'ps_attachment_queue' |
options.watchAttachments | (onUpdate, signal) => void | Callback for monitoring attachment changes in your data model |
Returns
Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
archivedCacheLimit | readonly | number | Alpha Maximum number of archived attachments to keep before cleanup. Default: 100 |
downloadAttachments | readonly | boolean | Alpha Whether to automatically download remote attachments. Default: true |
localStorage | readonly | LocalStorageAdapter | Alpha Adapter for local file storage operations |
logger | readonly | ILogger | Alpha Logger instance for diagnostic information |
remoteStorage | readonly | RemoteStorageAdapter | Alpha Adapter for remote file storage operations |
syncIntervalMs | readonly | number | Alpha Interval in milliseconds between periodic sync operations. Acts as a polling timer to retry failed uploads/downloads, especially after the app goes offline. Default: 30000 (30 seconds) |
syncThrottleDuration | readonly | number | Alpha Throttle duration in milliseconds for the reactive watch query on the attachments table. When attachment records change, a watch query detects the change and triggers a sync. This throttle prevents the sync from firing too rapidly when many changes happen in quick succession (e.g., bulk inserts). This is distinct from syncIntervalMs — it controls how quickly the queue reacts to changes, while syncIntervalMs controls how often it polls for retries. Default: 30 (from DEFAULT_WATCH_THROTTLE_MS) |
tableName | readonly | string | Alpha Name of the database table storing attachment records |
Methods
clearQueue()
clearQueue(): Promise<void>
Alpha Experimental
Returns
Promise<void>
deleteFile()
deleteFile(__namedParameters): Promise<void>
Alpha Experimental
Parameters
| Parameter | Type |
|---|---|
__namedParameters | { id: string; updateHook: (transaction, attachment) => Promise<void>; } |
__namedParameters.id | string |
__namedParameters.updateHook? | (transaction, attachment) => Promise<void> |
Returns
Promise<void>
expireCache()
expireCache(): Promise<void>
Alpha Experimental
Returns
Promise<void>
generateAttachmentId()
generateAttachmentId(): Promise<string>
Alpha
Returns
Promise<string>
Promise resolving to the new attachment ID
saveFile()
saveFile(options): Promise<AttachmentRecord>
Alpha
Parameters
| Parameter | Type | Description |
|---|---|---|
options | { data: AttachmentData; fileExtension: string; id: string; mediaType: string; metaData: string; updateHook: (transaction, attachment) => Promise<void>; } | File save options |
options.data | AttachmentData | The file data as ArrayBuffer, Blob, or base64 string |
options.fileExtension | string | File extension (e.g., 'jpg', 'pdf') |
options.id? | string | Optional custom ID. If not provided, a UUID will be generated |
options.mediaType? | string | MIME type of the file (e.g., 'image/jpeg') |
options.metaData? | string | Optional metadata to associate with the attachment |
options.updateHook? | (transaction, attachment) => Promise<void> | Optional callback to execute additional database operations within the same transaction as the attachment creation |
Returns
Promise<AttachmentRecord>
Promise resolving to the created attachment record
startSync()
startSync(): Promise<void>
Alpha
Returns
Promise<void>
stopSync()
stopSync(): Promise<void>
Alpha
Returns
Promise<void>
syncStorage()
syncStorage(): Promise<void>
Alpha
Returns
Promise<void>
verifyAttachments()
verifyAttachments(): Promise<void>
Alpha
Returns
Promise<void>