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

package/lib/client/AbstractPowerSyncDatabase.d.ts

@@ -6,15 +6,12 @@ import { UploadQueueStats } from '../db/crud/UploadQueueStatus.js';
 import { Schema } from '../db/schema/Schema.js';
 import { BaseObserver } from '../utils/BaseObserver.js';
 import { ConnectionManager } from './ConnectionManager.js';
-import { ArrayQueryDefinition, Query } from './Query.js';
 import { SQLOpenFactory, SQLOpenOptions } from './SQLOpenFactory.js';
 import { PowerSyncBackendConnector } from './connection/PowerSyncBackendConnector.js';
 import { BucketStorageAdapter } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { StreamingSyncImplementation, StreamingSyncImplementationListener, type AdditionalConnectionOptions, type PowerSyncConnectionOptions, type RequiredAdditionalConnectionOptions } from './sync/stream/AbstractStreamingSyncImplementation.js';
-import { WatchCompatibleQuery } from './watched/WatchedQuery.js';
-import { WatchedQueryComparator } from './watched/processors/comparators.js';
 export interface DisconnectAndClearOptions {
     /** When set to false, data in local-only tables is preserved. */
     clearLocal?: boolean;
@@ -47,7 +44,7 @@ export interface PowerSyncDatabaseOptionsWithOpenFactory extends BasePowerSyncDa
 export interface PowerSyncDatabaseOptionsWithSettings extends BasePowerSyncDatabaseOptions {
     database: SQLOpenOptions;
 }
-export interface SQLOnChangeOptions {
+export interface SQLWatchOptions {
     signal?: AbortSignal;
     tables?: string[];
     /** The minimum interval between queries. */
@@ -59,17 +56,6 @@ export interface SQLOnChangeOptions {
      * by not removing PowerSync table name prefixes
      */
     rawTableNames?: boolean;
-    /**
-     * Emits an empty result set immediately
-     */
-    triggerImmediate?: boolean;
-}
-export interface SQLWatchOptions extends SQLOnChangeOptions {
-    /**
-     * Optional comparator which will be used to compare the results of the query.
-     * The watched query will only yield results if the comparator returns false.
-     */
-    comparator?: WatchedQueryComparator<QueryResult>;
 }
 export interface WatchOnChangeEvent {
     changedTables: string[];
@@ -85,8 +71,6 @@ export interface WatchOnChangeHandler {
 export interface PowerSyncDBListener extends StreamingSyncImplementationListener {
     initialized: () => void;
     schemaChanged: (schema: Schema) => void;
-    closing: () => Promise<void> | void;
-    closed: () => Promise<void> | void;
 }
 export interface PowerSyncCloseOptions {
     /**
@@ -97,6 +81,7 @@ export interface PowerSyncCloseOptions {
     disconnect?: boolean;
 }
 export declare const DEFAULT_POWERSYNC_CLOSE_OPTIONS: PowerSyncCloseOptions;
+export declare const DEFAULT_WATCH_THROTTLE_MS = 30;
 export declare const DEFAULT_POWERSYNC_DB_OPTIONS: {
     retryDelayMs: number;
     logger: Logger.ILogger;
@@ -405,42 +390,6 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * ```
      */
     watch(sql: string, parameters?: any[], handler?: WatchHandler, options?: SQLWatchOptions): void;
-    /**
-     * Allows defining a query which can be used to build a {@link WatchedQuery}.
-     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
-     * An optional mapper function can be provided to transform the results.
-     *
-     * @example
-     * ```javascript
-     * const watchedTodos = powersync.query({
-     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
-     *  parameters: [],
-     *  mapper: (row) => ({
-     *    ...row,
-     *    created_at: new Date(row.created_at as string)
-     *  })
-     * })
-     * .watch()
-     * // OR use .differentialWatch() for fine-grained watches.
-     * ```
-     */
-    query<RowType>(query: ArrayQueryDefinition<RowType>): Query<RowType>;
-    /**
-     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
-     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
-     *
-     * @example
-     * ```javascript
-     *
-     * // Potentially a query from an ORM like Drizzle
-     * const query = db.select().from(lists);
-     *
-     * const watchedTodos = powersync.customQuery(query)
-     * .watch()
-     * // OR use .differentialWatch() for fine-grained watches.
-     * ```
-     */
-    customQuery<RowType>(query: WatchCompatibleQuery<RowType[]>): Query<RowType>;
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -489,7 +438,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(options?: SQLOnChangeOptions): AsyncIterable<WatchOnChangeEvent>;
+    onChange(options?: SQLWatchOptions): AsyncIterable<WatchOnChangeEvent>;
     /**
      * See {@link onChangeWithCallback}.
      *
@@ -504,7 +453,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * }
      * ```
      */
-    onChange(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
+    onChange(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
     /**
      * Invoke the provided callback on any changes to any of the specified tables.
      *
@@ -517,7 +466,7 @@ export declare abstract class AbstractPowerSyncDatabase extends BaseObserver<Pow
      * @param options Options for configuring watch behavior
      * @returns A dispose function to stop watching for changes
      */
-    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLOnChangeOptions): () => void;
+    onChangeWithCallback(handler?: WatchOnChangeHandler, options?: SQLWatchOptions): () => void;
     /**
      * Create a Stream of changes to any of the specified tables.
      *

package/lib/client/AbstractPowerSyncDatabase.js

@@ -9,15 +9,13 @@ import { BaseObserver } from '../utils/BaseObserver.js';
 import { ControlledExecutor } from '../utils/ControlledExecutor.js';
 import { throttleTrailing } from '../utils/async.js';
 import { ConnectionManager } from './ConnectionManager.js';
-import { CustomQuery } from './CustomQuery.js';
 import { isDBAdapter, isSQLOpenFactory, isSQLOpenOptions } from './SQLOpenFactory.js';
+import { runOnSchemaChange } from './runOnSchemaChange.js';
 import { PSInternalTable } from './sync/bucket/BucketStorageAdapter.js';
 import { CrudBatch } from './sync/bucket/CrudBatch.js';
 import { CrudEntry } from './sync/bucket/CrudEntry.js';
 import { CrudTransaction } from './sync/bucket/CrudTransaction.js';
 import { DEFAULT_CRUD_UPLOAD_THROTTLE_MS, DEFAULT_RETRY_DELAY_MS } from './sync/stream/AbstractStreamingSyncImplementation.js';
-import { DEFAULT_WATCH_THROTTLE_MS } from './watched/WatchedQuery.js';
-import { OnChangeQueryProcessor } from './watched/processors/OnChangeQueryProcessor.js';
 const POWERSYNC_TABLE_MATCH = /(^ps_data__|^ps_data_local__)/;
 const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
     clearLocal: true
@@ -25,6 +23,7 @@ const DEFAULT_DISCONNECT_CLEAR_OPTIONS = {
 export const DEFAULT_POWERSYNC_CLOSE_OPTIONS = {
     disconnect: true
 };
+export const DEFAULT_WATCH_THROTTLE_MS = 30;
 export const DEFAULT_POWERSYNC_DB_OPTIONS = {
     retryDelayMs: 5000,
     logger: Logger.get('PowerSyncDatabase'),
@@ -299,7 +298,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.
@@ -342,7 +343,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (this.closed) {
             return;
         }
-        await this.iterateAsyncListeners(async (cb) => cb.closing?.());
         const { disconnect } = options;
         if (disconnect) {
             await this.disconnect();
@@ -350,7 +350,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         await this.connectionManager.close();
         await this.database.close();
         this.closed = true;
-        await this.iterateAsyncListeners(async (cb) => cb.closed?.());
     }
     /**
      * Get upload queue size estimate and count.
@@ -597,60 +596,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         const options = handlerOrOptions;
         return this.watchWithAsyncGenerator(sql, parameters, options);
     }
-    /**
-     * Allows defining a query which can be used to build a {@link WatchedQuery}.
-     * The defined query will be executed with {@link AbstractPowerSyncDatabase#getAll}.
-     * An optional mapper function can be provided to transform the results.
-     *
-     * @example
-     * ```javascript
-     * const watchedTodos = powersync.query({
-     *  sql: `SELECT photo_id as id FROM todos WHERE photo_id IS NOT NULL`,
-     *  parameters: [],
-     *  mapper: (row) => ({
-     *    ...row,
-     *    created_at: new Date(row.created_at as string)
-     *  })
-     * })
-     * .watch()
-     * // OR use .differentialWatch() for fine-grained watches.
-     * ```
-     */
-    query(query) {
-        const { sql, parameters = [], mapper } = query;
-        const compatibleQuery = {
-            compile: () => ({
-                sql,
-                parameters
-            }),
-            execute: async ({ sql, parameters }) => {
-                const result = await this.getAll(sql, parameters);
-                return mapper ? result.map(mapper) : result;
-            }
-        };
-        return this.customQuery(compatibleQuery);
-    }
-    /**
-     * Allows building a {@link WatchedQuery} using an existing {@link WatchCompatibleQuery}.
-     * The watched query will use the provided {@link WatchCompatibleQuery.execute} method to query results.
-     *
-     * @example
-     * ```javascript
-     *
-     * // Potentially a query from an ORM like Drizzle
-     * const query = db.select().from(lists);
-     *
-     * const watchedTodos = powersync.customQuery(query)
-     * .watch()
-     * // OR use .differentialWatch() for fine-grained watches.
-     * ```
-     */
-    customQuery(query) {
-        return new CustomQuery({
-            db: this,
-            query
-        });
-    }
     /**
      * Execute a read query every time the source tables are modified.
      * Use {@link SQLWatchOptions.throttleMs} to specify the minimum interval between queries.
@@ -668,41 +613,35 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
         if (!onResult) {
             throw new Error('onResult is required');
         }
-        const { comparator } = options ?? {};
-        // This API yields a QueryResult type.
-        // This is not a standard Array result, which makes it incompatible with the .query API.
-        const watchedQuery = new OnChangeQueryProcessor({
-            db: this,
-            comparator,
-            placeholderData: null,
-            watchOptions: {
-                query: {
-                    compile: () => ({
-                        sql: sql,
-                        parameters: parameters ?? []
-                    }),
-                    execute: () => this.executeReadOnly(sql, parameters)
-                },
-                reportFetching: false,
-                throttleMs: options?.throttleMs ?? DEFAULT_WATCH_THROTTLE_MS
+        const watchQuery = async (abortSignal) => {
+            try {
+                const resolvedTables = await this.resolveTables(sql, parameters, options);
+                // Fetch initial data
+                const result = await this.executeReadOnly(sql, parameters);
+                onResult(result);
+                this.onChangeWithCallback({
+                    onChange: async () => {
+                        try {
+                            const result = await this.executeReadOnly(sql, parameters);
+                            onResult(result);
+                        }
+                        catch (error) {
+                            onError?.(error);
+                        }
+                    },
+                    onError
+                }, {
+                    ...(options ?? {}),
+                    tables: resolvedTables,
+                    // Override the abort signal since we intercept it
+                    signal: abortSignal
+                });
             }
-        });
-        const dispose = watchedQuery.registerListener({
-            onData: (data) => {
-                if (!data) {
-                    // This should not happen. We only use null for the initial data.
-                    return;
-                }
-                onResult(data);
-            },
-            onError: (error) => {
-                onError(error);
+            catch (error) {
+                onError?.(error);
             }
-        });
-        options?.signal?.addEventListener('abort', () => {
-            dispose();
-            watchedQuery.close();
-        });
+        };
+        runOnSchemaChange(watchQuery, this, options);
     }
     /**
      * Execute a read query every time the source tables are modified.
@@ -792,9 +731,6 @@ export class AbstractPowerSyncDatabase extends BaseObserver {
                 return;
             executor.schedule({ changedTables: intersection });
         }), throttleMs);
-        if (options?.triggerImmediate) {
-            executor.schedule({ changedTables: [] });
-        }
         const dispose = this.database.registerListener({
             tablesUpdated: async (update) => {
                 try {

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/bucket/BucketStorageAdapter.d.ts

@@ -1,4 +1,4 @@
-import { BaseListener, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
 import { CrudBatch } from './CrudBatch.js';
 import { CrudEntry, OpId } from './CrudEntry.js';
 import { SyncDataBatch } from './SyncDataBatch.js';
@@ -62,7 +62,7 @@ export declare enum PowerSyncControlCommand {
 export interface BucketStorageListener extends BaseListener {
     crudUpdate: () => void;
 }
-export interface BucketStorageAdapter extends BaseObserverInterface<BucketStorageListener>, Disposable {
+export interface BucketStorageAdapter extends BaseObserver<BucketStorageListener>, Disposable {
     init(): Promise<void>;
     saveSyncData(batch: SyncDataBatch, fixedKeyFormat?: boolean): Promise<void>;
     removeBuckets(buckets: string[]): Promise<void>;

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

@@ -1,6 +1,6 @@
 import Logger, { ILogger } from 'js-logger';
 import { SyncStatus, SyncStatusOptions } from '../../../db/crud/SyncStatus.js';
-import { BaseListener, BaseObserver, BaseObserverInterface, Disposable } from '../../../utils/BaseObserver.js';
+import { BaseListener, BaseObserver, Disposable } from '../../../utils/BaseObserver.js';
 import { BucketStorageAdapter } from '../bucket/BucketStorageAdapter.js';
 import { AbstractRemote, FetchStrategy } from './AbstractRemote.js';
 import { StreamingSyncRequestParameterType } from './streaming-sync-types.js';
@@ -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 {
@@ -131,11 +136,11 @@ export interface AdditionalConnectionOptions {
 }
 /** @internal */
 export type RequiredAdditionalConnectionOptions = Required<AdditionalConnectionOptions>;
-export interface StreamingSyncImplementation extends BaseObserverInterface<StreamingSyncImplementationListener>, Disposable {
+export interface StreamingSyncImplementation extends BaseObserver<StreamingSyncImplementationListener>, Disposable {
     /**
      * 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
@@ -164,7 +169,6 @@ export declare abstract class AbstractStreamingSyncImplementation extends BaseOb
     protected _lastSyncedAt: Date | null;
     protected options: AbstractStreamingSyncImplementationOptions;
     protected abortController: AbortController | null;
-    protected uploadAbortController: AbortController | null;
     protected crudUpdateListener?: () => void;
     protected streamingSyncPromise?: Promise<void>;
     private isUploadingCrud;

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

@@ -1,6 +1,6 @@
 import Logger from 'js-logger';
-import { FULL_SYNC_PRIORITY } from '../../../db/crud/SyncProgress.js';
 import { SyncStatus } from '../../../db/crud/SyncStatus.js';
+import { FULL_SYNC_PRIORITY } from '../../../db/crud/SyncProgress.js';
 import { AbortOperation } from '../../../utils/AbortOperation.js';
 import { BaseObserver } from '../../../utils/BaseObserver.js';
 import { throttleLeadingTrailing } from '../../../utils/async.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
@@ -83,9 +84,6 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
     _lastSyncedAt;
     options;
     abortController;
-    // In rare cases, mostly for tests, uploads can be triggered without being properly connected.
-    // This allows ensuring that all upload processes can be aborted.
-    uploadAbortController;
     crudUpdateListener;
     streamingSyncPromise;
     isUploadingCrud = false;
@@ -162,10 +160,8 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
         return this.options.logger;
     }
     async dispose() {
-        super.dispose();
         this.crudUpdateListener?.();
         this.crudUpdateListener = undefined;
-        this.uploadAbortController?.abort();
     }
     async hasCompletedSync() {
         return this.options.adapter.hasCompletedSync();
@@ -184,12 +180,7 @@ export class AbstractStreamingSyncImplementation extends BaseObserver {
                  * Keep track of the first item in the CRUD queue for the last `uploadCrud` iteration.
                  */
                 let checkedCrudItem;
-                const controller = new AbortController();
-                this.uploadAbortController = controller;
-                this.abortController?.signal.addEventListener('abort', () => {
-                    controller.abort();
-                }, { once: true });
-                while (!controller.signal.aborted) {
+                while (true) {
                     try {
                         /**
                          * This is the first item in the FIFO CRUD queue.
@@ -230,7 +221,7 @@ The next upload iteration will be delayed.`);
                                 uploadError: ex
                             }
                         });
-                        await this.delayRetry(controller.signal);
+                        await this.delayRetry();
                         if (!this.isConnected) {
                             // Exit the upload loop if the sync stream is no longer connected
                             break;
@@ -245,7 +236,6 @@ The next upload iteration will be delayed.`);
                         });
                     }
                 }
-                this.uploadAbortController = null;
             }
         });
     }
@@ -526,6 +516,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 +541,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 +586,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 +827,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;
 }