@powersync/common 1.41.0 → 1.42.0

package/src/client/triggers/TriggerManagerImpl.ts

@@ -0,0 +1,320 @@
+import { LockContext } from '../../db/DBAdapter.js';
+import { Schema } from '../../db/schema/Schema.js';
+import { type AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { DEFAULT_WATCH_THROTTLE_MS } from '../watched/WatchedQuery.js';
+import {
+  CreateDiffTriggerOptions,
+  DiffTriggerOperation,
+  TrackDiffOptions,
+  TriggerManager,
+  TriggerRemoveCallback,
+  WithDiffOptions
+} from './TriggerManager.js';
+
+export type TriggerManagerImplOptions = {
+  db: AbstractPowerSyncDatabase;
+  schema: Schema;
+};
+
+export class TriggerManagerImpl implements TriggerManager {
+  protected schema: Schema;
+
+  constructor(protected options: TriggerManagerImplOptions) {
+    this.schema = options.schema;
+    options.db.registerListener({
+      schemaChanged: (schema) => {
+        this.schema = schema;
+      }
+    });
+  }
+
+  protected get db() {
+    return this.options.db;
+  }
+
+  protected async getUUID() {
+    const { id: uuid } = await this.db.get<{ id: string }>(/* sql */ `
+      SELECT
+        uuid () as id
+    `);
+
+    // Replace dashes with underscores for SQLite table/trigger name compatibility
+    return uuid.replace(/-/g, '_');
+  }
+
+  protected async removeTriggers(tx: LockContext, triggerIds: string[]) {
+    for (const triggerId of triggerIds) {
+      await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
+    }
+  }
+
+  async createDiffTrigger(options: CreateDiffTriggerOptions) {
+    await this.db.waitForReady();
+    const { source, destination, columns, when, hooks } = options;
+    const operations = Object.keys(when) as DiffTriggerOperation[];
+    if (operations.length == 0) {
+      throw new Error('At least one WHEN operation must be specified for the trigger.');
+    }
+
+    const whenClauses = Object.fromEntries(
+      Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`])
+    );
+
+    /**
+     * Allow specifying the View name as the source.
+     * We can lookup the internal table name from the schema.
+     */
+    const sourceDefinition = this.schema.tables.find((table) => table.viewName == source);
+    if (!sourceDefinition) {
+      throw new Error(`Source table or view "${source}" not found in the schema.`);
+    }
+
+    const replicatedColumns = columns ?? sourceDefinition.columns.map((col) => col.name);
+
+    const internalSource = sourceDefinition.internalName;
+    const triggerIds: string[] = [];
+
+    const id = await this.getUUID();
+
+    /**
+     * We default to replicating all columns if no columns array is provided.
+     */
+    const jsonFragment = (source: 'NEW' | 'OLD' = 'NEW') => {
+      if (columns == null) {
+        // Track all columns
+        return `${source}.data`;
+      } else if (columns.length == 0) {
+        // Don't track any columns except for the id
+        return `'{}'`;
+      } else {
+        // Filter the data by the replicated columns
+        return `json_object(${replicatedColumns.map((col) => `'${col}', json_extract(${source}.data, '$.${col}')`).join(', ')})`;
+      }
+    };
+
+    const disposeWarningListener = this.db.registerListener({
+      schemaChanged: () => {
+        this.db.logger.warn(
+          `The PowerSync schema has changed while previously configured triggers are still operational. This might cause unexpected results.`
+        );
+      }
+    });
+
+    /**
+     * Declare the cleanup function early since if any of the init steps fail,
+     * we need to ensure we can cleanup the created resources.
+     * We unfortunately cannot rely on transaction rollback.
+     */
+    const cleanup = async () => {
+      disposeWarningListener();
+      return this.db.writeLock(async (tx) => {
+        await this.removeTriggers(tx, triggerIds);
+        await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+      });
+    };
+
+    const setup = async (tx: LockContext) => {
+      // 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} (
+          operation_id INTEGER PRIMARY KEY AUTOINCREMENT,
+          id TEXT,
+          operation TEXT,
+          timestamp TEXT,
+          value TEXT,
+          previous_value TEXT
+        );
+      `);
+
+      if (operations.includes(DiffTriggerOperation.INSERT)) {
+        const insertTriggerId = `ps_temp_trigger_insert_${id}`;
+        triggerIds.push(insertTriggerId);
+
+        await tx.execute(/* sql */ `
+          CREATE TEMP TRIGGER ${insertTriggerId} AFTER INSERT ON ${internalSource} ${whenClauses[
+            DiffTriggerOperation.INSERT
+          ]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value)
+          VALUES
+            (
+              NEW.id,
+              'INSERT',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('NEW')}
+            );
+
+          END;
+        `);
+      }
+
+      if (operations.includes(DiffTriggerOperation.UPDATE)) {
+        const updateTriggerId = `ps_temp_trigger_update_${id}`;
+        triggerIds.push(updateTriggerId);
+
+        await tx.execute(/* sql */ `
+          CREATE TEMP TRIGGER ${updateTriggerId} AFTER
+          UPDATE ON ${internalSource} ${whenClauses[DiffTriggerOperation.UPDATE]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value, previous_value)
+          VALUES
+            (
+              NEW.id,
+              'UPDATE',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('NEW')},
+              ${jsonFragment('OLD')}
+            );
+
+          END;
+        `);
+      }
+
+      if (operations.includes(DiffTriggerOperation.DELETE)) {
+        const deleteTriggerId = `ps_temp_trigger_delete_${id}`;
+        triggerIds.push(deleteTriggerId);
+
+        // Create delete trigger for basic JSON
+        await tx.execute(/* sql */ `
+          CREATE TEMP TRIGGER ${deleteTriggerId} AFTER DELETE ON ${internalSource} ${whenClauses[
+            DiffTriggerOperation.DELETE
+          ]} BEGIN
+          INSERT INTO
+            ${destination} (id, operation, timestamp, value)
+          VALUES
+            (
+              OLD.id,
+              'DELETE',
+              strftime ('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              ${jsonFragment('OLD')}
+            );
+
+          END;
+        `);
+      }
+    };
+
+    try {
+      await this.db.writeLock(setup);
+      return cleanup;
+    } catch (error) {
+      try {
+        await cleanup();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
+      }
+      throw error;
+    }
+  }
+
+  async trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback> {
+    const { source, when, columns, hooks, throttleMs = DEFAULT_WATCH_THROTTLE_MS } = options;
+
+    await this.db.waitForReady();
+
+    /**
+     * Allow specifying the View name as the source.
+     * We can lookup the internal table name from the schema.
+     */
+    const sourceDefinition = this.schema.tables.find((table) => table.viewName == source);
+    if (!sourceDefinition) {
+      throw new Error(`Source table or view "${source}" not found in the schema.`);
+    }
+
+    // The columns to present in the onChange context methods.
+    // 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}`;
+
+    // register an onChange before the trigger is created
+    const abortController = new AbortController();
+    const abortOnChange = () => abortController.abort();
+    this.db.onChange(
+      {
+        // Note that the onChange events here have their execution scheduled.
+        // Callbacks are throttled and are sequential.
+        onChange: async () => {
+          if (abortController.signal.aborted) return;
+
+          // Run the handler in a write lock to keep the state of the
+          // destination table consistent.
+          await this.db.writeTransaction(async (tx) => {
+            const callbackResult = await options.onChange({
+              ...tx,
+              destinationTable: destination,
+              withDiff: async <T>(query, params, options?: WithDiffOptions) => {
+                // Wrap the query to expose the destination table
+                const operationIdSelect = options?.castOperationIdAsText
+                  ? 'id, operation, CAST(operation_id AS TEXT) as operation_id, timestamp, value, previous_value'
+                  : '*';
+                const wrappedQuery = /* sql */ `
+                  WITH
+                    DIFF AS (
+                      SELECT
+                        ${operationIdSelect}
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        operation_id ASC
+                    ) ${query}
+                `;
+                return tx.getAll<T>(wrappedQuery, params);
+              },
+              withExtractedDiff: async <T>(query, params) => {
+                // Wrap the query to expose the destination table
+                const wrappedQuery = /* sql */ `
+                  WITH
+                    DIFF AS (
+                      SELECT
+                        id,
+                        ${contextColumns.length > 0
+                    ? `${contextColumns.map((col) => `json_extract(value, '$.${col}') as ${col}`).join(', ')},`
+                    : ''} operation_id as __operation_id,
+                        operation as __operation,
+                        timestamp as __timestamp,
+                        previous_value as __previous_value
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        __operation_id ASC
+                    ) ${query}
+                `;
+                return tx.getAll<T>(wrappedQuery, params);
+              }
+            });
+
+            // Clear the destination table after processing
+            await tx.execute(/* sql */ `DELETE FROM ${destination};`);
+            return callbackResult;
+          });
+        }
+      },
+      { tables: [destination], signal: abortController.signal, throttleMs }
+    );
+
+    try {
+      const removeTrigger = await this.createDiffTrigger({
+        source,
+        destination,
+        columns: contextColumns,
+        when,
+        hooks
+      });
+
+      return async () => {
+        abortOnChange();
+        await removeTrigger();
+      };
+    } catch (error) {
+      try {
+        abortOnChange();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
+      }
+      throw error;
+    }
+  }
+}

