@powersync/common 1.46.0 → 1.48.0

package/dist/bundle.cjs

@@ -2,6 +2,1233 @@
 
 var asyncMutex = require('async-mutex');
 
+// https://www.sqlite.org/lang_expr.html#castexpr
+exports.ColumnType = void 0;
+(function (ColumnType) {
+    ColumnType["TEXT"] = "TEXT";
+    ColumnType["INTEGER"] = "INTEGER";
+    ColumnType["REAL"] = "REAL";
+})(exports.ColumnType || (exports.ColumnType = {}));
+const text = {
+    type: exports.ColumnType.TEXT
+};
+const integer = {
+    type: exports.ColumnType.INTEGER
+};
+const real = {
+    type: exports.ColumnType.REAL
+};
+// powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
+// In earlier versions this was limited to 63.
+const MAX_AMOUNT_OF_COLUMNS = 1999;
+const column = {
+    text,
+    integer,
+    real
+};
+class Column {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get name() {
+        return this.options.name;
+    }
+    get type() {
+        return this.options.type;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type
+        };
+    }
+}
+
+const DEFAULT_INDEX_COLUMN_OPTIONS = {
+    ascending: true
+};
+class IndexedColumn {
+    options;
+    static createAscending(column) {
+        return new IndexedColumn({
+            name: column,
+            ascending: true
+        });
+    }
+    constructor(options) {
+        this.options = { ...DEFAULT_INDEX_COLUMN_OPTIONS, ...options };
+    }
+    get name() {
+        return this.options.name;
+    }
+    get ascending() {
+        return this.options.ascending;
+    }
+    toJSON(table) {
+        return {
+            name: this.name,
+            ascending: this.ascending,
+            type: table.columns.find((column) => column.name === this.name)?.type ?? exports.ColumnType.TEXT
+        };
+    }
+}
+
+const DEFAULT_INDEX_OPTIONS = {
+    columns: []
+};
+class Index {
+    options;
+    static createAscending(options, columnNames) {
+        return new Index({
+            ...options,
+            columns: columnNames.map((name) => IndexedColumn.createAscending(name))
+        });
+    }
+    constructor(options) {
+        this.options = options;
+        this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
+    }
+    get name() {
+        return this.options.name;
+    }
+    get columns() {
+        return this.options.columns ?? [];
+    }
+    toJSON(table) {
+        return {
+            name: this.name,
+            columns: this.columns.map((c) => c.toJSON(table))
+        };
+    }
+}
+
+/**
+ * @internal Not exported from `index.ts`.
+ */
+function encodeTableOptions(options) {
+    const trackPrevious = options.trackPrevious;
+    return {
+        local_only: options.localOnly,
+        insert_only: options.insertOnly,
+        include_old: trackPrevious && (trackPrevious.columns ?? true),
+        include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
+        include_metadata: options.trackMetadata,
+        ignore_empty_update: options.ignoreEmptyUpdates
+    };
+}
+
+const DEFAULT_TABLE_OPTIONS = {
+    indexes: [],
+    insertOnly: false,
+    localOnly: false,
+    trackPrevious: false,
+    trackMetadata: false,
+    ignoreEmptyUpdates: false
+};
+const InvalidSQLCharacters = /["'%,.#\s[\]]/;
+class Table {
+    options;
+    _mappedColumns;
+    static createLocalOnly(options) {
+        return new Table({ ...options, localOnly: true, insertOnly: false });
+    }
+    static createInsertOnly(options) {
+        return new Table({ ...options, localOnly: false, insertOnly: true });
+    }
+    /**
+     * Create a table.
+     * @deprecated This was only only included for TableV2 and is no longer necessary.
+     * Prefer to use new Table() directly.
+     *
+     * TODO remove in the next major release.
+     */
+    static createTable(name, table) {
+        return new Table({
+            name,
+            columns: table.columns,
+            indexes: table.indexes,
+            localOnly: table.options.localOnly,
+            insertOnly: table.options.insertOnly,
+            viewName: table.options.viewName
+        });
+    }
+    constructor(optionsOrColumns, v2Options) {
+        if (this.isTableV1(optionsOrColumns)) {
+            this.initTableV1(optionsOrColumns);
+        }
+        else {
+            this.initTableV2(optionsOrColumns, v2Options);
+        }
+    }
+    copyWithName(name) {
+        return new Table({
+            ...this.options,
+            name
+        });
+    }
+    isTableV1(arg) {
+        return 'columns' in arg && Array.isArray(arg.columns);
+    }
+    initTableV1(options) {
+        this.options = {
+            ...options,
+            indexes: options.indexes || []
+        };
+        this.applyDefaultOptions();
+    }
+    initTableV2(columns, options) {
+        const convertedColumns = Object.entries(columns).map(([name, columnInfo]) => new Column({ name, type: columnInfo.type }));
+        const convertedIndexes = Object.entries(options?.indexes ?? {}).map(([name, columnNames]) => new Index({
+            name,
+            columns: columnNames.map((name) => new IndexedColumn({
+                name: name.replace(/^-/, ''),
+                ascending: !name.startsWith('-')
+            }))
+        }));
+        this.options = {
+            name: '',
+            columns: convertedColumns,
+            indexes: convertedIndexes,
+            viewName: options?.viewName,
+            insertOnly: options?.insertOnly,
+            localOnly: options?.localOnly,
+            trackPrevious: options?.trackPrevious,
+            trackMetadata: options?.trackMetadata,
+            ignoreEmptyUpdates: options?.ignoreEmptyUpdates
+        };
+        this.applyDefaultOptions();
+        this._mappedColumns = columns;
+    }
+    applyDefaultOptions() {
+        this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
+        this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
+        this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
+        this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
+        this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
+    }
+    get name() {
+        return this.options.name;
+    }
+    get viewNameOverride() {
+        return this.options.viewName;
+    }
+    get viewName() {
+        return this.viewNameOverride ?? this.name;
+    }
+    get columns() {
+        return this.options.columns;
+    }
+    get columnMap() {
+        return (this._mappedColumns ??
+            this.columns.reduce((hash, column) => {
+                hash[column.name] = { type: column.type ?? exports.ColumnType.TEXT };
+                return hash;
+            }, {}));
+    }
+    get indexes() {
+        return this.options.indexes ?? [];
+    }
+    get localOnly() {
+        return this.options.localOnly;
+    }
+    get insertOnly() {
+        return this.options.insertOnly;
+    }
+    get trackPrevious() {
+        return this.options.trackPrevious;
+    }
+    get trackMetadata() {
+        return this.options.trackMetadata;
+    }
+    get ignoreEmptyUpdates() {
+        return this.options.ignoreEmptyUpdates;
+    }
+    get internalName() {
+        if (this.options.localOnly) {
+            return `ps_data_local__${this.name}`;
+        }
+        return `ps_data__${this.name}`;
+    }
+    get validName() {
+        if (InvalidSQLCharacters.test(this.name)) {
+            return false;
+        }
+        if (this.viewNameOverride != null && InvalidSQLCharacters.test(this.viewNameOverride)) {
+            return false;
+        }
+        return true;
+    }
+    validate() {
+        if (InvalidSQLCharacters.test(this.name)) {
+            throw new Error(`Invalid characters in table name: ${this.name}`);
+        }
+        if (this.viewNameOverride && InvalidSQLCharacters.test(this.viewNameOverride)) {
+            throw new Error(`Invalid characters in view name: ${this.viewNameOverride}`);
+        }
+        if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
+            throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
+        }
+        if (this.trackMetadata && this.localOnly) {
+            throw new Error(`Can't include metadata for local-only tables.`);
+        }
+        if (this.trackPrevious != false && this.localOnly) {
+            throw new Error(`Can't include old values for local-only tables.`);
+        }
+        const columnNames = new Set();
+        columnNames.add('id');
+        for (const column of this.columns) {
+            const { name: columnName } = column;
+            if (column.name === 'id') {
+                throw new Error(`An id column is automatically added, custom id columns are not supported`);
+            }
+            if (columnNames.has(columnName)) {
+                throw new Error(`Duplicate column ${columnName}`);
+            }
+            if (InvalidSQLCharacters.test(columnName)) {
+                throw new Error(`Invalid characters in column name: ${column.name}`);
+            }
+            columnNames.add(columnName);
+        }
+        const indexNames = new Set();
+        for (const index of this.indexes) {
+            if (indexNames.has(index.name)) {
+                throw new Error(`Duplicate index ${index.name}`);
+            }
+            if (InvalidSQLCharacters.test(index.name)) {
+                throw new Error(`Invalid characters in index name: ${index.name}`);
+            }
+            for (const column of index.columns) {
+                if (!columnNames.has(column.name)) {
+                    throw new Error(`Column ${column.name} not found for index ${index.name}`);
+                }
+            }
+            indexNames.add(index.name);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            view_name: this.viewName,
+            columns: this.columns.map((c) => c.toJSON()),
+            indexes: this.indexes.map((e) => e.toJSON(this)),
+            ...encodeTableOptions(this)
+        };
+    }
+}
+
+const ATTACHMENT_TABLE = 'attachments';
+/**
+ * Maps a database row to an AttachmentRecord.
+ *
+ * @param row - The database row object
+ * @returns The corresponding AttachmentRecord
+ *
+ * @experimental
+ */
+function attachmentFromSql(row) {
+    return {
+        id: row.id,
+        filename: row.filename,
+        localUri: row.local_uri,
+        size: row.size,
+        mediaType: row.media_type,
+        timestamp: row.timestamp,
+        metaData: row.meta_data,
+        hasSynced: row.has_synced === 1,
+        state: row.state
+    };
+}
+/**
+ * AttachmentState represents the current synchronization state of an attachment.
+ *
+ * @experimental
+ */
+exports.AttachmentState = void 0;
+(function (AttachmentState) {
+    AttachmentState[AttachmentState["QUEUED_UPLOAD"] = 0] = "QUEUED_UPLOAD";
+    AttachmentState[AttachmentState["QUEUED_DOWNLOAD"] = 1] = "QUEUED_DOWNLOAD";
+    AttachmentState[AttachmentState["QUEUED_DELETE"] = 2] = "QUEUED_DELETE";
+    AttachmentState[AttachmentState["SYNCED"] = 3] = "SYNCED";
+    AttachmentState[AttachmentState["ARCHIVED"] = 4] = "ARCHIVED"; // Attachment has been orphaned, i.e. the associated record has been deleted
+})(exports.AttachmentState || (exports.AttachmentState = {}));
+/**
+ * AttachmentTable defines the schema for the attachment queue table.
+ *
+ * @internal
+ */
+class AttachmentTable extends Table {
+    constructor(options) {
+        super({
+            filename: column.text,
+            local_uri: column.text,
+            timestamp: column.integer,
+            size: column.integer,
+            media_type: column.text,
+            state: column.integer, // Corresponds to AttachmentState
+            has_synced: column.integer,
+            meta_data: column.text
+        }, {
+            ...options,
+            viewName: options?.viewName ?? ATTACHMENT_TABLE,
+            localOnly: true,
+            insertOnly: false
+        });
+    }
+}
+
+/**
+ * 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
+ */
+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
+      `, [exports.AttachmentState.QUEUED_UPLOAD, exports.AttachmentState.QUEUED_DOWNLOAD, exports.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
+      `, [exports.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
+          ?
+      `, [exports.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);
+            }
+        });
+    }
+}
+
+exports.WatchedQueryListenerEvent = void 0;
+(function (WatchedQueryListenerEvent) {
+    WatchedQueryListenerEvent["ON_DATA"] = "onData";
+    WatchedQueryListenerEvent["ON_ERROR"] = "onError";
+    WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
+    WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
+    WatchedQueryListenerEvent["CLOSED"] = "closed";
+})(exports.WatchedQueryListenerEvent || (exports.WatchedQueryListenerEvent = {}));
+const DEFAULT_WATCH_THROTTLE_MS = 30;
+const DEFAULT_WATCH_QUERY_OPTIONS = {
+    throttleMs: DEFAULT_WATCH_THROTTLE_MS,
+    reportFetching: true
+};
+
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+class SyncingService {
+    attachmentService;
+    localStorage;
+    remoteStorage;
+    logger;
+    errorHandler;
+    constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
+        this.attachmentService = attachmentService;
+        this.localStorage = localStorage;
+        this.remoteStorage = remoteStorage;
+        this.logger = logger;
+        this.errorHandler = errorHandler;
+    }
+    /**
+     * 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
+     */
+    async processAttachments(attachments, context) {
+        const updatedAttachments = [];
+        for (const attachment of attachments) {
+            switch (attachment.state) {
+                case exports.AttachmentState.QUEUED_UPLOAD:
+                    const uploaded = await this.uploadAttachment(attachment);
+                    updatedAttachments.push(uploaded);
+                    break;
+                case exports.AttachmentState.QUEUED_DOWNLOAD:
+                    const downloaded = await this.downloadAttachment(attachment);
+                    updatedAttachments.push(downloaded);
+                    break;
+                case exports.AttachmentState.QUEUED_DELETE:
+                    const deleted = await this.deleteAttachment(attachment);
+                    updatedAttachments.push(deleted);
+                    break;
+            }
+        }
+        await context.saveAttachments(updatedAttachments);
+    }
+    /**
+     * 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
+     */
+    async uploadAttachment(attachment) {
+        this.logger.info(`Uploading attachment ${attachment.filename}`);
+        try {
+            if (attachment.localUri == null) {
+                throw new Error(`No localUri for attachment ${attachment.id}`);
+            }
+            const fileBlob = await this.localStorage.readFile(attachment.localUri);
+            await this.remoteStorage.uploadFile(fileBlob, attachment);
+            return {
+                ...attachment,
+                state: exports.AttachmentState.SYNCED,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * 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
+     */
+    async downloadAttachment(attachment) {
+        this.logger.info(`Downloading attachment ${attachment.filename}`);
+        try {
+            const fileData = await this.remoteStorage.downloadFile(attachment);
+            const localUri = this.localStorage.getLocalUri(attachment.filename);
+            await this.localStorage.saveFile(localUri, fileData);
+            return {
+                ...attachment,
+                state: exports.AttachmentState.SYNCED,
+                localUri: localUri,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * 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
+     */
+    async deleteAttachment(attachment) {
+        try {
+            await this.remoteStorage.deleteFile(attachment);
+            if (attachment.localUri) {
+                await this.localStorage.deleteFile(attachment.localUri);
+            }
+            await this.attachmentService.withContext(async (ctx) => {
+                await ctx.deleteAttachment(attachment.id);
+            });
+            return {
+                ...attachment,
+                state: exports.AttachmentState.ARCHIVED
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: exports.AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * 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.
+     */
+    async deleteArchivedAttachments(context) {
+        return await context.deleteArchivedAttachments(async (archivedAttachments) => {
+            for (const attachment of archivedAttachments) {
+                if (attachment.localUri) {
+                    try {
+                        await this.localStorage.deleteFile(attachment.localUri);
+                    }
+                    catch (error) {
+                        this.logger.error('Error deleting local file for archived attachment', error);
+                    }
+                }
+            }
+        });
+    }
+}
+
+/**
+ * Wrapper for async-mutex runExclusive, which allows for a timeout on each exclusive lock.
+ */
+async function mutexRunExclusive(mutex, callback, options) {
+    return new Promise((resolve, reject) => {
+        const timeout = options?.timeoutMs;
+        let timedOut = false;
+        const timeoutId = timeout
+            ? setTimeout(() => {
+                timedOut = true;
+                reject(new Error('Timeout waiting for lock'));
+            }, timeout)
+            : undefined;
+        mutex.runExclusive(async () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            if (timedOut)
+                return;
+            try {
+                resolve(await callback());
+            }
+            catch (ex) {
+                reject(ex);
+            }
+        });
+    });
+}
+
+/**
+ * Service for querying and watching attachment records in the database.
+ *
+ * @internal
+ */
+class AttachmentService {
+    db;
+    logger;
+    tableName;
+    mutex = new asyncMutex.Mutex();
+    context;
+    constructor(db, logger, tableName = 'attachments', archivedCacheLimit = 100) {
+        this.db = db;
+        this.logger = logger;
+        this.tableName = tableName;
+        this.context = new AttachmentContext(db, tableName, logger, archivedCacheLimit);
+    }
+    /**
+     * Creates a differential watch query for active attachments requiring synchronization.
+     * @returns Watch query that emits changes for queued uploads, downloads, and deletes
+     */
+    watchActiveAttachments({ throttleMs } = {}) {
+        this.logger.info('Watching active attachments...');
+        const watch = this.db
+            .query({
+            sql: /* sql */ `
+          SELECT
+            *
+          FROM
+            ${this.tableName}
+          WHERE
+            state = ?
+            OR state = ?
+            OR state = ?
+          ORDER BY
+            timestamp ASC
+        `,
+            parameters: [exports.AttachmentState.QUEUED_UPLOAD, exports.AttachmentState.QUEUED_DOWNLOAD, exports.AttachmentState.QUEUED_DELETE]
+        })
+            .differentialWatch({ throttleMs });
+        return watch;
+    }
+    /**
+     * Executes a callback with exclusive access to the attachment context.
+     */
+    async withContext(callback) {
+        return mutexRunExclusive(this.mutex, async () => {
+            return callback(this.context);
+        });
+    }
+}
+
+/**
+ * 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.
+ */
+class AttachmentQueue {
+    /** Timer for periodic synchronization operations */
+    periodicSyncTimer;
+    /** Service for synchronizing attachments between local and remote storage */
+    syncingService;
+    /** Adapter for local file storage operations */
+    localStorage;
+    /** Adapter for remote file storage operations */
+    remoteStorage;
+    /**
+     * Callback function to watch for changes in attachment references in your data model.
+     *
+     * This should be implemented by the user of AttachmentQueue to monitor changes in your application's
+     * data that reference attachments. When attachments are added, removed, or modified,
+     * this callback should trigger the onUpdate function with the current set of attachments.
+     */
+    watchAttachments;
+    /** Name of the database table storing attachment records */
+    tableName;
+    /** Logger instance for diagnostic information */
+    logger;
+    /** Interval in milliseconds between periodic sync operations. Default: 30000 (30 seconds) */
+    syncIntervalMs = 30 * 1000;
+    /** Duration in milliseconds to throttle sync operations */
+    syncThrottleDuration;
+    /** Whether to automatically download remote attachments. Default: true */
+    downloadAttachments = true;
+    /** Maximum number of archived attachments to keep before cleanup. Default: 100 */
+    archivedCacheLimit;
+    /** Service for managing attachment-related database operations */
+    attachmentService;
+    /** PowerSync database instance */
+    db;
+    /** Cleanup function for status change listener */
+    statusListenerDispose;
+    watchActiveAttachments;
+    watchAttachmentsAbortController;
+    /**
+     * Creates a new AttachmentQueue instance.
+     *
+     * @param options - Configuration options
+     * @param options.db - PowerSync database instance
+     * @param options.remoteStorage - Remote storage adapter for upload/download operations
+     * @param options.localStorage - Local storage adapter for file persistence
+     * @param options.watchAttachments - Callback for monitoring attachment changes in your data model
+     * @param options.tableName - Name of the table to store attachment records. Default: 'ps_attachment_queue'
+     * @param options.logger - Logger instance. Defaults to db.logger
+     * @param options.syncIntervalMs - Interval between automatic syncs in milliseconds. Default: 30000
+     * @param options.syncThrottleDuration - Throttle duration for sync operations in milliseconds. Default: 1000
+     * @param options.downloadAttachments - Whether to automatically download remote attachments. Default: true
+     * @param options.archivedCacheLimit - Maximum archived attachments before cleanup. Default: 100
+     */
+    constructor({ db, localStorage, remoteStorage, watchAttachments, logger, tableName = ATTACHMENT_TABLE, syncIntervalMs = 30 * 1000, syncThrottleDuration = DEFAULT_WATCH_THROTTLE_MS, downloadAttachments = true, archivedCacheLimit = 100, errorHandler }) {
+        this.db = db;
+        this.remoteStorage = remoteStorage;
+        this.localStorage = localStorage;
+        this.watchAttachments = watchAttachments;
+        this.tableName = tableName;
+        this.syncIntervalMs = syncIntervalMs;
+        this.syncThrottleDuration = syncThrottleDuration;
+        this.archivedCacheLimit = archivedCacheLimit;
+        this.downloadAttachments = downloadAttachments;
+        this.logger = logger ?? db.logger;
+        this.attachmentService = new AttachmentService(db, this.logger, tableName, archivedCacheLimit);
+        this.syncingService = new SyncingService(this.attachmentService, localStorage, remoteStorage, this.logger, errorHandler);
+    }
+    /**
+     * Generates a new attachment ID using a SQLite UUID function.
+     *
+     * @returns Promise resolving to the new attachment ID
+     */
+    async generateAttachmentId() {
+        return this.db.get('SELECT uuid() as id').then((row) => row.id);
+    }
+    /**
+     * Starts the attachment synchronization process.
+     *
+     * This method:
+     * - Stops any existing sync operations
+     * - Sets up periodic synchronization based on syncIntervalMs
+     * - Registers listeners for active attachment changes
+     * - Processes watched attachments to queue uploads/downloads
+     * - Handles state transitions for archived and new attachments
+     */
+    async startSync() {
+        await this.stopSync();
+        this.watchActiveAttachments = this.attachmentService.watchActiveAttachments({
+            throttleMs: this.syncThrottleDuration
+        });
+        // immediately invoke the sync storage to initialize local storage
+        await this.localStorage.initialize();
+        await this.verifyAttachments();
+        // Sync storage periodically
+        this.periodicSyncTimer = setInterval(async () => {
+            await this.syncStorage();
+        }, this.syncIntervalMs);
+        // Sync storage when there is a change in active attachments
+        this.watchActiveAttachments.registerListener({
+            onDiff: async () => {
+                await this.syncStorage();
+            }
+        });
+        this.statusListenerDispose = this.db.registerListener({
+            statusChanged: (status) => {
+                if (status.connected) {
+                    // Device came online, process attachments immediately
+                    this.syncStorage().catch((error) => {
+                        this.logger.error('Error syncing storage on connection:', error);
+                    });
+                }
+            }
+        });
+        this.watchAttachmentsAbortController = new AbortController();
+        const signal = this.watchAttachmentsAbortController.signal;
+        // Process attachments when there is a change in watched attachments
+        this.watchAttachments(async (watchedAttachments) => {
+            // Skip processing if sync has been stopped
+            if (signal.aborted) {
+                return;
+            }
+            await this.attachmentService.withContext(async (ctx) => {
+                // Need to get all the attachments which are tracked in the DB.
+                // We might need to restore an archived attachment.
+                const currentAttachments = await ctx.getAttachments();
+                const attachmentUpdates = [];
+                for (const watchedAttachment of watchedAttachments) {
+                    const existingQueueItem = currentAttachments.find((a) => a.id === watchedAttachment.id);
+                    if (!existingQueueItem) {
+                        // Item is watched but not in the queue yet. Need to add it.
+                        if (!this.downloadAttachments) {
+                            continue;
+                        }
+                        const filename = watchedAttachment.filename ?? `${watchedAttachment.id}.${watchedAttachment.fileExtension}`;
+                        attachmentUpdates.push({
+                            id: watchedAttachment.id,
+                            filename,
+                            state: exports.AttachmentState.QUEUED_DOWNLOAD,
+                            hasSynced: false,
+                            metaData: watchedAttachment.metaData,
+                            timestamp: new Date().getTime()
+                        });
+                        continue;
+                    }
+                    if (existingQueueItem.state === exports.AttachmentState.ARCHIVED) {
+                        // The attachment is present again. Need to queue it for sync.
+                        // We might be able to optimize this in future
+                        if (existingQueueItem.hasSynced === true) {
+                            // No remote action required, we can restore the record (avoids deletion)
+                            attachmentUpdates.push({
+                                ...existingQueueItem,
+                                state: exports.AttachmentState.SYNCED
+                            });
+                        }
+                        else {
+                            // The localURI should be set if the record was meant to be uploaded
+                            // and hasSynced is false then
+                            // it must be an upload operation
+                            const newState = existingQueueItem.localUri == null ? exports.AttachmentState.QUEUED_DOWNLOAD : exports.AttachmentState.QUEUED_UPLOAD;
+                            attachmentUpdates.push({
+                                ...existingQueueItem,
+                                state: newState
+                            });
+                        }
+                    }
+                }
+                for (const attachment of currentAttachments) {
+                    const notInWatchedItems = watchedAttachments.find((i) => i.id === attachment.id) == null;
+                    if (notInWatchedItems) {
+                        switch (attachment.state) {
+                            case exports.AttachmentState.QUEUED_DELETE:
+                            case exports.AttachmentState.QUEUED_UPLOAD:
+                                // Only archive if it has synced
+                                if (attachment.hasSynced === true) {
+                                    attachmentUpdates.push({
+                                        ...attachment,
+                                        state: exports.AttachmentState.ARCHIVED
+                                    });
+                                }
+                                break;
+                            default:
+                                // Archive other states such as QUEUED_DOWNLOAD
+                                attachmentUpdates.push({
+                                    ...attachment,
+                                    state: exports.AttachmentState.ARCHIVED
+                                });
+                        }
+                    }
+                }
+                if (attachmentUpdates.length > 0) {
+                    await ctx.saveAttachments(attachmentUpdates);
+                }
+            });
+        }, signal);
+    }
+    /**
+     * Synchronizes all active attachments between local and remote storage.
+     *
+     * This is called automatically at regular intervals when sync is started,
+     * but can also be called manually to trigger an immediate sync.
+     */
+    async syncStorage() {
+        await this.attachmentService.withContext(async (ctx) => {
+            const activeAttachments = await ctx.getActiveAttachments();
+            await this.localStorage.initialize();
+            await this.syncingService.processAttachments(activeAttachments, ctx);
+            await this.syncingService.deleteArchivedAttachments(ctx);
+        });
+    }
+    /**
+     * Stops the attachment synchronization process.
+     *
+     * Clears the periodic sync timer and closes all active attachment watchers.
+     */
+    async stopSync() {
+        clearInterval(this.periodicSyncTimer);
+        this.periodicSyncTimer = undefined;
+        if (this.watchActiveAttachments)
+            await this.watchActiveAttachments.close();
+        if (this.watchAttachmentsAbortController) {
+            this.watchAttachmentsAbortController.abort();
+        }
+        if (this.statusListenerDispose) {
+            this.statusListenerDispose();
+            this.statusListenerDispose = undefined;
+        }
+    }
+    /**
+     * Saves a file to local storage and queues it for upload to remote storage.
+     *
+     * @param options - File save options
+     * @param options.data - The file data as ArrayBuffer, Blob, or base64 string
+     * @param options.fileExtension - File extension (e.g., 'jpg', 'pdf')
+     * @param options.mediaType - MIME type of the file (e.g., 'image/jpeg')
+     * @param options.metaData - Optional metadata to associate with the attachment
+     * @param options.id - Optional custom ID. If not provided, a UUID will be generated
+     * @param options.updateHook - Optional callback to execute additional database operations
+     *                             within the same transaction as the attachment creation
+     * @returns Promise resolving to the created attachment record
+     */
+    async saveFile({ data, fileExtension, mediaType, metaData, id, updateHook }) {
+        const resolvedId = id ?? (await this.generateAttachmentId());
+        const filename = `${resolvedId}.${fileExtension}`;
+        const localUri = this.localStorage.getLocalUri(filename);
+        const size = await this.localStorage.saveFile(localUri, data);
+        const attachment = {
+            id: resolvedId,
+            filename,
+            mediaType,
+            localUri,
+            state: exports.AttachmentState.QUEUED_UPLOAD,
+            hasSynced: false,
+            size,
+            timestamp: new Date().getTime(),
+            metaData
+        };
+        await this.attachmentService.withContext(async (ctx) => {
+            await ctx.db.writeTransaction(async (tx) => {
+                await updateHook?.(tx, attachment);
+                await ctx.upsertAttachment(attachment, tx);
+            });
+        });
+        return attachment;
+    }
+    async deleteFile({ id, updateHook }) {
+        await this.attachmentService.withContext(async (ctx) => {
+            const attachment = await ctx.getAttachment(id);
+            if (!attachment) {
+                throw new Error(`Attachment with id ${id} not found`);
+            }
+            await ctx.db.writeTransaction(async (tx) => {
+                await updateHook?.(tx, attachment);
+                await ctx.upsertAttachment({
+                    ...attachment,
+                    state: exports.AttachmentState.QUEUED_DELETE,
+                    hasSynced: false
+                }, tx);
+            });
+        });
+    }
+    async expireCache() {
+        let isDone = false;
+        while (!isDone) {
+            await this.attachmentService.withContext(async (ctx) => {
+                isDone = await this.syncingService.deleteArchivedAttachments(ctx);
+            });
+        }
+    }
+    async clearQueue() {
+        await this.attachmentService.withContext(async (ctx) => {
+            await ctx.clearQueue();
+        });
+        await this.localStorage.clear();
+    }
+    /**
+     * Verifies the integrity of all attachment records and repairs inconsistencies.
+     *
+     * This method checks each attachment record against the local filesystem and:
+     * - Updates localUri if the file exists at a different path
+     * - Archives attachments with missing local files that haven't been uploaded
+     * - Requeues synced attachments for download if their local files are missing
+     */
+    async verifyAttachments() {
+        await this.attachmentService.withContext(async (ctx) => {
+            const attachments = await ctx.getAttachments();
+            const updates = [];
+            for (const attachment of attachments) {
+                if (attachment.localUri == null) {
+                    continue;
+                }
+                const exists = await this.localStorage.fileExists(attachment.localUri);
+                if (exists) {
+                    // The file exists, this is correct
+                    continue;
+                }
+                const newLocalUri = this.localStorage.getLocalUri(attachment.filename);
+                const newExists = await this.localStorage.fileExists(newLocalUri);
+                if (newExists) {
+                    // The file exists locally but the localUri is broken, we update it.
+                    updates.push({
+                        ...attachment,
+                        localUri: newLocalUri
+                    });
+                }
+                else {
+                    // the file doesn't exist locally.
+                    if (attachment.state === exports.AttachmentState.SYNCED) {
+                        // the file has been successfully synced to remote storage but is missing
+                        // we download it again
+                        updates.push({
+                            ...attachment,
+                            state: exports.AttachmentState.QUEUED_DOWNLOAD,
+                            localUri: undefined
+                        });
+                    }
+                    else {
+                        // the file wasn't successfully synced to remote storage, we archive it
+                        updates.push({
+                            ...attachment,
+                            state: exports.AttachmentState.ARCHIVED,
+                            localUri: undefined // Clears the value
+                        });
+                    }
+                }
+            }
+            await ctx.saveAttachments(updates);
+        });
+    }
+}
+
+exports.EncodingType = void 0;
+(function (EncodingType) {
+    EncodingType["UTF8"] = "utf8";
+    EncodingType["Base64"] = "base64";
+})(exports.EncodingType || (exports.EncodingType = {}));
+
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
 }
@@ -1318,20 +2545,6 @@ class MetaBaseObserver extends BaseObserver {
     }
 }
 
-exports.WatchedQueryListenerEvent = void 0;
-(function (WatchedQueryListenerEvent) {
-    WatchedQueryListenerEvent["ON_DATA"] = "onData";
-    WatchedQueryListenerEvent["ON_ERROR"] = "onError";
-    WatchedQueryListenerEvent["ON_STATE_CHANGE"] = "onStateChange";
-    WatchedQueryListenerEvent["SETTINGS_WILL_UPDATE"] = "settingsWillUpdate";
-    WatchedQueryListenerEvent["CLOSED"] = "closed";
-})(exports.WatchedQueryListenerEvent || (exports.WatchedQueryListenerEvent = {}));
-const DEFAULT_WATCH_THROTTLE_MS = 30;
-const DEFAULT_WATCH_QUERY_OPTIONS = {
-    throttleMs: DEFAULT_WATCH_THROTTLE_MS,
-    reportFetching: true
-};
-
 /**
  * Performs underlying watching and yields a stream of results.
  * @internal
@@ -9244,7 +10457,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.46.0";
+var version = "1.48.0";
 var PACKAGE = {
 	version: version};
 
@@ -12869,193 +14082,59 @@ class SqliteBucketStorage extends BaseObserver {
     async control(op, payload) {
         return await this.writeTransaction(async (tx) => {
             const [[raw]] = await tx.executeRaw('SELECT powersync_control(?, ?)', [op, payload]);
-            return raw;
-        });
-    }
-    async hasMigratedSubkeys() {
-        const { r } = await this.db.get('SELECT EXISTS(SELECT * FROM ps_kv WHERE key = ?) as r', [
-            SqliteBucketStorage._subkeyMigrationKey
-        ]);
-        return r != 0;
-    }
-    async migrateToFixedSubkeys() {
-        await this.writeTransaction(async (tx) => {
-            await tx.execute('UPDATE ps_oplog SET key = powersync_remove_duplicate_key_encoding(key);');
-            await tx.execute('INSERT OR REPLACE INTO ps_kv (key, value) VALUES (?, ?);', [
-                SqliteBucketStorage._subkeyMigrationKey,
-                '1'
-            ]);
-        });
-    }
-    static _subkeyMigrationKey = 'powersync_js_migrated_subkeys';
-}
-function hasMatchingPriority(priority, bucket) {
-    return bucket.priority != null && bucket.priority <= priority;
-}
-
-// TODO JSON
-class SyncDataBatch {
-    buckets;
-    static fromJSON(json) {
-        return new SyncDataBatch(json.buckets.map((bucket) => SyncDataBucket.fromRow(bucket)));
-    }
-    constructor(buckets) {
-        this.buckets = buckets;
-    }
-}
-
-/**
- * Thrown when an underlying database connection is closed.
- * This is particularly relevant when worker connections are marked as closed while
- * operations are still in progress.
- */
-class ConnectionClosedError extends Error {
-    static NAME = 'ConnectionClosedError';
-    static MATCHES(input) {
-        /**
-         * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
-         * check might fail. This also performs a failsafe check.
-         * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
-         */
-        return (input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME));
-    }
-    constructor(message) {
-        super(message);
-        this.name = ConnectionClosedError.NAME;
-    }
-}
-
-// https://www.sqlite.org/lang_expr.html#castexpr
-exports.ColumnType = void 0;
-(function (ColumnType) {
-    ColumnType["TEXT"] = "TEXT";
-    ColumnType["INTEGER"] = "INTEGER";
-    ColumnType["REAL"] = "REAL";
-})(exports.ColumnType || (exports.ColumnType = {}));
-const text = {
-    type: exports.ColumnType.TEXT
-};
-const integer = {
-    type: exports.ColumnType.INTEGER
-};
-const real = {
-    type: exports.ColumnType.REAL
-};
-// powersync-sqlite-core limits the number of column per table to 1999, due to internal SQLite limits.
-// In earlier versions this was limited to 63.
-const MAX_AMOUNT_OF_COLUMNS = 1999;
-const column = {
-    text,
-    integer,
-    real
-};
-class Column {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    get name() {
-        return this.options.name;
-    }
-    get type() {
-        return this.options.type;
-    }
-    toJSON() {
-        return {
-            name: this.name,
-            type: this.type
-        };
-    }
-}
-
-const DEFAULT_INDEX_COLUMN_OPTIONS = {
-    ascending: true
-};
-class IndexedColumn {
-    options;
-    static createAscending(column) {
-        return new IndexedColumn({
-            name: column,
-            ascending: true
-        });
-    }
-    constructor(options) {
-        this.options = { ...DEFAULT_INDEX_COLUMN_OPTIONS, ...options };
-    }
-    get name() {
-        return this.options.name;
-    }
-    get ascending() {
-        return this.options.ascending;
-    }
-    toJSON(table) {
-        return {
-            name: this.name,
-            ascending: this.ascending,
-            type: table.columns.find((column) => column.name === this.name)?.type ?? exports.ColumnType.TEXT
-        };
-    }
-}
-
-const DEFAULT_INDEX_OPTIONS = {
-    columns: []
-};
-class Index {
-    options;
-    static createAscending(options, columnNames) {
-        return new Index({
-            ...options,
-            columns: columnNames.map((name) => IndexedColumn.createAscending(name))
+            return raw;
         });
     }
-    constructor(options) {
-        this.options = options;
-        this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
+    async hasMigratedSubkeys() {
+        const { r } = await this.db.get('SELECT EXISTS(SELECT * FROM ps_kv WHERE key = ?) as r', [
+            SqliteBucketStorage._subkeyMigrationKey
+        ]);
+        return r != 0;
     }
-    get name() {
-        return this.options.name;
+    async migrateToFixedSubkeys() {
+        await this.writeTransaction(async (tx) => {
+            await tx.execute('UPDATE ps_oplog SET key = powersync_remove_duplicate_key_encoding(key);');
+            await tx.execute('INSERT OR REPLACE INTO ps_kv (key, value) VALUES (?, ?);', [
+                SqliteBucketStorage._subkeyMigrationKey,
+                '1'
+            ]);
+        });
     }
-    get columns() {
-        return this.options.columns ?? [];
+    static _subkeyMigrationKey = 'powersync_js_migrated_subkeys';
+}
+function hasMatchingPriority(priority, bucket) {
+    return bucket.priority != null && bucket.priority <= priority;
+}
+
+// TODO JSON
+class SyncDataBatch {
+    buckets;
+    static fromJSON(json) {
+        return new SyncDataBatch(json.buckets.map((bucket) => SyncDataBucket.fromRow(bucket)));
     }
-    toJSON(table) {
-        return {
-            name: this.name,
-            columns: this.columns.map((c) => c.toJSON(table))
-        };
+    constructor(buckets) {
+        this.buckets = buckets;
     }
 }
 
 /**
- * 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.
+ * Thrown when an underlying database connection is closed.
+ * This is particularly relevant when worker connections are marked as closed while
+ * operations are still in progress.
  */
-class RawTable {
-    /**
-     * 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;
-    put;
-    delete;
-    constructor(name, type) {
-        this.name = name;
-        this.put = type.put;
-        this.delete = type.delete;
+class ConnectionClosedError extends Error {
+    static NAME = 'ConnectionClosedError';
+    static MATCHES(input) {
+        /**
+         * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
+         * check might fail. This also performs a failsafe check.
+         * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
+         */
+        return (input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME));
+    }
+    constructor(message) {
+        super(message);
+        this.name = ConnectionClosedError.NAME;
     }
 }
 
@@ -13103,7 +14182,7 @@ class Schema {
      */
     withRawTables(tables) {
         for (const [name, rawTableDefinition] of Object.entries(tables)) {
-            this.rawTables.push(new RawTable(name, rawTableDefinition));
+            this.rawTables.push({ name, ...rawTableDefinition });
         }
     }
     validate() {
@@ -13114,213 +14193,30 @@ class Schema {
     toJSON() {
         return {
             tables: this.tables.map((t) => t.toJSON()),
-            raw_tables: this.rawTables
+            raw_tables: this.rawTables.map(Schema.rawTableToJson)
         };
     }
-}
-
-const DEFAULT_TABLE_OPTIONS = {
-    indexes: [],
-    insertOnly: false,
-    localOnly: false,
-    trackPrevious: false,
-    trackMetadata: false,
-    ignoreEmptyUpdates: false
-};
-const InvalidSQLCharacters = /["'%,.#\s[\]]/;
-class Table {
-    options;
-    _mappedColumns;
-    static createLocalOnly(options) {
-        return new Table({ ...options, localOnly: true, insertOnly: false });
-    }
-    static createInsertOnly(options) {
-        return new Table({ ...options, localOnly: false, insertOnly: true });
-    }
     /**
-     * Create a table.
-     * @deprecated This was only only included for TableV2 and is no longer necessary.
-     * Prefer to use new Table() directly.
+     * Returns a representation of the raw table that is understood by the PowerSync SQLite core extension.
      *
-     * TODO remove in the next major release.
-     */
-    static createTable(name, table) {
-        return new Table({
-            name,
-            columns: table.columns,
-            indexes: table.indexes,
-            localOnly: table.options.localOnly,
-            insertOnly: table.options.insertOnly,
-            viewName: table.options.viewName
-        });
-    }
-    constructor(optionsOrColumns, v2Options) {
-        if (this.isTableV1(optionsOrColumns)) {
-            this.initTableV1(optionsOrColumns);
-        }
-        else {
-            this.initTableV2(optionsOrColumns, v2Options);
-        }
-    }
-    copyWithName(name) {
-        return new Table({
-            ...this.options,
-            name
-        });
-    }
-    isTableV1(arg) {
-        return 'columns' in arg && Array.isArray(arg.columns);
-    }
-    initTableV1(options) {
-        this.options = {
-            ...options,
-            indexes: options.indexes || []
-        };
-        this.applyDefaultOptions();
-    }
-    initTableV2(columns, options) {
-        const convertedColumns = Object.entries(columns).map(([name, columnInfo]) => new Column({ name, type: columnInfo.type }));
-        const convertedIndexes = Object.entries(options?.indexes ?? {}).map(([name, columnNames]) => new Index({
-            name,
-            columns: columnNames.map((name) => new IndexedColumn({
-                name: name.replace(/^-/, ''),
-                ascending: !name.startsWith('-')
-            }))
-        }));
-        this.options = {
-            name: '',
-            columns: convertedColumns,
-            indexes: convertedIndexes,
-            viewName: options?.viewName,
-            insertOnly: options?.insertOnly,
-            localOnly: options?.localOnly,
-            trackPrevious: options?.trackPrevious,
-            trackMetadata: options?.trackMetadata,
-            ignoreEmptyUpdates: options?.ignoreEmptyUpdates
+     * 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) {
+        const serialized = {
+            name: table.name,
+            put: table.put,
+            delete: table.delete,
+            clear: table.clear
         };
-        this.applyDefaultOptions();
-        this._mappedColumns = columns;
-    }
-    applyDefaultOptions() {
-        this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
-        this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
-        this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
-        this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
-        this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
-    }
-    get name() {
-        return this.options.name;
-    }
-    get viewNameOverride() {
-        return this.options.viewName;
-    }
-    get viewName() {
-        return this.viewNameOverride ?? this.name;
-    }
-    get columns() {
-        return this.options.columns;
-    }
-    get columnMap() {
-        return (this._mappedColumns ??
-            this.columns.reduce((hash, column) => {
-                hash[column.name] = { type: column.type ?? exports.ColumnType.TEXT };
-                return hash;
-            }, {}));
-    }
-    get indexes() {
-        return this.options.indexes ?? [];
-    }
-    get localOnly() {
-        return this.options.localOnly;
-    }
-    get insertOnly() {
-        return this.options.insertOnly;
-    }
-    get trackPrevious() {
-        return this.options.trackPrevious;
-    }
-    get trackMetadata() {
-        return this.options.trackMetadata;
-    }
-    get ignoreEmptyUpdates() {
-        return this.options.ignoreEmptyUpdates;
-    }
-    get internalName() {
-        if (this.options.localOnly) {
-            return `ps_data_local__${this.name}`;
+        if ('schema' in table) {
+            // We have schema options, those are flattened into the outer JSON object for the core extension.
+            const schema = table.schema;
+            serialized.table_name = schema.tableName ?? table.name;
+            serialized.synced_columns = schema.syncedColumns;
+            Object.assign(serialized, encodeTableOptions(table.schema));
         }
-        return `ps_data__${this.name}`;
-    }
-    get validName() {
-        if (InvalidSQLCharacters.test(this.name)) {
-            return false;
-        }
-        if (this.viewNameOverride != null && InvalidSQLCharacters.test(this.viewNameOverride)) {
-            return false;
-        }
-        return true;
-    }
-    validate() {
-        if (InvalidSQLCharacters.test(this.name)) {
-            throw new Error(`Invalid characters in table name: ${this.name}`);
-        }
-        if (this.viewNameOverride && InvalidSQLCharacters.test(this.viewNameOverride)) {
-            throw new Error(`Invalid characters in view name: ${this.viewNameOverride}`);
-        }
-        if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
-            throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
-        }
-        if (this.trackMetadata && this.localOnly) {
-            throw new Error(`Can't include metadata for local-only tables.`);
-        }
-        if (this.trackPrevious != false && this.localOnly) {
-            throw new Error(`Can't include old values for local-only tables.`);
-        }
-        const columnNames = new Set();
-        columnNames.add('id');
-        for (const column of this.columns) {
-            const { name: columnName } = column;
-            if (column.name === 'id') {
-                throw new Error(`An id column is automatically added, custom id columns are not supported`);
-            }
-            if (columnNames.has(columnName)) {
-                throw new Error(`Duplicate column ${columnName}`);
-            }
-            if (InvalidSQLCharacters.test(columnName)) {
-                throw new Error(`Invalid characters in column name: ${column.name}`);
-            }
-            columnNames.add(columnName);
-        }
-        const indexNames = new Set();
-        for (const index of this.indexes) {
-            if (indexNames.has(index.name)) {
-                throw new Error(`Duplicate index ${index.name}`);
-            }
-            if (InvalidSQLCharacters.test(index.name)) {
-                throw new Error(`Invalid characters in index name: ${index.name}`);
-            }
-            for (const column of index.columns) {
-                if (!columnNames.has(column.name)) {
-                    throw new Error(`Column ${column.name} not found for index ${index.name}`);
-                }
-            }
-            indexNames.add(index.name);
-        }
-    }
-    toJSON() {
-        const trackPrevious = this.trackPrevious;
-        return {
-            name: this.name,
-            view_name: this.viewName,
-            local_only: this.localOnly,
-            insert_only: this.insertOnly,
-            include_old: trackPrevious && (trackPrevious.columns ?? true),
-            include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
-            include_metadata: this.trackMetadata,
-            ignore_empty_update: this.ignoreEmptyUpdates,
-            columns: this.columns.map((c) => c.toJSON()),
-            indexes: this.indexes.map((e) => e.toJSON(this))
-        };
+        return serialized;
     }
 }
 
