AttachmentQueue<TLocal>

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.

Type Parameters

Type Parameter	Default type
TLocal extends LocalStorageAdapter	LocalStorageAdapter

Constructors

Constructor

new AttachmentQueue<TLocal>(options): AttachmentQueue<TLocal>;

Alpha

Creates a new AttachmentQueue instance.

Parameters

Parameter	Type	Description
options	AttachmentQueueOptions<TLocal>	Configuration options

Returns

AttachmentQueue<TLocal>

Properties

Property	Modifier	Type	Default value	Description
archivedCacheLimit	readonly	number	undefined	Alpha Maximum number of archived attachments to keep before cleanup. Default: 100
downloadAttachments	readonly	boolean	true	Alpha Whether to automatically download remote attachments. Default: true
localStorage	readonly	TLocal	undefined	Alpha Adapter for local file storage operations
logger	readonly	PowerSyncLogger	undefined	Alpha Logger instance for diagnostic information
syncIntervalMs	readonly	number	undefined	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	undefined	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	undefined	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

Generates a new attachment ID using a SQLite UUID function.

Returns

Promise<string>

Promise resolving to the new attachment ID

---

saveFile()

saveFile(options): Promise<AttachmentRecord>;

Alpha

Saves in-memory file data to local storage and queues it for upload.

Parameters

Parameter	Type	Description
options	SaveAttachmentOptions & { data: AttachmentData; }	File data plus SaveAttachmentOptions

Returns

Promise<AttachmentRecord>

Promise resolving to the created attachment record

---

saveFileFromUri()

saveFileFromUri(this, options): Promise<AttachmentRecord>;

Alpha

Registers a file that already exists on disk and queues it for upload, moving it into managed storage without loading it into memory.

Prefer this over AttachmentQueue.saveFile for large, app-originated files (recordings, videos): it avoids reading the file into an ArrayBuffer just to write it back to disk. Requires the local storage adapter to implement moveFile.

Only available when the queue is configured with a StreamingLocalStorageAdapter (one that implements moveFile).

Parameters

Parameter	Type	Description
this	AttachmentQueue<StreamingLocalStorageAdapter>	-
options	SaveAttachmentOptions & { localUri: string; }	The existing file's localUri plus SaveAttachmentOptions

Returns

Promise<AttachmentRecord>

Promise resolving to the created attachment record

---

startSync()

startSync(): Promise<void>;

Alpha

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

Returns

Promise<void>

---

stopSync()

stopSync(): Promise<void>;

Alpha

Stops the attachment synchronization process.

Clears the periodic sync timer, closes all active attachment watchers, and aborts any in-flight syncStorage() call so it exits within one attachment's processing time instead of running the batch to completion.

Returns

Promise<void>

---

syncStorage()

syncStorage(): Promise<void>;

Alpha

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.

Concurrent invocations are serialized via syncLoopMutex.

Returns

Promise<void>

---

verifyAttachments()

verifyAttachments(): Promise<void>;

Alpha

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

Returns

Promise<void>

---

withAttachmentContext()

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

Alpha

Provides an AttachmentContext to a callback.

The callback runs while the attachment queue mutex is held. Do not call other AttachmentQueue methods from within the callback, as they may attempt to acquire the same mutex and block indefinitely.

Type Parameters

Type Parameter
T

Parameters

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

Returns

Promise<T>