@powersync/common 1.36.0 → 1.38.0

package/lib/client/triggers/TriggerManagerImpl.js

@@ -0,0 +1,265 @@
+import { DEFAULT_WATCH_THROTTLE_MS } from '../watched/WatchedQuery.js';
+import { DiffTriggerOperation } from './TriggerManager.js';
+export class TriggerManagerImpl {
+    options;
+    schema;
+    constructor(options) {
+        this.options = options;
+        this.schema = options.schema;
+        options.db.registerListener({
+            schemaChanged: (schema) => {
+                this.schema = schema;
+            }
+        });
+    }
+    get db() {
+        return this.options.db;
+    }
+    async getUUID() {
+        const { id: uuid } = await this.db.get(/* sql */ `
+      SELECT
+        uuid () as id
+    `);
+        // Replace dashes with underscores for SQLite table/trigger name compatibility
+        return uuid.replace(/-/g, '_');
+    }
+    async removeTriggers(tx, triggerIds) {
+        for (const triggerId of triggerIds) {
+            await tx.execute(/* sql */ `DROP TRIGGER IF EXISTS ${triggerId}; `);
+        }
+    }
+    async createDiffTrigger(options) {
+        await this.db.waitForReady();
+        const { source, destination, columns, when, hooks } = options;
+        const operations = Object.keys(when);
+        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 = [];
+        const id = await this.getUUID();
+        /**
+         * We default to replicating all columns if no columns array is provided.
+         */
+        const jsonFragment = (source = '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) => {
+            // 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} (
+          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) {
+        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 (query, params) => {
+                            // Wrap the query to expose the destination table
+                            const wrappedQuery = /* sql */ `
+                  WITH
+                    DIFF AS (
+                      SELECT
+                        *
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        timestamp ASC
+                    ) ${query}
+                `;
+                            return tx.getAll(wrappedQuery, params);
+                        },
+                        withExtractedDiff: async (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 as __operation,
+                        timestamp as __timestamp,
+                        previous_value as __previous_value
+                      FROM
+                        ${destination}
+                      ORDER BY
+                        __timestamp ASC
+                    ) ${query}
+                `;
+                            return tx.getAll(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/lib/client/triggers/sanitizeSQL.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export 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''
+ * ```
+ */
+export declare function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string;

package/lib/client/triggers/sanitizeSQL.js

@@ -0,0 +1,68 @@
+function sanitizeString(input) {
+    return `'${input.replace(/'/g, "''")}'`;
+}
+/**
+ * Helper function for sanitizing UUID input strings.
+ * Typically used with {@link sanitizeSQL}.
+ */
+export function sanitizeUUID(uuid) {
+    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, ...values) {
+    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/lib/client/watched/processors/AbstractQueryProcessor.js

@@ -38,6 +38,7 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
      * Updates the underlying query.
      */
     async updateSettings(settings) {
+        this.abortController.abort();
         await this.initialized;
         if (!this.state.isFetching && this.reportFetching) {
             await this.updateState({
@@ -45,7 +46,6 @@ export class AbstractQueryProcessor extends MetaBaseObserver {
             });
         }
         this.options.watchOptions = settings;
-        this.abortController.abort();
         this.abortController = new AbortController();
         await this.runWithReporting(() => this.linkQuery({
             abortSignal: this.abortController.signal,

package/lib/client/watched/processors/DifferentialQueryProcessor.js

@@ -113,7 +113,7 @@ export class DifferentialQueryProcessor extends AbstractQueryProcessor {
         });
         db.onChangeWithCallback({
             onChange: async () => {
-                if (this.closed) {
+                if (this.closed || abortSignal.aborted) {
                     return;
                 }
                 // This fires for each change of the relevant tables
@@ -130,6 +130,9 @@ export class DifferentialQueryProcessor extends AbstractQueryProcessor {
                         parameters: [...compiledQuery.parameters],
                         db: this.options.db
                     });
+                    if (abortSignal.aborted) {
+                        return;
+                    }
                     if (this.reportFetching) {
                         partialStateUpdate.isFetching = false;
                     }

package/lib/client/watched/processors/OnChangeQueryProcessor.js

@@ -26,7 +26,7 @@ export class OnChangeQueryProcessor extends AbstractQueryProcessor {
         });
         db.onChangeWithCallback({
             onChange: async () => {
-                if (this.closed) {
+                if (this.closed || abortSignal.aborted) {
                     return;
                 }
                 // This fires for each change of the relevant tables
@@ -43,6 +43,9 @@ export class OnChangeQueryProcessor extends AbstractQueryProcessor {
                         parameters: [...compiledQuery.parameters],
                         db: this.options.db
                     });
+                    if (abortSignal.aborted) {
+                        return;
+                    }
                     if (this.reportFetching) {
                         partialStateUpdate.isFetching = false;
                     }

package/lib/db/crud/SyncStatus.d.ts

@@ -1,3 +1,4 @@
+import { SyncClientImplementation } from '../../client/sync/stream/AbstractStreamingSyncImplementation.js';
 import { InternalProgressInformation, SyncProgress } from './SyncProgress.js';
 export type SyncDataFlowStatus = Partial<{
     downloading: boolean;
@@ -32,10 +33,18 @@ export type SyncStatusOptions = {
     lastSyncedAt?: Date;
     hasSynced?: boolean;
     priorityStatusEntries?: SyncPriorityStatus[];
+    clientImplementation?: SyncClientImplementation;
 };
 export declare class SyncStatus {
     protected options: SyncStatusOptions;
     constructor(options: SyncStatusOptions);
+    /**
+     * Returns the used sync client implementation (either the one implemented in JavaScript or the newer Rust-based
+     * implementation).
+     *
+     * This information is only available after a connection has been requested.
+     */
+    get clientImplementation(): SyncClientImplementation | undefined;
     /**
      * Indicates if the client is currently connected to the PowerSync service.
      *

package/lib/db/crud/SyncStatus.js

@@ -4,6 +4,15 @@ export class SyncStatus {
     constructor(options) {
         this.options = options;
     }
+    /**
+     * Returns the used sync client implementation (either the one implemented in JavaScript or the newer Rust-based
+     * implementation).
+     *
+     * This information is only available after a connection has been requested.
+     */
+    get clientImplementation() {
+        return this.options.clientImplementation;
+    }
     /**
      * Indicates if the client is currently connected to the PowerSync service.
      *

package/lib/index.d.ts

@@ -30,6 +30,8 @@ export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';
 export * from './client/Query.js';
+export * from './client/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
 export * from './client/watched/GetAllQuery.js';
 export * from './client/watched/processors/AbstractQueryProcessor.js';
 export * from './client/watched/processors/comparators.js';

package/lib/index.js

@@ -30,6 +30,8 @@ export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';
 export * from './client/Query.js';
+export * from './client/triggers/sanitizeSQL.js';
+export * from './client/triggers/TriggerManager.js';
 export * from './client/watched/GetAllQuery.js';
 export * from './client/watched/processors/AbstractQueryProcessor.js';
 export * from './client/watched/processors/comparators.js';

package/lib/utils/async.d.ts

@@ -1,3 +1,12 @@
+/**
+ * A ponyfill for `Symbol.asyncIterator` that is compatible with the
+ * [recommended polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6)
+ * we recommend for React Native.
+ *
+ * As long as we use this symbol (instead of `for await` and `async *`) in this package, we can be compatible with async
+ * iterators without requiring them.
+ */
+export declare const symbolAsyncIterator: typeof Symbol.asyncIterator;
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.

package/lib/utils/async.js

@@ -1,3 +1,12 @@
+/**
+ * A ponyfill for `Symbol.asyncIterator` that is compatible with the
+ * [recommended polyfill](https://github.com/Azure/azure-sdk-for-js/blob/%40azure/core-asynciterator-polyfill_1.0.2/sdk/core/core-asynciterator-polyfill/src/index.ts#L4-L6)
+ * we recommend for React Native.
+ *
+ * As long as we use this symbol (instead of `for await` and `async *`) in this package, we can be compatible with async
+ * iterators without requiring them.
+ */
+export const symbolAsyncIterator = Symbol.asyncIterator ?? Symbol.for('Symbol.asyncIterator');
 /**
  * Throttle a function to be called at most once every "wait" milliseconds,
  * on the trailing edge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"