@powersync/common 0.0.0-dev-20260202162549 → 0.0.0-dev-20260202163643

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,83 @@
+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 || abortSignal.aborted) {
+                    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 (abortSignal.aborted) {
+                        return;
+                    }
+                    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 (this.state.error) {
+                        partialStateUpdate.error = null;
+                    }
+                    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
+        });
+    }
+}
+//# sourceMappingURL=OnChangeQueryProcessor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"OnChangeQueryProcessor.js","sourceRoot":"","sources":["../../../../src/client/watched/processors/OnChangeQueryProcessor.ts"],"names":[],"mappings":"AACA,OAAO,EACL,sBAAsB,EAIvB,MAAM,6BAA6B,CAAC;AAuBrC;;;;GAIG;AACH,MAAM,OAAO,sBAA6B,SAAQ,sBAAwD;IAClF;IAAtB,YAAsB,OAA4C;QAChE,KAAK,CAAC,OAAO,CAAC,CAAC;QADK,YAAO,GAAP,OAAO,CAAqC;IAElE,CAAC;IAED;;OAEG;IACO,aAAa,CAAC,OAAa,EAAE,QAAc;QACnD,uFAAuF;QACvF,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,aAAa,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,KAAK,CAAC;IAC9E,CAAC;IAES,KAAK,CAAC,SAAS,CAAC,OAA+B;QACvD,MAAM,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC1C,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;QAEhC,MAAM,aAAa,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnD,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,aAAa,CAAC,aAAa,CAAC,GAAG,EAAE,aAAa,CAAC,UAAmB,EAAE;YAC1F,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,eAAe;SACzC,CAAC,CAAC;QAEH,EAAE,CAAC,oBAAoB,CACrB;YACE,QAAQ,EAAE,KAAK,IAAI,EAAE;gBACnB,IAAI,IAAI,CAAC,MAAM,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;oBACvC,OAAO;gBACT,CAAC;gBACD,oDAAoD;gBACpD,IAAI,CAAC;oBACH,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;wBAClD,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC/C,CAAC;oBAED,MAAM,kBAAkB,GAA8D,EAAE,CAAC;oBAEzF,0DAA0D;oBAC1D,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC;wBAC9C,GAAG,EAAE,aAAa,CAAC,GAAG;wBACtB,+DAA+D;wBAC/D,2DAA2D;wBAC3D,UAAU,EAAE,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC;wBACzC,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE;qBACpB,CAAC,CAAC;oBAEH,IAAI,WAAW,CAAC,OAAO,EAAE,CAAC;wBACxB,OAAO;oBACT,CAAC;oBAED,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;wBACxB,kBAAkB,CAAC,UAAU,GAAG,KAAK,CAAC;oBACxC,CAAC;oBAED,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;wBACzB,kBAAkB,CAAC,SAAS,GAAG,KAAK,CAAC;oBACvC,CAAC;oBAED,kCAAkC;oBAClC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;wBACjD,MAAM,CAAC,MAAM,CAAC,kBAAkB,EAAE;4BAChC,IAAI,EAAE,MAAM;yBACb,CAAC,CAAC;oBACL,CAAC;oBAED,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;wBACrB,kBAAkB,CAAC,KAAK,GAAG,IAAI,CAAC;oBAClC,CAAC;oBAED,IAAI,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBAC/C,MAAM,IAAI,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC;oBAC7C,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,MAAM,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YACpC,CAAC;SACF,EACD;YACE,MAAM,EAAE,WAAW;YACnB,MAAM;YACN,UAAU,EAAE,YAAY,CAAC,UAAU;YACnC,gBAAgB,EAAE,IAAI,CAAC,iCAAiC;SACzD,CACF,CAAC;IACJ,CAAC;CACF"}

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,35 @@
+/**
+ * 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
+};
+//# sourceMappingURL=comparators.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comparators.js","sourceRoot":"","sources":["../../../../src/client/watched/processors/comparators.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,MAAM,OAAO,eAAe;IACJ;IAAtB,YAAsB,OAAyC;QAAzC,YAAO,GAAP,OAAO,CAAkC;IAAG,CAAC;IAEnE,aAAa,CAAC,OAAmB,EAAE,QAAoB;QACrD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;YACvC,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAEnC,sCAAsC;QACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1C,MAAM,YAAY,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YAE5C,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;gBACjC,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAoC;IAC9D,aAAa,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,+CAA+C;CAC3E,CAAC"}

package/lib/db/ConnectionClosedError.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Thrown when an underlying database connection is closed.
+ * This is particularly relevant when worker connections are marked as closed while
+ * operations are still in progress.
+ */
+export declare class ConnectionClosedError extends Error {
+    static NAME: string;
+    static MATCHES(input: any): boolean;
+    constructor(message: string);
+}

