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
Constructor
new AttachmentQueue(options): AttachmentQueue;
Alpha
Creates a new AttachmentQueue instance.
Parameters
| Parameter | Type | Description |
|---|---|---|
options | AttachmentQueueOptions | Configuration options |
Returns
AttachmentQueue
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 | LocalStorageAdapter | undefined | Alpha Adapter for local file storage operations |
logger | readonly | PowerSyncLogger | undefined | Alpha Logger instance for diagnostic information |
remoteStorage | readonly | RemoteStorageAdapter | undefined | Alpha Adapter for remote file storage operations |
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 a file to local storage and queues it for upload to remote storage.
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
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>