@powersync/common 1.46.0 → 1.47.0

package/lib/attachments/AttachmentQueue.js

@@ -0,0 +1,362 @@
+import { DEFAULT_WATCH_THROTTLE_MS } from '../client/watched/WatchedQuery.js';
+import { ATTACHMENT_TABLE, AttachmentState } from './Schema.js';
+import { SyncingService } from './SyncingService.js';
+import { AttachmentService } from './AttachmentService.js';
+/**
+ * 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.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export class AttachmentQueue {
+    /** Timer for periodic synchronization operations */
+    periodicSyncTimer;
+    /** Service for synchronizing attachments between local and remote storage */
+    syncingService;
+    /** Adapter for local file storage operations */
+    localStorage;
+    /** Adapter for remote file storage operations */
+    remoteStorage;
+    /**
+     * Callback function to watch for changes in attachment references in your data model.
+     *
+     * This should be implemented by the user of AttachmentQueue to monitor changes in your application's
+     * data that reference attachments. When attachments are added, removed, or modified,
+     * this callback should trigger the onUpdate function with the current set of attachments.
+     */
+    watchAttachments;
+    /** Name of the database table storing attachment records */
+    tableName;
+    /** Logger instance for diagnostic information */
+    logger;
+    /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+    syncIntervalMs = 30 * 1000;
+    /** Duration in milliseconds to throttle sync operations */
+    syncThrottleDuration;
+    /** Whether to automatically download remote attachments. Default: true */
+    downloadAttachments = true;
+    /** Maximum number of archived attachments to keep before cleanup. Default: 100 */
+    archivedCacheLimit;
+    /** Service for managing attachment-related database operations */
+    attachmentService;
+    /** PowerSync database instance */
+    db;
+    /** Cleanup function for status change listener */
+    statusListenerDispose;
+    watchActiveAttachments;
+    watchAttachmentsAbortController;
+    /**
+     * Creates a new AttachmentQueue instance.
+     *
+     * @param options - Configuration options
+     * @param options.db - PowerSync database instance
+     * @param options.remoteStorage - Remote storage adapter for upload/download operations
+     * @param options.localStorage - Local storage adapter for file persistence
+     * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
+     * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
+     * @param options.logger - Logger instance. Defaults to db.logger
+     * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
+     * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
+     * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
+     * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
+     */
+    constructor({ db, localStorage, remoteStorage, watchAttachments, logger, tableName = ATTACHMENT_TABLE, syncIntervalMs = 30 * 1000, syncThrottleDuration = DEFAULT_WATCH_THROTTLE_MS, downloadAttachments = true, archivedCacheLimit = 100, errorHandler }) {
+        this.db = db;
+        this.remoteStorage = remoteStorage;
+        this.localStorage = localStorage;
+        this.watchAttachments = watchAttachments;
+        this.tableName = tableName;
+        this.syncIntervalMs = syncIntervalMs;
+        this.syncThrottleDuration = syncThrottleDuration;
+        this.archivedCacheLimit = archivedCacheLimit;
+        this.downloadAttachments = downloadAttachments;
+        this.logger = logger ?? db.logger;
+        this.attachmentService = new AttachmentService(db, this.logger, tableName, archivedCacheLimit);
+        this.syncingService = new SyncingService(this.attachmentService, localStorage, remoteStorage, this.logger, errorHandler);
+    }
+    /**
+     * Generates a new attachment ID using a SQLite UUID function.
+     *
+     * @returns Promise resolving to the new attachment ID
+     */
+    async generateAttachmentId() {
+        return this.db.get('SELECT uuid() as id').then((row) => row.id);
+    }
+    /**
+     * 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
+     */
+    async startSync() {
+        await this.stopSync();
+        this.watchActiveAttachments = this.attachmentService.watchActiveAttachments({
+            throttleMs: this.syncThrottleDuration
+        });
+        // immediately invoke the sync storage to initialize local storage
+        await this.localStorage.initialize();
+        await this.verifyAttachments();
+        // Sync storage periodically
+        this.periodicSyncTimer = setInterval(async () => {
+            await this.syncStorage();
+        }, this.syncIntervalMs);
+        // Sync storage when there is a change in active attachments
+        this.watchActiveAttachments.registerListener({
+            onDiff: async () => {
+                await this.syncStorage();
+            }
+        });
+        this.statusListenerDispose = this.db.registerListener({
+            statusChanged: (status) => {
+                if (status.connected) {
+                    // Device came online, process attachments immediately
+                    this.syncStorage().catch((error) => {
+                        this.logger.error('Error syncing storage on connection:', error);
+                    });
+                }
+            }
+        });
+        this.watchAttachmentsAbortController = new AbortController();
+        const signal = this.watchAttachmentsAbortController.signal;
+        // Process attachments when there is a change in watched attachments
+        this.watchAttachments(async (watchedAttachments) => {
+            // Skip processing if sync has been stopped
+            if (signal.aborted) {
+                return;
+            }
+            await this.attachmentService.withContext(async (ctx) => {
+                // Need to get all the attachments which are tracked in the DB.
+                // We might need to restore an archived attachment.
+                const currentAttachments = await ctx.getAttachments();
+                const attachmentUpdates = [];
+                for (const watchedAttachment of watchedAttachments) {
+                    const existingQueueItem = currentAttachments.find((a) => a.id === watchedAttachment.id);
+                    if (!existingQueueItem) {
+                        // Item is watched but not in the queue yet. Need to add it.
+                        if (!this.downloadAttachments) {
+                            continue;
+                        }
+                        const filename = watchedAttachment.filename ?? `${watchedAttachment.id}.${watchedAttachment.fileExtension}`;
+                        attachmentUpdates.push({
+                            id: watchedAttachment.id,
+                            filename,
+                            state: AttachmentState.QUEUED_DOWNLOAD,
+                            hasSynced: false,
+                            metaData: watchedAttachment.metaData,
+                            timestamp: new Date().getTime()
+                        });
+                        continue;
+                    }
+                    if (existingQueueItem.state === AttachmentState.ARCHIVED) {
+                        // The attachment is present again. Need to queue it for sync.
+                        // We might be able to optimize this in future
+                        if (existingQueueItem.hasSynced === true) {
+                            // No remote action required, we can restore the record (avoids deletion)
+                            attachmentUpdates.push({
+                                ...existingQueueItem,
+                                state: AttachmentState.SYNCED
+                            });
+                        }
+                        else {
+                            // The localURI should be set if the record was meant to be uploaded
+                            // and hasSynced is false then
+                            // it must be an upload operation
+                            const newState = existingQueueItem.localUri == null ? AttachmentState.QUEUED_DOWNLOAD : AttachmentState.QUEUED_UPLOAD;
+                            attachmentUpdates.push({
+                                ...existingQueueItem,
+                                state: newState
+                            });
+                        }
+                    }
+                }
+                for (const attachment of currentAttachments) {
+                    const notInWatchedItems = watchedAttachments.find((i) => i.id === attachment.id) == null;
+                    if (notInWatchedItems) {
+                        switch (attachment.state) {
+                            case AttachmentState.QUEUED_DELETE:
+                            case AttachmentState.QUEUED_UPLOAD:
+                                // Only archive if it has synced
+                                if (attachment.hasSynced === true) {
+                                    attachmentUpdates.push({
+                                        ...attachment,
+                                        state: AttachmentState.ARCHIVED
+                                    });
+                                }
+                                break;
+                            default:
+                                // Archive other states such as QUEUED_DOWNLOAD
+                                attachmentUpdates.push({
+                                    ...attachment,
+                                    state: AttachmentState.ARCHIVED
+                                });
+                        }
+                    }
+                }
+                if (attachmentUpdates.length > 0) {
+                    await ctx.saveAttachments(attachmentUpdates);
+                }
+            });
+        }, signal);
+    }
+    /**
+     * 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.
+     */
+    async syncStorage() {
+        await this.attachmentService.withContext(async (ctx) => {
+            const activeAttachments = await ctx.getActiveAttachments();
+            await this.localStorage.initialize();
+            await this.syncingService.processAttachments(activeAttachments, ctx);
+            await this.syncingService.deleteArchivedAttachments(ctx);
+        });
+    }
+    /**
+     * Stops the attachment synchronization process.
+     *
+     * Clears the periodic sync timer and closes all active attachment watchers.
+     */
+    async stopSync() {
+        clearInterval(this.periodicSyncTimer);
+        this.periodicSyncTimer = undefined;
+        if (this.watchActiveAttachments)
+            await this.watchActiveAttachments.close();
+        if (this.watchAttachmentsAbortController) {
+            this.watchAttachmentsAbortController.abort();
+        }
+        if (this.statusListenerDispose) {
+            this.statusListenerDispose();
+            this.statusListenerDispose = undefined;
+        }
+    }
+    /**
+     * Saves a file to local storage and queues it for upload to remote storage.
+     *
+     * @param options - File save options
+     * @param options.data - The file data as ArrayBuffer, Blob, or base64 string
+     * @param options.fileExtension - File extension (e.g., 'jpg', 'pdf')
+     * @param options.mediaType - MIME type of the file (e.g., 'image/jpeg')
+     * @param options.metaData - Optional metadata to associate with the attachment
+     * @param options.id - Optional custom ID. If not provided, a UUID will be generated
+     * @param options.updateHook - Optional callback to execute additional database operations
+     *                             within the same transaction as the attachment creation
+     * @returns Promise resolving to the created attachment record
+     */
+    async saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }) {
+        const resolvedId = id ?? (await this.generateAttachmentId());
+        const filename = `${resolvedId}.${fileExtension}`;
+        const localUri = this.localStorage.getLocalUri(filename);
+        const size = await this.localStorage.saveFile(localUri, data);
+        const attachment = {
+            id: resolvedId,
+            filename,
+            mediaType,
+            localUri,
+            state: AttachmentState.QUEUED_UPLOAD,
+            hasSynced: false,
+            size,
+            timestamp: new Date().getTime(),
+            metaData
+        };
+        await this.attachmentService.withContext(async (ctx) => {
+            await ctx.db.writeTransaction(async (tx) => {
+                await updateHook?.(tx, attachment);
+                await ctx.upsertAttachment(attachment, tx);
+            });
+        });
+        return attachment;
+    }
+    async deleteFile({ id, updateHook }) {
+        await this.attachmentService.withContext(async (ctx) => {
+            const attachment = await ctx.getAttachment(id);
+            if (!attachment) {
+                throw new Error(`Attachment with id ${id} not found`);
+            }
+            await ctx.db.writeTransaction(async (tx) => {
+                await updateHook?.(tx, attachment);
+                await ctx.upsertAttachment({
+                    ...attachment,
+                    state: AttachmentState.QUEUED_DELETE,
+                    hasSynced: false
+                }, tx);
+            });
+        });
+    }
+    async expireCache() {
+        let isDone = false;
+        while (!isDone) {
+            await this.attachmentService.withContext(async (ctx) => {
+                isDone = await this.syncingService.deleteArchivedAttachments(ctx);
+            });
+        }
+    }
+    async clearQueue() {
+        await this.attachmentService.withContext(async (ctx) => {
+            await ctx.clearQueue();
+        });
+        await this.localStorage.clear();
+    }
+    /**
+     * 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
+     */
+    async verifyAttachments() {
+        await this.attachmentService.withContext(async (ctx) => {
+            const attachments = await ctx.getAttachments();
+            const updates = [];
+            for (const attachment of attachments) {
+                if (attachment.localUri == null) {
+                    continue;
+                }
+                const exists = await this.localStorage.fileExists(attachment.localUri);
+                if (exists) {
+                    // The file exists, this is correct
+                    continue;
+                }
+                const newLocalUri = this.localStorage.getLocalUri(attachment.filename);
+                const newExists = await this.localStorage.fileExists(newLocalUri);
+                if (newExists) {
+                    // The file exists locally but the localUri is broken, we update it.
+                    updates.push({
+                        ...attachment,
+                        localUri: newLocalUri
+                    });
+                }
+                else {
+                    // the file doesn't exist locally.
+                    if (attachment.state === AttachmentState.SYNCED) {
+                        // the file has been successfully synced to remote storage but is missing
+                        // we download it again
+                        updates.push({
+                            ...attachment,
+                            state: AttachmentState.QUEUED_DOWNLOAD,
+                            localUri: undefined
+                        });
+                    }
+                    else {
+                        // the file wasn't successfully synced to remote storage, we archive it
+                        updates.push({
+                            ...attachment,
+                            state: AttachmentState.ARCHIVED,
+                            localUri: undefined // Clears the value
+                        });
+                    }
+                }
+            }
+            await ctx.saveAttachments(updates);
+        });
+    }
+}
+//# sourceMappingURL=AttachmentQueue.js.map

