@powersync/common 1.33.2 → 1.35.0

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

@@ -0,0 +1,135 @@
+import { MetaBaseObserver } from '../../../utils/MetaBaseObserver.js';
+/**
+ * Performs underlying watching and yields a stream of results.
+ * @internal
+ */
+export class AbstractQueryProcessor extends MetaBaseObserver {
+    options;
+    state;
+    abortController;
+    initialized;
+    _closed;
+    disposeListeners;
+    get closed() {
+        return this._closed;
+    }
+    constructor(options) {
+        super();
+        this.options = options;
+        this.abortController = new AbortController();
+        this._closed = false;
+        this.state = this.constructInitialState();
+        this.disposeListeners = null;
+        this.initialized = this.init();
+    }
+    constructInitialState() {
+        return {
+            isLoading: true,
+            isFetching: this.reportFetching, // Only set to true if we will report updates in future
+            error: null,
+            lastUpdated: null,
+            data: this.options.placeholderData
+        };
+    }
+    get reportFetching() {
+        return this.options.watchOptions.reportFetching ?? true;
+    }
+    /**
+     * Updates the underlying query.
+     */
+    async updateSettings(settings) {
+        await this.initialized;
+        if (!this.state.isFetching && this.reportFetching) {
+            await this.updateState({
+                isFetching: true
+            });
+        }
+        this.options.watchOptions = settings;
+        this.abortController.abort();
+        this.abortController = new AbortController();
+        await this.runWithReporting(() => this.linkQuery({
+            abortSignal: this.abortController.signal,
+            settings
+        }));
+    }
+    async updateState(update) {
+        if (typeof update.error !== 'undefined') {
+            await this.iterateAsyncListenersWithError(async (l) => l.onError?.(update.error));
+            // An error always stops for the current fetching state
+            update.isFetching = false;
+            update.isLoading = false;
+        }
+        Object.assign(this.state, { lastUpdated: new Date() }, update);
+        if (typeof update.data !== 'undefined') {
+            await this.iterateAsyncListenersWithError(async (l) => l.onData?.(this.state.data));
+        }
+        await this.iterateAsyncListenersWithError(async (l) => l.onStateChange?.(this.state));
+    }
+    /**
+     * Configures base DB listeners and links the query to listeners.
+     */
+    async init() {
+        const { db } = this.options;
+        const disposeCloseListener = db.registerListener({
+            closing: async () => {
+                await this.close();
+            }
+        });
+        // Wait for the schema to be set before listening to changes
+        await db.waitForReady();
+        const disposeSchemaListener = db.registerListener({
+            schemaChanged: async () => {
+                await this.runWithReporting(async () => {
+                    await this.updateSettings(this.options.watchOptions);
+                });
+            }
+        });
+        this.disposeListeners = () => {
+            disposeCloseListener();
+            disposeSchemaListener();
+        };
+        // Initial setup
+        this.runWithReporting(async () => {
+            await this.updateSettings(this.options.watchOptions);
+        });
+    }
+    async close() {
+        await this.initialized;
+        this.abortController.abort();
+        this.disposeListeners?.();
+        this.disposeListeners = null;
+        this._closed = true;
+        this.iterateListeners((l) => l.closed?.());
+        this.listeners.clear();
+    }
+    /**
+     * Runs a callback and reports errors to the error listeners.
+     */
+    async runWithReporting(callback) {
+        try {
+            await callback();
+        }
+        catch (error) {
+            // This will update the error on the state and iterate error listeners
+            await this.updateState({ error });
+        }
+    }
+    /**
+     * Iterate listeners and reports errors to onError handlers.
+     */
+    async iterateAsyncListenersWithError(callback) {
+        try {
+            await this.iterateAsyncListeners(async (l) => callback(l));
+        }
+        catch (error) {
+            try {
+                await this.iterateAsyncListeners(async (l) => l.onError?.(error));
+            }
+            catch (error) {
+                // Errors here are ignored
+                // since we are already in an error state
+                this.options.db.logger.error('Watched query error handler threw an Error', error);
+            }
+        }
+    }
+}

package/lib/client/watched/processors/DifferentialQueryProcessor.d.ts

