@powersync/common 0.0.0-dev-20260128023420 → 0.0.0-dev-20260128170746

package/dist/bundle.node.cjs

@@ -4,6 +4,1211 @@ var asyncMutex = require('async-mutex');
 var eventIterator = require('event-iterator');
 var node_buffer = require('node:buffer');
 
+// 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))
+        };
+    }
+}
+
+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() {
+        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))
+        };
+    }
+}
+
+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) => {
+        mutex.runExclusive(async () => {
+            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;
 }
@@ -1167,20 +2372,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
@@ -6722,7 +7913,7 @@ function requireDist () {
 
 var distExports = requireDist();
 
-var version = "1.45.0";
+var version = "1.46.0";
 var PACKAGE = {
 	version: version};
 
@@ -7624,18 +8815,17 @@ exports.SyncClientImplementation = void 0;
      *
      * This is the default option.
      *
-     * @deprecated Don't use {@link SyncClientImplementation.JAVASCRIPT} directly. Instead, use
-     * {@link DEFAULT_SYNC_CLIENT_IMPLEMENTATION} or omit the option. The explicit choice to use
-     * the JavaScript-based sync implementation will be removed from a future version of the SDK.
+     * @deprecated We recommend the {@link RUST} client implementation for all apps. If you have issues with
+     * the Rust client, please file an issue or reach out to us. The JavaScript client will be removed in a future
+     * version of the PowerSync SDK.
      */
     SyncClientImplementation["JAVASCRIPT"] = "js";
     /**
      * This implementation offloads the sync line decoding and handling into the PowerSync
      * core extension.
      *
-     * @experimental
-     * While this implementation is more performant than {@link SyncClientImplementation.JAVASCRIPT},
-     * it has seen less real-world testing and is marked as __experimental__ at the moment.
+     * This option is more performant than the {@link JAVASCRIPT} client, enabled by default and the
+     * recommended client implementation for all apps.
      *
      * ## Compatibility warning
      *
@@ -7653,13 +8843,9 @@ exports.SyncClientImplementation = void 0;
     SyncClientImplementation["RUST"] = "rust";
 })(exports.SyncClientImplementation || (exports.SyncClientImplementation = {}));
 /**
- * The default {@link SyncClientImplementation} to use.
- *
- * Please use this field instead of {@link SyncClientImplementation.JAVASCRIPT} directly. A future version
- * of the PowerSync SDK will enable {@link SyncClientImplementation.RUST} by default and remove the JavaScript
- * option.
+ * The default {@link SyncClientImplementation} to use, {@link SyncClientImplementation.RUST}.
  */
-const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = exports.SyncClientImplementation.JAVASCRIPT;
+const DEFAULT_SYNC_CLIENT_IMPLEMENTATION = exports.SyncClientImplementation.RUST;
 const DEFAULT_CRUD_UPLOAD_THROTTLE_MS = 1000;
 const DEFAULT_RETRY_DELAY_MS = 5000;
 const DEFAULT_STREAMING_SYNC_OPTIONS = {
@@ -8069,6 +9255,9 @@ The next upload iteration will be delayed.`);
         if (rawTables != null && rawTables.length) {
             this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
         }
+        if (this.activeStreams.length) {
+            this.logger.error('Sync streams require `clientImplementation: SyncClientImplementation.RUST` when connecting.');
+        }
         this.logger.debug('Streaming sync iteration started');
         this.options.adapter.startSession();
         let [req, bucketMap] = await this.collectLocalBucketState();
@@ -8584,6 +9773,27 @@ The next upload iteration will be delayed.`);
     }
 }
 
+const CLAIM_STORE = new Map();
+/**
+ * @internal
+ * @experimental
+ */
+const MEMORY_TRIGGER_CLAIM_MANAGER = {
+    async obtainClaim(identifier) {
+        if (CLAIM_STORE.has(identifier)) {
+            throw new Error(`A claim is already present for ${identifier}`);
+        }
+        const release = async () => {
+            CLAIM_STORE.delete(identifier);
+        };
+        CLAIM_STORE.set(identifier, release);
+        return release;
+    },
+    async checkClaim(identifier) {
+        return CLAIM_STORE.has(identifier);
+    }
+};
+
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
  * @experimental
@@ -8595,9 +9805,20 @@ exports.DiffTriggerOperation = void 0;
     DiffTriggerOperation["DELETE"] = "DELETE";
 })(exports.DiffTriggerOperation || (exports.DiffTriggerOperation = {}));
 
