@powersync/common 1.57.1 → 2.0.0

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

@@ -1,11 +1,4 @@
 import { WatchCompatibleQuery, WatchedQuery, WatchedQueryOptions } from '../WatchedQuery.js';
-import {
-  AbstractQueryProcessor,
-  AbstractQueryProcessorOptions,
-  LinkQueryOptions,
-  MutableWatchedQueryState
-} from './AbstractQueryProcessor.js';
-import { WatchedQueryComparator } from './comparators.js';
 
 /**
  * Settings for {@link WatchedQuery} instances created via {@link Query#watch}.
@@ -22,107 +15,3 @@ export interface WatchedQuerySettings<DataType> extends WatchedQueryOptions {
  * @public
  */
 export type StandardWatchedQuery<DataType> = WatchedQuery<DataType, WatchedQuerySettings<DataType>>;
-
-/**
- * @internal
- */
-export interface OnChangeQueryProcessorOptions<Data> extends AbstractQueryProcessorOptions<
-  Data,
-  WatchedQuerySettings<Data>
-> {
-  comparator?: WatchedQueryComparator<Data>;
-}
-
-/**
- * Uses the PowerSync onChange event to trigger watched queries.
- * Results are emitted on every change of the relevant tables.
- * @internal
- */
-export class OnChangeQueryProcessor<Data> extends AbstractQueryProcessor<Data, WatchedQuerySettings<Data>> {
-  constructor(protected options: OnChangeQueryProcessorOptions<Data>) {
-    super(options);
-  }
-
-  /**
-   * @returns If the sets are equal
-   */
-  protected checkEquality(current: Data, previous: Data): boolean {
-    // Use the provided comparator if available. Assume values are unique if not available.
-    return this.options.comparator?.checkEquality?.(current, previous) ?? false;
-  }
-
-  protected async linkQuery(options: LinkQueryOptions<Data>): 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
-    });
-
-    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<Data>> & { data?: Data } = {};
-
-            // Always run the query if an underlying table has changed
-            const result = await watchOptions.query.execute({
-              sql: compiledQuery.sql,
-              // Allows casting from ReadOnlyArray[unknown] to Array<unknown>
-              // This allows simpler compatibility with PowerSync queries
-              parameters: [...compiledQuery.parameters],
-              db: this.options.db
-            });
-
-            if (abortSignal.aborted) {
-              return;
-            }
-
-            if (this.reportFetching) {
-              partialStateUpdate.isFetching = false;
-            }
-
-            if (this.state.isLoading) {
-              partialStateUpdate.isLoading = false;
-            }
-
-            // Check if the result has changed
-            if (!this.checkEquality(result, this.state.data)) {
-              Object.assign(partialStateUpdate, {
-                data: result
-              });
-            }
-
-            if (this.state.error) {
-              partialStateUpdate.error = null;
-            }
-
-            if (Object.keys(partialStateUpdate).length > 0) {
-              await this.updateState(partialStateUpdate);
-            }
-          } catch (error: 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
-      }
-    );
-  }
-}

package/src/db/DBAdapter.ts

@@ -3,52 +3,43 @@
  * different SQLite DB implementations.
  */
 
-import { BaseListener, BaseObserverInterface } from '../utils/BaseObserver.js';
+import { BaseListener, BaseObserver } from '../utils/BaseObserver.js';
+import {
+  QueryResult,
+  queryResultFromRaw,
+  queryResultWithoutRows,
+  RawQueryResult,
+  SqliteRecord
+} from './QueryResult.js';
 
 /**
- * TODO most of these types could be exported to a common `types` package
- * which is used by the DB adapter libraries as well.
- */
-
-/**
- * Object returned by SQL Query executions.
- *
  * @public
  */
