@powersync/common 1.36.0 → 1.37.0

package/dist/index.d.cts

@@ -2217,6 +2217,368 @@ declare class CrudTransaction extends CrudBatch {
     transactionId?: number | undefined);
 }
 
+/**
+ * SQLite operations to track changes for with {@link TriggerManager}
+ * @experimental
+ */
+declare enum DiffTriggerOperation {
+    INSERT = "INSERT",
+    UPDATE = "UPDATE",
+    DELETE = "DELETE"
+}
+/**
+ * @experimental
+ * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
+ * This is the base record structure for all diff records.
+ */
+interface BaseTriggerDiffRecord {
+    /**
+     * The modified row's `id` column value.
+     */
+    id: string;
+    /**
+     * The operation performed which created this record.
+     */
+    operation: DiffTriggerOperation;
+    /**
+     * Time the change operation was recorded.
+     * This is in ISO 8601 format, e.g. `2023-10-01T12:00:00.000Z`.
+     */
+    timestamp: string;
+}
+/**
+ * @experimental
+ * Represents a diff record for a SQLite UPDATE operation.
+ * This record contains the new value and optionally the previous value.
+ * Values are stored as JSON strings.
+ */
+interface TriggerDiffUpdateRecord extends BaseTriggerDiffRecord {
+    operation: DiffTriggerOperation.UPDATE;
+    /**
+     * The updated state of the row in JSON string format.
+     */
+    value: string;
+    /**
+     * The previous value of the row in JSON string format.
+     */
+    previous_value: string;
+}
+/**
+ * @experimental
+ * Represents a diff record for a SQLite INSERT operation.
+ * This record contains the new value represented as a JSON string.
+ */
+interface TriggerDiffInsertRecord extends BaseTriggerDiffRecord {
+    operation: DiffTriggerOperation.INSERT;
+    /**
+     * The value of the row, at the time of INSERT, in JSON string format.
+     */
+    value: string;
+}
+/**
+ * @experimental
+ * Represents a diff record for a SQLite DELETE operation.
+ * This record contains the new value represented as a JSON string.
+ */
+interface TriggerDiffDeleteRecord extends BaseTriggerDiffRecord {
+    operation: DiffTriggerOperation.DELETE;
+    /**
+     * The value of the row, before the DELETE operation, in JSON string format.
+     */
+    value: string;
+}
+/**
+ * @experimental
+ * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
+ * This is the record structure for all diff records.
+ *
+ * Querying the DIFF table directly with {@link TriggerDiffHandlerContext#withDiff} will return records
+ * with the structure of this type.
+ * @example
+ * ```typescript
+ * const diffs = await context.withDiff<TriggerDiffRecord>('SELECT * FROM DIFF');
+ * diff.forEach(diff => console.log(diff.operation, diff.timestamp, JSON.parse(diff.value)))
+ * ```
+ */
+type TriggerDiffRecord = TriggerDiffUpdateRecord | TriggerDiffInsertRecord | TriggerDiffDeleteRecord;
+/**
+ * @experimental
+ * Querying the DIFF table directly with {@link TriggerDiffHandlerContext#withExtractedDiff} will return records
+ * with the tracked columns extracted from the JSON value.
+ * This type represents the structure of such records.
+ * @example
+ * ```typescript
+ * const diffs = await context.withExtractedDiff<ExtractedTriggerDiffRecord<{id: string, name: string}>>('SELECT * FROM DIFF');
+ * diff.forEach(diff => console.log(diff.__operation, diff.__timestamp, diff.columnName))
+ * ```
+ */
+type ExtractedTriggerDiffRecord<T> = T & {
+    [K in keyof Omit<BaseTriggerDiffRecord, 'id'> as `__${string & K}`]: TriggerDiffRecord[K];
+} & {
+    __previous_value?: string;
+};
+/**
+ * @experimental
+ * Hooks used in the creation of a table diff trigger.
+ */
+interface TriggerCreationHooks {
+    /**
+     * Executed inside a write lock before the trigger is created.
+     */
+    beforeCreate?: (context: LockContext) => Promise<void>;
+}
+/**
+ * Common interface for options used in creating a diff trigger.
+ */
+interface BaseCreateDiffTriggerOptions {
+    /**
+     * PowerSync source table/view to trigger and track changes from.
+     * This should be present in the PowerSync database's schema.
+     */
+    source: string;
+    /**
+     * Columns to track and report changes for.
+     * Defaults to all columns in the source table.
+     * Use an empty array to track only the ID and operation.
+     */
+    columns?: string[];
+    /**
+     * Condition to filter when the triggers should fire.
+     * This corresponds to a SQLite [WHEN](https://sqlite.org/lang_createtrigger.html) clause in the trigger body.
+     * This is useful for only triggering on specific conditions.
+     * For example, you can use it to only trigger on certain values in the NEW row.
+     * Note that for PowerSync the row data is stored in a JSON column named `data`.
+     * The row id is available in the `id` column.
+     *
+     * NB! The WHEN clauses here are added directly to the SQLite trigger creation SQL.
+     * Any user input strings here should be sanitized externally. The {@link when} string template function performs
+     * some basic sanitization, extra external sanitization is recommended.
+     *
+     * @example
+     * {
+     *  'INSERT': sanitizeSQL`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(list.id)}`,
+     *  'INSERT': `TRUE`,
+     *  'UPDATE': sanitizeSQL`NEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active'`,
+     *  'DELETE': sanitizeSQL`json_extract(OLD.data, '$.list_id') = 'abcd'`
+     * }
+     */
+    when: Partial<Record<DiffTriggerOperation, string>>;
+    /**
+     * Hooks which allow execution during the trigger creation process.
+     */
+    hooks?: TriggerCreationHooks;
+}
+/**
+ * @experimental
+ * Options for {@link TriggerManager#createDiffTrigger}.
+ */
+interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
+    /**
+     * Destination table to send changes to.
+     * This table is created internally as a SQLite temporary table.
+     * This table will be dropped once the trigger is removed.
+     */
+    destination: string;
+}
+/**
+ * @experimental
+ * Callback to drop a trigger after it has been created.
+ */
+type TriggerRemoveCallback = () => Promise<void>;
+/**
+ * @experimental
+ * Context for the `onChange` handler provided to {@link TriggerManager#trackTableDiff}.
+ */
+interface TriggerDiffHandlerContext extends LockContext {
+    /**
+     * The name of the temporary destination table created by the trigger.
+     */
+    destinationTable: string;
+    /**
+     * Allows querying the database with access to the table containing DIFF records.
+     * The diff table is accessible via the `DIFF` accessor.
+     *
+     * The `DIFF` table is of the form described in {@link TriggerManager#createDiffTrigger}
+     * ```sql
+     * CREATE TEMP DIFF (
+     *       id TEXT,
+     *       operation TEXT,
+     *       timestamp TEXT
+     *       value TEXT,
+     *       previous_value TEXT
+     *     );
+     * ```
+     *
+     * Note that the `value` and `previous_value` columns store the row state in JSON string format.
+     * To access the row state in an extracted form see {@link TriggerDiffHandlerContext#withExtractedDiff}.
+     *
+     * @example
+     * ```sql
+     * --- This fetches the current state of `todo` rows which have a diff operation present.
+     * --- The state of the row at the time of the operation is accessible in the DIFF records.
+     * SELECT
+     *  todos.*
+     * FROM
+     *    DIFF
+     * JOIN todos ON DIFF.id = todos.id
+     * WHERE json_extract(DIFF.value, '$.status') = 'active'
+     * ```
+     */
+    withDiff: <T = any>(query: string, params?: ReadonlyArray<Readonly<any>>) => Promise<T[]>;
+    /**
+     * Allows querying the database with access to the table containing diff records.
+     * The diff table is accessible via the `DIFF` accessor.
+     *
+     * This is similar to {@link withDiff} but extracts the row columns from the tracked JSON value. The diff operation
+     * data is aliased as `__` columns to avoid column conflicts.
+     *
+     * For {@link DiffTriggerOperation#DELETE} operations the previous_value columns are extracted for convenience.
+     *
+     *
+     * ```sql
+     * CREATE TEMP TABLE DIFF (
+     *       id TEXT,
+     *       replicated_column_1 COLUMN_TYPE,
+     *       replicated_column_2 COLUMN_TYPE,
+     *       __operation TEXT,
+     *       __timestamp TEXT,
+     *       __previous_value TEXT
+     *     );
+     * ```
+     *
+     * @example
+     * ```sql
+     * SELECT
+     *  todos.*
+     * FROM
+     *    DIFF
+     *  JOIN todos ON DIFF.id = todos.id
+     * --- The todo column names are extracted from json and are available as DIFF.name
+     * WHERE DIFF.name = 'example'
+     * ```
+     */
+    withExtractedDiff: <T = any>(query: string, params?: ReadonlyArray<Readonly<any>>) => Promise<T[]>;
+}
+/**
+ * @experimental
+ * Options for tracking changes to a table with {@link TriggerManager#trackTableDiff}.
+ */
+interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
+    /**
+     * Handler for processing diff operations.
+     * Automatically invoked once diff items are present.
+     * Diff items are automatically cleared after the handler is invoked.
+     */
+    onChange: (context: TriggerDiffHandlerContext) => Promise<void>;
+    /**
+     * The minimum interval, in milliseconds, between {@link onChange} invocations.
+     *  @default {@link DEFAULT_WATCH_THROTTLE_MS}
+     */
+    throttleMs?: number;
+}
+/**
+ * @experimental
+ */
+interface TriggerManager {
+    /**
+     * @experimental
+     * Creates a temporary trigger which tracks changes to a source table
+     * and writes changes to a destination table.
+     * The temporary destination table is created internally and will be dropped when the trigger is removed.
+     * The temporary destination table is created with the structure:
+     *
+     * ```sql
+     * CREATE TEMP TABLE ${destination} (
+     *       id TEXT,
+     *       operation TEXT,
+     *       timestamp TEXT
+     *       value TEXT,
+     *       previous_value TEXT
+     *     );
+     * ```
+     * The `value` column contains the JSON representation of the row's value at the change.
+     *
+     * For {@link DiffTriggerOperation#UPDATE} operations the `previous_value` column contains the previous value of the changed row
+     * in a JSON format.
+     *
+     * NB: The triggers created by this method might be invalidated by {@link AbstractPowerSyncDatabase#updateSchema} calls.
+     * These triggers should manually be dropped and recreated when updating the schema.
+     *
+     * @returns A callback to remove the trigger and drop the destination table.
+     *
+     * @example
+     * ```javascript
+     * const dispose = await database.triggers.createDiffTrigger({
+     *   source: 'lists',
+     *   destination: 'ps_temp_lists_diff',
+     *   columns: ['name'],
+     *   when: {
+     *    [DiffTriggerOperation.INSERT]: 'TRUE',
+     *    [DiffTriggerOperation.UPDATE]: 'TRUE',
+     *    [DiffTriggerOperation.DELETE]: 'TRUE'
+     *   }
+     * });
+     * ```
+     */
+    createDiffTrigger(options: CreateDiffTriggerOptions): Promise<TriggerRemoveCallback>;
+    /**
+     * @experimental
+     * Tracks changes for a table. Triggering a provided handler on changes.
+     * Uses {@link createDiffTrigger} internally to create a temporary destination table.
+     *
+     * @returns A callback to cleanup the trigger and stop tracking changes.
+     *
+     * NB: The triggers created by this method might be invalidated by {@link AbstractPowerSyncDatabase#updateSchema} calls.
+     * These triggers should manually be dropped and recreated when updating the schema.
+     *
+     * @example
+     * ```javascript
+     *  const dispose = database.triggers.trackTableDiff({
+     *        source: 'todos',
+     *        columns: ['list_id'],
+     *        when: {
+     *          [DiffTriggerOperation.INSERT]: sanitizeSQL`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(someIdVariable)}`
+     *        },
+     *        onChange: async (context) => {
+     *          // Fetches the todo records that were inserted during this diff
+     *          const newTodos = await context.getAll<Database['todos']>(`
+     *            SELECT
+     *              todos.*
+     *            FROM
+     *              DIFF
+     *              JOIN todos ON DIFF.id = todos.id
+     *          `);
+     *
+     *          // Process newly created todos
+     *        },
+     *        hooks: {
+     *          beforeCreate: async (lockContext) => {
+     *            // This hook is executed inside the write lock before the trigger is created.
+     *            // It can be used to synchronize the current state of the table with processor logic.
+     *            // Any changes after this callback are guaranteed to trigger the `onChange` handler.
+     *
+     *            // Read the current state of the todos table
+     *            const currentTodos = await lockContext.getAll<Database['todos']>(
+     *              `
+     *                SELECT
+     *                  *
+     *                FROM
+     *                  todos
+     *                WHERE
+     *                  list_id = ?
+     *              `,
+     *              ['123']
+     *            );
+     *
+     *            // Process existing todos
+     *          }
+     *        }
+     *      });
+     * ```
+     */
+    trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback>;
+}
+
 interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -2334,6 +2696,11 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
     protected _schema: Schema;
     private _database;
     protected runExclusiveMutex: Mutex;
