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	AttachmentQueueOptions	Configuration options

Returns

AttachmentQueue

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>

---

withAttachmentContext()

withAttachmentContext<T>(callback): Promise<T>

Alpha

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
callback	(context) => Promise<T>

Returns

Promise<T>