@powersync/common 1.46.0 → 1.48.0

package/dist/index.d.cts

@@ -1452,68 +1452,6 @@ declare class Column {
     };
 }
 
-/**
- * A pending variant of a {@link RawTable} that doesn't have a name (because it would be inferred when creating the
- * schema).
- */
-type RawTableType = {
-    /**
-     * The statement to run when PowerSync detects that a row needs to be inserted or updated.
-     */
-    put: PendingStatement;
-    /**
-     * The statement to run when PowerSync detects that a row needs to be deleted.
-     */
-    delete: PendingStatement;
-};
-/**
- * A parameter to use as part of {@link PendingStatement}.
- *
- * For delete statements, only the `"Id"` value is supported - the sync client will replace it with the id of the row to
- * be synced.
- *
- * For insert and replace operations, the values of columns in the table are available as parameters through
- * `{Column: 'name'}`.
- */
-type PendingStatementParameter = 'Id' | {
-    Column: string;
-};
-/**
- * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
- */
-type PendingStatement = {
-    sql: string;
-    params: PendingStatementParameter[];
-};
-/**
- * Instructs PowerSync to sync data into a "raw" table.
- *
- * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
- * using client-side table and column constraints.
- *
- * To collect local writes to raw tables with PowerSync, custom triggers are required. See
- * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
- * using raw tables.
- *
- * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
- *
- * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
- * stability guarantees.
- */
-declare class RawTable implements RawTableType {
-    /**
-     * The name of the table.
-     *
-     * This does not have to match the actual table name in the schema - {@link put} and {@link delete} are free to use
-     * another table. Instead, this name is used by the sync client to recognize that operations on this table (as it
-     * appears in the source / backend database) are to be handled specially.
-     */
-    name: string;
-    put: PendingStatement;
-    delete: PendingStatement;
-    constructor(name: string, type: RawTableType);
-}
-
 interface IndexColumnOptions {
     name: string;
     ascending?: boolean;
@@ -1561,14 +1499,19 @@ declare class Index {
 declare class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {
 }
 
-interface SharedTableOptions {
+/**
+ * Options that apply both to JSON-based tables and raw tables.
+ */
+interface TableOrRawTableOptions {
     localOnly?: boolean;
     insertOnly?: boolean;
-    viewName?: string;
     trackPrevious?: boolean | TrackPreviousOptions;
     trackMetadata?: boolean;
     ignoreEmptyUpdates?: boolean;
 }
+interface SharedTableOptions extends TableOrRawTableOptions {
+    viewName?: string;
+}
 /** Whether to include previous column values when PowerSync tracks local changes.
  *
  * Including old values may be helpful for some backend connector implementations, which is
@@ -1692,14 +1635,14 @@ declare class Table<Columns extends ColumnsType = ColumnsType> {
     get validName(): boolean;
     validate(): void;
     toJSON(): {
-        name: string;
-        view_name: string;
-        local_only: boolean;
-        insert_only: boolean;
+        local_only: boolean | undefined;
+        insert_only: boolean | undefined;
         include_old: any;
         include_old_only_when_changed: boolean;
-        include_metadata: boolean;
-        ignore_empty_update: boolean;
+        include_metadata: boolean | undefined;
+        ignore_empty_update: boolean | undefined;
+        name: string;
+        view_name: string;
         columns: {
             name: string;
             type: ColumnType | undefined;
@@ -1715,6 +1658,101 @@ declare class Table<Columns extends ColumnsType = ColumnsType> {
     };
 }
 
+/**
+ * Instructs PowerSync to sync data into a "raw" table.
+ *
+ * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+ * using client-side table and column constraints.
+ *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
+ * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+ *
+ * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
+ * stability guarantees.
+ */
+type RawTableType = RawTableTypeWithStatements | InferredRawTableType;
+interface RawTableTypeWithStatements {
+    /**
+     * The statement to run when PowerSync detects that a row needs to be inserted or updated.
+     */
+    put: PendingStatement;
+    /**
+     * The statement to run when PowerSync detects that a row needs to be deleted.
+     */
+    delete: PendingStatement;
+    /**
+     * An optional statement to run when `disconnectAndClear()` is called on a PowerSync database.
+     */
+    clear?: string;
+}
+/**
+ * The schema of a {@link RawTableType} in the local database.
+ *
+ * This information is optional when declaring raw tables. However, providing it allows the sync client to infer `put`
+ * and `delete` statements automatically.
+ */
+interface RawTableSchema extends TableOrRawTableOptions {
+    /**
+     * The actual name of the raw table in the local schema.
+     *
+     * Unlike {@link RawTable.name}, which describes the name of synced tables to match, this reflects  the SQLite table
+     * name. This is used to infer {@link RawTableType.put} and {@link RawTableType.delete} statements for the sync
+     * client. It can also be used to auto-generate triggers forwarding writes on raw tables into the CRUD upload queue
+     * (using the `powersync_create_raw_table_crud_trigger` SQL function).
+     *
+     * When absent, defaults to {@link RawTable.name}.
+     */
+    tableName?: string;
+    /**
+     * An optional filter of columns that should be synced.
+     *
+     * By default, all columns in a raw table are considered for sync. If a filter is specified, PowerSync treats
+     * unmatched columns as local-only and will not attempt to sync them.
+     */
+    syncedColumns?: string[];
+}
+interface InferredRawTableType extends Partial<RawTableTypeWithStatements> {
+    schema: RawTableSchema;
+}
+/**
+ * A parameter to use as part of {@link PendingStatement}.
+ *
+ * For delete statements, only the `"Id"` value is supported - the sync client will replace it with the id of the row to
+ * be synced.
+ *
+ * For insert and replace operations, the values of columns in the table are available as parameters through
+ * `{Column: 'name'}`.
+ * The `"Rest"` parameter gets resolved to a JSON object covering all values from the synced row that haven't been
+ * covered by a `Column` parameter.
+ */
+type PendingStatementParameter = 'Id' | {
+    Column: string;
+} | 'Rest';
+/**
+ * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
+ */
+type PendingStatement = {
+    sql: string;
+    params: PendingStatementParameter[];
+};
+/**
+ * @internal
+ */
+type RawTable<T extends RawTableType = RawTableType> = T & {
+    /**
+     * The name of the table.
+     *
+     * This does not have to match the actual table name in the schema - {@link RawTableType.put} and
+     * {@link RawTableType.delete} are free to use another table. Instead, this name is used by the sync client to
+     * recognize that operations on this table (as it appears in the source / backend database) are to be handled
+     * specially.
+     */
+    name: string;
+};
+
 type SchemaType = Record<string, Table<any>>;
 type SchemaTableType<S extends SchemaType> = {
     [K in keyof S]: RowType<S[K]>;
@@ -1742,14 +1780,14 @@ declare class Schema<S extends SchemaType = SchemaType> {
     validate(): void;
     toJSON(): {
         tables: {
-            name: string;
-            view_name: string;
-            local_only: boolean;
-            insert_only: boolean;
+            local_only: boolean | undefined;
+            insert_only: boolean | undefined;
             include_old: any;
             include_old_only_when_changed: boolean;
-            include_metadata: boolean;
-            ignore_empty_update: boolean;
+            include_metadata: boolean | undefined;
+            ignore_empty_update: boolean | undefined;
+            name: string;
+            view_name: string;
             columns: {
                 name: string;
                 type: ColumnType | undefined;
@@ -1763,8 +1801,15 @@ declare class Schema<S extends SchemaType = SchemaType> {
                 }[];
             }[];
         }[];
-        raw_tables: RawTable[];
+        raw_tables: unknown[];
     };
+    /**
+     * Returns a representation of the raw table that is understood by the PowerSync SQLite core extension.
+     *
+     * The output of this can be passed through `JSON.serialize` and then used in `powersync_create_raw_table_crud_trigger`
+     * to define triggers for this table.
+     */
+    static rawTableToJson(table: RawTable): unknown;
 }
 
 interface PowerSyncBackendConnector {
@@ -3529,6 +3574,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 +4300,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.
- *
- */
-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.
+ * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
  */
-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 +4313,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, 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, TableOrRawTableOptions, 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 };