-export type QueryResult = {
-  /** Represents the auto-generated row id if applicable. */
-  insertId?: number;
+export interface DBGetUtils {
   /**
-   * Number of affected rows reported by SQLite for a write query.
+   *  Execute a read-only query and return results.
    *
-   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
-   * `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
-   * Use a `RETURNING` clause and inspect `rows` when you need to confirm which rows changed.
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional array of parameters to bind to the query
+   * @returns An array of results
    */
-  rowsAffected: number;
-  /** if status is undefined or 0 this object will contain the query results */
-  rows?: {
-    /** Raw array with all dataset */
-    _array: any[];
-    /** The length of the dataset */
-    length: number;
-    /** A convenience function to acess the index based the row object
-     * @param idx - the row index
-     * @returns the row structure identified by column names
-     */
-    item: (idx: number) => any;
-  };
-};
-
-/**
- * @public
- */
-export interface DBGetUtils {
-  /** Execute a read-only query and return results. */
   getAll<T>(sql: string, parameters?: any[]): Promise<T[]>;
-  /** Execute a read-only query and return the first result, or null if the ResultSet is empty. */
+  /**
+   * Execute a read-only query and return the first result, or null if the ResultSet is empty.
+   *
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional array of parameters to bind to the query
+   * @returns The first result if found, or null if no results are returned
+   */
   getOptional<T>(sql: string, parameters?: any[]): Promise<T | null>;
-  /** Execute a read-only query and return the first result, error if the ResultSet is empty. */
+  /**
+   * Execute a read-only query and return the first result, error if the ResultSet is empty.
+   *
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional array of parameters to bind to the query
+   * @returns The first result matching the query
+   * @throws Error if no rows are returned
+   */
   get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
 
@@ -56,97 +47,91 @@ export interface DBGetUtils {
  * @public
  */
 export interface SqlExecutor {
-  /** Execute a single write statement. */
-  execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
   /**
-   * Execute a single write statement and return raw results.
-   * Unlike `execute`, which returns an object with structured key-value pairs,
-   * `executeRaw` returns a nested array of raw values, where each row is
-   * represented as an array of column values without field names.
-   *
-   * Example result:
-   *
-   * ```JavaScript
-   * [ [ '1', 'list 1', '33', 'Post content', '1' ] ]
-   * ```
+   * Execute a SQL write (INSERT/UPDATE/DELETE) query
+   * and optionally return results.
    *
-   * Where as `execute`'s `rows._array` would have been:
+   * When using the default client-side [JSON-based view system](https://docs.powersync.com/architecture/client-architecture#client-side-schema-and-sqlite-database-structure),
+   * the returned result's `rowsAffected` may be `0` for successful `UPDATE` and `DELETE` statements.
+   * Use a `RETURNING` clause and inspect `result.rows` when you need to confirm which rows changed.
    *
-   * ```JavaScript
-   * [ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]
-   * ```
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional array of parameters to bind to the query
+   * @returns The query result as an object with structured key-value pairs
    */
-  executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
+  execute: <T = SqliteRecord>(query: string, params?: any[] | undefined) => Promise<QueryResult<T>>;
 
-  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
-}
+  /**
+   * Execute a SQL write (INSERT/UPDATE/DELETE) query directly on the database without any PowerSync processing.
+   * This bypasses certain PowerSync abstractions and is useful for accessing the raw database results.
+   *
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional array of parameters to bind to the query
+   * @returns The {@link RawQueryResult} representing each row as an array.
+   */
+  executeRaw: (query: string, params?: any[] | undefined) => Promise<RawQueryResult>;
 
-/**
- * @public
- */
-export interface LockContext extends SqlExecutor, DBGetUtils {
   /**
-   * How the connection has been opened.
+   * Execute a write query (INSERT/UPDATE/DELETE) multiple times with each parameter set
+   * and optionally return results.
+   * This is faster than executing separately with each parameter set.
    *
-   * `writer` indicates that the lock context is capable of writing to the database.
-   * `queryOnly` indicates that the lock context has been opened in a readwrite mode, but a `PRAGMA query_only = TRUE`
-   * disabled writes.
-   * `readOnly` indicates that the lock context has been opened by passing `SQLITE_OPEN_READONLY` to `sqlite3_open_v2`.
+   * @param sql - The SQL query to execute
+   * @param parameters - Optional 2D array of parameter sets, where each inner array is a set of parameters for one execution
+   * @returns The query result
    */
-  connectionType?: 'writer' | 'queryOnly' | 'readOnly';
+  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult<never>>;
 }
 
 /**
- * Implements {@link DBGetUtils} on a {@link SqlExecutor}.
- *
- * @internal
+ * @public
  */
-export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omit<SqlExecutor, 'executeBatch'>>(
-  Base: TBase
-) {
-  return class extends Base implements DBGetUtils, SqlExecutor {
-    async getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
-      const res = await this.execute(sql, parameters);
-      return res.rows?._array ?? [];
-    }
+export abstract class LockContext implements SqlExecutor, DBGetUtils {
+  abstract executeRaw<T>(query: string, params?: any[] | undefined): Promise<RawQueryResult>;
 
-    async getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
-      const res = await this.execute(sql, parameters);
-      return res.rows?.item(0) ?? null;
+  async getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
+    const rs = await this.execute<T>(sql, parameters);
+    return Array.from(rs);
+  }
+
+  async getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
+    const { array } = await this.execute<T>(sql, parameters);
+    if (array.length > 0) {
+      return array[0];
     }
 
-    async get<T>(sql: string, parameters?: any[]): Promise<T> {
-      const res = await this.execute(sql, parameters);
-      const first = res.rows?.item(0);
-      if (!first) {
-        throw new Error('Result set is empty');
-      }
-      return first;
+    return null;
+  }
+
+  async get<T>(sql: string, parameters?: any[]): Promise<T> {
+    const row = await this.getOptional<T>(sql, parameters);
+    if (row == null) {
+      throw new Error('Result set is empty');
     }
 
-    async executeBatch(query: string, params: any[][] = []): Promise<QueryResult> {
-      // If this context can run batch statements natively, use that.
-      // @ts-ignore
-      if (super.executeBatch) {
-        // @ts-ignore
-        return super.executeBatch(query, params);
-      }
+    return row;
+  }
 
-      // Emulate executeBatch by running statements individually.
-      let lastInsertId: number | undefined;
-      let rowsAffected = 0;
-      for (const set of params) {
-        const result = await this.execute(query, set);
-        lastInsertId = result.insertId;
-        rowsAffected += result.rowsAffected;
-      }
+  async execute<T = SqliteRecord>(query: string, params?: any[] | undefined): Promise<QueryResult<T>> {
+    const raw = await this.executeRaw(query, params);
+    return queryResultFromRaw(raw);
+  }
 
-      return {
-        rowsAffected,
-        insertId: lastInsertId
-      };
+  async executeBatch(query: string, params: any[][] = []): Promise<QueryResult<never>> {
+    // Emulate executeBatch by running statements individually.
+    let lastInsertId: number | undefined;
+    let rowsAffected = 0;
+    for (const set of params) {
+      const result = await this.execute(query, set);
+      lastInsertId = result.insertId;
+      rowsAffected += result.rowsAffected ?? 0;
     }
-  };
+
+    return queryResultWithoutRows({
+      rowsAffected,
+      insertId: lastInsertId
+    });
+  }
 }
 
 /**
@@ -154,46 +139,16 @@ export function DBGetUtilsDefaultMixin<TBase extends new (...args: any[]) => Omi
  */
 export interface Transaction extends LockContext {
   /** Commit multiple changes to the local DB using the Transaction context. */
-  commit: () => Promise<QueryResult>;
+  commit: () => Promise<void>;
   /** Roll back multiple attempted changes using the Transaction context. */
-  rollback: () => Promise<QueryResult>;
-}
-
-/**
- * Update table operation numbers from SQLite
- *
- * @public
- */
-export enum RowUpdateType {
-  SQLITE_INSERT = 18,
-  SQLITE_DELETE = 9,
-  SQLITE_UPDATE = 23
-}
-
-/**
- * @public
- */
-export interface TableUpdateOperation {
-  opType: RowUpdateType;
-  rowId: number;
-}
-/**
- * Notification of an update to one or more tables, for the purpose of realtime change notifications.
- *
- * @public
- */
-export interface UpdateNotification extends TableUpdateOperation {
-  table: string;
+  rollback: () => Promise<void>;
 }
 
 /**
  * @public
  */
 export interface BatchedUpdateNotification {
-  // TODO (breaking change): Normalize to only including tables
-  rawUpdates: UpdateNotification[];
   tables: string[];
-  groupedUpdates: Record<string, TableUpdateOperation[]>;
 }
 
 /**
@@ -206,7 +161,7 @@ export interface DBAdapterListener extends BaseListener {
    * without the need for a major version bump
    * The DB adapter can also batch update notifications if supported.
    */
-  tablesUpdated: (updateNotification: BatchedUpdateNotification | UpdateNotification) => void;
+  tablesUpdated: (updateNotification: BatchedUpdateNotification) => void;
 }
 
 /**
@@ -219,116 +174,92 @@ export interface DBLockOptions {
 /**
  * @public
  */
-export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
-  name: string;
-  close: () => void | Promise<void>;
-  readLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
-  writeLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
+export abstract class DBAdapter extends BaseObserver<DBAdapterListener> implements SqlExecutor, DBGetUtils {
+  abstract get name(): string;
+
+  abstract close(): void | Promise<void>;
+
+  abstract readLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T>;
+  abstract writeLock<T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions): Promise<T>;
 
   /**
    * This method refreshes the schema information across all connections. This is for advanced use cases, and should generally not be needed.
    */
-  refreshSchema: () => Promise<void>;
-}
+  abstract refreshSchema(): Promise<void>;
 
-/**
- * @public
- */
-export interface DBAdapter extends ConnectionPool, SqlExecutor, DBGetUtils {
-  readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
-  writeTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
-}
-
-/**
- * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool#readLock} and
- * {@link ConnectionPool#writeLock}.
- *
- * @internal
- */
-export function DBAdapterDefaultMixin<TBase extends new (...args: any[]) => ConnectionPool>(Base: TBase) {
-  return class extends Base implements DBAdapter {
-    readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
-      return this.readLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
-    }
+  readTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.readLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
+  }
 
-    writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
-      return this.writeLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
-    }
+  writeTransaction<T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions): Promise<T> {
+    return this.writeLock((ctx) => TransactionImplementation.runWith(ctx, fn), options);
+  }
 