package/lib/attachments/AttachmentQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttachmentQueue.js","sourceRoot":"","sources":["../../src/attachments/AttachmentQueue.ts"],"names":[],"mappings":"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"}

package/lib/attachments/AttachmentService.d.ts

@@ -0,0 +1,29 @@
+import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
+import { DifferentialWatchedQuery } from '../client/watched/processors/DifferentialQueryProcessor.js';
+import { ILogger } from '../utils/Logger.js';
+import { AttachmentContext } from './AttachmentContext.js';
+import { AttachmentRecord } from './Schema.js';
+/**
+ * Service for querying and watching attachment records in the database.
+ *
+ * @internal
+ */
+export declare class AttachmentService {
+    private db;
+    private logger;
+    private tableName;
+    private mutex;
+    private context;
+    constructor(db: AbstractPowerSyncDatabase, logger: ILogger, tableName?: string, archivedCacheLimit?: number);
+    /**
+     * Creates a differential watch query for active attachments requiring synchronization.
+     * @returns Watch query that emits changes for queued uploads, downloads, and deletes
+     */
+    watchActiveAttachments({ throttleMs }?: {
+        throttleMs?: number;
+    }): DifferentialWatchedQuery<AttachmentRecord>;
+    /**
+     * Executes a callback with exclusive access to the attachment context.
+     */
+    withContext<T>(callback: (context: AttachmentContext) => Promise<T>): Promise<T>;
+}

