@powersync/common 1.29.0 → 1.31.0

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

@@ -51,6 +51,11 @@ export declare class CrudEntry {
      * Data associated with the change.
      */
     opData?: Record<string, any>;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues?: Record<string, any>;
     /**
      * Table that contained the change.
      */
@@ -59,8 +64,15 @@ export declare class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId?: number;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata?: string;
     static fromRow(dbRow: CrudEntryJSON): CrudEntry;
-    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>);
+    constructor(clientId: number, op: UpdateType, table: string, id: string, transactionId?: number, opData?: Record<string, any>, previousValues?: Record<string, any>, metadata?: string);
     /**
      * Converts the change to JSON format.
      */

package/lib/client/sync/bucket/CrudEntry.js

@@ -30,6 +30,11 @@ export class CrudEntry {
      * Data associated with the change.
      */
     opData;
+    /**
+     * For tables where the `trackPreviousValues` option has been enabled, this tracks previous values for
+     * `UPDATE` and `DELETE` statements.
+     */
+    previousValues;
     /**
      * Table that contained the change.
      */
@@ -38,17 +43,26 @@ export class CrudEntry {
      * Auto-incrementing transaction id. This is the same for all operations within the same transaction.
      */
     transactionId;
+    /**
+     * Client-side metadata attached with this write.
+     *
+     * This field is only available when the `trackMetadata` option was set to `true` when creating a table
+     * and the insert or update statement set the `_metadata` column.
+     */
+    metadata;
     static fromRow(dbRow) {
         const data = JSON.parse(dbRow.data);
-        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data);
+        return new CrudEntry(parseInt(dbRow.id), data.op, data.type, data.id, dbRow.tx_id, data.data, data.old, data.metadata);
     }
-    constructor(clientId, op, table, id, transactionId, opData) {
+    constructor(clientId, op, table, id, transactionId, opData, previousValues, metadata) {
         this.clientId = clientId;
         this.id = id;
         this.op = op;
         this.opData = opData;
         this.table = table;
         this.transactionId = transactionId;
+        this.previousValues = previousValues;
+        this.metadata = metadata;
     }
     /**
      * Converts the change to JSON format.

package/lib/client/sync/bucket/SqliteBucketStorage.js

@@ -119,9 +119,9 @@ export class SqliteBucketStorage extends BaseObserver {
             }
             return { ready: false, checkpointValid: false, checkpointFailures: r.checkpointFailures };
         }
-        const buckets = checkpoint.buckets;
+        let buckets = checkpoint.buckets;
         if (priority !== undefined) {
-            buckets.filter((b) => hasMatchingPriority(priority, b));
+            buckets = buckets.filter((b) => hasMatchingPriority(priority, b));
         }
         const bucketNames = buckets.map((b) => b.bucket);
         await this.writeTransaction(async (tx) => {

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

@@ -7,6 +7,7 @@ import { StreamingSyncLine, StreamingSyncRequest } from './streaming-sync-types.
 export type BSONImplementation = typeof BSON;
 export type RemoteConnector = {
     fetchCredentials: () => Promise<PowerSyncCredentials | null>;
+    invalidateCredentials?: () => void;
 };
 export declare const DEFAULT_REMOTE_LOGGER: Logger.ILogger;
 export type SyncStreamOptions = {
@@ -74,7 +75,35 @@ export declare abstract class AbstractRemote {
      * which can be called to perform fetch requests
      */
     get fetch(): FetchImplementation;
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     getCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    prefetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    fetchCredentials(): Promise<PowerSyncCredentials | null>;
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials(): void;
     getUserAgent(): string;
     protected buildRequest(path: string): Promise<{
         url: string;

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

@@ -8,8 +8,6 @@ import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { DataStream } from '../../../utils/DataStream.js';
 const POWERSYNC_TRAILING_SLASH_MATCH = /\/+$/;
 const POWERSYNC_JS_VERSION = PACKAGE.version;
-// Refresh at least 30 sec before it expires
-const REFRESH_CREDENTIALS_SAFETY_PERIOD_MS = 30_000;
 const SYNC_QUEUE_REQUEST_LOW_WATER = 5;
 // Keep alive message is sent every period
 const KEEP_ALIVE_MS = 20_000;
@@ -70,17 +68,52 @@ export class AbstractRemote {
             ? fetchImplementation.getFetch()
             : fetchImplementation;
     }
+    /**
+     * Get credentials currently cached, or fetch new credentials if none are
+     * available.
+     *
+     * These credentials may have expired already.
+     */
     async getCredentials() {
-        const { expiresAt } = this.credentials ?? {};
-        if (expiresAt && expiresAt > new Date(new Date().valueOf() + REFRESH_CREDENTIALS_SAFETY_PERIOD_MS)) {
+        if (this.credentials) {
             return this.credentials;
         }
-        this.credentials = await this.connector.fetchCredentials();
-        if (this.credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
-            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${this.credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
-        }
+        return this.prefetchCredentials();
+    }
+    /**
+     * Fetch a new set of credentials and cache it.
+     *
+     * Until this call succeeds, `getCredentials` will still return the
+     * old credentials.
+     *
+     * This may be called before the current credentials have expired.
+     */
+    async prefetchCredentials() {
+        this.credentials = await this.fetchCredentials();
         return this.credentials;
     }
+    /**
+     * Get credentials for PowerSync.
+     *
+     * This should always fetch a fresh set of credentials - don't use cached
+     * values.
+     */
+    async fetchCredentials() {
+        const credentials = await this.connector.fetchCredentials();
+        if (credentials?.endpoint.match(POWERSYNC_TRAILING_SLASH_MATCH)) {
+            throw new Error(`A trailing forward slash "/" was found in the fetchCredentials endpoint: "${credentials.endpoint}". Remove the trailing forward slash "/" to fix this error.`);
+        }
+        return credentials;
+    }
+    /***
+     * Immediately invalidate credentials.
+     *
+     * This may be called when the current credentials have expired.
+     */
+    invalidateCredentials() {
+        this.credentials = null;
+        this.connector.invalidateCredentials?.();
+    }
     getUserAgent() {
         return `powersync-js/${POWERSYNC_JS_VERSION}`;
     }
@@ -114,6 +147,9 @@ export class AbstractRemote {
             },
             body: JSON.stringify(data)
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when posting to ${path}: ${await res.text()}}`);
         }
@@ -128,6 +164,9 @@ export class AbstractRemote {
                 ...request.headers
             }
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             throw new Error(`Received ${res.status} - ${res.statusText} when getting from ${path}: ${await res.text()}}`);
         }
@@ -145,6 +184,9 @@ export class AbstractRemote {
             this.logger.error(`Caught ex when POST streaming to ${path}`, ex);
             throw ex;
         });
+        if (res.status === 401) {
+            this.invalidateCredentials();
+        }
         if (!res.ok) {
             const text = await res.text();
             this.logger.error(`Could not POST streaming to ${path} - ${res.status} - ${res.statusText}: ${text}`);
@@ -169,10 +211,18 @@ export class AbstractRemote {
         // headers with websockets on web. The browser userAgent is however added
         // automatically as a header.
         const userAgent = this.getUserAgent();
+        let socketCreationError;
         const connector = new RSocketConnector({
             transport: new WebsocketClientTransport({
                 url: this.options.socketUrlTransformer(request.url),
-                wsCreator: (url) => this.createSocket(url)
+                wsCreator: (url) => {
+                    const s = this.createSocket(url);
+                    s.addEventListener('error', (e) => {
+                        socketCreationError = new Error('Failed to create connection to websocket: ', e.target.url ?? '');
+                        this.logger.warn('Socket error', e);
+                    });
+                    return s;
+                }
             }),
             setup: {
                 keepAlive: KEEP_ALIVE_MS,
@@ -197,7 +247,7 @@ export class AbstractRemote {
              * On React native the connection exception can be `undefined` this causes issues
              * with detecting the exception inside async-mutex
              */
-            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex)}`);
+            throw new Error(`Could not connect to PowerSync instance: ${JSON.stringify(ex ?? socketCreationError)}`);
         }
         const stream = new DataStream({
             logger: this.logger,
@@ -233,6 +283,17 @@ export class AbstractRemote {
             }, syncQueueRequestSize, // The initial N amount
             {
                 onError: (e) => {
+                    if (e.message.includes('PSYNC_')) {
+                        if (e.message.includes('PSYNC_S21')) {
+                            this.invalidateCredentials();
+                        }
+                    }
+                    else {
+                        // Possible that connection is with an older service, always invalidate to be safe
+                        if (e.message !== 'Closed. ') {
+                            this.invalidateCredentials();
+                        }
+                    }
                     // Don't log closed as an error
                     if (e.message !== 'Closed. ') {
                         this.logger.error(e);

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

@@ -514,6 +514,7 @@ The next upload iteration will be delayed.`);
                         if (remaining_seconds == 0) {
                             // Connection would be closed automatically right after this
                             this.logger.debug('Token expiring; reconnect');
+                            this.options.remote.invalidateCredentials();
                             /**
                              * For a rare case where the backend connector does not update the token
                              * (uses the same one), this should have some delay.
@@ -521,6 +522,12 @@ The next upload iteration will be delayed.`);
                             await this.delayRetry();
                             return;
                         }
+                        else if (remaining_seconds < 30) {
+                            this.logger.debug('Token will expire soon; reconnect');
+                            // Pre-emptively refresh the token
+                            this.options.remote.invalidateCredentials();
+                            return;
+                        }
                         this.triggerCrudUpload();
                     }
                     else {

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

@@ -44,7 +44,7 @@ export interface ProgressWithOperations {
  * 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 th end of a sync iteration (after
+ * 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)

package/lib/db/crud/SyncProgress.js

@@ -10,7 +10,7 @@ export const FULL_SYNC_PRIORITY = 2147483647;
  * 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 th end of a sync iteration (after
+ * 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)

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

@@ -18,6 +18,10 @@ export declare class Schema<S extends SchemaType = SchemaType> {
             view_name: string;
             local_only: boolean;
             insert_only: boolean;
+            include_old: any;
+            include_old_only_when_changed: boolean;
+            include_metadata: boolean;
+            ignore_empty_update: boolean;
             columns: {
                 name: string;
                 type: import("./Column.js").ColumnType | undefined;

package/lib/db/schema/Schema.js

@@ -1,4 +1,3 @@
-import { Table } from './Table.js';
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
  */
@@ -41,15 +40,7 @@ export class Schema {
     }
     convertToClassicTables(props) {
         return Object.entries(props).map(([name, table]) => {
-            const convertedTable = new Table({
-                name,
-                columns: table.columns,
-                indexes: table.indexes,
-                localOnly: table.localOnly,
-                insertOnly: table.insertOnly,
-                viewName: table.viewNameOverride || name
-            });
-            return convertedTable;
+            return table.copyWithName(name);
         });
     }
 }

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

@@ -1,16 +1,32 @@
 import { Column, ColumnsType, ColumnType, ExtractColumnValueType } from './Column.js';
 import { Index } from './Index.js';
 import { TableV2 } from './TableV2.js';
-export interface TableOptions {
+interface SharedTableOptions {
+    localOnly?: boolean;
+    insertOnly?: boolean;
+    viewName?: string;
+    trackPrevious?: boolean | TrackPreviousOptions;
+    trackMetadata?: boolean;
+    ignoreEmptyUpdates?: boolean;
+}
+/** Whether to include previous column values when PowerSync tracks local changes.
+ *
+ * Including old values may be helpful for some backend connector implementations, which is
+ * why it can be enabled on per-table or per-columm basis.
+ */
+export interface TrackPreviousOptions {
+    /** When defined, a list of column names for which old values should be tracked. */
+    columns?: string[];
+    /** When enabled, only include values that have actually been changed by an update. */
+    onlyWhenChanged?: boolean;
+}
+export interface TableOptions extends SharedTableOptions {
     /**
      * The synced table name, matching sync rules
      */
     name: string;
     columns: Column[];
     indexes?: Index[];
-    localOnly?: boolean;
-    insertOnly?: boolean;
-    viewName?: string;
 }
 export type RowType<T extends TableV2<any>> = {
     [K in keyof T['columnMap']]: ExtractColumnValueType<T['columnMap'][K]>;
@@ -18,16 +34,16 @@ export type RowType<T extends TableV2<any>> = {
     id: string;
 };
 export type IndexShorthand = Record<string, string[]>;
-export interface TableV2Options {
+export interface TableV2Options extends SharedTableOptions {
     indexes?: IndexShorthand;
-    localOnly?: boolean;
-    insertOnly?: boolean;
-    viewName?: string;
 }
 export declare const DEFAULT_TABLE_OPTIONS: {
     indexes: never[];
     insertOnly: boolean;
     localOnly: boolean;
+    trackPrevious: boolean;
+    trackMetadata: boolean;
+    ignoreEmptyUpdates: boolean;
 };
 export declare const InvalidSQLCharacters: RegExp;
 export declare class Table<Columns extends ColumnsType = ColumnsType> {
@@ -96,9 +112,11 @@ export declare class Table<Columns extends ColumnsType = ColumnsType> {
      *```
      */
     constructor(options: TableOptions);
+    copyWithName(name: string): Table;
     private isTableV1;
     private initTableV1;
     private initTableV2;
+    private applyDefaultOptions;
     get name(): string;
     get viewNameOverride(): string | undefined;
     get viewName(): string;
@@ -107,6 +125,9 @@ export declare class Table<Columns extends ColumnsType = ColumnsType> {
     get indexes(): Index[];
     get localOnly(): boolean;
     get insertOnly(): boolean;
+    get trackPrevious(): boolean | TrackPreviousOptions;
+    get trackMetadata(): boolean;
+    get ignoreEmptyUpdates(): boolean;
     get internalName(): string;
     get validName(): boolean;
     validate(): void;
@@ -115,6 +136,10 @@ export declare class Table<Columns extends ColumnsType = ColumnsType> {
         view_name: string;
         local_only: boolean;
         insert_only: boolean;
+        include_old: any;
+        include_old_only_when_changed: boolean;
+        include_metadata: boolean;
+        ignore_empty_update: boolean;
         columns: {
             name: string;
             type: ColumnType | undefined;
@@ -129,3 +154,4 @@ export declare class Table<Columns extends ColumnsType = ColumnsType> {
         }[];
     };
 }
+export {};

package/lib/db/schema/Table.js

@@ -4,7 +4,10 @@ import { IndexedColumn } from './IndexedColumn.js';
 export const DEFAULT_TABLE_OPTIONS = {
     indexes: [],
     insertOnly: false,
-    localOnly: false
+    localOnly: false,
+    trackPrevious: false,
+    trackMetadata: false,
+    ignoreEmptyUpdates: false
 };
 export const InvalidSQLCharacters = /["'%,.#\s[\]]/;
 export class Table {
@@ -41,16 +44,21 @@ export class Table {
             this.initTableV2(optionsOrColumns, v2Options);
         }
     }
+    copyWithName(name) {
+        return new Table({
+            ...this.options,
+            name
+        });
+    }
     isTableV1(arg) {
         return 'columns' in arg && Array.isArray(arg.columns);
     }
     initTableV1(options) {
         this.options = {
             ...options,
-            indexes: options.indexes || [],
-            insertOnly: options.insertOnly ?? DEFAULT_TABLE_OPTIONS.insertOnly,
-            localOnly: options.localOnly ?? DEFAULT_TABLE_OPTIONS.localOnly
+            indexes: options.indexes || []
         };
+        this.applyDefaultOptions();
     }
     initTableV2(columns, options) {
         const convertedColumns = Object.entries(columns).map(([name, columnInfo]) => new Column({ name, type: columnInfo.type }));
@@ -65,12 +73,23 @@ export class Table {
             name: '',
             columns: convertedColumns,
             indexes: convertedIndexes,
-            insertOnly: options?.insertOnly ?? DEFAULT_TABLE_OPTIONS.insertOnly,
-            localOnly: options?.localOnly ?? DEFAULT_TABLE_OPTIONS.localOnly,
-            viewName: options?.viewName
+            viewName: options?.viewName,
+            insertOnly: options?.insertOnly,
+            localOnly: options?.localOnly,
+            trackPrevious: options?.trackPrevious,
+            trackMetadata: options?.trackMetadata,
+            ignoreEmptyUpdates: options?.ignoreEmptyUpdates
         };
+        this.applyDefaultOptions();
         this._mappedColumns = columns;
     }
+    applyDefaultOptions() {
+        this.options.insertOnly ??= DEFAULT_TABLE_OPTIONS.insertOnly;
+        this.options.localOnly ??= DEFAULT_TABLE_OPTIONS.localOnly;
+        this.options.trackPrevious ??= DEFAULT_TABLE_OPTIONS.trackPrevious;
+        this.options.trackMetadata ??= DEFAULT_TABLE_OPTIONS.trackMetadata;
+        this.options.ignoreEmptyUpdates ??= DEFAULT_TABLE_OPTIONS.ignoreEmptyUpdates;
+    }
     get name() {
         return this.options.name;
     }
@@ -94,10 +113,19 @@ export class Table {
         return this.options.indexes ?? [];
     }
     get localOnly() {
-        return this.options.localOnly ?? false;
+        return this.options.localOnly;
     }
     get insertOnly() {
-        return this.options.insertOnly ?? false;
+        return this.options.insertOnly;
+    }
+    get trackPrevious() {
+        return this.options.trackPrevious;
+    }
+    get trackMetadata() {
+        return this.options.trackMetadata;
+    }
+    get ignoreEmptyUpdates() {
+        return this.options.ignoreEmptyUpdates;
     }
     get internalName() {
         if (this.options.localOnly) {
@@ -124,6 +152,12 @@ export class Table {
         if (this.columns.length > MAX_AMOUNT_OF_COLUMNS) {
             throw new Error(`Table has too many columns. The maximum number of columns is ${MAX_AMOUNT_OF_COLUMNS}.`);
         }
+        if (this.trackMetadata && this.localOnly) {
+            throw new Error(`Can't include metadata for local-only tables.`);
+        }
+        if (this.trackPrevious != false && this.localOnly) {
+            throw new Error(`Can't include old values for local-only tables.`);
+        }
         const columnNames = new Set();
         columnNames.add('id');
         for (const column of this.columns) {
@@ -156,11 +190,16 @@ export class Table {
         }
     }
     toJSON() {
+        const trackPrevious = this.trackPrevious;
         return {
             name: this.name,
             view_name: this.viewName,
             local_only: this.localOnly,
             insert_only: this.insertOnly,
+            include_old: trackPrevious && (trackPrevious.columns ?? true),
+            include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
+            include_metadata: this.trackMetadata,
+            ignore_empty_update: this.ignoreEmptyUpdates,
             columns: this.columns.map((c) => c.toJSON()),
             indexes: this.indexes.map((e) => e.toJSON(this))
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"