-    getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
-      return this.readLock((ctx) => ctx.getAll(sql, parameters));
-    }
+  getAll<T>(sql: string, parameters?: any[]): Promise<T[]> {
+    return this.readLock((ctx) => ctx.getAll(sql, parameters));
+  }
 
-    getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
-      return this.readLock((ctx) => ctx.getOptional(sql, parameters));
-    }
+  getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
+    return this.readLock((ctx) => ctx.getOptional(sql, parameters));
+  }
 
-    get<T>(sql: string, parameters?: any[]): Promise<T> {
-      return this.readLock((ctx) => ctx.get(sql, parameters));
-    }
+  get<T>(sql: string, parameters?: any[]): Promise<T> {
+    return this.readLock((ctx) => ctx.get(sql, parameters));
+  }
 
-    execute(query: string, params?: any[]): Promise<QueryResult> {
-      return this.writeLock((ctx) => ctx.execute(query, params));
-    }
+  execute<T>(query: string, params?: any[]): Promise<QueryResult<T>> {
+    return this.writeLock((ctx) => ctx.execute(query, params));
+  }
 
-    executeRaw(query: string, params?: any[]): Promise<any[][]> {
-      return this.writeLock((ctx) => ctx.executeRaw(query, params));
-    }
+  executeRaw(query: string, params?: any[]): Promise<RawQueryResult> {
+    return this.writeLock((ctx) => ctx.executeRaw(query, params));
+  }
 
