@powersync/common 1.34.0 → 1.35.0

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -6,12 +6,15 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ConnectionManager } from './ConnectionManager.js';
+import { ArrayQueryDefinition, Query } from './Query.js';
 import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
+import { WatchedQueryComparator } from './watched/processors/comparators.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -44,7 +47,7 @@ export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDa
 export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
     database: SQLOpenOptions;
 }
-export interface SQLWatchOptions {
+export interface SQLOnChangeOptions {
     signal?: AbortSignal;
     tables?: string[];
     /** The minimum interval between queries. */
@@ -56,6 +59,17 @@ export interface SQLWatchOptions {
      * by not removing PowerSync table name prefixes
      */
     rawTableNames?: boolean;
+    /**
+     * Emits an empty result set immediately
+     */
+    triggerImmediate?: boolean;
+}
+export interface SQLWatchOptions extends SQLOnChangeOptions {
+    /**
+     * Optional comparator which will be used to compare the results of the query.
+     * The watched query will only yield results if the comparator returns false.
+     */
+    comparator?: WatchedQueryComparator<QueryResult>;
 }
 export interface WatchOnChangeEvent {
     changedTables: string[];
@@ -71,6 +85,8 @@ export interface WatchOnChangeHandler {
 export interface PowerSyncDBListener extends StreamingSyncImplementationListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
+    closing: () => Promise<void> | void;
+    closed: () => Promise<void> | void;
 }
 export interface PowerSyncCloseOptions {
     /**
@@ -81,7 +97,6 @@ export interface PowerSyncCloseOptions {
     disconnect?: boolean;
 }
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
-export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
     crudUploadThrottleMs: number;
@@ -389,6 +404,42 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * ```
      */
     watch(sql: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
+    /**
+     * Allows defining a query which can be used to build a {@link WatchedQuery}.
+     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+     * An optional mapper function can be provided to transform the results.
+     *
+     * @example
+     * ```javascript
+     * const watchedTodos = powersync.query({
+     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
+     *  parameters: [],
+     *  mapper: (row) => ({
+     *    ...row,
+     *    created_at: new Date(row.created_at as string)
+     *  })
+     * })
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    query<RowType>(query: ArrayQueryDefinition<RowType>): Query<RowType>;
+    /**
+     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
+     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
+     *
+     * @example
+     * ```javascript
+     *
+     * // Potentially a query from an ORM like Drizzle
+     * const query = db.select().from(lists);
+     *
+     * const watchedTodos = powersync.customQuery(query)
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    customQuery<RowType>(query: WatchCompatibleQuery<RowType[]>): Query<RowType>;
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -437,7 +488,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
+    onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
      * See {@link onChangeWithCallback}.
      *
@@ -452,7 +503,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
+    onChange(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
     /**
      * Invoke the provided callback on any changes to any of the specified tables.
      *
@@ -465,7 +516,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @param options Options for configuring watch behavior
      * @returns A dispose function to stop watching for changes
      */
-    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
+    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
     /**
      * Create a Stream of changes to any of the specified tables.
      *

package/lib/client/AbstractPowerSyncDatabase.js

@@ -9,13 +9,15 @@ import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { throttleTrailing } from '../utils/async.js';
 import { ConnectionManager } from './ConnectionManager.js';
+import { CustomQuery } from './CustomQuery.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
-import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { DEFAULT_WATCH_THROTTLE_MS } from './watched/WatchedQuery.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -23,7 +25,6 @@ const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
 export const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
     disconnect: true
 };
-export const DEFAULT_WATCH_THROTTLE_MS = 30;
 export const DEFAULT_POWERSYNC_DB_OPTIONS = {
     retryDelayMs: 5000,
     crudUploadThrottleMs: DEFAULT_CRUD_UPLOAD_THROTTLE_MS
@@ -341,6 +342,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             return;
         }
+        await this.iterateAsyncListeners(async (cb) => cb.closing?.());
         const { disconnect } = options;
         if (disconnect) {
             await this.disconnect();
@@ -348,6 +350,7 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.connectionManager.close();
         await this.database.close();
         this.closed = true;
+        await this.iterateAsyncListeners(async (cb) => cb.closed?.());
     }
     /**
      * Get upload queue size estimate and count.
@@ -594,6 +597,60 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const options = handlerOrOptions;
         return this.watchWithAsyncGenerator(sql, parameters, options);
     }
+    /**
+     * Allows defining a query which can be used to build a {@link WatchedQuery}.
+     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+     * An optional mapper function can be provided to transform the results.
+     *
+     * @example
+     * ```javascript
+     * const watchedTodos = powersync.query({
+     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
+     *  parameters: [],
+     *  mapper: (row) => ({
+     *    ...row,
+     *    created_at: new Date(row.created_at as string)
+     *  })
+     * })
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    query(query) {
+        const { sql, parameters = [], mapper } = query;
+        const compatibleQuery = {
+            compile: () => ({
+                sql,
+                parameters
+            }),
+            execute: async ({ sql, parameters }) => {
+                const result = await this.getAll(sql, parameters);
+                return mapper ? result.map(mapper) : result;
+            }
+        };
+        return this.customQuery(compatibleQuery);
+    }
+    /**
+     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
+     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
+     *
+     * @example
+     * ```javascript
+     *
+     * // Potentially a query from an ORM like Drizzle
+     * const query = db.select().from(lists);
+     *
+     * const watchedTodos = powersync.customQuery(query)
+     * .watch()
+     * // OR use .differentialWatch() for fine-grained watches.
+     * ```
+     */
+    customQuery(query) {
+        return new CustomQuery({
+            db: this,
+            query
+        });
+    }
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -611,35 +668,42 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (!onResult) {
             throw new Error('onResult is required');
         }
-        const watchQuery = async (abortSignal) => {
-            try {
-                const resolvedTables = await this.resolveTables(sql, parameters, options);
-                // Fetch initial data
-                const result = await this.executeReadOnly(sql, parameters);
-                onResult(result);
-                this.onChangeWithCallback({
-                    onChange: async () => {
-                        try {
-                            const result = await this.executeReadOnly(sql, parameters);
-                            onResult(result);
-                        }
-                        catch (error) {
-                            onError?.(error);
-                        }
-                    },
-                    onError
-                }, {
-                    ...(options ?? {}),
-                    tables: resolvedTables,
-                    // Override the abort signal since we intercept it
-                    signal: abortSignal
-                });
+        const { comparator } = options ?? {};
+        // This API yields a QueryResult type.
+        // This is not a standard Array result, which makes it incompatible with the .query API.
+        const watchedQuery = new OnChangeQueryProcessor({
+            db: this,
+            comparator,
+            placeholderData: null,
+            watchOptions: {
+                query: {
+                    compile: () => ({
+                        sql: sql,
+                        parameters: parameters ?? []
+                    }),
+                    execute: () => this.executeReadOnly(sql, parameters)
+                },
+                reportFetching: false,
+                throttleMs: options?.throttleMs ?? DEFAULT_WATCH_THROTTLE_MS,
+                triggerOnTables: options?.tables
             }
-            catch (error) {
-                onError?.(error);
+        });
+        const dispose = watchedQuery.registerListener({
+            onData: (data) => {
+                if (!data) {
+                    // This should not happen. We only use null for the initial data.
+                    return;
+                }
+                onResult(data);
+            },
+            onError: (error) => {
+                onError(error);
             }
-        };
-        runOnSchemaChange(watchQuery, this, options);
+        });
+        options?.signal?.addEventListener('abort', () => {
+            dispose();
+            watchedQuery.close();
+        });
     }
     /**
      * Execute a read query every time the source tables are modified.
@@ -729,6 +793,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 return;
             executor.schedule({ changedTables: intersection });
         }), throttleMs);
+        if (options?.triggerImmediate) {
+            executor.schedule({ changedTables: [] });
+        }
         const dispose = this.database.registerListener({
             tablesUpdated: async (update) => {
                 try {

package/lib/client/CustomQuery.d.ts

@@ -0,0 +1,22 @@
+import { AbstractPowerSyncDatabase } from './AbstractPowerSyncDatabase.js';
+import { Query, StandardWatchedQueryOptions } from './Query.js';
+import { DifferentialQueryProcessor, DifferentialWatchedQueryOptions } from './watched/processors/DifferentialQueryProcessor.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
+import { WatchCompatibleQuery, WatchedQueryOptions } from './watched/WatchedQuery.js';
+/**
+ * @internal
+ */
+export interface CustomQueryOptions<RowType> {
+    db: AbstractPowerSyncDatabase;
+    query: WatchCompatibleQuery<RowType[]>;
+}
+/**
+ * @internal
+ */
+export declare class CustomQuery<RowType> implements Query<RowType> {
+    protected options: CustomQueryOptions<RowType>;
+    constructor(options: CustomQueryOptions<RowType>);
+    protected resolveOptions(options: WatchedQueryOptions): WatchedQueryOptions;
+    watch(watchOptions: StandardWatchedQueryOptions<RowType>): OnChangeQueryProcessor<RowType[]>;
+    differentialWatch(differentialWatchOptions: DifferentialWatchedQueryOptions<RowType>): DifferentialQueryProcessor<RowType>;
+}

package/lib/client/CustomQuery.js

@@ -0,0 +1,42 @@
+import { FalsyComparator } from './watched/processors/comparators.js';
+import { DifferentialQueryProcessor } from './watched/processors/DifferentialQueryProcessor.js';
+import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
+import { DEFAULT_WATCH_QUERY_OPTIONS } from './watched/WatchedQuery.js';
+/**
+ * @internal
+ */
+export class CustomQuery {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    resolveOptions(options) {
+        return {
+            reportFetching: options?.reportFetching ?? DEFAULT_WATCH_QUERY_OPTIONS.reportFetching,
+            throttleMs: options?.throttleMs ?? DEFAULT_WATCH_QUERY_OPTIONS.throttleMs,
+            triggerOnTables: options?.triggerOnTables
+        };
+    }
+    watch(watchOptions) {
+        return new OnChangeQueryProcessor({
+            db: this.options.db,
+            comparator: watchOptions?.comparator ?? FalsyComparator,
+            placeholderData: watchOptions?.placeholderData ?? [],
+            watchOptions: {
+                ...this.resolveOptions(watchOptions),
+                query: this.options.query
+            }
+        });
+    }
+    differentialWatch(differentialWatchOptions) {
+        return new DifferentialQueryProcessor({
+            db: this.options.db,
+            rowComparator: differentialWatchOptions?.rowComparator,
+            placeholderData: differentialWatchOptions?.placeholderData ?? [],
+            watchOptions: {
+                ...this.resolveOptions(differentialWatchOptions),
+                query: this.options.query
+            }
+        });
+    }
+}

package/lib/client/Query.d.ts

@@ -0,0 +1,97 @@
+import { WatchedQueryComparator } from './watched/processors/comparators.js';
+import { DifferentialWatchedQuery, DifferentialWatchedQueryOptions } from './watched/processors/DifferentialQueryProcessor.js';
+import { StandardWatchedQuery } from './watched/processors/OnChangeQueryProcessor.js';
+import { WatchedQueryOptions } from './watched/WatchedQuery.js';
+/**
+ * Query parameters for {@link ArrayQueryDefinition#parameters}
+ */
+export type QueryParam = string | number | boolean | null | undefined | bigint | Uint8Array;
+/**
+ * Options for building a query with {@link AbstractPowerSyncDatabase#query}.
+ * This query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
+ */
+export interface ArrayQueryDefinition<RowType = unknown> {
+    sql: string;
+    parameters?: ReadonlyArray<Readonly<QueryParam>>;
+    /**
+     * Maps the raw SQLite row to a custom typed object.
+     * @example
+     * ```javascript
+     * mapper: (row) => ({
+     *  ...row,
+     *  created_at: new Date(row.created_at as string),
+     * })
+     * ```
+     */
+    mapper?: (row: Record<string, unknown>) => RowType;
+}
+/**
+ * Options for {@link Query#watch}.
+ */
+export interface StandardWatchedQueryOptions<RowType> extends WatchedQueryOptions {
+    /**
+     * The underlying watched query implementation (re)evaluates the query on any SQLite table change.
+     *
+     * Providing this optional comparator can be used to filter duplicate result set emissions when the result set is unchanged.
+     * The comparator compares the previous and current result set.
+     *
+     * For an efficient comparator see {@link ArrayComparator}.
+     *
+     * @example
+     * ```javascript
+     * comparator: new ArrayComparator({
+     *     compareBy: (item) => JSON.stringify(item)
+     * })
+     * ```
+     */
+    comparator?: WatchedQueryComparator<RowType[]>;
+    /**
+     * The initial data state reported while the query is loading for the first time.
+     * @default []
+     */
+    placeholderData?: RowType[];
+}
+export interface Query<RowType> {
+    /**
+     * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
+     *
+     * By default the returned watched query will emit changes whenever a change to the underlying SQLite tables is made.
+     * These changes might not be relevant to the query, but the query will emit a new result set.
+     *
+     * A {@link StandardWatchedQueryOptions#comparator} can be provided to limit the data emissions. The watched query will still
+     * query the underlying DB on underlying table changes, but the result will only be emitted if the comparator detects a change in the results.
+     *
+     * The comparator in this method is optimized and returns early as soon as it detects a change. Each data emission will correlate to a change in the result set,
+     * but note that the result set will not maintain internal object references to the previous result set. If internal object references are needed,
+     * consider using {@link Query#differentialWatch} instead.
+     */
+    watch(options?: StandardWatchedQueryOptions<RowType>): StandardWatchedQuery<ReadonlyArray<Readonly<RowType>>>;
+    /**
+     * Creates a {@link WatchedQuery} which watches and emits results of the linked query.
+     *
+     * This query method watches for changes in the underlying SQLite tables and runs the query on each table change.
+     * The difference between the current and previous result set is computed.
+     * The watched query will not emit changes if the result set is identical to the previous result set.
+     *
+     * If the result set is different, the watched query will emit the new result set and emit a detailed diff of the changes via the `onData` and `onDiff` listeners.
+     *
+     * The deep differentiation allows maintaining result set object references between result emissions.
+     * The {@link DifferentialWatchedQuery#state} `data` array will contain the previous row references for unchanged rows.
+     *
+     * @example
+     * ```javascript
+     * const watchedLists = powerSync.query({sql: 'SELECT * FROM lists'})
+     *  .differentialWatch();
+     *
+     * const disposeListener = watchedLists.registerListener({
+     *  onData: (lists) => {
+     *    console.log('The latest result set for the query is', lists);
+     *  },
+     *  onDiff: (diff) => {
+     *    console.log('The lists result set has changed since the last emission', diff.added, diff.removed, diff.updated, diff.all)
+     *  }
+     * })
+     * ```
+     */
+    differentialWatch(options?: DifferentialWatchedQueryOptions<RowType>): DifferentialWatchedQuery<RowType>;
+}

package/lib/client/Query.js

@@ -0,0 +1 @@
+export {};

package/lib/client/sync/bucket/BucketStorageAdapter.d.ts

@@ -1,4 +1,4 @@
-import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, OpId } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -62,7 +62,7 @@ export declare enum PowerSyncControlCommand {
 export interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
 }
-export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener>, Disposable {
+export interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
     init(): Promise<void>;
     saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;

package/lib/client/sync/stream/AbstractRemote.js

@@ -204,6 +204,22 @@ export class AbstractRemote {
         // headers with websockets on web. The browser userAgent is however added
         // automatically as a header.
         const userAgent = this.getUserAgent();
+        const stream = new DataStream({
+            logger: this.logger,
+            pressure: {
+                lowWaterMark: SYNC_QUEUE_REQUEST_LOW_WATER
+            },
+            mapLine: map
+        });
+        // Handle upstream abort
+        if (options.abortSignal?.aborted) {
+            throw new AbortOperation('Connection request aborted');
+        }
+        else {
+            options.abortSignal?.addEventListener('abort', () => {
+                stream.close();
+            }, { once: true });
+        }
         let keepAliveTimeout;
         const resetTimeout = () => {
             clearTimeout(keepAliveTimeout);
@@ -213,12 +229,22 @@ export class AbstractRemote {
             }, SOCKET_TIMEOUT_MS);
         };
         resetTimeout();
+        // Typescript complains about this being `never` if it's not assigned here.
+        // This is assigned in `wsCreator`.
+        let disposeSocketConnectionTimeout = () => { };
         const url = this.options.socketUrlTransformer(request.url);
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url,
                 wsCreator: (url) => {
                     const socket = this.createSocket(url);
+                    disposeSocketConnectionTimeout = stream.registerListener({
+                        closed: () => {
+                            // Allow closing the underlying WebSocket if the stream was closed before the
+                            // RSocket connect completed. This should effectively abort the request.
+                            socket.close();
+                        }
+                    });
                     socket.addEventListener('message', (event) => {
                         resetTimeout();
                     });
@@ -242,20 +268,18 @@ export class AbstractRemote {
         let rsocket;
         try {
             rsocket = await connector.connect();
+            // The connection is established, we no longer need to monitor the initial timeout
+            disposeSocketConnectionTimeout();
         }
         catch (ex) {
             this.logger.error(`Failed to connect WebSocket`, ex);
             clearTimeout(keepAliveTimeout);
+            if (!stream.closed) {
+                await stream.close();
+            }
             throw ex;
         }
         resetTimeout();
-        const stream = new DataStream({
-            logger: this.logger,
-            pressure: {
-                lowWaterMark: SYNC_QUEUE_REQUEST_LOW_WATER
-            },
-            mapLine: map
-        });
         let socketIsClosed = false;
         const closeSocket = () => {
             clearTimeout(keepAliveTimeout);
@@ -341,18 +365,6 @@ export class AbstractRemote {
                 l();
             }
         });
-        /**
-         * Handle abort operations here.
-         * Unfortunately cannot insert them into the connection.
-         */
-        if (options.abortSignal?.aborted) {
-            stream.close();
-        }
-        else {
-            options.abortSignal?.addEventListener('abort', () => {
-                stream.close();
-            });
-        }
         return stream;
     }
     /**

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -1,6 +1,6 @@
 import { ILogger } from 'js-logger';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js';
-import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserver, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter.js';
 import { AbstractRemote, FetchStrategy } from './AbstractRemote.js';
 import { StreamingSyncRequestParameterType } from './streaming-sync-types.js';
@@ -136,7 +136,7 @@ export interface AdditionalConnectionOptions {
 }
 /** @internal */
 export type RequiredAdditionalConnectionOptions = Required<AdditionalConnectionOptions>;
-export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
+export interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
     /**
      * Connects to the sync service
      */
@@ -168,6 +168,7 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected _lastSyncedAt: Date | null;
     protected options: AbstractStreamingSyncImplementationOptions;
     protected abortController: AbortController | null;
+    protected uploadAbortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
     protected logger: ILogger;

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.js

@@ -1,6 +1,6 @@
 import Logger from 'js-logger';
-import { SyncStatus } from '../../../db/crud/SyncStatus.js';
 import { FULL_SYNC_PRIORITY } from '../../../db/crud/SyncProgress.js';
+import { SyncStatus } from '../../../db/crud/SyncStatus.js';
 import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
 import { throttleLeadingTrailing } from '../../../utils/async.js';
@@ -83,6 +83,9 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
     options;
     abortController;
+    // In rare cases, mostly for tests, uploads can be triggered without being properly connected.
+    // This allows ensuring that all upload processes can be aborted.
+    uploadAbortController;
     crudUpdateListener;
     streamingSyncPromise;
     logger;
@@ -158,8 +161,10 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         return this.syncStatus.connected;
     }
     async dispose() {
+        super.dispose();
         this.crudUpdateListener?.();
         this.crudUpdateListener = undefined;
+        this.uploadAbortController?.abort();
     }
     async hasCompletedSync() {
         return this.options.adapter.hasCompletedSync();
@@ -180,7 +185,12 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                  * Keep track of the first item in the CRUD queue for the last `uploadCrud` iteration.
                  */
                 let checkedCrudItem;
-                while (true) {
+                const controller = new AbortController();
+                this.uploadAbortController = controller;
+                this.abortController?.signal.addEventListener('abort', () => {
+                    controller.abort();
+                }, { once: true });
+                while (!controller.signal.aborted) {
                     try {
                         /**
                          * This is the first item in the FIFO CRUD queue.
@@ -225,7 +235,7 @@ The next upload iteration will be delayed.`);
                                 uploadError: ex
                             }
                         });
-                        await this.delayRetry();
+                        await this.delayRetry(controller.signal);
                         if (!this.isConnected) {
                             // Exit the upload loop if the sync stream is no longer connected
                             break;
@@ -240,6 +250,7 @@ The next upload iteration will be delayed.`);
                         });
                     }
                 }
+                this.uploadAbortController = null;
             }
         });
     }
@@ -439,7 +450,8 @@ The next upload iteration will be delayed.`);
         });
     }
     async legacyStreamingSyncIteration(signal, resolvedOptions) {
-        if (resolvedOptions.serializedSchema?.raw_tables != null) {
+        const rawTables = resolvedOptions.serializedSchema?.raw_tables;
+        if (rawTables != null && rawTables.length) {
             this.logger.warn('Raw tables require the Rust-based sync client. The JS client will ignore them.');
         }
         this.logger.debug('Streaming sync iteration started');