package/src/client/triggers/sanitizeSQL.ts

@@ -0,0 +1,66 @@
+function sanitizeString(input: string): string {
+  return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export function sanitizeUUID(uuid: string): string {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  const isValid = uuidRegex.test(uuid);
+  if (!isValid) {
+    throw new Error(`${uuid} is not a valid UUID`);
+  }
+  return uuid;
+}
+
+/**
+ * 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''
+ * ```
+ */
+export function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string {
+  let result = '';
+  strings.forEach((str, i) => {
+    result += str;
+    if (i < values.length) {
+      // For SQL, escape single quotes in string values
+      const value = values[i];
+      if (typeof value == 'string') {
+        result += sanitizeString(value);
+      } else if (value == null) {
+        result += 'NULL';
+      } else if (typeof value == 'object') {
+        // Stringify the object and escape single quotes in the result
+        const stringified = JSON.stringify(value);
+        result += sanitizeString(stringified);
+      } else {
+        result += value;
+      }
+    }
+  });
+  return result;
+}

package/src/client/watched/GetAllQuery.ts

@@ -0,0 +1,46 @@
+import { CompiledQuery } from '../../types/types.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { WatchCompatibleQuery } from './WatchedQuery.js';
+
+/**
+ * Options for {@link GetAllQuery}.
+ */
+export type GetAllQueryOptions<RowType = unknown> = {
+  sql: string;
+  parameters?: ReadonlyArray<unknown>;
+  /**
+   * Optional mapper function to convert raw rows into the desired RowType.
+   * @example
+   * ```javascript
+   * (rawRow) => ({
+   *   id: rawRow.id,
+   *   created_at: new Date(rawRow.created_at),
+   * })
+   * ```
+   */
+  mapper?: (rawRow: Record<string, unknown>) => RowType;
+};
+
+/**
+ * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ */
+export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowType[]> {
+  constructor(protected options: GetAllQueryOptions<RowType>) {}
+
+  compile(): CompiledQuery {
+    return {
+      sql: this.options.sql,
+      parameters: this.options.parameters ?? []
+    };
+  }
+
+  async execute(options: { db: AbstractPowerSyncDatabase }): Promise<RowType[]> {
+    const { db } = options;
+    const { sql, parameters = [] } = this.compile();
+    const rawResult = await db.getAll<unknown>(sql, [...parameters]);
+    if (this.options.mapper) {
+      return rawResult.map(this.options.mapper);
+    }
+    return rawResult as RowType[];
+  }
+}

package/src/client/watched/WatchedQuery.ts

@@ -0,0 +1,121 @@
+import { CompiledQuery } from '../../types/types.js';
+import { BaseListener } from '../../utils/BaseObserver.js';
+import { MetaBaseObserverInterface } from '../../utils/MetaBaseObserver.js';
+import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+
+/**
+ * State for {@link WatchedQuery} instances.
+ */
+export interface WatchedQueryState<Data> {
+  /**
+   * Indicates the initial loading state (hard loading).
+   * Loading becomes false once the first set of results from the watched query is available or an error occurs.
+   */
+  readonly isLoading: boolean;
+  /**
+   * Indicates whether the query is currently fetching data, is true during the initial load
+   * and any time when the query is re-evaluating (useful for large queries).
+   */
+  readonly isFetching: boolean;
+  /**
+   * The last error that occurred while executing the query.
+   */
+  readonly error: Error | null;
+  /**
+   * The last time the query was updated.
+   */
+  readonly lastUpdated: Date | null;
+  /**
+   * The last data returned by the query.
+   */
+  readonly data: Data;
+}
+
+/**
+ * Options provided to the `execute` method of a {@link WatchCompatibleQuery}.
+ */
+export interface WatchExecuteOptions {
+  sql: string;
+  parameters: any[];
+  db: AbstractPowerSyncDatabase;
+}
+
+/**
+ * Similar to {@link CompatibleQuery}, except the `execute` method
+ * does not enforce an Array result type.
+ */
+export interface WatchCompatibleQuery<ResultType> {
+  execute(options: WatchExecuteOptions): Promise<ResultType>;
+  compile(): CompiledQuery;
+}
+
+export interface WatchedQueryOptions {
+  /** The minimum interval between queries. */
+  throttleMs?: number;
+  /**
+   * If true (default) the watched query will update its state to report
+   * on the fetching state of the query.
+   * Setting to false reduces the number of state changes if the fetch status
+   * is not relevant to the consumer.
+   */
+  reportFetching?: boolean;
+
+  /**
+   * By default, watched queries requery the database on any change to any dependent table of the query.
+   * Supplying an override here can be used to limit the tables which trigger querying the database.
+   */
+  triggerOnTables?: string[];
+}
+
+export enum WatchedQueryListenerEvent {
+  ON_DATA = 'onData',
+  ON_ERROR = 'onError',
+  ON_STATE_CHANGE = 'onStateChange',
+  SETTINGS_WILL_UPDATE = 'settingsWillUpdate',
+  CLOSED = 'closed'
+}
+
+export interface WatchedQueryListener<Data> extends BaseListener {
+  [WatchedQueryListenerEvent.ON_DATA]?: (data: Data) => void | Promise<void>;
+  [WatchedQueryListenerEvent.ON_ERROR]?: (error: Error) => void | Promise<void>;
+  [WatchedQueryListenerEvent.ON_STATE_CHANGE]?: (state: WatchedQueryState<Data>) => void | Promise<void>;
+  [WatchedQueryListenerEvent.SETTINGS_WILL_UPDATE]?: () => void;
+  [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
+}
+
+export const DEFAULT_WATCH_THROTTLE_MS = 30;
+
+export const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions = {
+  throttleMs: DEFAULT_WATCH_THROTTLE_MS,
+  reportFetching: true
+};
+
+export interface WatchedQuery<
+  Data = unknown,
+  Settings extends WatchedQueryOptions = WatchedQueryOptions,
+  Listener extends WatchedQueryListener<Data> = WatchedQueryListener<Data>
+> extends MetaBaseObserverInterface<Listener> {
+  /**
+   * Current state of the watched query.
+   */
+  readonly state: WatchedQueryState<Data>;
+
+  readonly closed: boolean;
+
+  /**
+   * Subscribe to watched query events.
+   * @returns A function to unsubscribe from the events.
+   */
+  registerListener(listener: Listener): () => void;
+
+  /**
+   * Updates the underlying query options.
+   * This will trigger a re-evaluation of the query and update the state.
+   */
+  updateSettings(options: Settings): Promise<void>;
+
+  /**
+   * Close the watched query and end all subscriptions.
+   */
+  close(): Promise<void>;
+}