@@ -0,0 +1,121 @@
+import { WatchCompatibleQuery, WatchedQuery, WatchedQueryListener, WatchedQueryOptions } from '../WatchedQuery.js';
+import { AbstractQueryProcessor, AbstractQueryProcessorOptions, LinkQueryOptions } from './AbstractQueryProcessor.js';
+/**
+ * Represents an updated row in a differential watched query.
+ * It contains both the current and previous state of the row.
+ */
+export interface WatchedQueryRowDifferential<RowType> {
+    readonly current: RowType;
+    readonly previous: RowType;
+}
+/**
+ * Represents the result of a watched query that has been diffed.
+ * {@link DifferentialWatchedQueryState#diff} is of the {@link WatchedQueryDifferential} form.
+ */
+export interface WatchedQueryDifferential<RowType> {
+    readonly added: ReadonlyArray<Readonly<RowType>>;
+    /**
+     * The entire current result set.
+     * Array item object references are preserved between updates if the item is unchanged.
+     *
+     * e.g. In the query
+     * ```sql
+     *  SELECT name, make FROM assets ORDER BY make ASC;
+     * ```
+     *
+     * If a previous result set contains an item (A) `{name: 'pc', make: 'Cool PC'}` and
+     * an update has been made which adds another item (B) to the result set (the item A is unchanged) - then
+     * the updated result set will be contain the same object reference, to item A, as the previous result set.
+     * This is regardless of the item A's position in the updated result set.
+     */
+    readonly all: ReadonlyArray<Readonly<RowType>>;
+    readonly removed: ReadonlyArray<Readonly<RowType>>;
+    readonly updated: ReadonlyArray<WatchedQueryRowDifferential<Readonly<RowType>>>;
+    readonly unchanged: ReadonlyArray<Readonly<RowType>>;
+}
+/**
+ * Row comparator for differentially watched queries which keys and compares items in the result set.
+ */
+export interface DifferentialWatchedQueryComparator<RowType> {
+    /**
+     * Generates a unique key for the item.
+     */
+    keyBy: (item: RowType) => string;
+    /**
+     * Generates a token for comparing items with matching keys.
+     */
+    compareBy: (item: RowType) => string;
+}
+/**
+ * Options for building a differential watched query with the {@link Query} builder.
+ */
+export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOptions {
+    /**
+     * Initial result data which is presented while the initial loading is executing.
+     */
+    placeholderData?: RowType[];
+    /**
+     * Row comparator used to identify and compare rows in the result set.
+     * If not provided, the default comparator will be used which keys items by their `id` property if available,
+     * otherwise it uses JSON stringification of the entire item for keying and comparison.
+     * @defaultValue {@link DEFAULT_ROW_COMPARATOR}
+     */
+    rowComparator?: DifferentialWatchedQueryComparator<RowType>;
+}
+/**
+ * Settings for differential incremental watched queries using.
+ */
+export interface DifferentialWatchedQuerySettings<RowType> extends DifferentialWatchedQueryOptions<RowType> {
+    /**
+     * The query here must return an array of items that can be differentiated.
+     */
+    query: WatchCompatibleQuery<RowType[]>;
+}
+export interface DifferentialWatchedQueryListener<RowType> extends WatchedQueryListener<ReadonlyArray<Readonly<RowType>>> {
+    onDiff?: (diff: WatchedQueryDifferential<RowType>) => void | Promise<void>;
+}
+export type DifferentialWatchedQuery<RowType> = WatchedQuery<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>, DifferentialWatchedQueryListener<RowType>>;
+/**
+ * @internal
+ */
+export interface DifferentialQueryProcessorOptions<RowType> extends AbstractQueryProcessorOptions<RowType[], DifferentialWatchedQuerySettings<RowType>> {
+    rowComparator?: DifferentialWatchedQueryComparator<RowType>;
+}
+type DataHashMap<RowType> = Map<string, {
+    hash: string;
+    item: RowType;
+}>;
+/**
+ * An empty differential result set.
+ * This is used as the initial state for differential incrementally watched queries.
+ */
+export declare const EMPTY_DIFFERENTIAL: {
+    added: never[];
+    all: never[];
+    removed: never[];
+    updated: never[];
+    unchanged: never[];
+};
+/**
+ * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
+ * It keys items by their `id` property if available, alternatively it uses JSON stringification
+ * of the entire item for the key and comparison.
+ */
+export declare const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any>;
+/**
+ * Uses the PowerSync onChange event to trigger watched queries.
+ * Results are emitted on every change of the relevant tables.
+ * @internal
+ */
+export declare class DifferentialQueryProcessor<RowType> extends AbstractQueryProcessor<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>> implements DifferentialWatchedQuery<RowType> {
+    protected options: DifferentialQueryProcessorOptions<RowType>;
+    protected comparator: DifferentialWatchedQueryComparator<RowType>;
+    constructor(options: DifferentialQueryProcessorOptions<RowType>);
+    protected differentiate(current: RowType[], previousMap: DataHashMap<RowType>): {
+        diff: WatchedQueryDifferential<RowType>;
+        map: DataHashMap<RowType>;
+        hasChanged: boolean;
+    };
+    protected linkQuery(options: LinkQueryOptions<WatchedQueryDifferential<RowType>>): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,166 @@
+import { AbstractQueryProcessor } from './AbstractQueryProcessor.js';
+/**
+ * An empty differential result set.
+ * This is used as the initial state for differential incrementally watched queries.
+ */
+export const EMPTY_DIFFERENTIAL = {
+    added: [],
+    all: [],
+    removed: [],
+    updated: [],
+    unchanged: []
+};
+/**
+ * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
+ * It keys items by their `id` property if available, alternatively it uses JSON stringification
+ * of the entire item for the key and comparison.
+ */
+export const DEFAULT_ROW_COMPARATOR = {
+    keyBy: (item) => {
+        if (item && typeof item == 'object' && typeof item['id'] == 'string') {
+            return item['id'];
+        }
+        return JSON.stringify(item);
+    },
+    compareBy: (item) => JSON.stringify(item)
+};
+/**
+ * Uses the PowerSync onChange event to trigger watched queries.
+ * Results are emitted on every change of the relevant tables.
+ * @internal
+ */
+export class DifferentialQueryProcessor extends AbstractQueryProcessor {
+    options;
+    comparator;
+    constructor(options) {
+        super(options);
+        this.options = options;
+        this.comparator = options.rowComparator ?? DEFAULT_ROW_COMPARATOR;
+    }
+    /*
+     * @returns If the sets are equal
+     */
+    differentiate(current, previousMap) {
+        const { keyBy, compareBy } = this.comparator;
+        let hasChanged = false;
+        const currentMap = new Map();
+        const removedTracker = new Set(previousMap.keys());
+        // Allow mutating to populate the data temporarily.
+        const diff = {
+            all: [],
+            added: [],
+            removed: [],
+            updated: [],
+            unchanged: []
+        };
+        /**
+         * Looping over the current result set array is important to preserve
+         * the ordering of the result set.
+         * We can replace items in the current array with previous object references if they are equal.
+         */
+        for (const item of current) {
+            const key = keyBy(item);
+            const hash = compareBy(item);
+            currentMap.set(key, { hash, item });
+            const previousItem = previousMap.get(key);
+            if (!previousItem) {
+                // New item
+                hasChanged = true;
+                diff.added.push(item);
+                diff.all.push(item);
+            }
+            else {
+                // Existing item
+                if (hash == previousItem.hash) {
+                    diff.unchanged.push(previousItem.item);
+                    // Use the previous object reference
+                    diff.all.push(previousItem.item);
+                    // update the map to preserve the reference
+                    currentMap.set(key, previousItem);
+                }
+                else {
+                    hasChanged = true;
+                    diff.updated.push({ current: item, previous: previousItem.item });
+                    // Use the new reference
+                    diff.all.push(item);
+                }
+            }
+            // The item is present, we don't consider it removed
+            removedTracker.delete(key);
+        }
+        diff.removed = Array.from(removedTracker).map((key) => previousMap.get(key).item);
+        hasChanged = hasChanged || diff.removed.length > 0;
+        return {
+            diff,
+            hasChanged,
+            map: currentMap
+        };
+    }
+    async linkQuery(options) {
+        const { db, watchOptions } = this.options;
+        const { abortSignal } = options;
+        const compiledQuery = watchOptions.query.compile();
+        const tables = await db.resolveTables(compiledQuery.sql, compiledQuery.parameters, {
+            tables: options.settings.triggerOnTables
+        });
+        let currentMap = new Map();
+        // populate the currentMap from the placeholder data
+        this.state.data.forEach((item) => {
+            currentMap.set(this.comparator.keyBy(item), {
+                hash: this.comparator.compareBy(item),
+                item
+            });
+        });
+        db.onChangeWithCallback({
+            onChange: async () => {
+                if (this.closed) {
+                    return;
+                }
+                // This fires for each change of the relevant tables
+                try {
+                    if (this.reportFetching && !this.state.isFetching) {
+                        await this.updateState({ isFetching: true });
+                    }
+                    const partialStateUpdate = {};
+                    // Always run the query if an underlying table has changed
+                    const result = await watchOptions.query.execute({
+                        sql: compiledQuery.sql,
+                        // Allows casting from ReadOnlyArray[unknown] to Array<unknown>
+                        // This allows simpler compatibility with PowerSync queries
+                        parameters: [...compiledQuery.parameters],
+                        db: this.options.db
+                    });
+                    if (this.reportFetching) {
+                        partialStateUpdate.isFetching = false;
+                    }
+                    if (this.state.isLoading) {
+                        partialStateUpdate.isLoading = false;
+                    }
+                    const { diff, hasChanged, map } = this.differentiate(result, currentMap);
+                    // Update for future comparisons
+                    currentMap = map;
+                    if (hasChanged) {
+                        await this.iterateAsyncListenersWithError((l) => l.onDiff?.(diff));
+                        Object.assign(partialStateUpdate, {
+                            data: diff.all
+                        });
+                    }
+                    if (Object.keys(partialStateUpdate).length > 0) {
+                        await this.updateState(partialStateUpdate);
+                    }
+                }
+                catch (error) {
+                    await this.updateState({ error });
+                }
+            },
+            onError: async (error) => {
+                await this.updateState({ error });
+            }
+        }, {
+            signal: abortSignal,
+            tables,
+            throttleMs: watchOptions.throttleMs,
+            triggerImmediate: true // used to emit the initial state
+        });
+    }
+}

package/lib/client/watched/processors/OnChangeQueryProcessor.d.ts

@@ -0,0 +1,33 @@
+import { WatchCompatibleQuery, WatchedQuery, WatchedQueryOptions } from '../WatchedQuery.js';
+import { AbstractQueryProcessor, AbstractQueryProcessorOptions, LinkQueryOptions } from './AbstractQueryProcessor.js';
+import { WatchedQueryComparator } from './comparators.js';
+/**
+ * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
+ */
+export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
+    query: WatchCompatibleQuery<DataType>;
+}
+/**
+ * {@link WatchedQuery} returned from {@link Query#watch}.
+ */
+export type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
+/**
+ * @internal
+ */
+export interface OnChangeQueryProcessorOptions<Data> extends AbstractQueryProcessorOptions<Data, WatchedQuerySettings<Data>> {
+    comparator?: WatchedQueryComparator<Data>;
+}
+/**
+ * Uses the PowerSync onChange event to trigger watched queries.
+ * Results are emitted on every change of the relevant tables.
+ * @internal
+ */
+export declare class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, WatchedQuerySettings<Data>> {
+    protected options: OnChangeQueryProcessorOptions<Data>;
+    constructor(options: OnChangeQueryProcessorOptions<Data>);
+    /**
+     * @returns If the sets are equal
+     */
+    protected checkEquality(current: Data, previous: Data): boolean;
+    protected linkQuery(options: LinkQueryOptions<Data>): Promise<void>;
+}

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