+    /**
+     * @experimental
+     * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
+     */
+    readonly triggers: TriggerManager;
     logger: ILogger;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
@@ -2482,6 +2849,38 @@ declare abstract class AbstractPowerSyncDatabase extends BaseObserver<PowerSyncD
      * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     getNextCrudTransaction(): Promise<CrudTransaction | null>;
+    /**
+     * Returns an async iterator of completed transactions with local writes against the database.
+     *
+     * This is typically used from the {@link PowerSyncBackendConnector.uploadData} callback. Each entry emitted by the
+     * returned iterator is a full transaction containing all local writes made while that transaction was active.
+     *
+     * Unlike {@link getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
+     * {@link CrudTransaction.complete}d yet, this iterator can be used to receive multiple transactions. Calling
+     * {@link CrudTransaction.complete} will mark that and all prior transactions emitted by the iterator as completed.
+     *
+     * This can be used to upload multiple transactions in a single batch, e.g with:
+     *
+     * ```JavaScript
+     * let lastTransaction = null;
+     * let batch = [];
+     *
+     * for await (const transaction of database.getCrudTransactions()) {
+     *   batch.push(...transaction.crud);
+     *   lastTransaction = transaction;
+     *
+     *   if (batch.length > 10) {
+     *     break;
+     *    }
+     * }
+     * ```
+     *
+     * If there is no local data to upload, the async iterator complete without emitting any items.
+     *
+     * Note that iterating over async iterables requires a [polyfill](https://github.com/powersync-ja/powersync-js/tree/main/packages/react-native#babel-plugins-watched-queries)
+     * for React Native.
+     */
+    getCrudTransactions(): AsyncIterable<CrudTransaction, null>;
     /**
      * Get an unique client id for this database.
      *
@@ -2828,6 +3227,41 @@ declare class SqliteBucketStorage extends BaseObserver<BucketStorageListener> im
     static _subkeyMigrationKey: string;
 }
 
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+declare function sanitizeUUID(uuid: string): string;
+/**
+ * SQL string template function for {@link TrackDiffOptions#when} and {@link CreateDiffTriggerOptions#when}.
+ *
+ * This function performs basic string interpolation for SQLite WHEN clauses.
+ *
+ * **String placeholders:**
+ * - All string values passed as placeholders are automatically wrapped in single quotes (`'`).
+ * - Do not manually wrap placeholders in single quotes in your template string; the function will handle quoting and escaping for you.
+ * - Any single quotes within the string value are escaped by doubling them (`''`), as required by SQL syntax.
+ *
+ * **Other types:**
+ * - `null` and `undefined` are converted to SQL `NULL`.
+ * - Objects are stringified using `JSON.stringify()` and wrapped in single quotes, with any single quotes inside the stringified value escaped.
+ * - Numbers and other primitive types are inserted directly.
+ *
+ * **Usage example:**
+ * ```typescript
+ * const myID = "O'Reilly";
+ * const clause = sanitizeSQL`New.id = ${myID}`;
+ * // Result: "New.id = 'O''Reilly'"
+ * ```
+ *
+ * Avoid manually quoting placeholders:
+ * ```typescript
+ * // Incorrect:
+ * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
+ * ```
+ */
+declare function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string;
+
 /**
  * Options for {@link GetAllQuery}.
  */
