@powersync/common 1.47.0 → 1.48.0

package/lib/db/schema/internal.js

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

package/lib/db/schema/internal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../../../src/db/schema/internal.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAA+B;IAChE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAE5C,OAAO;QACL,UAAU,EAAE,OAAO,CAAC,SAAS;QAC7B,WAAW,EAAE,OAAO,CAAC,UAAU;QAC/B,WAAW,EAAE,aAAa,IAAI,CAAE,aAAqB,CAAC,OAAO,IAAI,IAAI,CAAC;QACtE,6BAA6B,EAAE,OAAO,aAAa,IAAI,QAAQ,IAAI,aAAa,CAAC,eAAe,IAAI,IAAI;QACxG,gBAAgB,EAAE,OAAO,CAAC,aAAa;QACvC,mBAAmB,EAAE,OAAO,CAAC,kBAAkB;KAChD,CAAC;AACJ,CAAC"}

package/lib/index.d.ts

@@ -37,7 +37,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';

package/lib/index.js

@@ -37,7 +37,6 @@ 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 * from './db/schema/Schema.js';
 export * from './db/schema/Table.js';
 export * from './db/schema/TableV2.js';

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,wCAAwC,CAAC;AAEvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAE,SAAS,EAAQ,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAE9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAA0B,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACjF,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gDAAgD,CAAC;AAC9F,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,cAAc,iCAAiC,CAAC;AAChD,cAAc,uDAAuD,CAAC;AACtE,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAEjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oCAAoC,CAAC;AACnD,cAAc,yCAAyC,CAAC;AACxD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,sCAAsC,CAAC;AACrD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,wCAAwC,CAAC;AAEvD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0CAA0C,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAA+B,MAAM,kCAAkC,CAAC;AACrG,cAAc,kDAAkD,CAAC;AACjE,cAAc,6CAA6C,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,mCAAmC,CAAC;AAClD,OAAO,EAAE,SAAS,EAAQ,UAAU,EAAE,MAAM,mCAAmC,CAAC;AAChF,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6CAA6C,CAAC;AAC5D,cAAc,uCAAuC,CAAC;AACtD,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,6DAA6D,CAAC;AAC5E,cAAc,8CAA8C,CAAC;AAC7D,cAAc,+BAA+B,CAAC;AAE9C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,+BAA+B,CAAC;AAC9C,OAAO,EAA0B,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACjF,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,4BAA4B,EAAE,MAAM,gDAAgD,CAAC;AAC9F,cAAc,kCAAkC,CAAC;AACjD,cAAc,qCAAqC,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,cAAc,iCAAiC,CAAC;AAChD,cAAc,uDAAuD,CAAC;AACtE,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2DAA2D,CAAC;AAC1E,cAAc,uDAAuD,CAAC;AACtE,cAAc,kCAAkC,CAAC;AAEjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "1.47.0",
+  "version": "1.48.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"

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';