package/lib/db/ConnectionClosedError.js

@@ -0,0 +1,21 @@
+/**
+ * Thrown when an underlying database connection is closed.
+ * This is particularly relevant when worker connections are marked as closed while
+ * operations are still in progress.
+ */
+export class ConnectionClosedError extends Error {
+    static NAME = 'ConnectionClosedError';
+    static MATCHES(input) {
+        /**
+         * If there are weird package issues which cause multiple versions of classes to be present, the instanceof
+         * check might fail. This also performs a failsafe check.
+         * This might also happen if the Error is serialized and parsed over a bridging channel like a MessagePort.
+         */
+        return (input instanceof ConnectionClosedError || (input instanceof Error && input.name == ConnectionClosedError.NAME));
+    }
+    constructor(message) {
+        super(message);
+        this.name = ConnectionClosedError.NAME;
+    }
+}
+//# sourceMappingURL=ConnectionClosedError.js.map

package/lib/db/ConnectionClosedError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConnectionClosedError.js","sourceRoot":"","sources":["../../src/db/ConnectionClosedError.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,MAAM,CAAC,IAAI,GAAG,uBAAuB,CAAC;IAEtC,MAAM,CAAC,OAAO,CAAC,KAAU;QACvB;;;;WAIG;QACH,OAAO,CACL,KAAK,YAAY,qBAAqB,IAAI,CAAC,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAC/G,CAAC;IACJ,CAAC;IACD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC;IACzC,CAAC"}

package/lib/db/DBAdapter.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Set of generic interfaces to allow PowerSync compatibility with
+ * different SQLite DB implementations.
+ */
+import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
+/**
+ * TODO most of these types could be exported to a common `types` package
+ * which is used by the DB adapter libraries as well.
+ */
+/**
+ * Object returned by SQL Query executions.
+ */
+export type QueryResult = {
+    /** Represents the auto-generated row id if applicable. */
+    insertId?: number;
+    /** Number of affected rows if result of a update query. */
+    rowsAffected: number;
+    /** if status is undefined or 0 this object will contain the query results */
+    rows?: {
+        /** Raw array with all dataset */
+        _array: any[];
+        /** The length of the dataset */
+        length: number;
+        /** A convenience function to acess the index based the row object
+         * @param idx the row index
+         * @returns the row structure identified by column names
+         */
+        item: (idx: number) => any;
+    };
+};
+export interface DBGetUtils {
+    /** Execute a read-only query and return results. */
+    getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
+    /** Execute a read-only query and return the first result, or null if the ResultSet is empty. */
+    getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
+    /** Execute a read-only query and return the first result, error if the ResultSet is empty. */
+    get<T>(sql: string, parameters?: any[]): Promise<T>;
+}
+export interface LockContext extends DBGetUtils {
+    /** Execute a single write statement. */
+    execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
+    /**
+     * Execute a single write statement and return raw results.
+     * Unlike `execute`, which returns an object with structured key-value pairs,
+     * `executeRaw` returns a nested array of raw values, where each row is
+     * represented as an array of column values without field names.
+     *
+     * Example result:
+     *
+     * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+     *
+     * Where as `execute`'s `rows._array` would have been:
+     *
+     * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
+     */
+    executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
+}
+export interface Transaction extends LockContext {
+    /** Commit multiple changes to the local DB using the Transaction context. */
+    commit: () => Promise<QueryResult>;
+    /** Roll back multiple attempted changes using the Transaction context. */
+    rollback: () => Promise<QueryResult>;
+}
+/**
+ * Update table operation numbers from SQLite
+ */
+export declare enum RowUpdateType {
+    SQLITE_INSERT = 18,
+    SQLITE_DELETE = 9,
+    SQLITE_UPDATE = 23
+}
+export interface TableUpdateOperation {
+    opType: RowUpdateType;
+    rowId: number;
+}
+/**
+ * Notification of an update to one or more tables, for the purpose of realtime change notifications.
+ */
+export interface UpdateNotification extends TableUpdateOperation {
+    table: string;
+}
+export interface BatchedUpdateNotification {
+    rawUpdates: UpdateNotification[];
+    tables: string[];
+    groupedUpdates: Record<string, TableUpdateOperation[]>;
+}
+export interface DBAdapterListener extends BaseListener {
+    /**
+     * Listener for table updates.
+     * Allows for single table updates in order to maintain API compatibility
+     * without the need for a major version bump
+     * The DB adapter can also batch update notifications if supported.
+     */
+    tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
+}
+export interface DBLockOptions {
+    timeoutMs?: number;
+}
+export interface DBAdapter extends BaseObserverInterface<DBAdapterListener>, DBGetUtils {
+    close: () => void | Promise<void>;
+    execute: (query: string, params?: any[]) => Promise<QueryResult>;
+    executeRaw: (query: string, params?: any[]) => Promise<any[][]>;
+    executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
+    name: string;
+    readLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+    readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+    writeLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+    writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+    /**
+     * This method refreshes the schema information across all connections. This is for advanced use cases, and should generally not be needed.
+     */
+    refreshSchema: () => Promise<void>;
+}
+export declare function isBatchedUpdateNotification(update: BatchedUpdateNotification | UpdateNotification): update is BatchedUpdateNotification;
+export declare function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification): string[];