@@ -2930,5 +3364,5 @@ interface ParsedQuery {
 }
 declare const parseQuery: <T>(query: string | CompilableQuery<T>, parameters: any[]) => ParsedQuery;
 
-export { AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, BaseObserver, Column, ColumnType, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, Table, TableV2, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange };
-export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateLoggerOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, LinkQueryOptions, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RemoteConnector, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStreamOptions, TableOptions, TableUpdateOperation, TableV2Options, TrackPreviousOptions, Transaction, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState };
+export { AbortOperation, AbstractPowerSyncDatabase, AbstractPowerSyncDatabaseOpenFactory, AbstractQueryProcessor, AbstractRemote, AbstractStreamingSyncImplementation, ArrayComparator, BaseObserver, Column, ColumnType, ConnectionManager, ControlledExecutor, CrudBatch, CrudEntry, CrudTransaction, DEFAULT_CRUD_BATCH_LIMIT, DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_INDEX_COLUMN_OPTIONS, DEFAULT_INDEX_OPTIONS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_POWERSYNC_CLOSE_OPTIONS, DEFAULT_POWERSYNC_DB_OPTIONS, DEFAULT_PRESSURE_LIMITS, DEFAULT_REMOTE_LOGGER, DEFAULT_REMOTE_OPTIONS, DEFAULT_RETRY_DELAY_MS, DEFAULT_ROW_COMPARATOR, DEFAULT_STREAMING_SYNC_OPTIONS, DEFAULT_STREAM_CONNECTION_OPTIONS, DEFAULT_SYNC_CLIENT_IMPLEMENTATION, DEFAULT_TABLE_OPTIONS, DEFAULT_WATCH_QUERY_OPTIONS, DEFAULT_WATCH_THROTTLE_MS, DataStream, DiffTriggerOperation, DifferentialQueryProcessor, EMPTY_DIFFERENTIAL, FalsyComparator, FetchImplementationProvider, FetchStrategy, GetAllQuery, Index, IndexedColumn, InvalidSQLCharacters, LockType, LogLevel, MAX_AMOUNT_OF_COLUMNS, MAX_OP_ID, OnChangeQueryProcessor, OpType, OpTypeEnum, OplogEntry, PSInternalTable, PowerSyncControlCommand, RowUpdateType, Schema, SqliteBucketStorage, SyncClientImplementation, SyncDataBatch, SyncDataBucket, SyncProgress, SyncStatus, SyncStreamConnectionMethod, Table, TableV2, UpdateType, UploadQueueStats, WatchedQueryListenerEvent, column, compilableQueryWatch, createBaseLogger, createLogger, extractTableUpdates, isBatchedUpdateNotification, isContinueCheckpointRequest, isDBAdapter, isPowerSyncDatabaseOptionsWithSettings, isSQLOpenFactory, isSQLOpenOptions, isStreamingKeepalive, isStreamingSyncCheckpoint, isStreamingSyncCheckpointComplete, isStreamingSyncCheckpointDiff, isStreamingSyncCheckpointPartiallyComplete, isStreamingSyncData, isSyncNewCheckpointRequest, parseQuery, runOnSchemaChange, sanitizeSQL, sanitizeUUID };
+export type { AbstractQueryProcessorOptions, AbstractRemoteOptions, AbstractStreamingSyncImplementationOptions, AdditionalConnectionOptions, ArrayComparatorOptions, ArrayQueryDefinition, BSONImplementation, BaseColumnType, BaseConnectionOptions, BaseListener, BaseObserverInterface, BasePowerSyncDatabaseOptions, BaseTriggerDiffRecord, BatchedUpdateNotification, BucketChecksum, BucketDescription, BucketOperationProgress, BucketRequest, BucketState, BucketStorageAdapter, BucketStorageListener, Checkpoint, ChecksumCache, ColumnOptions, ColumnsType, CompilableQuery, CompilableQueryWatchHandler, CompiledQuery, ConnectionManagerListener, ConnectionManagerOptions, ConnectionManagerSyncImplementationResult, ContinueCheckpointRequest, ControlledExecutorOptions, CreateDiffTriggerOptions, CreateLoggerOptions, CrudRequest, CrudResponse, CrudUploadNotification, DBAdapter, DBAdapterListener, DBGetUtils, DBLockOptions, DataStreamCallback, DataStreamListener, DataStreamOptions, DifferentialQueryProcessorOptions, DifferentialWatchedQuery, DifferentialWatchedQueryComparator, DifferentialWatchedQueryListener, DifferentialWatchedQueryOptions, DifferentialWatchedQuerySettings, DisconnectAndClearOptions, Disposable, ExtractColumnValueType, ExtractedTriggerDiffRecord, FetchImplementation, GetAllQueryOptions, IndexColumnOptions, IndexOptions, IndexShorthand, InternalConnectionOptions, LinkQueryOptions, LockContext, LockOptions, MutableWatchedQueryState, OnChangeQueryProcessorOptions, OpId, OpTypeJSON, OplogEntryJSON, ParsedQuery, PowerSyncBackendConnector, PowerSyncCloseOptions, PowerSyncConnectionOptions, PowerSyncCredentials, PowerSyncDBListener, PowerSyncDatabaseOptions, PowerSyncDatabaseOptionsWithDBAdapter, PowerSyncDatabaseOptionsWithOpenFactory, PowerSyncDatabaseOptionsWithSettings, PowerSyncOpenFactoryOptions, ProgressWithOperations, Query, QueryParam, QueryResult, RemoteConnector, RequiredAdditionalConnectionOptions, RequiredPowerSyncConnectionOptions, RowType, SQLOnChangeOptions, SQLOpenFactory, SQLOpenOptions, SQLWatchOptions, SavedProgress, SchemaTableType, SocketSyncStreamOptions, StandardWatchedQuery, StandardWatchedQueryOptions, StreamingSyncCheckpoint, StreamingSyncCheckpointComplete, StreamingSyncCheckpointDiff, StreamingSyncCheckpointPartiallyComplete, StreamingSyncDataJSON, StreamingSyncImplementation, StreamingSyncImplementationListener, StreamingSyncKeepalive, StreamingSyncLine, StreamingSyncLineOrCrudUploadComplete, StreamingSyncRequest, StreamingSyncRequestParameterType, SyncDataBucketJSON, SyncDataFlowStatus, SyncLocalDatabaseResult, SyncNewCheckpointRequest, SyncPriorityStatus, SyncRequest, SyncResponse, SyncStatusOptions, SyncStreamOptions, TableOptions, TableUpdateOperation, TableV2Options, TrackDiffOptions, TrackPreviousOptions, Transaction, TriggerCreationHooks, TriggerDiffDeleteRecord, TriggerDiffHandlerContext, TriggerDiffInsertRecord, TriggerDiffRecord, TriggerDiffUpdateRecord, TriggerManager, TriggerRemoveCallback, UpdateNotification, WatchCompatibleQuery, WatchExecuteOptions, WatchHandler, WatchOnChangeEvent, WatchOnChangeHandler, WatchedQuery, WatchedQueryComparator, WatchedQueryDifferential, WatchedQueryListener, WatchedQueryOptions, WatchedQueryRowDifferential, WatchedQuerySettings, WatchedQueryState };

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -13,6 +13,7 @@ import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { TriggerManager } from './triggers/TriggerManager.js';
 import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
 import { WatchedQueryComparator } from './watched/processors/comparators.js';
 export interface DisconnectAndClearOptions {
@@ -132,6 +133,11 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
     protected _schema: Schema;
     private _database;
     protected runExclusiveMutex: Mutex;
+    /**
+     * @experimental
+     * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
+     */
+    readonly triggers: TriggerManager;
     logger: ILogger;
     constructor(options: PowerSyncDatabaseOptionsWithDBAdapter);
     constructor(options: PowerSyncDatabaseOptionsWithOpenFactory);
@@ -280,6 +286,38 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     getNextCrudTransaction(): Promise<CrudTransaction | null>;
+    /**
+     * Returns an async iterator of completed transactions with local writes against the database.
+     *
+     * This is typically used from the {@link PowerSyncBackendConnector.uploadData} callback. Each entry emitted by the
+     * returned iterator is a full transaction containing all local writes made while that transaction was active.
+     *
+     * Unlike {@link getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
+     * {@link CrudTransaction.complete}d yet, this iterator can be used to receive multiple transactions. Calling
+     * {@link CrudTransaction.complete} will mark that and all prior transactions emitted by the iterator as completed.
+     *
+     * This can be used to upload multiple transactions in a single batch, e.g with:
+     *
+     * ```JavaScript
+     * let lastTransaction = null;
+     * let batch = [];
+     *
+     * for await (const transaction of database.getCrudTransactions()) {
+     *   batch.push(...transaction.crud);
+     *   lastTransaction = transaction;
+     *
+     *   if (batch.length > 10) {
+     *     break;
+     *    }
+     * }
+     * ```
+     *
+     * If there is no local data to upload, the async iterator complete without emitting any items.
+     *
+     * Note that iterating over async iterables requires a [polyfill](https://github.com/powersync-ja/powersync-js/tree/main/packages/react-native#babel-plugins-watched-queries)
+     * for React Native.
+     */
+    getCrudTransactions(): AsyncIterable<CrudTransaction, null>;
     /**
      * Get an unique client id for this database.
      *

package/lib/client/AbstractPowerSyncDatabase.js

@@ -7,7 +7,7 @@ import { SyncStatus } from '../db/crud/SyncStatus.js';
 import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
-import { throttleTrailing } from '../utils/async.js';
+import { symbolAsyncIterator, throttleTrailing } from '../utils/async.js';
 import { ConnectionManager } from './ConnectionManager.js';
 import { CustomQuery } from './CustomQuery.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
@@ -16,6 +16,7 @@ import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { TriggerManagerImpl } from './triggers/TriggerManagerImpl.js';
 import { DEFAULT_WATCH_THROTTLE_MS } from './watched/WatchedQuery.js';
 import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
@@ -64,6 +65,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
     _schema;
     _database;
     runExclusiveMutex;
+    /**
+     * @experimental
+     * Allows creating SQLite triggers which can be used to track various operations on SQLite tables.
+     */
+    triggers;
     logger;
     constructor(options) {
         super();
@@ -118,6 +124,10 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
             logger: this.logger
         });
         this._isReadyPromise = this.initialize();