package/lib/attachments/AttachmentService.js

@@ -0,0 +1,56 @@
+import { Mutex } from 'async-mutex';
+import { mutexRunExclusive } from '../utils/mutex.js';
+import { AttachmentContext } from './AttachmentContext.js';
+import { AttachmentState } from './Schema.js';
+/**
+ * Service for querying and watching attachment records in the database.
+ *
+ * @internal
+ */
+export class AttachmentService {
+    db;
+    logger;
+    tableName;
+    mutex = new Mutex();
+    context;
+    constructor(db, logger, tableName = 'attachments', archivedCacheLimit = 100) {
+        this.db = db;
+        this.logger = logger;
+        this.tableName = tableName;
+        this.context = new AttachmentContext(db, tableName, logger, archivedCacheLimit);
+    }
+    /**
+     * Creates a differential watch query for active attachments requiring synchronization.
+     * @returns Watch query that emits changes for queued uploads, downloads, and deletes
+     */
+    watchActiveAttachments({ throttleMs } = {}) {
+        this.logger.info('Watching active attachments...');
+        const watch = this.db
+            .query({
+            sql: /* sql */ `
+          SELECT
+            *
+          FROM
+            ${this.tableName}
+          WHERE
+            state = ?
+            OR state = ?
+            OR state = ?
+          ORDER BY
+            timestamp ASC
+        `,
+            parameters: [AttachmentState.QUEUED_UPLOAD, AttachmentState.QUEUED_DOWNLOAD, AttachmentState.QUEUED_DELETE]
+        })
+            .differentialWatch({ throttleMs });
+        return watch;
+    }
+    /**
+     * Executes a callback with exclusive access to the attachment context.
+     */
+    async withContext(callback) {
+        return mutexRunExclusive(this.mutex, async () => {
+            return callback(this.context);
+        });
+    }
+}
+//# sourceMappingURL=AttachmentService.js.map

