@powersync/common 1.57.1 → 2.0.0

package/src/client/sync/bucket/CrudEntry.ts

@@ -21,44 +21,12 @@ export enum UpdateType {
   DELETE = 'DELETE'
 }
 
-/**
- * @internal
- */
-export type CrudEntryJSON = {
-  id: string;
-  data: string;
-  tx_id?: number;
-};
-
-type CrudEntryDataJSON = {
-  data: Record<string, any>;
-  old?: Record<string, any>;
-  op: UpdateType;
-  type: string;
-  id: string;
-  metadata?: string;
-};
-
-/**
- * The output JSON seems to be a third type of JSON, not the same as the input JSON.
- */
-type CrudEntryOutputJSON = {
-  op_id: number;
-  op: UpdateType;
-  type: string;
-  id: string;
-  tx_id?: number;
-  data?: Record<string, any>;
-  old?: Record<string, any>;
-  metadata?: string;
-};
-
 /**
  * A single client-side change.
  *
  * @public
  */
-export class CrudEntry {
+export interface CrudEntry {
   /**
    * Auto-incrementing client-side id.
    */
@@ -99,83 +67,15 @@ export class CrudEntry {
    */
   metadata?: string;
 
-  static fromRow(dbRow: CrudEntryJSON) {
-    const data: CrudEntryDataJSON = JSON.parse(dbRow.data);
-    return new CrudEntry(
-      parseInt(dbRow.id),
-      data.op,
-      data.type,
-      data.id,
-      dbRow.tx_id,
-      data.data,
-      data.old,
-      data.metadata
-    );
-  }
-
-  constructor(
-    clientId: number,
-    op: UpdateType,
-    table: string,
-    id: string,
-    transactionId?: number,
-    opData?: Record<string, any>,
-    previousValues?: Record<string, any>,
-    metadata?: string
-  ) {
-    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.
    */
-  toJSON(): CrudEntryOutputJSON {
-    return {
-      op_id: this.clientId,
-      op: this.op,
-      type: this.table,
-      id: this.id,
-      tx_id: this.transactionId,
-      data: this.opData,
-      old: this.previousValues,
-      metadata: this.metadata
-    };
-  }
-
-  equals(entry: CrudEntry) {
-    return JSON.stringify(this.toComparisonArray()) == JSON.stringify(entry.toComparisonArray());
-  }
+  toJSON(): unknown;
 
-  /**
-   * The hash code for this object.
-   * @deprecated This should not be necessary in the JS SDK.
-   * Use the  @see CrudEntry#equals method instead.
-   * TODO remove in the next major release.
-   */
-  hashCode() {
-    return JSON.stringify(this.toComparisonArray());
-  }
+  equals(entry: CrudEntry): boolean;
 
   /**
    * Generates an array for use in deep comparison operations
    */
-  toComparisonArray() {
-    return [
-      this.transactionId,
-      this.clientId,
-      this.op,
-      this.table,
-      this.id,
-      this.opData,
-      this.previousValues,
-      this.metadata
-    ];
-  }
+  toComparisonArray(): unknown[];
 }

package/src/client/sync/options.ts

@@ -0,0 +1,77 @@
+import { StreamingSyncRequestParameterType } from './stream/JsonValue.js';
+
+/**
+ * Options that affect how the PowerSync SDK connects to the PowerSync Service.
+ *
+ * @public
+ */
+export interface SyncOptions {
+  // Note: When adding new fields to this interface, consider that these objects need to be serializable.
+
+  /**
+   * A set of metadata to be included in service logs.
+   */
+  appMetadata?: Record<string, string>;
+
+  /**
+   * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
+   */
+  params?: Record<string, StreamingSyncRequestParameterType>;
+
+  /**
+   * The connection method to use when streaming updates from
+   * the PowerSync backend instance.
+   *
+   * The default value is SDK-specific. {@link SyncStreamConnectionMethod.HTTP} is the preferred implementation and used
+   * by default, except for React Native apps without Expo. Those don't support streaming HTTP responses, which is why
+   * {@link SyncStreamConnectionMethod.WEB_SOCKET} is used as a workaround.
+   */
+  connectionMethod?: SyncStreamConnectionMethod;
+
+  fetchStrategy?: FetchStrategy;
+
+  /**
+   * Whether to include streams that have `auto_subscribe: true` in their definition.
+   *
+   * This defaults to `true`.
+   */
+  includeDefaultStreams?: boolean;
+
+  /**
+   * Delay for retrying sync streaming operations
+   * from the PowerSync backend after an error occurs.
+   */
+  retryDelayMs?: number;
+
+  /**
+   * Backend Connector CRUD operations are throttled
+   * to occur at most every `crudUploadThrottleMs`
+   * milliseconds.
+   */
+  crudUploadThrottleMs?: number;
+}
+
+/**
+ * @public
+ */
+export enum SyncStreamConnectionMethod {
+  HTTP = 'http',
+  WEB_SOCKET = 'web-socket'
+}
+
+/**
+ * @public
+ */
+export enum FetchStrategy {
+  /**
+   * Queues multiple sync events before processing, reducing round-trips.
+   * This comes at the cost of more processing overhead, which may cause ACK timeouts on older/weaker devices for big enough datasets.
+   */
+  Buffered = 'buffered',
+
+  /**
+   * Processes each sync event immediately before requesting the next.
+   * This reduces processing overhead and improves real-time responsiveness.
+   */
+  Sequential = 'sequential'
+}

package/src/client/sync/sync-streams.ts

@@ -81,7 +81,7 @@ export interface SyncStreamSubscribeOptions {
 /**
  * A handle to a {@link SyncStreamDescription} that allows subscribing to the stream.
  *
- * To obtain an instance of {@link SyncStream}, call {@link AbstractPowerSyncDatabase.syncStream}.
+ * To obtain an instance of {@link SyncStream}, call {@link CommonPowerSyncDatabase.syncStream}.
  *
  * @public
  */

package/src/client/triggers/TriggerManager.ts

@@ -163,9 +163,10 @@ export interface TriggerCreationHooks {
 
 /**
  * Common interface for options used in creating a diff trigger.
+ *
+ * @alpha @experimental
  */
-
-interface BaseCreateDiffTriggerOptions {
+export interface BaseCreateDiffTriggerOptions {
   /**
    * PowerSync source table/view to trigger and track changes from.
    * This should be present in the PowerSync database's schema.
@@ -188,16 +189,18 @@ interface BaseCreateDiffTriggerOptions {
    * The row id is available in the `id` column.
    *
    * NB! The WHEN clauses here are added directly to the SQLite trigger creation SQL.
-   * Any user input strings here should be sanitized externally. The {@link when} string template function performs
-   * some basic sanitization, extra external sanitization is recommended.
+   * Any user input strings here should be sanitized externally. The {@link BaseCreateDiffTriggerOptions.when} string
+   * template function performs some basic sanitization, extra external sanitization is recommended.
    *
    * @example
+   * ```JavaScript
    * {
    *  'INSERT': sanitizeSQL`json_extract(NEW.data, '$.list_id') = ${sanitizeUUID(list.id)}`,
    *  'INSERT': `TRUE`,
    *  'UPDATE': sanitizeSQL`NEW.id = 'abcd' AND json_extract(NEW.data, '$.status') = 'active'`,
    *  'DELETE': sanitizeSQL`json_extract(OLD.data, '$.list_id') = 'abcd'`
    * }
+   * ```
    */
   when: Partial<Record<DiffTriggerOperation, string>>;
 
@@ -264,7 +267,9 @@ export interface WithDiffOptions {
  * @experimental @alpha
  * Context for the `onChange` handler provided to {@link TriggerManager#trackTableDiff}.
  */
-export interface TriggerDiffHandlerContext extends LockContext {
+export interface TriggerDiffHandlerContext {
+  context: LockContext;
+
   /**
    * The name of the temporary destination table created by the trigger.
    */
@@ -363,7 +368,6 @@ export interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
 
   /**
    * The minimum interval, in milliseconds, between {@link TrackDiffOptions.onChange} invocations.
-   *  @default {@link DEFAULT_WATCH_THROTTLE_MS}
    */
   throttleMs?: number;
 }
@@ -472,38 +476,3 @@ export interface TriggerManager {
    */
   trackTableDiff(options: TrackDiffOptions): Promise<TriggerRemoveCallback>;
 }
-
-/**
- * @experimental
- * @internal
- * Manages claims on persisted SQLite triggers and destination tables to enable proper cleanup
- * when they are no longer actively in use.
- *
- * When using persisted triggers (especially for OPFS multi-tab scenarios), we need a reliable way to determine which resources are still actively in use across different connections/tabs so stale resources can be safely cleaned up without interfering with active triggers.
- *
- * A cleanup process runs
- * on database creation (and every 2 minutes) that:
- * 1. Queries for existing managed persisted resources
- * 2. Checks with the claim manager if any consumer is actively using those resources
- * 3. Deletes unused resources
- */
-
-export interface TriggerClaimManager {
-  /**
-   * Obtains or marks a claim on a certain identifier.
-   * @returns a callback to release the claim.
-   */
-  obtainClaim: (identifier: string) => Promise<() => Promise<void>>;
-  /**
-   * Checks if a claim is present for an identifier.
-   */
-  checkClaim: (identifier: string) => Promise<boolean>;
-}
-
-/**
- * @experimental
- * @internal
- */
-export interface TriggerManagerConfig {
-  claimManager: TriggerClaimManager;
-}

package/src/client/watched/GetAllQuery.ts

@@ -1,5 +1,5 @@
 import { CompiledQuery } from '../../types/types.js';
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 import { WatchCompatibleQuery } from './WatchedQuery.js';
 
 /**
@@ -24,7 +24,7 @@ export type GetAllQueryOptions<RowType = unknown> = {
 };
 
 /**
- * Performs a {@link AbstractPowerSyncDatabase.getAll} operation for a watched query.
+ * Performs a {@link DBGetUtils.getAll} operation for a watched query.
  *
  * @public
  */
@@ -38,7 +38,7 @@ export class GetAllQuery<RowType = unknown> implements WatchCompatibleQuery<RowT
     };
   }
 
-  async execute(options: { db: AbstractPowerSyncDatabase }): Promise<RowType[]> {
+  async execute(options: { db: CommonPowerSyncDatabase }): Promise<RowType[]> {
     const { db } = options;
     const { sql, parameters = [] } = this.compile();
     const rawResult = await db.getAll<Record<string, unknown>>(sql, [...parameters]);

package/src/client/watched/WatchedQuery.ts

@@ -1,7 +1,7 @@
 import { CompiledQuery } from '../../types/types.js';
 import { BaseListener } from '../../utils/BaseObserver.js';
 import { MetaBaseObserverInterface } from '../../utils/MetaBaseObserver.js';
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 
 /**
  * State for {@link WatchedQuery} instances.
@@ -41,7 +41,7 @@ export interface WatchedQueryState<Data> {
 export interface WatchExecuteOptions {
   sql: string;
   parameters: any[];
-  db: AbstractPowerSyncDatabase;
+  db: CommonPowerSyncDatabase;
 }
 
 /**
@@ -96,19 +96,6 @@ export interface WatchedQueryListener<Data> extends BaseListener {
   [WatchedQueryListenerEvent.CLOSED]?: () => void | Promise<void>;
 }
 
-/**
- * @internal
- */
-export const DEFAULT_WATCH_THROTTLE_MS = 30;
-
-/**
- * @internal
- */
-export const DEFAULT_WATCH_QUERY_OPTIONS: WatchedQueryOptions = {
-  throttleMs: DEFAULT_WATCH_THROTTLE_MS,
-  reportFetching: true
-};
-
 /**
  * @public
  */

package/src/client/watched/processors/DifferentialQueryProcessor.ts

@@ -1,10 +1,4 @@
 import { WatchCompatibleQuery, WatchedQuery, WatchedQueryListener, WatchedQueryOptions } from '../WatchedQuery.js';
-import {
-  AbstractQueryProcessor,
-  AbstractQueryProcessorOptions,
-  LinkQueryOptions,
-  MutableWatchedQueryState
-} from './AbstractQueryProcessor.js';
 
 /**
  * Represents an updated row in a differential watched query.
@@ -76,7 +70,6 @@ export interface DifferentialWatchedQueryOptions<RowType> extends WatchedQueryOp
    * Row comparator used to identify and compare rows in the result set.
    * If not provided, the default comparator will be used which keys items by their `id` property if available,
    * otherwise it uses JSON stringification of the entire item for keying and comparison.
-   * @defaultValue {@link DEFAULT_ROW_COMPARATOR}
    */
   rowComparator?: DifferentialWatchedQueryComparator<RowType>;
 }
@@ -110,219 +103,3 @@ export type DifferentialWatchedQuery<RowType> = WatchedQuery<
   DifferentialWatchedQuerySettings<RowType>,
   DifferentialWatchedQueryListener<RowType>
 >;
-
-/**
- * @internal
- */
-export interface DifferentialQueryProcessorOptions<RowType> extends AbstractQueryProcessorOptions<
-  RowType[],
-  DifferentialWatchedQuerySettings<RowType>
-> {
-  rowComparator?: DifferentialWatchedQueryComparator<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.
- *
- * @internal
- */
-export const EMPTY_DIFFERENTIAL = {
-  added: [],
-  all: [],
-  removed: [],
-  updated: [],
-  unchanged: []
-};
-
-/**
- * Default implementation of the {@link DifferentialWatchedQueryComparator} for watched queries.
- * It keys items by their `id` property if available, alternatively it uses JSON stringification
- * of the entire item for the key and comparison.
- *
- * @internal
- */
-export const DEFAULT_ROW_COMPARATOR: DifferentialWatchedQueryComparator<any> = {
-  keyBy: (item) => {
-    if (item && typeof item == 'object' && typeof item['id'] == 'string') {
-      return item['id'];
-    }
-    return JSON.stringify(item);
-  },
-  compareBy: (item) => JSON.stringify(item)
-};
-
-/**
- * Uses the PowerSync onChange event to trigger watched queries.
- * Results are emitted on every change of the relevant tables.
- * @internal
- */
-export class DifferentialQueryProcessor<RowType>
-  extends AbstractQueryProcessor<ReadonlyArray<Readonly<RowType>>, DifferentialWatchedQuerySettings<RowType>>
-  implements DifferentialWatchedQuery<RowType>
-{
-  protected comparator: DifferentialWatchedQueryComparator<RowType>;
-
-  constructor(protected options: DifferentialQueryProcessorOptions<RowType>) {
-    super(options);
-    this.comparator = options.rowComparator ?? DEFAULT_ROW_COMPARATOR;
-  }
-
-  /*
-   * @returns If the sets are equal
-   */
-  protected differentiate(
-    current: RowType[],
-    previousMap: DataHashMap<RowType>
-  ): { diff: WatchedQueryDifferential<RowType>; map: DataHashMap<RowType>; hasChanged: boolean } {
-    const { keyBy, compareBy } = this.comparator;
-
-    let hasChanged = false;
-    const currentMap = new Map<string, { hash: string; item: RowType }>();
-    const removedTracker = new Set(previousMap.keys());
-
-    // Allow mutating to populate the data temporarily.
-    const diff = {
-      all: [] as RowType[],
-      added: [] as RowType[],
-      removed: [] as RowType[],
-      updated: [] as WatchedQueryRowDifferential<RowType>[],
-      unchanged: [] as RowType[]
-    };
-
-    /**
-     * Looping over the current result set array is important to preserve
-     * the ordering of the result set.
-     * We can replace items in the current array with previous object references if they are equal.
-     */
-    for (const item of current) {
-      const key = keyBy(item);
-      const hash = compareBy(item);
-      currentMap.set(key, { hash, item });
-
-      const previousItem = previousMap.get(key);
-      if (!previousItem) {
-        // New item
-        hasChanged = true;
-        diff.added.push(item);
-        diff.all.push(item);
-      } else {
-        // Existing item
-        if (hash == previousItem.hash) {
-          diff.unchanged.push(previousItem.item);
-          // Use the previous object reference
-          diff.all.push(previousItem.item);
-          // update the map to preserve the reference
-          currentMap.set(key, previousItem);
-        } else {
-          hasChanged = true;
-          diff.updated.push({ current: item, previous: previousItem.item });
-          // Use the new reference
-          diff.all.push(item);
-        }
-      }
-      // The item is present, we don't consider it removed
-      removedTracker.delete(key);
-    }
-
-    diff.removed = Array.from(removedTracker).map((key) => previousMap.get(key)!.item);
-    hasChanged = hasChanged || diff.removed.length > 0;
-
-    return {
-      diff,
-      hasChanged,
-      map: currentMap
-    };
-  }
-
-  protected async linkQuery(options: LinkQueryOptions<WatchedQueryDifferential<RowType>>): Promise<void> {
-    const { db, watchOptions } = this.options;
-    const { abortSignal } = options;
-
-    const compiledQuery = watchOptions.query.compile();
-    const tables = await db.resolveTables(compiledQuery.sql, compiledQuery.parameters as any[], {
-      tables: options.settings.triggerOnTables
-    });
-
-    let currentMap: DataHashMap<RowType> = new Map();
-
-    // populate the currentMap from the placeholder data
-    this.state.data.forEach((item) => {
-      currentMap.set(this.comparator.keyBy(item), {
-        hash: this.comparator.compareBy(item),
-        item
-      });
-    });
-
-    db.onChangeWithCallback(
-      {
-        onChange: async () => {
-          if (this.closed || 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: Partial<MutableWatchedQueryState<RowType[]>> = {};
-
-            // 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;
-            }
-
-            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 (this.state.error) {
-              partialStateUpdate.error = null;
-            }
-
-            if (Object.keys(partialStateUpdate).length > 0) {
-              await this.updateState(partialStateUpdate);
-            }
-          } catch (error: any) {
-            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
-      }
-    );
-  }
-}