+const DEFAULT_TRIGGER_MANAGER_CONFIGURATION = {
+    useStorageByDefault: false
+};
+const TRIGGER_CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
+/**
+ * @internal
+ * @experimental
+ */
 class TriggerManagerImpl {
     options;
     schema;
+    defaultConfig;
+    cleanupTimeout;
+    isDisposed;
     constructor(options) {
         this.options = options;
         this.schema = options.schema;
@@ -8606,6 +9827,33 @@ class TriggerManagerImpl {
                 this.schema = schema;
             }
         });
+        this.isDisposed = false;
+        /**
+         * Configure a cleanup to run on an interval.
+         * The interval is configured using setTimeout to take the async
+         * execution time of the callback into account.
+         */
+        this.defaultConfig = DEFAULT_TRIGGER_MANAGER_CONFIGURATION;
+        const cleanupCallback = async () => {
+            this.cleanupTimeout = null;
+            if (this.isDisposed) {
+                return;
+            }
+            try {
+                await this.cleanupResources();
+            }
+            catch (ex) {
+                this.db.logger.error(`Caught error while attempting to cleanup triggers`, ex);
+            }
+            finally {
+                // if not closed, set another timeout
+                if (this.isDisposed) {
+                    return;
+                }
+                this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
+            }
+        };
+        this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
     }
     get db() {
         return this.options.db;
@@ -8623,13 +9871,95 @@ class TriggerManagerImpl {
             await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
         }
     }