@@ -13479,6 +14375,7 @@ const parseQuery = (query, parameters) => {
     return { sqlStatement, parameters: parameters };
 };
 
+exports.ATTACHMENT_TABLE = ATTACHMENT_TABLE;
 exports.AbortOperation = AbortOperation;
 exports.AbstractPowerSyncDatabase = AbstractPowerSyncDatabase;
 exports.AbstractPowerSyncDatabaseOpenFactory = AbstractPowerSyncDatabaseOpenFactory;
@@ -13486,6 +14383,10 @@ exports.AbstractQueryProcessor = AbstractQueryProcessor;
 exports.AbstractRemote = AbstractRemote;
 exports.AbstractStreamingSyncImplementation = AbstractStreamingSyncImplementation;
 exports.ArrayComparator = ArrayComparator;
+exports.AttachmentContext = AttachmentContext;
+exports.AttachmentQueue = AttachmentQueue;
+exports.AttachmentService = AttachmentService;
+exports.AttachmentTable = AttachmentTable;
 exports.BaseObserver = BaseObserver;
 exports.Column = Column;
 exports.ConnectionClosedError = ConnectionClosedError;
@@ -13528,17 +14429,18 @@ exports.MEMORY_TRIGGER_CLAIM_MANAGER = MEMORY_TRIGGER_CLAIM_MANAGER;
 exports.OnChangeQueryProcessor = OnChangeQueryProcessor;
 exports.OpType = OpType;
 exports.OplogEntry = OplogEntry;