-    executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
-      return this.writeTransaction((tx) => tx.executeBatch(query, params));
-    }
-  };
+  executeBatch(query: string, params?: any[][]): Promise<QueryResult<never>> {
+    return this.writeTransaction((tx) => tx.executeBatch(query, params));
+  }
 }
 
-class BaseTransaction implements SqlExecutor {
+class TransactionImplementation extends LockContext {
   private finalized = false;
 
-  constructor(private inner: SqlExecutor) {}
+  constructor(private inner: LockContext) {
+    super();
+  }
 
-  async commit(): Promise<QueryResult> {
+  async commit(): Promise<void> {
     if (this.finalized) {
-      return { rowsAffected: 0 };
+      return;
     }
     this.finalized = true;
-    return this.inner.execute('COMMIT');
+    await this.inner.execute('COMMIT');
   }
 
-  async rollback(): Promise<QueryResult> {
+  async rollback(): Promise<void> {
     if (this.finalized) {
-      return { rowsAffected: 0 };
+      return;
     }
     this.finalized = true;
-    return this.inner.execute('ROLLBACK');
+    await this.inner.execute('ROLLBACK');
   }
 
-  execute(query: string, params?: any[] | undefined): Promise<QueryResult> {
+  execute<T>(query: string, params?: any[] | undefined): Promise<QueryResult<T>> {
     return this.inner.execute(query, params);
   }
 
-  executeRaw(query: string, params?: any[] | undefined): Promise<any[][]> {
+  executeRaw(query: string, params?: any[] | undefined): Promise<RawQueryResult> {
     return this.inner.executeRaw(query, params);
   }
 
-  executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
+  executeBatch(query: string, params?: any[][]): Promise<QueryResult<never>> {
     return this.inner.executeBatch(query, params);
   }
-}
 
-class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction) {
   static async runWith<T>(ctx: LockContext, fn: (tx: Transaction) => Promise<T>): Promise<T> {
     let tx = new TransactionImplementation(ctx);
 
-    // For write transactions, use BEGIN IMMEDIATE to immediately obtain a write lock on the database (instead of doing
-    // that on the first statement). If we have a genuine read-only connection, we also use BEGIN IMMEDIATE there: In
-    // WAL mode, that ensures we pin the current state of the database (instead of the state at the first statement in
-    // the transaction). But if we have a "fake" read-only connection implemented through `pragma query_only = true`, we
-    // can't use this trick because it would attempt to lock the connection. So there, we use a regular `BEGIN`
-    // statement.
-    const useBeginImmediate = ctx.connectionType != 'queryOnly';
-
     try {
-      await ctx.execute(useBeginImmediate ? 'BEGIN IMMEDIATE' : 'BEGIN');
+      await ctx.execute('BEGIN IMMEDIATE');
 
       const result = await fn(tx);
       await tx.commit();
@@ -344,19 +275,3 @@ class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction)
     }
   }
 }
-
-/**
- * @internal
- */
-export function isBatchedUpdateNotification(
-  update: BatchedUpdateNotification | UpdateNotification
-): update is BatchedUpdateNotification {
-  return 'tables' in update;
-}
-
-/**
- * @internal
- */
-export function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification) {
-  return isBatchedUpdateNotification(update) ? update.tables : [update.table];
-}