@@ -0,0 +1,76 @@
+import { AbstractQueryProcessor } from './AbstractQueryProcessor.js';
+/**
+ * Uses the PowerSync onChange event to trigger watched queries.
+ * Results are emitted on every change of the relevant tables.
+ * @internal
+ */
+export class OnChangeQueryProcessor extends AbstractQueryProcessor {
+    options;
+    constructor(options) {
+        super(options);
+        this.options = options;
+    }
+    /**
+     * @returns If the sets are equal
+     */
+    checkEquality(current, previous) {
+        // Use the provided comparator if available. Assume values are unique if not available.
+        return this.options.comparator?.checkEquality?.(current, previous) ?? false;
+    }
+    async linkQuery(options) {
+        const { db, watchOptions } = this.options;
+        const { abortSignal } = options;
+        const compiledQuery = watchOptions.query.compile();
+        const tables = await db.resolveTables(compiledQuery.sql, compiledQuery.parameters, {
+            tables: options.settings.triggerOnTables
+        });
+        db.onChangeWithCallback({
+            onChange: async () => {
+                if (this.closed) {
+                    return;
+                }
+                // This fires for each change of the relevant tables
+                try {
+                    if (this.reportFetching && !this.state.isFetching) {
+                        await this.updateState({ isFetching: true });
+                    }
+                    const partialStateUpdate = {};
+                    // Always run the query if an underlying table has changed
+                    const result = await watchOptions.query.execute({
+                        sql: compiledQuery.sql,
+                        // Allows casting from ReadOnlyArray[unknown] to Array<unknown>
+                        // This allows simpler compatibility with PowerSync queries
+                        parameters: [...compiledQuery.parameters],
+                        db: this.options.db
+                    });
+                    if (this.reportFetching) {
+                        partialStateUpdate.isFetching = false;
+                    }
+                    if (this.state.isLoading) {
+                        partialStateUpdate.isLoading = false;
+                    }
+                    // Check if the result has changed
+                    if (!this.checkEquality(result, this.state.data)) {
+                        Object.assign(partialStateUpdate, {
+                            data: result
+                        });
+                    }
+                    if (Object.keys(partialStateUpdate).length > 0) {
+                        await this.updateState(partialStateUpdate);
+                    }
+                }
+                catch (error) {
+                    await this.updateState({ error });
+                }
+            },
+            onError: async (error) => {
+                await this.updateState({ error });
+            }
+        }, {
+            signal: abortSignal,
+            tables,
+            throttleMs: watchOptions.throttleMs,
+            triggerImmediate: true // used to emit the initial state
+        });
+    }
+}

