@powersync/common 0.0.0-dev-20250714151300 → 0.0.0-dev-20250715104704

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

@@ -1,129 +0,0 @@
-import { WatchCompatibleQuery, WatchedQuery, WatchedQueryListener, WatchedQueryOptions, WatchedQueryState } 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>>;
-}
-/**
- * Differentiator for incremental watched queries which allows to identify and compare items in the result set.
- */
-export interface WatchedQueryDifferentiator<RowType> {
-    /**
-     * Unique identifier for the item.
-     */
-    identify: (item: RowType) => string;
-    /**
-     * Generates a key for comparing items with matching identifiers.
-     */
-    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[];
-    /**
-     * Differentiator used to identify and compare items in the result set.
-     * If not provided, the default differentiator will be used which identifies items by their `id` property if available,
-     * otherwise it uses JSON stringification of the entire item for identification and comparison.
-     * @defaultValue {@link DEFAULT_WATCHED_QUERY_DIFFERENTIATOR}
-     */
-    differentiator?: WatchedQueryDifferentiator<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 DifferentialWatchedQueryState<RowType> extends WatchedQueryState<ReadonlyArray<Readonly<RowType>>> {
-    /**
-     * The difference between the current and previous result set.
-     */
-    readonly diff: WatchedQueryDifferential<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>> {
-    differentiator?: WatchedQueryDifferentiator<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 Differentiator} for watched queries.
- * It identifies items by their `id` property if available, otherwise it uses JSON stringification
- * of the entire item for identification and comparison.
- */
-export declare const DEFAULT_WATCHED_QUERY_DIFFERENTIATOR: WatchedQueryDifferentiator<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>;
-    readonly state: DifferentialWatchedQueryState<RowType>;
-    protected differentiator: WatchedQueryDifferentiator<RowType>;
-    constructor(options: DifferentialQueryProcessorOptions<RowType>);
-    protected constructInitialState(): DifferentialWatchedQueryState<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

@@ -1,175 +0,0 @@
-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 Differentiator} for watched queries.
- * It identifies items by their `id` property if available, otherwise it uses JSON stringification
- * of the entire item for identification and comparison.
- */
-export const DEFAULT_WATCHED_QUERY_DIFFERENTIATOR = {
-    identify: (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;
-    state;
-    differentiator;
-    constructor(options) {
-        super(options);
-        this.options = options;
-        this.state = this.constructInitialState();
-        this.differentiator = options.differentiator ?? DEFAULT_WATCHED_QUERY_DIFFERENTIATOR;
-    }
-    constructInitialState() {
-        return {
-            ...super.constructInitialState(),
-            diff: {
-                ...EMPTY_DIFFERENTIAL,
-                all: this.options.placeholderData
-            }
-        };
-    }
-    /*
-     * @returns If the sets are equal
-     */
-    differentiate(current, previousMap) {
-        const { identify, compareBy } = this.differentiator;
-        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 = identify(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(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);
-        let currentMap = new Map();
-        // populate the currentMap from the placeholder data
-        this.state.data.forEach((item) => {
-            currentMap.set(this.differentiator.identify(item), {
-                hash: this.differentiator.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

@@ -1,27 +0,0 @@
-import { WatchCompatibleQuery, WatchedQuery, WatchedQueryOptions } from '../WatchedQuery.js';
-import { AbstractQueryProcessor, AbstractQueryProcessorOptions, LinkQueryOptions } from './AbstractQueryProcessor.js';
-import { WatchedQueryComparator } from './comparators.js';
-export interface ComparisonWatchedQuerySettings<DataType> extends WatchedQueryOptions {
-    query: WatchCompatibleQuery<DataType>;
-}
-export type ComparisonWatchedQuery<DataType> = WatchedQuery<DataType, ComparisonWatchedQuerySettings<DataType>>;
-/**
- * @internal
- */
-export interface OnChangeQueryProcessorOptions<Data> extends AbstractQueryProcessorOptions<Data, ComparisonWatchedQuerySettings<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, ComparisonWatchedQuerySettings<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

@@ -1,74 +0,0 @@
-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);
-        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

@@ -1,24 +0,0 @@
-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;
-};
-/**
- * Compares array results of watched queries for incrementally watched queries created in the standard mode.
- */
-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

@@ -1,33 +0,0 @@
-/**
- * Compares array results of watched queries for incrementally watched queries created in the standard mode.
- */
-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/utils/MetaBaseObserver.d.ts

@@ -1,29 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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);
-            });
-        };
-    }
-}