package/lib/db/DBAdapter.js

@@ -0,0 +1,20 @@
+/**
+ * Set of generic interfaces to allow PowerSync compatibility with
+ * different SQLite DB implementations.
+ */
+/**
+ * Update table operation numbers from SQLite
+ */
+export var RowUpdateType;
+(function (RowUpdateType) {
+    RowUpdateType[RowUpdateType["SQLITE_INSERT"] = 18] = "SQLITE_INSERT";
+    RowUpdateType[RowUpdateType["SQLITE_DELETE"] = 9] = "SQLITE_DELETE";
+    RowUpdateType[RowUpdateType["SQLITE_UPDATE"] = 23] = "SQLITE_UPDATE";
+})(RowUpdateType || (RowUpdateType = {}));
+export function isBatchedUpdateNotification(update) {
+    return 'tables' in update;
+}
+export function extractTableUpdates(update) {
+    return isBatchedUpdateNotification(update) ? update.tables : [update.table];
+}
+//# sourceMappingURL=DBAdapter.js.map

package/lib/db/DBAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DBAdapter.js","sourceRoot":"","sources":["../../src/db/DBAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmEH;;GAEG;AACH,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACvB,oEAAkB,CAAA;IAClB,mEAAiB,CAAA;IACjB,oEAAkB,CAAA;AACpB,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AAgDD,MAAM,UAAU,2BAA2B,CACzC,MAAsD;IAEtD,OAAO,QAAQ,IAAI,MAAM,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAsD;IACxF,OAAO,2BAA2B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

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

@@ -0,0 +1,68 @@
+import type { BucketProgress } from '../../client/sync/stream/core-instruction.js';
+/** @internal */
+export type InternalProgressInformation = Record<string, BucketProgress>;
+/**
+ * @internal The priority used by the core extension to indicate that a full sync was completed.
+ */
+export declare const FULL_SYNC_PRIORITY = 2147483647;
+/**
+ * Information about a progressing download made by the PowerSync SDK.
+ *
+ * To obtain these values, use {@link SyncProgress}, available through
+ * {@link SyncStatus#downloadProgress}.
+ */
+export interface ProgressWithOperations {
+    /**
+     * The total amount of operations to download for the current sync iteration
+     * to complete.
+     */
+    totalOperations: number;
+    /**
+     * The amount of operations that have already been downloaded.
+     */
+    downloadedOperations: number;
+    /**
+     * Relative progress, as {@link downloadedOperations} of {@link totalOperations}.
+     *
+     * This will be a number between `0.0` and `1.0` (inclusive).
+     *
+     * When this number reaches `1.0`, all changes have been received from the sync service.
+     * Actually applying these changes happens before the `downloadProgress` field is cleared from
+     * {@link SyncStatus}, so progress can stay at `1.0` for a short while before completing.
+     */
+    downloadedFraction: number;
+}
+/**
+ * Provides realtime progress on how PowerSync is downloading rows.
+ *
+ * The progress until the next complete sync is available through the fields on {@link ProgressWithOperations},
+ * which this class implements.
+ * Additionally, the {@link SyncProgress.untilPriority} method can be used to otbain progress towards
+ * a specific priority (instead of the progress for the entire download).
+ *
+ * The reported progress always reflects the status towards the end of a sync iteration (after
+ * which a consistent snapshot of all buckets is available locally).
+ *
+ * In rare cases (in particular, when a [compacting](https://docs.powersync.com/usage/lifecycle-maintenance/compacting-buckets)
+ * operation takes place between syncs), it's possible for the returned numbers to be slightly
+ * inaccurate. For this reason, {@link SyncProgress} should be seen as an approximation of progress.
+ * The information returned is good enough to build progress bars, but not exact enough to track
+ * individual download counts.
+ *
+ * Also note that data is downloaded in bulk, which means that individual counters are unlikely
+ * to be updated one-by-one.
+ */
+export declare class SyncProgress implements ProgressWithOperations {
+    protected internal: InternalProgressInformation;
+    totalOperations: number;
+    downloadedOperations: number;
+    downloadedFraction: number;
+    constructor(internal: InternalProgressInformation);
+    /**
+     * Returns download progress towards all data up until the specified priority being received.
+     *
+     * The returned {@link ProgressWithOperations} tracks the target amount of operations that need
+     * to be downloaded in total and how many of them have already been received.
+     */
+    untilPriority(priority: number): ProgressWithOperations;
+}