+        this.triggers = new TriggerManagerImpl({
+            db: this,
+            schema: this.schema
+        });
     }
     /**
      * Schema used for the local database.
@@ -426,23 +436,72 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * @returns A transaction of CRUD operations to upload, or null if there are none
      */
     async getNextCrudTransaction() {
-        return await this.readTransaction(async (tx) => {
-            const first = await tx.getOptional(`SELECT id, tx_id, data FROM ${PSInternalTable.CRUD} ORDER BY id ASC LIMIT 1`);
-            if (!first) {
-                return null;
-            }
-            const txId = first.tx_id;
-            let all;
-            if (!txId) {
-                all = [CrudEntry.fromRow(first)];
-            }
-            else {
-                const result = await tx.getAll(`SELECT id, tx_id, data FROM ${PSInternalTable.CRUD} WHERE tx_id = ? ORDER BY id ASC`, [txId]);
-                all = result.map((row) => CrudEntry.fromRow(row));
+        const iterator = this.getCrudTransactions()[symbolAsyncIterator]();
+        return (await iterator.next()).value;
+    }
+    /**
+     * Returns an async iterator of completed transactions with local writes against the database.
+     *
+     * This is typically used from the {@link PowerSyncBackendConnector.uploadData} callback. Each entry emitted by the
+     * returned iterator is a full transaction containing all local writes made while that transaction was active.
+     *
+     * Unlike {@link getNextCrudTransaction}, which always returns the oldest transaction that hasn't been
+     * {@link CrudTransaction.complete}d yet, this iterator can be used to receive multiple transactions. Calling
+     * {@link CrudTransaction.complete} will mark that and all prior transactions emitted by the iterator as completed.
+     *
+     * This can be used to upload multiple transactions in a single batch, e.g with:
+     *
+     * ```JavaScript
+     * let lastTransaction = null;
+     * let batch = [];
+     *
+     * for await (const transaction of database.getCrudTransactions()) {
+     *   batch.push(...transaction.crud);
+     *   lastTransaction = transaction;
+     *
+     *   if (batch.length > 10) {
+     *     break;
+     *    }
+     * }
+     * ```
+     *
+     * If there is no local data to upload, the async iterator complete without emitting any items.
+     *
+     * Note that iterating over async iterables requires a [polyfill](https://github.com/powersync-ja/powersync-js/tree/main/packages/react-native#babel-plugins-watched-queries)
+     * for React Native.
+     */
+    getCrudTransactions() {
+        return {
+            [symbolAsyncIterator]: () => {
+                let lastCrudItemId = -1;
+                const sql = `
+WITH RECURSIVE crud_entries AS (
+  SELECT id, tx_id, data FROM ps_crud WHERE id = (SELECT min(id) FROM ps_crud WHERE id > ?)
+  UNION ALL
+  SELECT ps_crud.id, ps_crud.tx_id, ps_crud.data FROM ps_crud
+    INNER JOIN crud_entries ON crud_entries.id + 1 = rowid
+  WHERE crud_entries.tx_id = ps_crud.tx_id
+)
+SELECT * FROM crud_entries;
+    `;
+                return {
+                    next: async () => {
+                        const nextTransaction = await this.database.getAll(sql, [lastCrudItemId]);
+                        if (nextTransaction.length == 0) {
+                            return { done: true, value: null };
+                        }
+                        const items = nextTransaction.map((row) => CrudEntry.fromRow(row));
+                        const last = items[items.length - 1];
+                        const txId = last.transactionId;
+                        lastCrudItemId = last.clientId;
+                        return {
+                            done: false,
+                            value: new CrudTransaction(items, async (writeCheckpoint) => this.handleCrudCheckpoint(last.clientId, writeCheckpoint), txId)
+                        };
+                    }
+                };
             }
-            const last = all[all.length - 1];
-            return new CrudTransaction(all, async (writeCheckpoint) => this.handleCrudCheckpoint(last.clientId, writeCheckpoint), txId);
-        });
+        };
     }
     /**
      * Get an unique client id for this database.

package/lib/client/sync/stream/AbstractRemote.js

@@ -382,6 +382,9 @@ export class AbstractRemote {
          *  Aborting the active fetch request while it is being consumed seems to throw
          *  an unhandled exception on the window level.
          */
+        if (abortSignal?.aborted) {
+            throw new AbortOperation('Abort request received before making postStreamRaw request');
+        }
         const controller = new AbortController();
         let requestResolved = false;
         abortSignal?.addEventListener('abort', () => {