package/lib/client/watched/processors/comparators.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A basic comparator for incrementally watched queries. This performs a single comparison which
+ * determines if the result set has changed. The {@link WatchedQuery} will only emit the new result
+ * if a change has been detected.
+ */
+export interface WatchedQueryComparator<Data> {
+    checkEquality: (current: Data, previous: Data) => boolean;
+}
+/**
+ * Options for {@link ArrayComparator}
+ */
+export type ArrayComparatorOptions<ItemType> = {
+    /**
+     * Returns a string to uniquely identify an item in the array.
+     */
+    compareBy: (item: ItemType) => string;
+};
+/**
+ * An efficient comparator for {@link WatchedQuery} created with {@link Query#watch}. This has the ability to determine if a query
+ * result has changes without necessarily processing all items in the result.
+ */
+export declare class ArrayComparator<ItemType> implements WatchedQueryComparator<ItemType[]> {
+    protected options: ArrayComparatorOptions<ItemType>;
+    constructor(options: ArrayComparatorOptions<ItemType>);
+    checkEquality(current: ItemType[], previous: ItemType[]): boolean;
+}
+/**
+ * Watched query comparator that always reports changed result sets.
+ */
+export declare const FalsyComparator: WatchedQueryComparator<unknown>;

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

@@ -0,0 +1,34 @@
+/**
+ * An efficient comparator for {@link WatchedQuery} created with {@link Query#watch}. This has the ability to determine if a query
+ * result has changes without necessarily processing all items in the result.
+ */
+export class ArrayComparator {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    checkEquality(current, previous) {
+        if (current.length === 0 && previous.length === 0) {
+            return true;
+        }
+        if (current.length !== previous.length) {
+            return false;
+        }
+        const { compareBy } = this.options;
+        // At this point the lengths are equal
+        for (let i = 0; i < current.length; i++) {
+            const currentItem = compareBy(current[i]);
+            const previousItem = compareBy(previous[i]);
+            if (currentItem !== previousItem) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+/**
+ * Watched query comparator that always reports changed result sets.
+ */
+export const FalsyComparator = {
+    checkEquality: () => false // Default comparator that always returns false
+};

package/lib/db/schema/RawTable.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A pending variant of a {@link RawTable} that doesn't have a name (because it would be inferred when creating the
+ * schema).
+ */
+export type RawTableType = {
+    /**
+     * The statement to run when PowerSync detects that a row needs to be inserted or updated.
+     */
+    put: PendingStatement;
+    /**
+     * The statement to run when PowerSync detects that a row needs to be deleted.
+     */
+    delete: PendingStatement;
+};
+/**
+ * A parameter to use as part of {@link PendingStatement}.
+ *
+ * For delete statements, only the `"Id"` value is supported - the sync client will replace it with the id of the row to
+ * be synced.
+ *
+ * For insert and replace operations, the values of columns in the table are available as parameters through
+ * `{Column: 'name'}`.
+ */
+export type PendingStatementParameter = 'Id' | {
+    Column: string;
+};
+/**
+ * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
+ */
+export type PendingStatement = {
+    sql: string;
+    params: PendingStatementParameter[];
+};
+/**
+ * Instructs PowerSync to sync data into a "raw" table.
+ *
+ * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+ * using client-side table and column constraints.
+ *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
+ * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+ *
+ * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
+ * stability guarantees.
+ */
+export declare class RawTable implements RawTableType {
+    /**
+     * The name of the table.
+     *
+     * This does not have to match the actual table name in the schema - {@link put} and {@link delete} are free to use
+     * another table. Instead, this name is used by the sync client to recognize that operations on this table (as it
+     * appears in the source / backend database) are to be handled specially.
+     */
+    name: string;
+    put: PendingStatement;
+    delete: PendingStatement;
+    constructor(name: string, type: RawTableType);
+}