@powersync/common 1.46.0 → 1.47.0

package/lib/attachments/AttachmentContext.js

@@ -0,0 +1,229 @@
+import { AttachmentState, attachmentFromSql } from './Schema.js';
+/**
+ * AttachmentContext provides database operations for managing attachment records.
+ *
+ * Provides methods to query, insert, update, and delete attachment records with
+ * proper transaction management through PowerSync.
+ *
+ * @internal
+ */
+export class AttachmentContext {
+    /** PowerSync database instance for executing queries */
+    db;
+    /** Name of the database table storing attachment records */
+    tableName;
+    /** Logger instance for diagnostic information */
+    logger;
+    /** Maximum number of archived attachments to keep before cleanup */
+    archivedCacheLimit = 100;
+    /**
+     * Creates a new AttachmentContext instance.
+     *
+     * @param db - PowerSync database instance
+     * @param tableName - Name of the table storing attachment records. Default: 'attachments'
+     * @param logger - Logger instance for diagnostic output
+     */
+    constructor(db, tableName = 'attachments', logger, archivedCacheLimit) {
+        this.db = db;
+        this.tableName = tableName;
+        this.logger = logger;
+        this.archivedCacheLimit = archivedCacheLimit;
+    }
+    /**
+     * Retrieves all active attachments that require synchronization.
+     * Active attachments include those queued for upload, download, or delete.
+     * Results are ordered by timestamp in ascending order.
+     *
+     * @returns Promise resolving to an array of active attachment records
+     */
+    async getActiveAttachments() {
+        const attachments = await this.db.getAll(
+        /* sql */
+        `
+        SELECT
+          *
+        FROM
+          ${this.tableName}
+        WHERE
+          state = ?
+          OR state = ?
+          OR state = ?
+        ORDER BY
+          timestamp ASC
+      `, [AttachmentState.QUEUED_UPLOAD, AttachmentState.QUEUED_DOWNLOAD, AttachmentState.QUEUED_DELETE]);
+        return attachments.map(attachmentFromSql);
+    }
+    /**
+     * Retrieves all archived attachments.
+     *
+     * Archived attachments are no longer referenced but haven't been permanently deleted.
+     * These are candidates for cleanup operations to free up storage space.
+     *
+     * @returns Promise resolving to an array of archived attachment records
+     */
+    async getArchivedAttachments() {
+        const attachments = await this.db.getAll(
+        /* sql */
+        `
+        SELECT
+          *
+        FROM
+          ${this.tableName}
+        WHERE
+          state = ?
+        ORDER BY
+          timestamp ASC
+      `, [AttachmentState.ARCHIVED]);
+        return attachments.map(attachmentFromSql);
+    }
+    /**
+     * Retrieves all attachment records regardless of state.
+     * Results are ordered by timestamp in ascending order.
+     *
+     * @returns Promise resolving to an array of all attachment records
+     */
+    async getAttachments() {
+        const attachments = await this.db.getAll(
+        /* sql */
+        `
+        SELECT
+          *
+        FROM
+          ${this.tableName}
+        ORDER BY
+          timestamp ASC
+      `, []);
+        return attachments.map(attachmentFromSql);
+    }
+    /**
+     * Inserts or updates an attachment record within an existing transaction.
+     *
+     * Performs an upsert operation (INSERT OR REPLACE). Must be called within
+     * an active database transaction context.
+     *
+     * @param attachment - The attachment record to upsert
+     * @param context - Active database transaction context
+     */
+    async upsertAttachment(attachment, context) {
+        await context.execute(
+        /* sql */
+        `
+        INSERT
+        OR REPLACE INTO ${this.tableName} (
+          id,
+          filename,
+          local_uri,
+          size,
+          media_type,
+          timestamp,
+          state,
+          has_synced,
+          meta_data
+        )
+        VALUES
+          (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `, [
+            attachment.id,
+            attachment.filename,
+            attachment.localUri || null,
+            attachment.size || null,
+            attachment.mediaType || null,
+            attachment.timestamp,
+            attachment.state,
+            attachment.hasSynced ? 1 : 0,
+            attachment.metaData || null
+        ]);
+    }
+    async getAttachment(id) {
+        const attachment = await this.db.get(
+        /* sql */
+        `
+        SELECT
+          *
+        FROM
+          ${this.tableName}
+        WHERE
+          id = ?
+      `, [id]);
+        return attachment ? attachmentFromSql(attachment) : undefined;
+    }
+    /**
+     * Permanently deletes an attachment record from the database.
+     *
+     * This operation removes the attachment record but does not delete
+     * the associated local or remote files. File deletion should be handled
+     * separately through the appropriate storage adapters.
+     *
+     * @param attachmentId - Unique identifier of the attachment to delete
+     */
+    async deleteAttachment(attachmentId) {
+        await this.db.writeTransaction((tx) => tx.execute(
+        /* sql */
+        `
+          DELETE FROM ${this.tableName}
+          WHERE
+            id = ?
+        `, [attachmentId]));
+    }
+    async clearQueue() {
+        await this.db.writeTransaction((tx) => tx.execute(/* sql */ ` DELETE FROM ${this.tableName} `));
+    }
+    async deleteArchivedAttachments(callback) {
+        const limit = 1000;
+        const results = await this.db.getAll(
+        /* sql */
+        `
+        SELECT
+          *
+        FROM
+          ${this.tableName}
+        WHERE
+          state = ?
+        ORDER BY
+          timestamp DESC
+        LIMIT
+          ?
+        OFFSET
+          ?
+      `, [AttachmentState.ARCHIVED, limit, this.archivedCacheLimit]);
+        const archivedAttachments = results.map(attachmentFromSql);
+        if (archivedAttachments.length === 0)
+            return false;
+        await callback?.(archivedAttachments);
+        this.logger.info(`Deleting ${archivedAttachments.length} archived attachments. Archived attachment exceeds cache archiveCacheLimit of ${this.archivedCacheLimit}.`);
+        const ids = archivedAttachments.map((attachment) => attachment.id);
+        await this.db.execute(
+        /* sql */
+        `
+        DELETE FROM ${this.tableName}
+        WHERE
+          id IN (
+            SELECT
+              json_each.value
+            FROM
+              json_each (?)
+          );
+      `, [JSON.stringify(ids)]);
+        this.logger.info(`Deleted ${archivedAttachments.length} archived attachments`);
+        return archivedAttachments.length < limit;
+    }
+    /**
+     * Saves multiple attachment records in a single transaction.
+     *
+     * All updates are saved in a single batch after processing.
+     * If the attachments array is empty, no database operations are performed.
+     *
+     * @param attachments - Array of attachment records to save
+     */
+    async saveAttachments(attachments) {
+        if (attachments.length === 0) {
+            return;
+        }
+        await this.db.writeTransaction(async (tx) => {
+            for (const attachment of attachments) {
+                await this.upsertAttachment(attachment, tx);
+            }
+        });
+    }
+}
+//# sourceMappingURL=AttachmentContext.js.map

