@powersync/common 1.46.0 → 1.47.0

package/dist/index.d.cts

@@ -3529,6 +3529,530 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     private executeReadOnly;
 }
 
+declare const LogLevel: {
+    TRACE: Logger.ILogLevel;
+    DEBUG: Logger.ILogLevel;
+    INFO: Logger.ILogLevel;
+    TIME: Logger.ILogLevel;
+    WARN: Logger.ILogLevel;
+    ERROR: Logger.ILogLevel;
+    OFF: Logger.ILogLevel;
+};
+interface CreateLoggerOptions {
+    logLevel?: ILogLevel;
+}
+/**
+ * Retrieves the base (default) logger instance.
+ *
+ * This base logger controls the default logging configuration and is shared
+ * across all loggers created with `createLogger`. Adjusting settings on this
+ * base logger affects all loggers derived from it unless explicitly overridden.
+ *
+ */
+declare function createBaseLogger(): typeof Logger;
+/**
+ * Creates and configures a new named logger based on the base logger.
+ *
+ * Named loggers allow specific modules or areas of your application to have
+ * their own logging levels and behaviors. These loggers inherit configuration
+ * from the base logger by default but can override settings independently.
+ */
+declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;
+
+declare const ATTACHMENT_TABLE = "attachments";
+/**
+ * AttachmentRecord represents an attachment in the local database.
+ *
+ * @experimental
+ */
+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
+ */
+declare function attachmentFromSql(row: any): AttachmentRecord;
+/**
+ * AttachmentState represents the current synchronization state of an attachment.
+ *
+ * @experimental
+ */
+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
+}
+interface AttachmentTableOptions extends Omit<TableV2Options, 'name' | 'columns'> {
+}
+/**
+ * AttachmentTable defines the schema for the attachment queue table.
+ *
+ * @internal
+ */
+declare class AttachmentTable extends Table {
+    constructor(options?: AttachmentTableOptions);
+}
+
+/**
+ * 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
+ */
+declare class AttachmentContext {
+    /** PowerSync database instance for executing queries */
+    db: AbstractPowerSyncDatabase;
+    /** Name of the database table storing attachment records */
+    tableName: string;
+    /** Logger instance for diagnostic information */
+    logger: ILogger;
+    /** Maximum number of archived attachments to keep before cleanup */
+    archivedCacheLimit: number;
+    /**
+     * 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: AbstractPowerSyncDatabase, tableName: string | undefined, logger: ILogger, archivedCacheLimit: number);
+    /**
+     * 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
+     */
+    getActiveAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    getArchivedAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    getAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    upsertAttachment(attachment: AttachmentRecord, context: Transaction): Promise<void>;
+    getAttachment(id: string): Promise<AttachmentRecord | 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
+     */
+    deleteAttachment(attachmentId: string): Promise<void>;
+    clearQueue(): Promise<void>;
+    deleteArchivedAttachments(callback?: (attachments: AttachmentRecord[]) => Promise<void>): Promise<boolean>;
+    /**
+     * 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
+     */
+    saveAttachments(attachments: AttachmentRecord[]): Promise<void>;
+}
+
+/**
+ * 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.
+ */
+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>;
+}
+
+type AttachmentData = ArrayBuffer | string;
+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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+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>;
+}
+
+/**
+ * WatchedAttachmentItem represents an attachment reference in your application's data model.
+ * Use either filename OR fileExtension (not both).
+ *
+ * @experimental
+ */
+type WatchedAttachmentItem = {
+    id: string;
+    filename: string;
+    fileExtension?: never;
+    metaData?: string;
+} | {
+    id: string;
+    fileExtension: string;
+    filename?: never;
+    metaData?: string;
+};
+
+/**
+ * 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.
+ */
+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>;
+}
+
+/**
+ * Service for querying and watching attachment records in the database.
+ *
+ * @internal
+ */
+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>;
+}
+
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+declare class SyncingService {
+    private attachmentService;
+    private localStorage;
+    private remoteStorage;
+    private logger;
+    private errorHandler?;
+    constructor(attachmentService: AttachmentService, localStorage: LocalStorageAdapter, remoteStorage: RemoteStorageAdapter, logger: ILogger, errorHandler?: AttachmentErrorHandler);
+    /**
+     * Processes attachments based on their state (upload, download, or delete).
+     * All updates are saved in a single batch after processing.
+     *
+     * @param attachments - Array of attachment records to process
+     * @param context - Attachment context for database operations
+     * @returns Promise that resolves when all attachments have been processed and saved
+     */
+    processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void>;
+    /**
+     * Uploads an attachment from local storage to remote storage.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to upload
+     * @returns Updated attachment record with new state
+     * @throws Error if the attachment has no localUri
+     */
+    uploadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Downloads an attachment from remote storage to local storage.
+     * Retrieves the file, converts to base64, and saves locally.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to download
+     * @returns Updated attachment record with local URI and new state
+     */
+    downloadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Deletes an attachment from both remote and local storage.
+     * Removes the remote file, local file (if exists), and the attachment record.
+     * On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to delete
+     * @returns Updated attachment record
+     */
+    deleteAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Performs cleanup of archived attachments by removing their local files and records.
+     * Errors during local file deletion are logged but do not prevent record deletion.
+     */
+    deleteArchivedAttachments(context: AttachmentContext): Promise<boolean>;
+}
+
 interface PowerSyncOpenFactoryOptions extends Partial<PowerSyncDatabaseOptions>, SQLOpenOptions {
     /** Schema used for the local database. */
     schema: Schema;
@@ -3731,35 +4255,12 @@ declare class ControlledExecutor<T> {
     private execute;
 }
 
-declare const LogLevel: {
-    TRACE: Logger.ILogLevel;
-    DEBUG: Logger.ILogLevel;
-    INFO: Logger.ILogLevel;
-    TIME: Logger.ILogLevel;
-    WARN: Logger.ILogLevel;
-    ERROR: Logger.ILogLevel;
-    OFF: Logger.ILogLevel;
-};
-interface CreateLoggerOptions {
-    logLevel?: ILogLevel;
-}
 /**
- * Retrieves the base (default) logger instance.
- *
- * This base logger controls the default logging configuration and is shared
- * across all loggers created with `createLogger`. Adjusting settings on this
- * base logger affects all loggers derived from it unless explicitly overridden.
- *
+ * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
  */
-declare function createBaseLogger(): typeof Logger;
-/**
- * Creates and configures a new named logger based on the base logger.
- *
- * Named loggers allow specific modules or areas of your application to have
- * their own logging levels and behaviors. These loggers inherit configuration
- * from the base logger by default but can override settings independently.
- */
-declare function createLogger(name: string, options?: CreateLoggerOptions): ILogger;
+declare function mutexRunExclusive<T>(mutex: Mutex, callback: () => Promise<T>, options?: {
+    timeoutMs?: number;
+}): Promise<T>;
 
 interface ParsedQuery {
     sqlStatement: string;
@@ -3767,5 +4268,5 @@ interface ParsedQuery {
 }
 declare const parseQuery: <T>(query: string | CompilableQuery<T>, parameters: any[]) => ParsedQuery;
 
-export { AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RawTable, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
-export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CreateSyncImplementationOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, InternalSubscriptionAdapter, LinkQueryOptions, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PendingStatement, PendingStatementParameter, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RawTableType, RemoteConnector, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SubscribedStream, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStream, SyncStreamDescription, SyncStreamOptions, SyncStreamStatus, SyncStreamSubscribeOptions, SyncStreamSubscription, SyncSubscriptionDescription, TableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerClaimManager, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerManagerConfig, TriggerRemoveCallback, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState, WithDiffOptions };
+export { ATTACHMENT_TABLE, AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, AttachmentContext, AttachmentQueue, AttachmentService, AttachmentState, AttachmentTable, BaseObserver, Column, ColumnType, ConnectionClosedError, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, EncodingType, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, MEMORY_TRIGGER_CLAIM_MANAGER, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RawTable, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, SyncingService, Table, TableV2, TriggerManagerImpl, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, attachmentFromSql, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, mutexRunExclusive, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
+export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, AttachmentData, AttachmentErrorHandler, AttachmentRecord, AttachmentTableOptions, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CreateSyncImplementationOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, InternalSubscriptionAdapter, LinkQueryOptions, LocalStorageAdapter, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PendingStatement, PendingStatementParameter, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RawTableType, RemoteConnector, RemoteStorageAdapter, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SubscribedStream, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStream, SyncStreamDescription, SyncStreamOptions, SyncStreamStatus, SyncStreamSubscribeOptions, SyncStreamSubscription, SyncSubscriptionDescription, TableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerClaimManager, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerManagerConfig, TriggerRemoveCallback, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedAttachmentItem, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState, WithDiffOptions };

package/lib/attachments/AttachmentContext.d.ts

@@ -0,0 +1,86 @@
+import { AbstractPowerSyncDatabase } from '../client/AbstractPowerSyncDatabase.js';
+import { ILogger } from '../utils/Logger.js';
+import { Transaction } from '../db/DBAdapter.js';
+import { AttachmentRecord } 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 declare class AttachmentContext {
+    /** PowerSync database instance for executing queries */
+    db: AbstractPowerSyncDatabase;
+    /** Name of the database table storing attachment records */
+    tableName: string;
+    /** Logger instance for diagnostic information */
+    logger: ILogger;
+    /** Maximum number of archived attachments to keep before cleanup */
+    archivedCacheLimit: number;
+    /**
+     * 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: AbstractPowerSyncDatabase, tableName: string | undefined, logger: ILogger, archivedCacheLimit: number);
+    /**
+     * 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
+     */
+    getActiveAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    getArchivedAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    getAttachments(): Promise<AttachmentRecord[]>;
+    /**
+     * 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
+     */
+    upsertAttachment(attachment: AttachmentRecord, context: Transaction): Promise<void>;
+    getAttachment(id: string): Promise<AttachmentRecord | 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
+     */
+    deleteAttachment(attachmentId: string): Promise<void>;
+    clearQueue(): Promise<void>;
+    deleteArchivedAttachments(callback?: (attachments: AttachmentRecord[]) => Promise<void>): Promise<boolean>;
+    /**
+     * 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
+     */
+    saveAttachments(attachments: AttachmentRecord[]): Promise<void>;
+}