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

package/src/db/DBAdapter.ts

@@ -3,157 +3,157 @@
  * 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.
+ * @public
  */
-
-/**
- * Object returned by SQL Query executions.
- */
-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;
-  };
-};
-
-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>;
 }
 
+/**
+ * @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.
+   * Execute a SQL write (INSERT/UPDATE/DELETE) query
+   * and optionally return results.
    *
-   * Example result:
-   *
-   * ```[ [ '1', 'list 1', '33', 'Post content', '1' ] ]```
+   * 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.
    *
-   * Where as `execute`'s `rows._array` would have been:
+   * @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
+   */
+  execute: <T = SqliteRecord>(query: string, params?: any[] | undefined) => Promise<QueryResult<T>>;
+
+  /**
+   * 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.
    *
-   * ```[ { 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 {@link RawQueryResult} representing each row as an array.
    */
-  executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
+  executeRaw: (query: string, params?: any[] | undefined) => Promise<RawQueryResult>;
 
-  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
+  /**
+   * 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.
+   *
+   * @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
+   */
+  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult<never>>;
 }
 
-export interface LockContext extends SqlExecutor, DBGetUtils {}
-
 /**
- * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ * @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
+    });
+  }
 }
 
+/**
+ * @public
+ */
 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>;
+  rollback: () => Promise<void>;
 }
 
 /**
- * Update table operation numbers from SQLite
+ * @public
  */
-export enum RowUpdateType {
-  SQLITE_INSERT = 18,
-  SQLITE_DELETE = 9,
-  SQLITE_UPDATE = 23
-}
-export interface TableUpdateOperation {
-  opType: RowUpdateType;
-  rowId: number;
-}
-/**
- * Notification of an update to one or more tables, for the purpose of realtime change notifications.
- */
-export interface UpdateNotification extends TableUpdateOperation {
-  table: string;
-}
-
 export interface BatchedUpdateNotification {
-  rawUpdates: UpdateNotification[];
   tables: string[];
-  groupedUpdates: Record<string, TableUpdateOperation[]>;
 }
 
+/**
+ * @public
+ */
 export interface DBAdapterListener extends BaseListener {
   /**
    * Listener for table updates.
@@ -161,105 +161,100 @@ 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;
 }
 
+/**
+ * @public
+ */
 export interface DBLockOptions {
   timeoutMs?: number;
 }
 
-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>;
+/**
+ * @public
+ */
+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>;
-}
-
-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>;
-}
+  abstract refreshSchema(): Promise<void>;
 
-/**
- * A mixin to implement {@link DBAdapter} by delegating to {@link ConnectionPool.readLock} and
- * {@link ConnectionPool.writeLock}.
- */
-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);
 
@@ -280,13 +275,3 @@ class TransactionImplementation extends DBGetUtilsDefaultMixin(BaseTransaction)
     }
   }
 }
-
-export function isBatchedUpdateNotification(
-  update: BatchedUpdateNotification | UpdateNotification
-): update is BatchedUpdateNotification {
-  return 'tables' in update;
-}
-
-export function extractTableUpdates(update: BatchedUpdateNotification | UpdateNotification) {
-  return isBatchedUpdateNotification(update) ? update.tables : [update.table];
-}

package/src/db/QueryResult.ts

