@powersync/common 0.0.0-dev-20260503073249 → 0.0.0-dev-20260630141119

package/src/client/triggers/TriggerManagerImpl.ts

@@ -1,496 +0,0 @@
-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,
-  TriggerManagerConfig,
-  TriggerRemoveCallback,
-  TriggerRemoveCallbackOptions,
-  WithDiffOptions
-} from './TriggerManager.js';
-
-export type TriggerManagerImplOptions = TriggerManagerConfig & {
-  db: AbstractPowerSyncDatabase;
-  schema: Schema;
-};
-
-export type TriggerManagerImplConfiguration = {
-  useStorageByDefault: boolean;
-};
-
-export const DEFAULT_TRIGGER_MANAGER_CONFIGURATION: TriggerManagerImplConfiguration = {
-  useStorageByDefault: false
-};
-
-/**
- * A record of persisted table/trigger information.
- * This is used for fail-safe cleanup.
- */
-type TrackedTableRecord = {
-  /**
-   * The id of the trigger. This is used in the SQLite trigger name
-   */
-  id: string;
-  /**
-   * The destination table name for the trigger
-   */
-  table: string;
-  /**
-   * Array of actual trigger names found for this table/id combo
-   */
-  triggerNames: string[];
-};
-
-const TRIGGER_CLEANUP_INTERVAL_MS = 120_000; // 2 minutes
-
-/**
- * @internal
- * @experimental
- */
-export class TriggerManagerImpl implements TriggerManager {
-  protected schema: Schema;
-
-  protected defaultConfig: TriggerManagerImplConfiguration;
-  protected cleanupTimeout: ReturnType<typeof setTimeout> | null;
-  protected isDisposed: boolean;
-
-  constructor(protected options: TriggerManagerImplOptions) {
-    this.schema = options.schema;
-    options.db.registerListener({
-      schemaChanged: (schema) => {
-        this.schema = schema;
-      }
-    });
-    this.isDisposed = false;
-
-    /**
-     * Configure a cleanup to run on an interval.
-     * The interval is configured using setTimeout to take the async
-     * execution time of the callback into account.
-     */
-    this.defaultConfig = DEFAULT_TRIGGER_MANAGER_CONFIGURATION;
-    const cleanupCallback = async () => {
-      this.cleanupTimeout = null;
-      if (this.isDisposed) {
-        return;
-      }
-      try {
-        await this.cleanupResources();
-      } catch (ex) {
-        this.db.logger.error(`Caught error while attempting to cleanup triggers`, ex);
-      } finally {
-        // if not closed, set another timeout
-        if (this.isDisposed) {
-          return;
-        }
-        this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
-      }
-    };
-    this.cleanupTimeout = setTimeout(cleanupCallback, TRIGGER_CLEANUP_INTERVAL_MS);
-  }
-
-  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}; `);
-    }
-  }
-
-  dispose() {
-    this.isDisposed = true;
-    if (this.cleanupTimeout) {
-      clearTimeout(this.cleanupTimeout);
-    }
-  }
-
-  /**
-   * Updates default config settings for platform specific use-cases.
-   */
-  updateDefaults(config: TriggerManagerImplConfiguration) {
-    this.defaultConfig = {
-      ...this.defaultConfig,
-      ...config
-    };
-  }
-
-  protected generateTriggerName(operation: DiffTriggerOperation, destinationTable: string, triggerId: string) {
-    return `__ps_temp_trigger_${operation.toLowerCase()}__${destinationTable}__${triggerId}`;
-  }
-
-  /**
-   * Cleanup any SQLite triggers or tables that are no longer in use.
-   */
-  async cleanupResources() {
-    // we use the database here since cleanupResources is called during the PowerSyncDatabase initialization
-    await this.db.database.writeLock(async (ctx) => {
-      /**
-       * Note: We only cleanup persisted triggers. These are tracked in the sqlite_master table.
-       * temporary triggers will not be affected by this.
-       * Query all triggers that match our naming pattern
-       */
-      const triggers = await ctx.getAll<{ name: string }>(/* sql */ `
-        SELECT
-          name
-        FROM
-          sqlite_master
-        WHERE
-          type = 'trigger'
-          AND name LIKE '__ps_temp_trigger_%'
-      `);
-
-      /** Use regex to extract table names and IDs from trigger names
-       * Trigger naming convention: __ps_temp_trigger_<operation>__<destination_table>__<id>
-       */
-      const triggerPattern = /^__ps_temp_trigger_(?:insert|update|delete)__(.+)__([a-f0-9_]{36})$/i;
-      const trackedItems = new Map<string, TrackedTableRecord>();
-
-      for (const trigger of triggers) {
-        const match = trigger.name.match(triggerPattern);
-        if (match) {
-          const [, table, id] = match;
-          // Collect all trigger names for each id combo
-          const existing = trackedItems.get(id);
-          if (existing) {
-            existing.triggerNames.push(trigger.name);
-          } else {
-            trackedItems.set(id, { table, id, triggerNames: [trigger.name] });
-          }
-        }
-      }
-
-      for (const trackedItem of trackedItems.values()) {
-        // check if there is anything holding on to this item
-        const hasClaim = await this.options.claimManager.checkClaim(trackedItem.id);
-        if (hasClaim) {
-          // This does not require cleanup
-          continue;
-        }
-
-        this.db.logger.debug(`Clearing resources for trigger ${trackedItem.id} with table ${trackedItem.table}`);
-
-        // We need to delete the triggers and table
-        for (const triggerName of trackedItem.triggerNames) {
-          await ctx.execute(`DROP TRIGGER IF EXISTS ${triggerName}`);
-        }
-        await ctx.execute(`DROP TABLE IF EXISTS ${trackedItem.table}`);
-      }
-    });
-  }
-
-  async createDiffTrigger(options: CreateDiffTriggerOptions) {
-    await this.db.waitForReady();
-    const {
-      source,
-      destination,
-      columns,
-      when,
-      hooks,
-      setupContext,
-      // Fall back to the provided default if not given on this level
-      useStorage = this.defaultConfig.useStorageByDefault
-    } = 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.');
-    }
-
-    /**
-     * The clause to use when executing
-     * CREATE ${tableTriggerTypeClause} TABLE
-     * OR
-     * CREATE ${tableTriggerTypeClause} TRIGGER
-     */
-    const tableTriggerTypeClause = !useStorage ? 'TEMP' : '';
-
-    const whenClauses = Object.fromEntries(
-      Object.entries(when).map(([operation, filter]) => [operation, `WHEN ${filter}`])
-    );
-
-    /**
-     * Allow specifying the View name as the source.
-     * 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();
-
-    const releaseStorageClaim = useStorage ? await this.options.claimManager.obtainClaim(id) : null;
-
-    /**
-     * 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 (options?: TriggerRemoveCallbackOptions) => {
-      const { context } = options ?? {};
-      disposeWarningListener();
-      const doCleanup = async (tx: LockContext) => {
-        await this.removeTriggers(tx, triggerIds);
-        await tx.execute(`DROP TABLE IF EXISTS ${destination};`);
-        await releaseStorageClaim?.();
-      };
-      if (context) {
-        await doCleanup(context);
-      } else {
-        await this.db.writeLock(doCleanup);
-      }
-    };
-
-    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 ${tableTriggerTypeClause} 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 = this.generateTriggerName(DiffTriggerOperation.INSERT, destination, id);
-        triggerIds.push(insertTriggerId);
-
-        await tx.execute(/* sql */ `
-          CREATE ${tableTriggerTypeClause} 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 = this.generateTriggerName(DiffTriggerOperation.UPDATE, destination, id);
-        triggerIds.push(updateTriggerId);
-
-        await tx.execute(/* sql */ `
-          CREATE ${tableTriggerTypeClause} 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 = this.generateTriggerName(DiffTriggerOperation.DELETE, destination, id);
-        triggerIds.push(deleteTriggerId);
-
-        // Create delete trigger for basic JSON
-        await tx.execute(/* sql */ `
-          CREATE ${tableTriggerTypeClause} 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 {
-      if (setupContext) {
-        await setup(setupContext);
-      } else {
-        await this.db.writeLock(setup);
-      }
-      return cleanup;
-    } catch (error) {
-      try {
-        await cleanup(setupContext ? { context: setupContext } : undefined);
-      } 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;
-    }
-  }
-}