@powersync/common 0.0.0-dev-20260503073249 → 0.0.0-dev-20260630141119

package/src/client/compilableQueryWatch.ts

@@ -1,14 +1,20 @@
 import { CompilableQuery } from './../types/types.js';
-import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase, SQLWatchOptions } from './CommonPowerSyncDatabase.js';
 import { runOnSchemaChange } from './runOnSchemaChange.js';
 
+/**
+ * @public
+ */
 export interface CompilableQueryWatchHandler<T> {
   onResult: (results: T[]) => void;
   onError?: (error: Error) => void;
 }
 
+/**
+ * @public
+ */
 export function compilableQueryWatch<T>(
-  db: AbstractPowerSyncDatabase,
+  db: CommonPowerSyncDatabase,
   query: CompilableQuery<T>,
   handler: CompilableQueryWatchHandler<T>,
   options?: SQLWatchOptions
@@ -36,8 +42,7 @@ export function compilableQueryWatch<T>(
             } catch (error: any) {
               onError(error);
             }
-          },
-          onError
+          }
         },
         {
           ...(options ?? {}),

package/src/client/connection/PowerSyncBackendConnector.ts

@@ -1,6 +1,9 @@
 import { PowerSyncCredentials } from './PowerSyncCredentials.js';
-import type { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase } from '../CommonPowerSyncDatabase.js';
 
+/**
+ * @public
+ */
 export interface PowerSyncBackendConnector {
   /** Allows the PowerSync client to retrieve an authentication token from your backend
    * which is used to authenticate against the PowerSync service.
@@ -17,9 +20,9 @@ export interface PowerSyncBackendConnector {
 
   /** Upload local changes to the app backend.
    *
-   * Use {@link AbstractPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
+   * Use {@link CommonPowerSyncDatabase.getCrudBatch} to get a batch of changes to upload.
    *
    * Any thrown errors will result in a retry after the configured wait period (default: 5 seconds).
    */
-  uploadData: (database: AbstractPowerSyncDatabase) => Promise<void>;
+  uploadData: (database: CommonPowerSyncDatabase) => Promise<void>;
 }

package/src/client/connection/PowerSyncCredentials.ts

@@ -1,3 +1,6 @@
+/**
+ * @public
+ */
 export interface PowerSyncCredentials {
   endpoint: string;
   token: string;

package/src/client/runOnSchemaChange.ts

@@ -1,8 +1,11 @@
-import { AbstractPowerSyncDatabase, SQLWatchOptions } from './AbstractPowerSyncDatabase.js';
+import { CommonPowerSyncDatabase, SQLWatchOptions } from './CommonPowerSyncDatabase.js';
 
+/**
+ * @internal
+ */
 export function runOnSchemaChange(
   callback: (signal: AbortSignal) => void,
-  db: AbstractPowerSyncDatabase,
+  db: CommonPowerSyncDatabase,
   options?: SQLWatchOptions
 ): void {
   const triggerWatchedQuery = () => {

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

@@ -2,6 +2,8 @@ import { CrudEntry } from './CrudEntry.js';
 
 /**
  * A batch of client-side changes.
+ *
+ * @public
  */
 export class CrudBatch {
   constructor(

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

@@ -2,11 +2,15 @@
  * 64-bit unsigned integer stored as a string in base-10.
  *
  * Not sortable as a string.
+ *
+ * @public
  */
 export type OpId = string;
 
 /**
  * Type of local change.
+ *
+ * @public
  */
 export enum UpdateType {
   /** Insert or replace existing row. All non-null columns are included in the data. Generated by INSERT statements. */
@@ -17,39 +21,12 @@ export enum UpdateType {
   DELETE = 'DELETE'
 }
 
-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.
    */
@@ -90,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/bucket/CrudTransaction.ts

@@ -1,6 +1,9 @@
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry } from './CrudEntry.js';
 
+/**
+ * @public
+ */
 export class CrudTransaction extends CrudBatch {
   constructor(
     /**

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/stream/JsonValue.ts

@@ -0,0 +1,11 @@
+type JSONValue = string | number | boolean | null | undefined | JSONObject | JSONArray;
+
+interface JSONObject {
+  [key: string]: JSONValue;
+}
+type JSONArray = JSONValue[];
+
+/**
+ * @public
+ */
+export type StreamingSyncRequestParameterType = JSONValue;

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

@@ -1,7 +1,8 @@
-import { AbstractPowerSyncDatabase } from '../AbstractPowerSyncDatabase.js';
-
 /**
- * A description of a sync stream, consisting of its {@link name} and the {@link parameters} used when subscribing.
+ * A description of a sync stream, consisting of its {@link SyncStreamDescription.name} and the
+ * {@link SyncStreamDescription.parameters} used when subscribing.
+ *
+ * @public
  */
 export interface SyncStreamDescription {
   /**
@@ -21,6 +22,8 @@ export interface SyncStreamDescription {
  * Information about a subscribed sync stream.
  *
  * This includes the {@link SyncStreamDescription}, along with information about the current sync status.
+ *
+ * @public
  */
 export interface SyncSubscriptionDescription extends SyncStreamDescription {
   active: boolean;
@@ -28,15 +31,17 @@ export interface SyncSubscriptionDescription extends SyncStreamDescription {
    * Whether this stream subscription is included by default, regardless of whether the stream has explicitly been
    * subscribed to or not.
    *
-   * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-   * happens when a default stream was subscribed explicitly.
+   * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+   * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+   * default stream was subscribed explicitly.
    */
   isDefault: boolean;
   /**
    * Whether this stream has been subscribed to explicitly.
    *
-   * It's possible for both {@link isDefault} and {@link hasExplicitSubscription} to be true at the same time - this
-   * happens when a default stream was subscribed explicitly.
+   * It's possible for both {@link SyncSubscriptionDescription.isDefault} and
+   * {@link SyncSubscriptionDescription.hasExplicitSubscription} to be true at the same time - this happens when a
+   * default stream was subscribed explicitly.
    */
   hasExplicitSubscription: boolean;
   /**
@@ -49,11 +54,14 @@ export interface SyncSubscriptionDescription extends SyncStreamDescription {
    */
   hasSynced: boolean;
   /**
-   * If {@link hasSynced} is true, the last time data from this stream has been synced.
+   * If {@link SyncSubscriptionDescription.hasSynced} is true, the last time data from this stream has been synced.
    */
   lastSyncedAt: Date | null;
 }
 
+/**
+ * @public
+ */
 export interface SyncStreamSubscribeOptions {
   /**
    * A "time to live" for this stream subscription, in seconds.
@@ -73,7 +81,9 @@ 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
  */
 export interface SyncStream extends SyncStreamDescription {
   /**
@@ -82,7 +92,7 @@ export interface SyncStream extends SyncStreamDescription {
    * You should keep a reference to the returned {@link SyncStreamSubscription} object along as you need data for that
    * stream. As soon as {@link SyncStreamSubscription.unsubscribe} is called for all subscriptions on this stream
    * (including subscriptions created on other tabs), the {@link SyncStreamSubscribeOptions.ttl} starts ticking and will
-   * eventually evict the stream (unless {@link subscribe} is called again).
+   * eventually evict the stream (unless {@link SyncStream.subscribe} is called again).
    */
   subscribe(options?: SyncStreamSubscribeOptions): Promise<SyncStreamSubscription>;
 
@@ -94,6 +104,9 @@ export interface SyncStream extends SyncStreamDescription {
   unsubscribeAll(): Promise<void>;
 }
 
+/**
+ * @public
+ */
 export interface SyncStreamSubscription extends SyncStreamDescription {
   /**
    * A promise that resolves once data from in this sync stream has been synced and applied.

package/src/client/triggers/TriggerManager.ts

@@ -2,7 +2,8 @@ import { LockContext } from '../../db/DBAdapter.js';
 
 /**
  * SQLite operations to track changes for with {@link TriggerManager}
- * @experimental
+ *
+ * @experimental @alpha
  */
 export enum DiffTriggerOperation {
   INSERT = 'INSERT',
@@ -11,7 +12,7 @@ export enum DiffTriggerOperation {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the base record structure for all diff records.
  *
@@ -42,7 +43,7 @@ export interface BaseTriggerDiffRecord<TOperationId extends string | number = nu
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite UPDATE operation.
  * This record contains the new value and optionally the previous value.
  * Values are stored as JSON strings.
@@ -62,7 +63,7 @@ export interface TriggerDiffUpdateRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite INSERT operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -77,7 +78,7 @@ export interface TriggerDiffInsertRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Represents a diff record for a SQLite DELETE operation.
  * This record contains the new value represented as a JSON string.
  */
@@ -92,7 +93,7 @@ export interface TriggerDiffDeleteRecord<
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Diffs created by {@link TriggerManager#createDiffTrigger} are stored in a temporary table.
  * This is the record structure for all diff records.
  *
@@ -121,7 +122,7 @@ export type TriggerDiffRecord<TOperationId extends string | number = number> =
   | TriggerDiffDeleteRecord<TOperationId>;
 
 /**
- * @experimental
+ * @experimental @alpha
  * Querying the DIFF table directly with {@link TriggerDiffHandlerContext#withExtractedDiff} will return records
  * with the tracked columns extracted from the JSON value.
  * This type represents the structure of such records.
@@ -150,7 +151,7 @@ export type ExtractedTriggerDiffRecord<T, TOperationId extends string | number =
 };
 
 /**
- * @experimental
+ * @experimental @alpha
  * Hooks used in the creation of a table diff trigger.
  */
 export interface TriggerCreationHooks {
@@ -162,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.
@@ -187,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>>;
 
@@ -213,7 +217,7 @@ interface BaseCreateDiffTriggerOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerManager#createDiffTrigger}.
  */
 export interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
@@ -232,7 +236,7 @@ export interface CreateDiffTriggerOptions extends BaseCreateDiffTriggerOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerRemoveCallback}.
  */
 export interface TriggerRemoveCallbackOptions {
@@ -240,12 +244,12 @@ export interface TriggerRemoveCallbackOptions {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Callback to drop a trigger after it has been created.
  */
 export type TriggerRemoveCallback = (options?: TriggerRemoveCallbackOptions) => Promise<void>;
 /**
- * @experimental
+ * @experimental @alpha
  * Options for {@link TriggerDiffHandlerContext#withDiff}.
  */
 export interface WithDiffOptions {
@@ -260,10 +264,12 @@ export interface WithDiffOptions {
 }
 
 /**
- * @experimental
+ * @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.
    */
@@ -317,7 +323,7 @@ export interface TriggerDiffHandlerContext extends LockContext {
    * Allows querying the database with access to the table containing diff records.
    * The diff table is accessible via the `DIFF` accessor.
    *
-   * This is similar to {@link withDiff} but extracts the row columns from the tracked JSON value. The diff operation
+   * This is similar to {@link TriggerDiffHandlerContext#withDiff} but extracts the row columns from the tracked JSON value. The diff operation
    * data is aliased as `__` columns to avoid column conflicts.
    *
    * For {@link DiffTriggerOperation#DELETE} operations the previous_value columns are extracted for convenience.
@@ -349,7 +355,7 @@ export interface TriggerDiffHandlerContext extends LockContext {
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  * Options for tracking changes to a table with {@link TriggerManager#trackTableDiff}.
  */
 export interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
@@ -361,14 +367,13 @@ export interface TrackDiffOptions extends BaseCreateDiffTriggerOptions {
   onChange: (context: TriggerDiffHandlerContext) => Promise<void>;
 
   /**
-   * The minimum interval, in milliseconds, between {@link onChange} invocations.
-   *  @default {@link DEFAULT_WATCH_THROTTLE_MS}
+   * The minimum interval, in milliseconds, between {@link TrackDiffOptions.onChange} invocations.
    */
   throttleMs?: number;
 }
 
 /**
- * @experimental
+ * @experimental @alpha
  */
 export interface TriggerManager {
   /**
@@ -417,7 +422,7 @@ export interface TriggerManager {
   /**
    * @experimental
    * Tracks changes for a table. Triggering a provided handler on changes.
-   * Uses {@link createDiffTrigger} internally to create a temporary destination table.
+   * Uses {@link TriggerManager.createDiffTrigger} internally to create a temporary destination table.
    *
    * @returns A callback to cleanup the trigger and stop tracking changes.
    *
@@ -471,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/triggers/sanitizeSQL.ts

@@ -1,9 +1,12 @@
 function sanitizeString(input: string): string {
   return `'${input.replace(/'/g, "''")}'`;
 }
+
 /**
  * Helper function for sanitizing UUID input strings.
  * Typically used with {@link sanitizeSQL}.
+ *
+ * @alpha
  */
 export function sanitizeUUID(uuid: string): string {
   const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
@@ -41,6 +44,8 @@ export function sanitizeUUID(uuid: string): string {
  * // Incorrect:
  * sanitizeSQL`New.id = '${myID}'` // Produces double quotes: New.id = ''O''Reilly''
  * ```
+ *
+ * @alpha
  */
 export function sanitizeSQL(strings: TemplateStringsArray, ...values: any[]): string {
   let result = '';