@@ -0,0 +1,195 @@
+/**
+ * A SQLite value, either text, a number, a blob value or null.
+ *
+ * @public
+ */
+export type SqliteValue = string | number | bigint | number[] | Uint8Array | null;
+
+/**
+ * A record of SQLite values representing a row.
+ *
+ * @public
+ */
+export type SqliteRecord = Record<string, SqliteValue>;
+
+/**
+ * A representation of query results as JavaScript object.
+ *
+ * @public
+ */
+export interface ResultSet {
+  /**
+   * The amount of rows in the result set.
+   */
+  get length(): number;
+
+  /**
+   * @deprecated Use {@link QueryResult.array} instead.
+   */
+  get _array(): any[];
+
+  /**
+   * @deprecated Use {@link QueryResult.array} instead.
+   */
+  item<T>(idx: number): T;
+}
+
+/**
+ * Shared superinterface for {@link QueryResult} and {@link RawQueryResult}.
+ *
+ * @public
+ */
+export interface BaseQueryResult {
+  /** Represents the auto-generated row id if applicable. */
+  insertId?: number;
+  /**
+   * Number of affected rows reported by SQLite for a write query.
+   *
+   * 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.
+   */
+  rowsAffected?: number;
+}
+
+/**
+ * Object returned by SQL Query executions.
+ *
+ * @public
+ */
+export interface QueryResult<T = SqliteRecord> extends BaseQueryResult, Iterable<T, undefined> {
+  /**
+   * If the query returned rows, the result set containing returned values.
+   */
+  rows?: ResultSet;
+  /**
+   * Rows in this result set.
+   */
+  array: T[];
+}
+
+/**
+ * A raw array-based result set representing rows returned by SQLite.
+ *
+ * @public
+ */
+export interface RawQueryResult extends BaseQueryResult {
+  /**
+   * Names of columns in this result set. Every column has a name, so the length of this array is always equal to the
+   * amount of columns in the result set.
+   *
+   * Note that column names are not necessarily unique, e.g. a `SELECT foo.user, bar.user FROM ...` will have
+   * `['user', 'user']` in this array.
+   */
+  columnNames: string[];
+
+  /**
+   * Rows in the result set.
+   *
+   * Each row has a length equal to {@link RawQueryResult.columnNames}.
+   */
+  rawRows: SqliteValue[][];
+}
+
+function rowToRecord<T>(columnNames: string[], row: SqliteValue[]) {
+  const record: SqliteRecord = {};
+  columnNames.forEach((name, idx) => (record[name] = row[idx]));
+  return record as T;
+}
+
+/**
+ * Creates a query result by mapping raw rows to JavaScript.
+ *
+ * This should not be used with libraries doing this mapping natively, as that is typically more performant.
+ *
+ * @public
+ */
+export function queryResultFromRaw<T>(raw: RawQueryResult): QueryResult<T> {
+  const { insertId, rowsAffected, columnNames, rawRows } = raw;
+  let array: any[] | undefined;
+
+  function loadAsArray() {
+    if (array) return array;
+
+    return (array = rawRows.map((row) => rowToRecord(columnNames, row)));
+  }
+
+  function getRow<T>(idx: number) {
+    if (array) return array[idx];
+    return rowToRecord(columnNames, rawRows[idx]);
+  }
+
+  return {
+    insertId,
+    rowsAffected,
+    get array() {
+      return loadAsArray();
+    },
+    rows: {
+      length: rawRows.length,
+      get _array() {
+        return loadAsArray();
+      },
+      item: getRow
+    } satisfies ResultSet,
+    [Symbol.iterator](): Iterator<T> {
+      let nextIndex = 0;
+
+      return {
+        next: function (): IteratorResult<T, any> {
+          if (nextIndex >= rawRows.length) {
+            return { done: true, value: undefined };
+          }
+
+          const row = getRow(nextIndex);
+          nextIndex++;
+          return { done: false, value: row };
+        }
+      };
+    }
+  };
+}
+
+/**
+ * Creates a query result from rows that have already been mapped to JavaScript.
+ *
+ * @public
+ */
+export function queryResultFromMapped<T>(base: BaseQueryResult, rows?: T[]): QueryResult<T> {
+  if (rows == null) return queryResultWithoutRows(base);
+
+  return {
+    insertId: base.insertId,
+    rowsAffected: base.rowsAffected,
+    array: rows ?? [],
+    rows: {
+      length: rows.length,
+      _array: rows,
+      item(i: number) {
+        return rows[i] as any;
+      }
+    } satisfies ResultSet,
+    [Symbol.iterator](): Iterator<T> {
+      return rows[Symbol.iterator]();
+    }
+  };
+}
+
+/**
+ * Creates a {@link QueryResult} not containing any rows.
+ *
+ * @public
+ */
+export function queryResultWithoutRows(result: BaseQueryResult): QueryResult<never> {
+  return {
+    ...result,
+    array: [],
+    [Symbol.iterator](): Iterator<never> {
+      return {
+        next() {
+          return { done: true, value: undefined };
+        }
+      };
+    }
+  };
+}