-exports.RawTable = RawTable;
 exports.Schema = Schema;
 exports.SqliteBucketStorage = SqliteBucketStorage;
 exports.SyncDataBatch = SyncDataBatch;
 exports.SyncDataBucket = SyncDataBucket;
 exports.SyncProgress = SyncProgress;
 exports.SyncStatus = SyncStatus;
+exports.SyncingService = SyncingService;
 exports.Table = Table;
 exports.TableV2 = TableV2;
 exports.TriggerManagerImpl = TriggerManagerImpl;
 exports.UploadQueueStats = UploadQueueStats;
+exports.attachmentFromSql = attachmentFromSql;
 exports.column = column;
 exports.compilableQueryWatch = compilableQueryWatch;
 exports.createBaseLogger = createBaseLogger;
@@ -13557,6 +14459,7 @@ exports.isStreamingSyncCheckpointDiff = isStreamingSyncCheckpointDiff;
 exports.isStreamingSyncCheckpointPartiallyComplete = isStreamingSyncCheckpointPartiallyComplete;
 exports.isStreamingSyncData = isStreamingSyncData;
 exports.isSyncNewCheckpointRequest = isSyncNewCheckpointRequest;
+exports.mutexRunExclusive = mutexRunExclusive;
 exports.parseQuery = parseQuery;
 exports.runOnSchemaChange = runOnSchemaChange;
 exports.sanitizeSQL = sanitizeSQL;