package/lib/attachments/AttachmentService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AttachmentService.js","sourceRoot":"","sources":["../../src/attachments/AttachmentService.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAoB,eAAe,EAAE,MAAM,aAAa,CAAC;AAEhE;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAKlB;IACA;IACA;IANF,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;IACpB,OAAO,CAAoB;IAEnC,YACU,EAA6B,EAC7B,MAAe,EACf,YAAoB,aAAa,EACzC,qBAA6B,GAAG;QAHxB,OAAE,GAAF,EAAE,CAA2B;QAC7B,WAAM,GAAN,MAAM,CAAS;QACf,cAAS,GAAT,SAAS,CAAwB;QAGzC,IAAI,CAAC,OAAO,GAAG,IAAI,iBAAiB,CAAC,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAClF,CAAC;IAED;;;OAGG;IACH,sBAAsB,CAAC,EAAE,UAAU,KAA8B,EAAE;QACjE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;QACnD,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE;aAClB,KAAK,CAAmB;YACvB,GAAG,EAAE,SAAS,CAAC;;;;cAIT,IAAI,CAAC,SAAS;;;;;;;SAOnB;YACD,UAAU,EAAE,CAAC,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,eAAe,EAAE,eAAe,CAAC,aAAa,CAAC;SAC5G,CAAC;aACD,iBAAiB,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QAErC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAI,QAAoD;QACvE,OAAO,iBAAiB,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,IAAI,EAAE;YAC9C,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/lib/attachments/LocalStorageAdapter.d.ts

