@powersync/common 1.47.0 → 1.49.0

package/src/client/triggers/TriggerManagerImpl.ts

@@ -9,6 +9,7 @@ import {
   TriggerManager,
   TriggerManagerConfig,
   TriggerRemoveCallback,
+  TriggerRemoveCallbackOptions,
   WithDiffOptions
 } from './TriggerManager.js';
 
@@ -201,6 +202,7 @@ export class TriggerManagerImpl implements TriggerManager {
       columns,
       when,
       hooks,
+      setupContext,
       // Fall back to the provided default if not given on this level
       useStorage = this.defaultConfig.useStorageByDefault
     } = options;
@@ -268,13 +270,19 @@ export class TriggerManagerImpl implements TriggerManager {
      * we need to ensure we can cleanup the created resources.
      * We unfortunately cannot rely on transaction rollback.
      */
-    const cleanup = async () => {
+    const cleanup = async (options?: TriggerRemoveCallbackOptions) => {
+      const { context } = options ?? {};
       disposeWarningListener();
-      return this.db.writeLock(async (tx) => {
+      const doCleanup = async (tx: LockContext) => {
         await this.removeTriggers(tx, triggerIds);
-        await tx.execute(/* sql */ `DROP TABLE IF EXISTS ${destination};`);
+        await tx.execute(`DROP TABLE IF EXISTS ${destination};`);
         await releaseStorageClaim?.();
-      });
+      };
+      if (context) {
+        await doCleanup(context);
+      } else {
+        await this.db.writeLock(doCleanup);
+      }
     };
 
     const setup = async (tx: LockContext) => {
@@ -360,11 +368,15 @@ export class TriggerManagerImpl implements TriggerManager {
     };
 
     try {
-      await this.db.writeLock(setup);
+      if (setupContext) {
+        await setup(setupContext);
+      } else {
+        await this.db.writeLock(setup);
+      }
       return cleanup;
     } catch (error) {
       try {
-        await cleanup();
+        await cleanup(setupContext ? { context: setupContext } : undefined);
       } catch (cleanupError) {
         throw new AggregateError([error, cleanupError], 'Error during operation and cleanup');
       }

package/src/db/DBAdapter.ts

@@ -41,7 +41,7 @@ export interface DBGetUtils {
   get<T>(sql: string, parameters?: any[]): Promise<T>;
 }
 
-export interface LockContext extends DBGetUtils {
+export interface SqlExecutor {
   /** Execute a single write statement. */
   execute: (query: string, params?: any[] | undefined) => Promise<QueryResult>;
   /**
@@ -59,6 +59,61 @@ export interface LockContext extends DBGetUtils {
    * ```[ { id: '33', name: 'list 1', content: 'Post content', list_id: '1' } ]```
    */
   executeRaw: (query: string, params?: any[] | undefined) => Promise<any[][]>;
+
+  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
+}
+
+export interface LockContext extends SqlExecutor, DBGetUtils {}
+
+/**
+ * Implements {@link DBGetUtils} on a {@link SqlRunner}.
+ */
+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 ?? [];
+    }
+
+    async getOptional<T>(sql: string, parameters?: any[]): Promise<T | null> {
+      const res = await this.execute(sql, parameters);
+      return res.rows?.item(0) ?? null;
+    }
+
+    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;
+    }
+
+    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);
+      }
+
+      // 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;
+      }
+
+      return {
+        rowsAffected,
+        insertId: lastInsertId
+      };
+    }
+  };
 }
 
 export interface Transaction extends LockContext {
@@ -107,22 +162,119 @@ export interface DBLockOptions {
   timeoutMs?: number;
 }
 
-export interface DBAdapter extends BaseObserverInterface<DBAdapterListener>, DBGetUtils {
-  close: () => void | Promise<void>;
-  execute: (query: string, params?: any[]) => Promise<QueryResult>;
-  executeRaw: (query: string, params?: any[]) => Promise<any[][]>;
-  executeBatch: (query: string, params?: any[][]) => Promise<QueryResult>;
+export interface ConnectionPool extends BaseObserverInterface<DBAdapterListener> {
   name: string;
+  close: () => void | Promise<void>;
   readLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
-  readTransaction: <T>(fn: (tx: Transaction) => Promise<T>, options?: DBLockOptions) => Promise<T>;
   writeLock: <T>(fn: (tx: LockContext) => Promise<T>, options?: DBLockOptions) => Promise<T>;
-  writeTransaction: <T>(fn: (tx: Transaction) => 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>;
+}
+
+/**
+ * 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);
+    }
+
+    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));
+    }
+
+    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));
+    }
+
+    execute(query: string, params?: any[]): Promise<QueryResult> {
+      return this.writeLock((ctx) => ctx.execute(query, params));
+    }
+
+    executeRaw(query: string, params?: any[]): Promise<any[][]> {
+      return this.writeLock((ctx) => ctx.executeRaw(query, params));
+    }
+
+    executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
+      return this.writeTransaction((tx) => tx.executeBatch(query, params));
+    }
+  };
+}
+
+class BaseTransaction implements SqlExecutor {
+  private finalized = false;
+
+  constructor(private inner: SqlExecutor) {}
+
+  async commit(): Promise<QueryResult> {
+    if (this.finalized) {
+      return { rowsAffected: 0 };
+    }
+    this.finalized = true;
+    return this.inner.execute('COMMIT');
+  }
+
+  async rollback(): Promise<QueryResult> {
+    if (this.finalized) {
+      return { rowsAffected: 0 };
+    }
+    this.finalized = true;
+    return this.inner.execute('ROLLBACK');
+  }
+
+  execute(query: string, params?: any[] | undefined): Promise<QueryResult> {
+    return this.inner.execute(query, params);
+  }
+
+  executeRaw(query: string, params?: any[] | undefined): Promise<any[][]> {
+    return this.inner.executeRaw(query, params);
+  }
+
+  executeBatch(query: string, params?: any[][]): Promise<QueryResult> {
+    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);
+
+    try {
+      await ctx.execute('BEGIN IMMEDIATE');
+
+      const result = await fn(tx);
+      await tx.commit();
+      return result;
+    } catch (ex) {
+      try {
+        await tx.rollback();
+      } catch (ex2) {
+        // In rare cases, a rollback may fail.
+        // Safe to ignore.
+      }
+      throw ex;
+    }
+  }
+}
+
 export function isBatchedUpdateNotification(
   update: BatchedUpdateNotification | UpdateNotification
 ): update is BatchedUpdateNotification {

package/src/db/schema/RawTable.ts

@@ -1,8 +1,23 @@
+import { TableOrRawTableOptions } from './Table.js';
+
 /**
- * A pending variant of a {@link RawTable} that doesn't have a name (because it would be inferred when creating the
- * schema).
+ * Instructs PowerSync to sync data into a "raw" table.
+ *
+ * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
+ * using client-side table and column constraints.
+ *
+ * To collect local writes to raw tables with PowerSync, custom triggers are required. See
+ * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
+ * using raw tables.
+ *
+ * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+ *
+ * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
+ * stability guarantees.
  */
-export type RawTableType = {
+export type RawTableType = RawTableTypeWithStatements | InferredRawTableType;
+
+interface RawTableTypeWithStatements {
   /**
    * The statement to run when PowerSync detects that a row needs to be inserted or updated.
    */
@@ -11,7 +26,44 @@ export type RawTableType = {
    * The statement to run when PowerSync detects that a row needs to be deleted.
    */
   delete: PendingStatement;
-};
+
+  /**
+   * An optional statement to run when `disconnectAndClear()` is called on a PowerSync database.
+   */
+  clear?: string;
+}
+
+/**
+ * The schema of a {@link RawTableType} in the local database.
+ *
+ * This information is optional when declaring raw tables. However, providing it allows the sync client to infer `put`
+ * and `delete` statements automatically.
+ */
+interface RawTableSchema extends TableOrRawTableOptions {
+  /**
+   * The actual name of the raw table in the local schema.
+   *
+   * Unlike {@link RawTable.name}, which describes the name of synced tables to match, this reflects  the SQLite table
+   * name. This is used to infer {@link RawTableType.put} and {@link RawTableType.delete} statements for the sync
+   * client. It can also be used to auto-generate triggers forwarding writes on raw tables into the CRUD upload queue
+   * (using the `powersync_create_raw_table_crud_trigger` SQL function).
+   *
+   * When absent, defaults to {@link RawTable.name}.
+   */
+  tableName?: string;
+
+  /**
+   * An optional filter of columns that should be synced.
+   *
+   * By default, all columns in a raw table are considered for sync. If a filter is specified, PowerSync treats
+   * unmatched columns as local-only and will not attempt to sync them.
+   */
+  syncedColumns?: string[];
+}
+
+interface InferredRawTableType extends Partial<RawTableTypeWithStatements> {
+  schema: RawTableSchema;
+}
 
 /**
  * A parameter to use as part of {@link PendingStatement}.
@@ -21,8 +73,10 @@ export type RawTableType = {
  *
  * For insert and replace operations, the values of columns in the table are available as parameters through
  * `{Column: 'name'}`.
+ * The `"Rest"` parameter gets resolved to a JSON object covering all values from the synced row that haven't been
+ * covered by a `Column` parameter.
  */
-export type PendingStatementParameter = 'Id' | { Column: string };
+export type PendingStatementParameter = 'Id' | { Column: string } | 'Rest';
 
 /**
  * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
@@ -33,35 +87,16 @@ export type PendingStatement = {
 };
 
 /**
- * Instructs PowerSync to sync data into a "raw" table.
- *
- * Since raw tables are not backed by JSON, running complex queries on them may be more efficient. Further, they allow
- * using client-side table and column constraints.
- *
- * To collect local writes to raw tables with PowerSync, custom triggers are required. See
- * {@link https://docs.powersync.com/usage/use-case-examples/raw-tables the documentation} for details and an example on
- * using raw tables.
- *
- * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
- *
- * @experimental Please note that this feature is experimental at the moment, and not covered by PowerSync semver or
- * stability guarantees.
+ * @internal
  */
-export class RawTable implements RawTableType {
+export type RawTable<T extends RawTableType = RawTableType> = T & {
   /**
    * The name of the table.
    *
-   * This does not have to match the actual table name in the schema - {@link put} and {@link delete} are free to use
-   * another table. Instead, this name is used by the sync client to recognize that operations on this table (as it
-   * appears in the source / backend database) are to be handled specially.
+   * This does not have to match the actual table name in the schema - {@link RawTableType.put} and
+   * {@link RawTableType.delete} are free to use another table. Instead, this name is used by the sync client to
+   * recognize that operations on this table (as it appears in the source / backend database) are to be handled
+   * specially.
    */
   name: string;
-  put: PendingStatement;
-  delete: PendingStatement;
-
-  constructor(name: string, type: RawTableType) {
-    this.name = name;
-    this.put = type.put;
-    this.delete = type.delete;
-  }
-}
+};

package/src/db/schema/Schema.ts

@@ -1,3 +1,4 @@
+import { encodeTableOptions } from './internal.js';
 import { RawTable, RawTableType } from './RawTable.js';
 import { RowType, Table } from './Table.js';
 
@@ -57,7 +58,7 @@ export class Schema<S extends SchemaType = SchemaType> {
    */
   withRawTables(tables: Record<string, RawTableType>) {
     for (const [name, rawTableDefinition] of Object.entries(tables)) {
-      this.rawTables.push(new RawTable(name, rawTableDefinition));
+      this.rawTables.push({ name, ...rawTableDefinition });
     }
   }
 
@@ -70,7 +71,31 @@ export class Schema<S extends SchemaType = SchemaType> {
   toJSON() {
     return {
       tables: this.tables.map((t) => t.toJSON()),
-      raw_tables: this.rawTables
+      raw_tables: this.rawTables.map(Schema.rawTableToJson)
     };
   }
+
+  /**
+   * Returns a representation of the raw table that is understood by the PowerSync SQLite core extension.
+   *
+   * The output of this can be passed through `JSON.serialize` and then used in `powersync_create_raw_table_crud_trigger`
+   * to define triggers for this table.
+   */
+  static rawTableToJson(table: RawTable): unknown {
+    const serialized: any = {
+      name: table.name,
+      put: table.put,
+      delete: table.delete,
+      clear: table.clear
+    };
+    if ('schema' in table) {
+      // We have schema options, those are flattened into the outer JSON object for the core extension.
+      const schema = table.schema;
+      serialized.table_name = schema.tableName ?? table.name;
+      serialized.synced_columns = schema.syncedColumns;
+      Object.assign(serialized, encodeTableOptions(table.schema));
+    }
+
+    return serialized;
+  }
 }

package/src/db/schema/Table.ts

@@ -8,17 +8,24 @@ import {
 } from './Column.js';
 import { Index } from './Index.js';
 import { IndexedColumn } from './IndexedColumn.js';
+import { encodeTableOptions } from './internal.js';
 import { TableV2 } from './TableV2.js';
 
-interface SharedTableOptions {
+/**
+ * Options that apply both to JSON-based tables and raw tables.
+ */
+export interface TableOrRawTableOptions {
   localOnly?: boolean;
   insertOnly?: boolean;
-  viewName?: string;
   trackPrevious?: boolean | TrackPreviousOptions;
   trackMetadata?: boolean;
   ignoreEmptyUpdates?: boolean;
 }
 
+interface SharedTableOptions extends TableOrRawTableOptions {
+  viewName?: string;
+}
+
 /** Whether to include previous column values when PowerSync tracks local changes.
  *
  * Including old values may be helpful for some backend connector implementations, which is
@@ -341,19 +348,12 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
   }
 
   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 as any).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))
+      indexes: this.indexes.map((e) => e.toJSON(this)),
+      ...encodeTableOptions(this)
     };
   }
 }

package/src/db/schema/internal.ts

@@ -0,0 +1,17 @@
+import { TableOrRawTableOptions } from './Table.js';
+
+/**
+ * @internal Not exported from `index.ts`.
+ */
+export function encodeTableOptions(options: TableOrRawTableOptions) {
+  const trackPrevious = options.trackPrevious;
+
+  return {
+    local_only: options.localOnly,
+    insert_only: options.insertOnly,
+    include_old: trackPrevious && ((trackPrevious as any).columns ?? true),
+    include_old_only_when_changed: typeof trackPrevious == 'object' && trackPrevious.onlyWhenChanged == true,
+    include_metadata: options.trackMetadata,
+    ignore_empty_update: options.ignoreEmptyUpdates
+  };
+}

package/src/index.ts

@@ -39,7 +39,7 @@ export * from './db/DBAdapter.js';
 export * from './db/schema/Column.js';
 export * from './db/schema/Index.js';
 export * from './db/schema/IndexedColumn.js';
-export * from './db/schema/RawTable.js';
+export { RawTableType, PendingStatementParameter, PendingStatement } from './db/schema/RawTable.js';
 export * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';