@powersync/common 0.0.0-dev-20250714151300 → 0.0.0-dev-20250715080712

package/lib/client/AbstractPowerSyncDatabase.js

@@ -299,7 +299,9 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
      * Connects to stream of events from the PowerSync instance.
      */
     async connect(connector, options) {
-        return this.connectionManager.connect(connector, options);
+        const resolvedOptions = options ?? {};
+        resolvedOptions.serializedSchema = this.schema.toJSON();
+        return this.connectionManager.connect(connector, resolvedOptions);
     }
     /**
      * Close the sync connection.

package/lib/client/ConnectionManager.d.ts

@@ -1,7 +1,7 @@
 import { ILogger } from 'js-logger';
 import { BaseListener, BaseObserver } from '../utils/BaseObserver.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
-import { PowerSyncConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
+import { InternalConnectionOptions, StreamingSyncImplementation } from './sync/stream/AbstractStreamingSyncImplementation.js';
 /**
  * @internal
  */
@@ -17,12 +17,12 @@ export interface ConnectionManagerSyncImplementationResult {
  * @internal
  */
 export interface ConnectionManagerOptions {
-    createSyncImplementation(connector: PowerSyncBackendConnector, options: PowerSyncConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
+    createSyncImplementation(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<ConnectionManagerSyncImplementationResult>;
     logger: ILogger;
 }
 type StoredConnectionOptions = {
     connector: PowerSyncBackendConnector;
-    options: PowerSyncConnectionOptions;
+    options: InternalConnectionOptions;
 };
 /**
  * @internal
@@ -66,7 +66,7 @@ export declare class ConnectionManager extends BaseObserver<ConnectionManagerLis
     constructor(options: ConnectionManagerOptions);
     get logger(): ILogger;
     close(): Promise<void>;
-    connect(connector: PowerSyncBackendConnector, options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(connector: PowerSyncBackendConnector, options: InternalConnectionOptions): Promise<void>;
     protected connectInternal(): Promise<void>;
     /**
      * Close the sync connection.

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.d.ts

@@ -88,7 +88,8 @@ export interface StreamingSyncImplementationListener extends BaseListener {
  * Configurable options to be used when connecting to the PowerSync
  * backend instance.
  */
-export interface PowerSyncConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
+export type PowerSyncConnectionOptions = Omit<InternalConnectionOptions, 'serializedSchema'>;
+export interface InternalConnectionOptions extends BaseConnectionOptions, AdditionalConnectionOptions {
 }
 /** @internal */
 export interface BaseConnectionOptions {
@@ -114,6 +115,10 @@ export interface BaseConnectionOptions {
      * These parameters are passed to the sync rules, and will be available under the`user_parameters` object.
      */
     params?: Record<string, StreamingSyncRequestParameterType>;
+    /**
+     * The serialized schema - mainly used to forward information about raw tables to the sync client.
+     */
+    serializedSchema?: any;
 }
 /** @internal */
 export interface AdditionalConnectionOptions {
@@ -135,7 +140,7 @@ export interface StreamingSyncImplementation extends BaseObserverInterface<Strea
     /**
      * Connects to the sync service
      */
-    connect(options?: PowerSyncConnectionOptions): Promise<void>;
+    connect(options?: InternalConnectionOptions): Promise<void>;
     /**
      * Disconnects from the sync services.
      * @throws if not connected or if abort is not controlled internally

package/lib/client/sync/stream/AbstractStreamingSyncImplementation.js

@@ -72,7 +72,8 @@ export const DEFAULT_STREAM_CONNECTION_OPTIONS = {
     connectionMethod: SyncStreamConnectionMethod.WEB_SOCKET,
     clientImplementation: DEFAULT_SYNC_CLIENT_IMPLEMENTATION,
     fetchStrategy: FetchStrategy.Buffered,
-    params: {}
+    params: {},
+    serializedSchema: undefined
 };
 // The priority we assume when we receive checkpoint lines where no priority is set.
 // This is the default priority used by the sync service, but can be set to an arbitrary
@@ -526,6 +527,8 @@ The next upload iteration will be delayed.`);
             }
             if (isStreamingSyncCheckpoint(line)) {
                 targetCheckpoint = line.checkpoint;
+                // New checkpoint - existing validated checkpoint is no longer valid
+                pendingValidatedCheckpoint = null;
                 const bucketsToDelete = new Set(bucketMap.keys());
                 const newBuckets = new Map();
                 for (const checksum of line.checkpoint.buckets) {
@@ -549,8 +552,15 @@ The next upload iteration will be delayed.`);
                     return;
                 }
                 else if (!result.applied) {
+                    // "Could not apply checkpoint due to local data". We need to retry after
+                    // finishing uploads.
                     pendingValidatedCheckpoint = targetCheckpoint;
                 }
+                else {
+                    // Nothing to retry later. This would likely already be null from the last
+                    // checksum or checksum_diff operation, but we make sure.
+                    pendingValidatedCheckpoint = null;
+                }
             }
             else if (isStreamingSyncCheckpointPartiallyComplete(line)) {
                 const priority = line.partial_checkpoint_complete.priority;
@@ -587,6 +597,8 @@ The next upload iteration will be delayed.`);
                 if (targetCheckpoint == null) {
                     throw new Error('Checkpoint diff without previous checkpoint');
                 }
+                // New checkpoint - existing validated checkpoint is no longer valid
+                pendingValidatedCheckpoint = null;
                 const diff = line.checkpoint_diff;
                 const newBuckets = new Map();
                 for (const checksum of targetCheckpoint.buckets) {
@@ -826,9 +838,11 @@ The next upload iteration will be delayed.`);
             }
         }
         try {
-            await control(PowerSyncControlCommand.START, JSON.stringify({
-                parameters: resolvedOptions.params
-            }));
+            const options = { parameters: resolvedOptions.params };
+            if (resolvedOptions.serializedSchema) {
+                options.schema = resolvedOptions.serializedSchema;
+            }
+            await control(PowerSyncControlCommand.START, JSON.stringify(options));
             this.notifyCompletedUploads = () => {
                 controlInvocations?.enqueueData({ command: PowerSyncControlCommand.NOTIFY_CRUD_UPLOAD_COMPLETED });
             };

package/lib/db/schema/RawTable.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A pending variant of a {@link RawTable} that doesn't have a name (because it would be inferred when creating the
+ * schema).
+ */
+export type RawTableType = {
+    /**
+     * The statement to run when PowerSync detects that a row needs to be inserted or updated.
+     */
+    put: PendingStatement;
+    /**
+     * The statement to run when PowerSync detects that a row needs to be deleted.
+     */
+    delete: PendingStatement;
+};
+/**
+ * A parameter to use as part of {@link PendingStatement}.
+ *
+ * For delete statements, only the `"Id"` value is supported - the sync client will replace it with the id of the row to
+ * be synced.
+ *
+ * For insert and replace operations, the values of columns in the table are available as parameters through
+ * `{Column: 'name'}`.
+ */
+export type PendingStatementParameter = 'Id' | {
+    Column: string;
+};
+/**
+ * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
+ */
+export type PendingStatement = {
+    sql: string;
+    params: PendingStatementParameter[];
+};
+/**
+ * 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.
+ *
+ * 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 declare class RawTable implements RawTableType {
+    /**
+     * 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.
+     */
+    name: string;
+    put: PendingStatement;
+    delete: PendingStatement;
+    constructor(name: string, type: RawTableType);
+}

package/lib/db/schema/RawTable.js

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ *
+ * 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 class RawTable {
+    /**
+     * 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.
+     */
+    name;
+    put;
+    delete;
+    constructor(name, type) {
+        this.name = name;
+        this.put = type.put;
+        this.delete = type.delete;
+    }
+}

package/lib/db/schema/Schema.d.ts

@@ -1,3 +1,4 @@
+import { RawTable, RawTableType } from './RawTable.js';
 import { RowType, Table } from './Table.js';
 type SchemaType = Record<string, Table<any>>;
 export type SchemaTableType<S extends SchemaType> = {
@@ -10,7 +11,19 @@ export declare class Schema<S extends SchemaType = SchemaType> {
     readonly types: SchemaTableType<S>;
     readonly props: S;
     readonly tables: Table[];
+    readonly rawTables: RawTable[];
     constructor(tables: Table[] | S);
+    /**
+     * Adds raw tables to this schema. Raw tables are identified by their name, but entirely managed by the application
+     * developer instead of automatically by PowerSync.
+     * 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.
+     * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+     *
+     * @param tables An object of (table name, raw table definition) entries.
+     * @experimental Note that the raw tables API is still experimental and may change in the future.
+     */
+    withRawTables(tables: Record<string, RawTableType>): void;
     validate(): void;
     toJSON(): {
         tables: {
@@ -35,6 +48,7 @@ export declare class Schema<S extends SchemaType = SchemaType> {
                 }[];
             }[];
         }[];
+        raw_tables: RawTable[];
     };
     private convertToClassicTables;
 }

package/lib/db/schema/Schema.js

@@ -1,3 +1,4 @@
+import { RawTable } from './RawTable.js';
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
  */
@@ -8,6 +9,7 @@ export class Schema {
     types;
     props;
     tables;
+    rawTables;
     constructor(tables) {
         if (Array.isArray(tables)) {
             /*
@@ -26,6 +28,22 @@ export class Schema {
             this.props = tables;
             this.tables = this.convertToClassicTables(this.props);
         }
+        this.rawTables = [];
+    }
+    /**
+     * Adds raw tables to this schema. Raw tables are identified by their name, but entirely managed by the application
+     * developer instead of automatically by PowerSync.
+     * 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.
+     * Note that raw tables are only supported when using the new `SyncClientImplementation.rust` sync client.
+     *
+     * @param tables An object of (table name, raw table definition) entries.
+     * @experimental Note that the raw tables API is still experimental and may change in the future.
+     */
+    withRawTables(tables) {
+        for (const [name, rawTableDefinition] of Object.entries(tables)) {
+            this.rawTables.push(new RawTable(name, rawTableDefinition));
+        }
     }
     validate() {
         for (const table of this.tables) {
@@ -35,7 +53,8 @@ export class Schema {
     toJSON() {
         return {
             // This is required because "name" field is not present in TableV2
-            tables: this.tables.map((t) => t.toJSON())
+            tables: this.tables.map((t) => t.toJSON()),
+            raw_tables: this.rawTables
         };
     }
     convertToClassicTables(props) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powersync/common",
-  "version": "0.0.0-dev-20250714151300",
+  "version": "0.0.0-dev-20250715080712",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"