@@ -0,0 +1,62 @@
+export type AttachmentData = ArrayBuffer | string;
+export declare enum EncodingType {
+    UTF8 = "utf8",
+    Base64 = "base64"
+}
+/**
+ * LocalStorageAdapter defines the interface for local file storage operations.
+ * Implementations handle file I/O, directory management, and storage initialization.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface LocalStorageAdapter {
+    /**
+     * Saves data to a local file.
+     * @param filePath Path where the file will be stored
+     * @param data Data to store (ArrayBuffer, Blob, or string)
+     * @returns Number of bytes written
+     */
+    saveFile(filePath: string, data: AttachmentData): Promise<number>;
+    /**
+     * Retrieves file data as an ArrayBuffer.
+     * @param filePath Path where the file is stored
+     * @returns ArrayBuffer containing the file data
+     */
+    readFile(filePath: string): Promise<ArrayBuffer>;
+    /**
+     * Deletes the file at the given path.
+     * @param filePath Path where the file is stored
+     */
+    deleteFile(filePath: string): Promise<void>;
+    /**
+     * Checks if a file exists at the given path.
+     * @param filePath Path where the file is stored
+     * @returns True if the file exists, false otherwise
+     */
+    fileExists(filePath: string): Promise<boolean>;
+    /**
+     * Creates a directory at the specified path.
+     * @param path The full path to the directory
+     */
+    makeDir(path: string): Promise<void>;
+    /**
+     * Removes a directory at the specified path.
+     * @param path The full path to the directory
+     */
+    rmDir(path: string): Promise<void>;
+    /**
+     * Initializes the storage adapter (e.g., creating necessary directories).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Clears all files in the storage.
+     */
+    clear(): Promise<void>;
+    /**
+     * Returns the file path for the provided filename in the storage directory.
+     * @param filename The filename to get the path for
+     * @returns The full file path
+     */
+    getLocalUri(filename: string): string;
+}