package/lib/db/crud/SyncProgress.js

@@ -0,0 +1,61 @@
+/**
+ * @internal The priority used by the core extension to indicate that a full sync was completed.
+ */
+export const FULL_SYNC_PRIORITY = 2147483647;
+/**
+ * Provides realtime progress on how PowerSync is downloading rows.
+ *
+ * The progress until the next complete sync is available through the fields on {@link ProgressWithOperations},
+ * which this class implements.
+ * Additionally, the {@link SyncProgress.untilPriority} method can be used to otbain progress towards
+ * a specific priority (instead of the progress for the entire download).
+ *
+ * The reported progress always reflects the status towards the end of a sync iteration (after
+ * which a consistent snapshot of all buckets is available locally).
+ *
+ * In rare cases (in particular, when a [compacting](https://docs.powersync.com/usage/lifecycle-maintenance/compacting-buckets)
+ * operation takes place between syncs), it's possible for the returned numbers to be slightly
+ * inaccurate. For this reason, {@link SyncProgress} should be seen as an approximation of progress.
+ * The information returned is good enough to build progress bars, but not exact enough to track
+ * individual download counts.
+ *
+ * Also note that data is downloaded in bulk, which means that individual counters are unlikely
+ * to be updated one-by-one.
+ */
+export class SyncProgress {
+    internal;
+    totalOperations;
+    downloadedOperations;
+    downloadedFraction;
+    constructor(internal) {
+        this.internal = internal;
+        const untilCompletion = this.untilPriority(FULL_SYNC_PRIORITY);
+        this.totalOperations = untilCompletion.totalOperations;
+        this.downloadedOperations = untilCompletion.downloadedOperations;
+        this.downloadedFraction = untilCompletion.downloadedFraction;
+    }
+    /**
+     * Returns download progress towards all data up until the specified priority being received.
+     *
+     * The returned {@link ProgressWithOperations} tracks the target amount of operations that need
+     * to be downloaded in total and how many of them have already been received.
+     */
+    untilPriority(priority) {
+        let total = 0;
+        let downloaded = 0;
+        for (const progress of Object.values(this.internal)) {
+            // Include higher-priority buckets, which are represented by lower numbers.
+            if (progress.priority <= priority) {
+                downloaded += progress.since_last;
+                total += progress.target_count - progress.at_last;
+            }
+        }
+        let progress = total == 0 ? 0.0 : downloaded / total;
+        return {
+            totalOperations: total,
+            downloadedOperations: downloaded,
+            downloadedFraction: progress
+        };
+    }
+}
+//# sourceMappingURL=SyncProgress.js.map

package/lib/db/crud/SyncProgress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncProgress.js","sourceRoot":"","sources":["../../../src/db/crud/SyncProgress.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AA+B7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,OAAO,YAAY;IAKD;IAJtB,eAAe,CAAS;IACxB,oBAAoB,CAAS;IAC7B,kBAAkB,CAAS;IAE3B,YAAsB,QAAqC;QAArC,aAAQ,GAAR,QAAQ,CAA6B;QACzD,MAAM,eAAe,GAAG,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC;QAE/D,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC,eAAe,CAAC;QACvD,IAAI,CAAC,oBAAoB,GAAG,eAAe,CAAC,oBAAoB,CAAC;QACjE,IAAI,CAAC,kBAAkB,GAAG,eAAe,CAAC,kBAAkB,CAAC;IAC/D,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAC,QAAgB;QAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACpD,2EAA2E;YAC3E,IAAI,QAAQ,CAAC,QAAQ,IAAI,QAAQ,EAAE,CAAC;gBAClC,UAAU,IAAI,QAAQ,CAAC,UAAU,CAAC;gBAClC,KAAK,IAAI,QAAQ,CAAC,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC;YACpD,CAAC;QACH,CAAC;QAED,IAAI,QAAQ,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,GAAG,KAAK,CAAC;QACrD,OAAO;YACL,eAAe,EAAE,KAAK;YACtB,oBAAoB,EAAE,UAAU;YAChC,kBAAkB,EAAE,QAAQ;SAC7B,CAAC;IACJ,CAAC;CACF"}