package/lib/attachments/AttachmentContext.js.map

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

package/lib/attachments/AttachmentErrorHandler.d.ts

@@ -0,0 +1,31 @@
+import { AttachmentRecord } from './Schema.js';
+/**
+ * SyncErrorHandler provides custom error handling for attachment sync operations.
+ * Implementations determine whether failed operations should be retried or archived.
+ *
+ * @experimental
+ * @alpha This is currently experimental and may change without a major version bump.
+ */
+export interface AttachmentErrorHandler {
+    /**
+     * Handles a download error for a specific attachment.
+     * @param attachment The attachment that failed to download
+     * @param error The error encountered during the download
+     * @returns `true` to retry the operation, `false` to archive the attachment
+     */
+    onDownloadError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
+    /**
+     * Handles an upload error for a specific attachment.
+     * @param attachment The attachment that failed to upload
+     * @param error The error encountered during the upload
+     * @returns `true` to retry the operation, `false` to archive the attachment
+     */
+    onUploadError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
+    /**
+     * Handles a delete error for a specific attachment.
+     * @param attachment The attachment that failed to delete
+     * @param error The error encountered during the delete
+     * @returns `true` to retry the operation, `false` to archive the attachment
+     */
+    onDeleteError(attachment: AttachmentRecord, error: unknown): Promise<boolean>;
+}