+    dispose() {
+        this.isDisposed = true;
+        if (this.cleanupTimeout) {
+            clearTimeout(this.cleanupTimeout);
+        }
+    }
+    /**
+     * Updates default config settings for platform specific use-cases.
+     */
+    updateDefaults(config) {
+        this.defaultConfig = {
+            ...this.defaultConfig,
+            ...config
+        };
+    }
+    generateTriggerName(operation, destinationTable, triggerId) {
+        return `__ps_temp_trigger_${operation.toLowerCase()}__${destinationTable}__${triggerId}`;
+    }
+    /**
+     * Cleanup any SQLite triggers or tables that are no longer in use.
+     */
+    async cleanupResources() {
+        // we use the database here since cleanupResources is called during the PowerSyncDatabase initialization
+        await this.db.database.writeLock(async (ctx) => {
+            /**
+             * Note: We only cleanup persisted triggers. These are tracked in the sqlite_master table.
+             * temporary triggers will not be affected by this.
+             * Query all triggers that match our naming pattern
+             */
+            const triggers = await ctx.getAll(/* sql */ `
+        SELECT
+          name
+        FROM
+          sqlite_master
+        WHERE
+          type = 'trigger'
+          AND name LIKE '__ps_temp_trigger_%'
+      `);
+            /** Use regex to extract table names and IDs from trigger names
+             * Trigger naming convention: __ps_temp_trigger_<operation>__<destination_table>__<id>
+             */
+            const triggerPattern = /^__ps_temp_trigger_(?:insert|update|delete)__(.+)__([a-f0-9_]{36})$/i;
+            const trackedItems = new Map();
+            for (const trigger of triggers) {
+                const match = trigger.name.match(triggerPattern);
+                if (match) {
+                    const [, table, id] = match;
+                    // Collect all trigger names for each id combo
+                    const existing = trackedItems.get(id);
+                    if (existing) {
+                        existing.triggerNames.push(trigger.name);
+                    }
+                    else {
+                        trackedItems.set(id, { table, id, triggerNames: [trigger.name] });
+                    }
+                }
+            }
+            for (const trackedItem of trackedItems.values()) {
+                // check if there is anything holding on to this item
+                const hasClaim = await this.options.claimManager.checkClaim(trackedItem.id);
+                if (hasClaim) {
+                    // This does not require cleanup
+                    continue;
+                }
+                this.db.logger.debug(`Clearing resources for trigger ${trackedItem.id} with table ${trackedItem.table}`);
+                // We need to delete the triggers and table
+                for (const triggerName of trackedItem.triggerNames) {
+                    await ctx.execute(`DROP TRIGGER IF EXISTS ${triggerName}`);
+                }
+                await ctx.execute(`DROP TABLE IF EXISTS ${trackedItem.table}`);
+            }
+        });
+    }
     async createDiffTrigger(options) {
         await this.db.waitForReady();
-        const { source, destination, columns, when, hooks } = options;
+        const { source, destination, columns, when, hooks, 
+        // Fall back to the provided default if not given on this level
+        useStorage = this.defaultConfig.useStorageByDefault } = options;
         const operations = Object.keys(when);
         if (operations.length == 0) {
             throw new Error('At least one WHEN operation must be specified for the trigger.');
         }
+        /**
+         * The clause to use when executing
+         * CREATE ${tableTriggerTypeClause} TABLE
+         * OR
+         * CREATE ${tableTriggerTypeClause} TRIGGER
+         */
+        const tableTriggerTypeClause = !useStorage ? 'TEMP' : '';
         const whenClauses = Object.fromEntries(Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`]));
         /**
          * Allow specifying the View name as the source.
@@ -8643,6 +9973,7 @@ class TriggerManagerImpl {
         const internalSource = sourceDefinition.internalName;
         const triggerIds = [];
         const id = await this.getUUID();
+        const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
         /**
          * We default to replicating all columns if no columns array is provided.
          */
@@ -8675,26 +10006,27 @@ class TriggerManagerImpl {
             return this.db.writeLock(async (tx) => {
                 await this.removeTriggers(tx, triggerIds);
                 await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+                await releaseStorageClaim?.();
             });
         };
         const setup = async (tx) => {
             // Allow user code to execute in this lock context before the trigger is created.
             await hooks?.beforeCreate?.(tx);
             await tx.execute(/* sql */ `
-        CREATE TEMP TABLE ${destination} (
+        CREATE ${tableTriggerTypeClause} TABLE ${destination} (
           operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
           id TEXT,
           operation TEXT,
           timestamp TEXT,
           value TEXT,
           previous_value TEXT
-        );
+        )
       `);
             if (operations.includes(exports.DiffTriggerOperation.INSERT)) {
-                const insertTriggerId = `ps_temp_trigger_insert_${id}`;
+                const insertTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.INSERT, destination, id);
                 triggerIds.push(insertTriggerId);
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.INSERT]} BEGIN
+          CREATE ${tableTriggerTypeClause} TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.INSERT]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value)
           VALUES
@@ -8705,14 +10037,14 @@ class TriggerManagerImpl {
               ${jsonFragment('NEW')}
             );
 
-          END;
+          END
         `);
             }
             if (operations.includes(exports.DiffTriggerOperation.UPDATE)) {
-                const updateTriggerId = `ps_temp_trigger_update_${id}`;
+                const updateTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.UPDATE, destination, id);
                 triggerIds.push(updateTriggerId);
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${updateTriggerId} AFTER
+          CREATE ${tableTriggerTypeClause} TRIGGER ${updateTriggerId} AFTER
           UPDATE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.UPDATE]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value, previous_value)
@@ -8729,11 +10061,11 @@ class TriggerManagerImpl {
         `);
             }
             if (operations.includes(exports.DiffTriggerOperation.DELETE)) {
-                const deleteTriggerId = `ps_temp_trigger_delete_${id}`;
+                const deleteTriggerId = this.generateTriggerName(exports.DiffTriggerOperation.DELETE, destination, id);
                 triggerIds.push(deleteTriggerId);
                 // Create delete trigger for basic JSON
                 await tx.execute(/* sql */ `
-          CREATE TEMP TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.DELETE]} BEGIN
+          CREATE ${tableTriggerTypeClause} TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[exports.DiffTriggerOperation.DELETE]} BEGIN
           INSERT INTO
             ${destination} (id, operation, timestamp, value)
           VALUES
