@powersync/common 1.41.0 → 1.42.0

package/src/client/triggers/TriggerManager.ts

@@ -0,0 +1,451 @@
+import { LockContext } from '../../db/DBAdapter.js';
+
+/**
+ * SQLite operations to track changes for with {@link TriggerManager}
+ * @experimental
+ */
+export 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.
+ *
+ * @template TOperationId - The type for `operation_id`. Defaults to `number` as returned by default SQLite database queries.
+ * Use `string` for full 64-bit precision when using `{ castOperationIdAsText: true }` option.
+ */
+export interface BaseTriggerDiffRecord<TOperationId extends string | number = number> {
+  /**
+   * The modified row's `id` column value.
+   */
+  id: string;
+  /**
+   * The operation performed which created this record.
+   */
+  operation: DiffTriggerOperation;
+  /**
+   * Auto-incrementing primary key for the operation.
+   * Defaults to number as returned by database queries (wa-sqlite returns lower 32 bits).
+   * Can be string for full 64-bit precision when using `{ castOperationIdAsText: true }` option.
+   */
+  operation_id: TOperationId;
+
+  /**
+   * 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<TOperationId extends string | number = number>
+  extends BaseTriggerDiffRecord<TOperationId> {
+  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<TOperationId extends string | number = number>
+  extends BaseTriggerDiffRecord<TOperationId> {
+  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<TOperationId extends string | number = number>
+  extends BaseTriggerDiffRecord<TOperationId> {
+  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.
+ *
+ * @template TOperationId - The type for `operation_id`. Defaults to `number` as returned by database queries.
+ * Use `string` for full 64-bit precision when using `{ castOperationIdAsText: true }` option.
+ *
+ * @example
+ * ```typescript
+ * // Default: operation_id is number
+ * const diffs = await context.withDiff<TriggerDiffRecord>('SELECT * FROM DIFF');
+ *
+ * // With string operation_id for full precision
+ * const diffsWithString = await context.withDiff<TriggerDiffRecord<string>>(
+ *   'SELECT * FROM DIFF',
+ *   undefined,
+ *   { castOperationIdAsText: true }
+ * );
+ * ```
+ */
+export type TriggerDiffRecord<TOperationId extends string | number = number> =
+  | TriggerDiffUpdateRecord<TOperationId>
+  | TriggerDiffInsertRecord<TOperationId>
+  | TriggerDiffDeleteRecord<TOperationId>;
+
+/**
+ * @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.
+ *
+ * @template T - The type for the extracted columns from the tracked JSON value.
+ * @template TOperationId - The type for `operation_id`. Defaults to `number` as returned by database queries.
+ * Use `string` for full 64-bit precision when using `{ castOperationIdAsText: true }` option.
+ *
+ * @example
+ * ```typescript
+ * // Default: operation_id is number
+ * const diffs = await context.withExtractedDiff<ExtractedTriggerDiffRecord<{id: string, name: string}>>('SELECT * FROM DIFF');
+ *
+ * // With string operation_id for full precision
+ * const diffsWithString = await context.withExtractedDiff<ExtractedTriggerDiffRecord<{id: string, name: string}, string>>(
+ *   'SELECT * FROM DIFF',
+ *   undefined,
+ *   { castOperationIdAsText: true }
+ * );
+ * ```
+ */
+export type ExtractedTriggerDiffRecord<T, TOperationId extends string | number = number> = T & {
+  [K in keyof Omit<BaseTriggerDiffRecord<TOperationId>, 'id'> as `__${string & K}`]: TriggerDiffRecord<TOperationId>[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
+ * Options for {@link TriggerDiffHandlerContext#withDiff}.
+ */
+export interface WithDiffOptions {
+  /**
+   * If true, casts `operation_id` as TEXT in the internal CTE to preserve full 64-bit precision.
+   * Use this when you need to ensure `operation_id` is treated as a string to avoid precision loss
+   * for values exceeding JavaScript's Number.MAX_SAFE_INTEGER.
+   *
+   * When enabled, use {@link TriggerDiffRecord}<string> to type the result correctly.
+   */
+  castOperationIdAsText?: boolean;
+}
+
+/**
+ * @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 (
+   *       operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+   *       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'
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With operation_id cast as TEXT for full precision
+   * const diffs = await context.withDiff<TriggerDiffRecord<string>>(
+   *   'SELECT * FROM DIFF',
+   *   undefined,
+   *   { castOperationIdAsText: true }
+   * );
+   * // diffs[0].operation_id is now typed as string
+   * ```
+   */
+  withDiff: <T = any>(query: string, params?: ReadonlyArray<Readonly<any>>, options?: WithDiffOptions) => 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} (
+   *       operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+   *       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.withDiff<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>;
+}