package/lib/attachments/AttachmentErrorHandler.js

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

package/lib/attachments/AttachmentErrorHandler.js.map

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

package/lib/attachments/AttachmentQueue.d.ts

@@ -0,0 +1,149 @@
+import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
+import { ILogger } from '../utils/Logger.js';
+import { Transaction } from '../db/DBAdapter.js';
+import { AttachmentData, LocalStorageAdapter } from './LocalStorageAdapter.js';
+import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
+import { AttachmentRecord } from './Schema.js';
+import { WatchedAttachmentItem } from './WatchedAttachmentItem.js';
+import { AttachmentErrorHandler } from './AttachmentErrorHandler.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 declare class AttachmentQueue {
+    /** Timer for periodic synchronization operations */
+    private periodicSyncTimer?;
+    /** Service for synchronizing attachments between local and remote storage */
+    private readonly syncingService;
+    /** Adapter for local file storage operations */
+    readonly localStorage: LocalStorageAdapter;
+    /** Adapter for remote file storage operations */
+    readonly remoteStorage: RemoteStorageAdapter;
+    /**
+     * 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.
+     */
+    private readonly watchAttachments;
+    /** Name of the database table storing attachment records */
+    readonly tableName: string;
+    /** Logger instance for diagnostic information */
+    readonly logger: ILogger;
+    /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+    readonly syncIntervalMs: number;
+    /** Duration in milliseconds to throttle sync operations */
+    readonly syncThrottleDuration: number;
+    /** Whether to automatically download remote attachments. Default: true */
+    readonly downloadAttachments: boolean;
+    /** Maximum number of archived attachments to keep before cleanup. Default: 100 */
+    readonly archivedCacheLimit: number;
+    /** Service for managing attachment-related database operations */
+    private readonly attachmentService;
+    /** PowerSync database instance */
+    private readonly db;
+    /** Cleanup function for status change listener */
+    private statusListenerDispose?;
+    private watchActiveAttachments;
+    private 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, syncIntervalMs, syncThrottleDuration, downloadAttachments, archivedCacheLimit, errorHandler }: {
+        db: AbstractPowerSyncDatabase;
+        remoteStorage: RemoteStorageAdapter;
+        localStorage: LocalStorageAdapter;
+        watchAttachments: (onUpdate: (attachment: WatchedAttachmentItem[]) => Promise<void>, signal: AbortSignal) => void;
+        tableName?: string;
+        logger?: ILogger;
+        syncIntervalMs?: number;
+        syncThrottleDuration?: number;
+        downloadAttachments?: boolean;
+        archivedCacheLimit?: number;
+        errorHandler?: AttachmentErrorHandler;
+    });
+    /**
+     * Generates a new attachment ID using a SQLite UUID function.
+     *
+     * @returns Promise resolving to the new attachment ID
+     */
+    generateAttachmentId(): Promise<string>;
+    /**
+     * 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
+     */
+    startSync(): Promise<void>;
+    /**
+     * 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.
+     */
+    syncStorage(): Promise<void>;
+    /**
+     * Stops the attachment synchronization process.
+     *
+     * Clears the periodic sync timer and closes all active attachment watchers.
+     */
+    stopSync(): Promise<void>;
+    /**
+     * 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
+     */
+    saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }: {
+        data: AttachmentData;
+        fileExtension: string;
+        mediaType?: string;
+        metaData?: string;
+        id?: string;
+        updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
+    }): Promise<AttachmentRecord>;
+    deleteFile({ id, updateHook }: {
+        id: string;
+        updateHook?: (transaction: Transaction, attachment: AttachmentRecord) => Promise<void>;
+    }): Promise<void>;
+    expireCache(): Promise<void>;
+    clearQueue(): Promise<void>;
+    /**
+     * 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
+     */
+    verifyAttachments(): Promise<void>;
+}