@powersync/common 1.36.0 → 1.38.0

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.
@@ -213,11 +223,11 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 .map((n) => parseInt(n));
         }
         catch (e) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
+            throw new Error(`Unsupported powersync extension version. Need >=0.4.5 <1.0.0, got: ${this.sdkVersion}. Details: ${e.message}`);
         }
-        // Validate >=0.3.11 <1.0.0
-        if (versionInts[0] != 0 || versionInts[1] < 3 || (versionInts[1] == 3 && versionInts[2] < 11)) {
-            throw new Error(`Unsupported powersync extension version. Need >=0.3.11 <1.0.0, got: ${this.sdkVersion}`);
+        // Validate >=0.4.5 <1.0.0
+        if (versionInts[0] != 0 || versionInts[1] < 4 || (versionInts[1] == 4 && versionInts[2] < 5)) {
+            throw new Error(`Unsupported powersync extension version. Need >=0.4.5 <1.0.0, got: ${this.sdkVersion}`);
         }
     }
     async updateHasSynced() {
@@ -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', () => {

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

@@ -439,7 +439,9 @@ The next upload iteration will be delayed.`);
                     ...DEFAULT_STREAM_CONNECTION_OPTIONS,
                     ...(options ?? {})
                 };
-                if (resolvedOptions.clientImplementation == SyncClientImplementation.JAVASCRIPT) {
+                const clientImplementation = resolvedOptions.clientImplementation;
+                this.updateSyncStatus({ clientImplementation });
+                if (clientImplementation == SyncClientImplementation.JAVASCRIPT) {
                     await this.legacyStreamingSyncIteration(signal, resolvedOptions);
                 }
                 else {
@@ -693,6 +695,9 @@ The next upload iteration will be delayed.`);
         const remote = this.options.remote;
         let receivingLines = null;
         let hadSyncLine = false;
+        if (signal.aborted) {
+            throw new AbortOperation('Connection request has been aborted');
+        }
         const abortController = new AbortController();
         signal.addEventListener('abort', () => abortController.abort());
         // Pending sync lines received from the service, as well as local events that trigger a powersync_control
@@ -934,7 +939,8 @@ The next upload iteration will be delayed.`);
                 ...this.syncStatus.dataFlowStatus,
                 ...options.dataFlow
             },
-            priorityStatusEntries: options.priorityStatusEntries ?? this.syncStatus.priorityStatusEntries
+            priorityStatusEntries: options.priorityStatusEntries ?? this.syncStatus.priorityStatusEntries,
+            clientImplementation: options.clientImplementation ?? this.syncStatus.clientImplementation
         });
         if (!this.syncStatus.isEqual(updatedStatus)) {
             this.syncStatus = updatedStatus;

package/lib/client/triggers/TriggerManager.d.ts

@@ -0,0 +1,363 @@
+import { LockContext } from '../../db/DBAdapter.js';
+/**
+ * SQLite operations to track changes for with {@link TriggerManager}
+ * @experimental
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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)))
+ * ```
+ */
+export 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))
+ * ```
+ */
+export 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.
+ */
+export 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}.
+ */
+export 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.
+ */
+export type TriggerRemoveCallback = () => Promise<void>;
+/**
+ * @experimental
+ * Context for the `onChange` handler provided to {@link TriggerManager#trackTableDiff}.
+ */
+export 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}.
+ */
+export 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
+ */
+export 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>;
+}
+export {};

package/lib/client/triggers/TriggerManager.js

@@ -0,0 +1,10 @@
+/**
+ * SQLite operations to track changes for with {@link TriggerManager}
+ * @experimental
+ */
+export var DiffTriggerOperation;
+(function (DiffTriggerOperation) {
+    DiffTriggerOperation["INSERT"] = "INSERT";
+    DiffTriggerOperation["UPDATE"] = "UPDATE";
+    DiffTriggerOperation["DELETE"] = "DELETE";
+})(DiffTriggerOperation || (DiffTriggerOperation = {}));

package/lib/client/triggers/TriggerManagerImpl.d.ts

@@ -0,0 +1,18 @@
+import { LockContext } from '../../db/DBAdapter.js';
+import { Schema } from '../../db/schema/Schema.js';
+import { type AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CreateDiffTriggerOptions, TrackDiffOptions, TriggerManager, TriggerRemoveCallback } from './TriggerManager.js';
+export type TriggerManagerImplOptions = {
+    db: AbstractPowerSyncDatabase;
+    schema: Schema;
+};
+export declare class TriggerManagerImpl implements TriggerManager {
+    protected options: TriggerManagerImplOptions;
+    protected schema: Schema;
+    constructor(options: TriggerManagerImplOptions);
+    protected get db(): AbstractPowerSyncDatabase;
+    protected getUUID(): Promise<string>;
+    protected removeTriggers(tx: LockContext, triggerIds: string[]): Promise<void>;
+    createDiffTrigger(options: CreateDiffTriggerOptions): Promise<() => Promise<void>>;
+    trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback>;
+}