@powersync/common 1.34.0 → 1.36.0

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/index.d.ts

@@ -29,8 +29,16 @@ export * from './db/schema/IndexedColumn.js';
 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/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
 export * from './utils/DataStream.js';
 export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';

package/lib/index.js

@@ -29,8 +29,16 @@ export * from './db/schema/IndexedColumn.js';
 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/watched/GetAllQuery.js';
+export * from './client/watched/processors/AbstractQueryProcessor.js';
+export * from './client/watched/processors/comparators.js';
+export * from './client/watched/processors/DifferentialQueryProcessor.js';
+export * from './client/watched/processors/OnChangeQueryProcessor.js';
+export * from './client/watched/WatchedQuery.js';
 export * from './utils/AbortOperation.js';
 export * from './utils/BaseObserver.js';
+export * from './utils/ControlledExecutor.js';
 export * from './utils/DataStream.js';
 export * from './utils/Logger.js';
 export * from './utils/parseQuery.js';

package/lib/utils/BaseObserver.d.ts

@@ -1,15 +1,14 @@
 export interface Disposable {
-    dispose: () => Promise<void>;
+    dispose: () => Promise<void> | void;
 }
+export type BaseListener = Record<string, ((...event: any) => any) | undefined>;
 export interface BaseObserverInterface<T extends BaseListener> {
     registerListener(listener: Partial<T>): () => void;
 }
-export type BaseListener = {
-    [key: string]: ((...event: any) => any) | undefined;
-};
 export declare class BaseObserver<T extends BaseListener = BaseListener> implements BaseObserverInterface<T> {
     protected listeners: Set<Partial<T>>;
     constructor();
+    dispose(): void;
     /**
      * Register a listener for updates to the PowerSync client.
      */

package/lib/utils/BaseObserver.js

@@ -1,6 +1,9 @@
 export class BaseObserver {
     listeners = new Set();
     constructor() { }
+    dispose() {
+        this.listeners.clear();
+    }
     /**
      * Register a listener for updates to the PowerSync client.
      */

package/lib/utils/MetaBaseObserver.d.ts

@@ -0,0 +1,29 @@
+import { BaseListener, BaseObserver, BaseObserverInterface } from './BaseObserver.js';
+/**
+ * Represents the counts of listeners for each event type in a BaseListener.
+ */
+export type ListenerCounts<Listener extends BaseListener> = Partial<Record<keyof Listener, number>> & {
+    total: number;
+};
+/**
+ * Meta listener which reports the counts of listeners for each event type.
+ */
+export interface MetaListener<ParentListener extends BaseListener> extends BaseListener {
+    listenersChanged?: (counts: ListenerCounts<ParentListener>) => void;
+}
+export interface ListenerMetaManager<Listener extends BaseListener> extends BaseObserverInterface<MetaListener<Listener>> {
+    counts: ListenerCounts<Listener>;
+}
+export interface MetaBaseObserverInterface<Listener extends BaseListener> extends BaseObserverInterface<Listener> {
+    listenerMeta: ListenerMetaManager<Listener>;
+}
+/**
+ * A BaseObserver that tracks the counts of listeners for each event type.
+ */
+export declare class MetaBaseObserver<Listener extends BaseListener> extends BaseObserver<Listener> implements MetaBaseObserverInterface<Listener> {
+    protected get listenerCounts(): ListenerCounts<Listener>;
+    get listenerMeta(): ListenerMetaManager<Listener>;
+    protected metaListener: BaseObserver<MetaListener<Listener>>;
+    constructor();
+    registerListener(listener: Partial<Listener>): () => void;
+}

package/lib/utils/MetaBaseObserver.js

@@ -0,0 +1,50 @@
+import { BaseObserver } from './BaseObserver.js';
+/**
+ * A BaseObserver that tracks the counts of listeners for each event type.
+ */
+export class MetaBaseObserver extends BaseObserver {
+    get listenerCounts() {
+        const counts = {};
+        let total = 0;
+        for (const listener of this.listeners) {
+            for (const key in listener) {
+                if (listener[key]) {
+                    counts[key] = (counts[key] ?? 0) + 1;
+                    total++;
+                }
+            }
+        }
+        return {
+            ...counts,
+            total
+        };
+    }
+    get listenerMeta() {
+        return {
+            counts: this.listenerCounts,
+            // Allows registering a meta listener that will be notified of changes in listener counts
+            registerListener: (listener) => {
+                return this.metaListener.registerListener(listener);
+            }
+        };
+    }
+    metaListener;
+    constructor() {
+        super();
+        this.metaListener = new BaseObserver();
+    }
+    registerListener(listener) {
+        const dispose = super.registerListener(listener);
+        const updatedCount = this.listenerCounts;
+        this.metaListener.iterateListeners((l) => {
+            l.listenersChanged?.(updatedCount);
+        });
+        return () => {
+            dispose();
+            const updatedCount = this.listenerCounts;
+            this.metaListener.iterateListeners((l) => {
+                l.listenersChanged?.(updatedCount);
+            });
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.34.0",
+  "version": "1.36.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -12,10 +12,14 @@
   "types": "lib/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/bundle.mjs",
-      "require": "./dist/bundle.cjs",
-      "types": "./lib/index.d.ts",
-      "default": "./dist/bundle.mjs"
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./dist/bundle.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "require": "./dist/bundle.cjs"
+      }
     }
   },
   "author": "JOURNEYAPPS",
@@ -57,7 +61,8 @@
   "scripts": {
     "build": "tsc -b && rollup -c rollup.config.mjs",
     "build:prod": "tsc -b --sourceMap false && rollup -c rollup.config.mjs --sourceMap false",
-    "clean": "rm -rf lib dist tsconfig.tsbuildinfo node_modules",
-    "test": "vitest"
+    "clean": "rm -rf lib dist tsconfig.tsbuildinfo",
+    "test": "vitest",
+    "test:exports": "attw --pack ."
   }
 }