package/lib/attachments/LocalStorageAdapter.js

@@ -0,0 +1,6 @@
+export var EncodingType;
+(function (EncodingType) {
+    EncodingType["UTF8"] = "utf8";
+    EncodingType["Base64"] = "base64";
+})(EncodingType || (EncodingType = {}));
+//# sourceMappingURL=LocalStorageAdapter.js.map

package/lib/attachments/LocalStorageAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalStorageAdapter.js","sourceRoot":"","sources":["../../src/attachments/LocalStorageAdapter.ts"],"names":[],"mappings":"AAEA,MAAM,CAAN,IAAY,YAGX;AAHD,WAAY,YAAY;IACtB,6BAAa,CAAA;IACb,iCAAiB,CAAA;AACnB,CAAC,EAHW,YAAY,KAAZ,YAAY,QAGvB"}

package/lib/attachments/RemoteStorageAdapter.d.ts

@@ -0,0 +1,27 @@
+import { AttachmentRecord } from './Schema.js';
+/**
+ * RemoteStorageAdapter defines the interface for remote storage operations.
+ * Implementations handle uploading, downloading, and deleting files from remote storage.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface RemoteStorageAdapter {
+    /**
+     * Uploads a file to remote storage.
+     * @param fileData The binary content of the file to upload
+     * @param attachment The associated attachment metadata
+     */
+    uploadFile(fileData: ArrayBuffer, attachment: AttachmentRecord): Promise<void>;
+    /**
+     * Downloads a file from remote storage.
+     * @param attachment The attachment describing the file to download
+     * @returns The binary data of the downloaded file
+     */
+    downloadFile(attachment: AttachmentRecord): Promise<ArrayBuffer>;
+    /**
+     * Deletes a file from remote storage.
+     * @param attachment The attachment describing the file to delete
+     */
+    deleteFile(attachment: AttachmentRecord): Promise<void>;
+}

package/lib/attachments/RemoteStorageAdapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=RemoteStorageAdapter.js.map

package/lib/attachments/RemoteStorageAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteStorageAdapter.js","sourceRoot":"","sources":["../../src/attachments/RemoteStorageAdapter.ts"],"names":[],"mappings":""}

package/lib/attachments/Schema.d.ts

@@ -0,0 +1,50 @@
+import { Table } from '../db/schema/Table.js';
+import { TableV2Options } from '../db/schema/Table.js';
+export declare const ATTACHMENT_TABLE = "attachments";
+/**
+ * AttachmentRecord represents an attachment in the local database.
+ *
+ * @experimental
+ */
+export interface AttachmentRecord {
+    id: string;
+    filename: string;
+    localUri?: string;
+    size?: number;
+    mediaType?: string;
+    timestamp?: number;
+    metaData?: string;
+    hasSynced?: boolean;
+    state: AttachmentState;
+}
+/**
+ * Maps a database row to an AttachmentRecord.
+ *
+ * @param row - The database row object
+ * @returns The corresponding AttachmentRecord
+ *
+ * @experimental
+ */
+export declare function attachmentFromSql(row: any): AttachmentRecord;
+/**
+ * AttachmentState represents the current synchronization state of an attachment.
+ *
+ * @experimental
+ */
+export declare enum AttachmentState {
+    QUEUED_UPLOAD = 0,// Attachment to be uploaded
+    QUEUED_DOWNLOAD = 1,// Attachment to be downloaded
+    QUEUED_DELETE = 2,// Attachment to be deleted
+    SYNCED = 3,// Attachment has been synced
+    ARCHIVED = 4
+}
+export interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {
+}
+/**
+ * AttachmentTable defines the schema for the attachment queue table.
+ *
+ * @internal
+ */
+export declare class AttachmentTable extends Table {
+    constructor(options?: AttachmentTableOptions);
+}