@@ -8777,7 +10109,7 @@ class TriggerManagerImpl {
         // If no array is provided, we use all columns from the source table.
         const contextColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
         const id = await this.getUUID();
-        const destination = `ps_temp_track_${source}_${id}`;
+        const destination = `__ps_temp_track_${source}_${id}`;
         // register an onChange before the trigger is created
         const abortController = new AbortController();
         const abortOnChange = () => abortController.abort();
@@ -8932,6 +10264,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
      * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
      */
     triggers;
+    triggersImpl;
     logger;
     constructor(options) {
         super();
@@ -8995,9 +10328,10 @@ class AbstractPowerSyncDatabase extends BaseObserver {
             logger: this.logger
         });
         this._isReadyPromise = this.initialize();
-        this.triggers = new TriggerManagerImpl({
+        this.triggers = this.triggersImpl = new TriggerManagerImpl({
             db: this,
-            schema: this.schema
+            schema: this.schema,
+            ...this.generateTriggerManagerConfig()
         });
     }
     /**
@@ -9023,6 +10357,15 @@ class AbstractPowerSyncDatabase extends BaseObserver {
     get connecting() {
         return this.currentStatus?.connecting || false;
     }
+    /**
+     * Generates a base configuration for {@link TriggerManagerImpl}.
+     * Implementations should override this if necessary.
+     */
+    generateTriggerManagerConfig() {
+        return {
+            claimManager: MEMORY_TRIGGER_CLAIM_MANAGER
+        };
+    }
     /**
      * @returns A promise which will resolve once initialization is completed.
      */
@@ -9087,6 +10430,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         await this.updateSchema(this.options.schema);
         await this.resolveOfflineSyncStatus();
         await this.database.execute('PRAGMA RECURSIVE_TRIGGERS=TRUE');
+        await this.triggersImpl.cleanupResources();
         this.ready = true;
         this.iterateListeners((cb) => cb.initialized?.());
     }
@@ -9206,7 +10550,6 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         await this.disconnect();
         await this.waitForReady();
         const { clearLocal } = options;
-        // TODO DB name, verify this is necessary with extension
         await this.database.writeTransaction(async (tx) => {
             await tx.execute('SELECT powersync_clear(?)', [clearLocal ? 1 : 0]);
         });
@@ -9238,6 +10581,7 @@ class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             return;
         }
+        this.triggersImpl.dispose();
         await this.iterateAsyncListeners(async (cb) => cb.closing?.());
         const { disconnect } = options;
         if (disconnect) {
@@ -10203,151 +11547,50 @@ class SqliteBucketStorage extends BaseObserver {
         ]);
         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))
+    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'
+            ]);
         });
     }
-    constructor(options) {
-        this.options = options;
-        this.options = { ...DEFAULT_INDEX_OPTIONS, ...options };
+    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)));
     }
-    get name() {
-        return this.options.name;
+    constructor(buckets) {
+        this.buckets = buckets;
     }
-    get columns() {
-        return this.options.columns ?? [];
+}
+
+/**
+ * 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));
     }
-    toJSON(table) {
-        return {
-            name: this.name,
-            columns: this.columns.map((c) => c.toJSON(table))
-        };
+    constructor(message) {
+        super(message);
+        this.name = ConnectionClosedError.NAME;
     }
 }
 
@@ -10444,211 +11687,6 @@ class Schema {
     }
 }
 
-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() {
-        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))
-        };
-    }
-}
-
 /**
   Generate a new table from the columns and indexes
   @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
@@ -10804,6 +11842,7 @@ const parseQuery = (query, parameters) => {
     return { sqlStatement, parameters: parameters };
 };
 
+exports.ATTACHMENT_TABLE = ATTACHMENT_TABLE;
 exports.AbortOperation = AbortOperation;
 exports.AbstractPowerSyncDatabase = AbstractPowerSyncDatabase;
 exports.AbstractPowerSyncDatabaseOpenFactory = AbstractPowerSyncDatabaseOpenFactory;
@@ -10811,6 +11850,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;
@@ -10849,6 +11892,7 @@ exports.InvalidSQLCharacters = InvalidSQLCharacters;
 exports.LogLevel = LogLevel;
 exports.MAX_AMOUNT_OF_COLUMNS = MAX_AMOUNT_OF_COLUMNS;
 exports.MAX_OP_ID = MAX_OP_ID;
+exports.MEMORY_TRIGGER_CLAIM_MANAGER = MEMORY_TRIGGER_CLAIM_MANAGER;
 exports.OnChangeQueryProcessor = OnChangeQueryProcessor;
 exports.OpType = OpType;
 exports.OplogEntry = OplogEntry;
@@ -10859,9 +11903,12 @@ 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;