@powersync/common 1.46.0 → 1.48.0

package/lib/attachments/Schema.js

@@ -0,0 +1,62 @@
+import { column } from '../db/schema/Column.js';
+import { Table } from '../db/schema/Table.js';
+export const ATTACHMENT_TABLE = 'attachments';
+/**
+ * Maps a database row to an AttachmentRecord.
+ *
+ * @param row - The database row object
+ * @returns The corresponding AttachmentRecord
+ *
+ * @experimental
+ */
+export function attachmentFromSql(row) {
+    return {
+        id: row.id,
+        filename: row.filename,
+        localUri: row.local_uri,
+        size: row.size,
+        mediaType: row.media_type,
+        timestamp: row.timestamp,
+        metaData: row.meta_data,
+        hasSynced: row.has_synced === 1,
+        state: row.state
+    };
+}
+/**
+ * AttachmentState represents the current synchronization state of an attachment.
+ *
+ * @experimental
+ */
+export var AttachmentState;
+(function (AttachmentState) {
+    AttachmentState[AttachmentState["QUEUED_UPLOAD"] = 0] = "QUEUED_UPLOAD";
+    AttachmentState[AttachmentState["QUEUED_DOWNLOAD"] = 1] = "QUEUED_DOWNLOAD";
+    AttachmentState[AttachmentState["QUEUED_DELETE"] = 2] = "QUEUED_DELETE";
+    AttachmentState[AttachmentState["SYNCED"] = 3] = "SYNCED";
+    AttachmentState[AttachmentState["ARCHIVED"] = 4] = "ARCHIVED"; // Attachment has been orphaned, i.e. the associated record has been deleted
+})(AttachmentState || (AttachmentState = {}));
+/**
+ * AttachmentTable defines the schema for the attachment queue table.
+ *
+ * @internal
+ */
+export class AttachmentTable extends Table {
+    constructor(options) {
+        super({
+            filename: column.text,
+            local_uri: column.text,
+            timestamp: column.integer,
+            size: column.integer,
+            media_type: column.text,
+            state: column.integer, // Corresponds to AttachmentState
+            has_synced: column.integer,
+            meta_data: column.text
+        }, {
+            ...options,
+            viewName: options?.viewName ?? ATTACHMENT_TABLE,
+            localOnly: true,
+            insertOnly: false
+        });
+    }
+}
+//# sourceMappingURL=Schema.js.map

package/lib/attachments/Schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../src/attachments/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAChD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAG9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAmB9C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO;QACL,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,SAAS,EAAE,GAAG,CAAC,UAAU,KAAK,CAAC;QAC/B,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAN,IAAY,eAMX;AAND,WAAY,eAAe;IACzB,uEAAiB,CAAA;IACjB,2EAAmB,CAAA;IACnB,uEAAiB,CAAA;IACjB,yDAAU,CAAA;IACV,6DAAY,CAAA,CAAC,4EAA4E;AAC3F,CAAC,EANW,eAAe,KAAf,eAAe,QAM1B;AAID;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAgC;QAC1C,KAAK,CACH;YACE,QAAQ,EAAE,MAAM,CAAC,IAAI;YACrB,SAAS,EAAE,MAAM,CAAC,IAAI;YACtB,SAAS,EAAE,MAAM,CAAC,OAAO;YACzB,IAAI,EAAE,MAAM,CAAC,OAAO;YACpB,UAAU,EAAE,MAAM,CAAC,IAAI;YACvB,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,iCAAiC;YACxD,UAAU,EAAE,MAAM,CAAC,OAAO;YAC1B,SAAS,EAAE,MAAM,CAAC,IAAI;SACvB,EACD;YACE,GAAG,OAAO;YACV,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,gBAAgB;YAC/C,SAAS,EAAE,IAAI;YACf,UAAU,EAAE,KAAK;SAClB,CACF,CAAC;IACJ,CAAC;CACF"}

package/lib/attachments/SyncingService.d.ts

@@ -0,0 +1,62 @@
+import { ILogger } from '../utils/Logger.js';
+import { AttachmentService } from './AttachmentService.js';
+import { LocalStorageAdapter } from './LocalStorageAdapter.js';
+import { RemoteStorageAdapter } from './RemoteStorageAdapter.js';
+import { AttachmentRecord } from './Schema.js';
+import { AttachmentErrorHandler } from './AttachmentErrorHandler.js';
+import { AttachmentContext } from './AttachmentContext.js';
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+export declare class SyncingService {
+    private attachmentService;
+    private localStorage;
+    private remoteStorage;
+    private logger;
+    private errorHandler?;
+    constructor(attachmentService: AttachmentService, localStorage: LocalStorageAdapter, remoteStorage: RemoteStorageAdapter, logger: ILogger, errorHandler?: AttachmentErrorHandler);
+    /**
+     * Processes attachments based on their state (upload, download, or delete).
+     * All updates are saved in a single batch after processing.
+     *
+     * @param attachments - Array of attachment records to process
+     * @param context - Attachment context for database operations
+     * @returns Promise that resolves when all attachments have been processed and saved
+     */
+    processAttachments(attachments: AttachmentRecord[], context: AttachmentContext): Promise<void>;
+    /**
+     * Uploads an attachment from local storage to remote storage.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to upload
+     * @returns Updated attachment record with new state
+     * @throws Error if the attachment has no localUri
+     */
+    uploadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Downloads an attachment from remote storage to local storage.
+     * Retrieves the file, converts to base64, and saves locally.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to download
+     * @returns Updated attachment record with local URI and new state
+     */
+    downloadAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Deletes an attachment from both remote and local storage.
+     * Removes the remote file, local file (if exists), and the attachment record.
+     * On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to delete
+     * @returns Updated attachment record
+     */
+    deleteAttachment(attachment: AttachmentRecord): Promise<AttachmentRecord>;
+    /**
+     * Performs cleanup of archived attachments by removing their local files and records.
+     * Errors during local file deletion are logged but do not prevent record deletion.
+     */
+    deleteArchivedAttachments(context: AttachmentContext): Promise<boolean>;
+}

package/lib/attachments/SyncingService.js

@@ -0,0 +1,168 @@
+import { AttachmentState } from './Schema.js';
+/**
+ * Orchestrates attachment synchronization between local and remote storage.
+ * Handles uploads, downloads, deletions, and state transitions.
+ *
+ * @internal
+ */
+export class SyncingService {
+    attachmentService;
+    localStorage;
+    remoteStorage;
+    logger;
+    errorHandler;
+    constructor(attachmentService, localStorage, remoteStorage, logger, errorHandler) {
+        this.attachmentService = attachmentService;
+        this.localStorage = localStorage;
+        this.remoteStorage = remoteStorage;
+        this.logger = logger;
+        this.errorHandler = errorHandler;
+    }
+    /**
+     * Processes attachments based on their state (upload, download, or delete).
+     * All updates are saved in a single batch after processing.
+     *
+     * @param attachments - Array of attachment records to process
+     * @param context - Attachment context for database operations
+     * @returns Promise that resolves when all attachments have been processed and saved
+     */
+    async processAttachments(attachments, context) {
+        const updatedAttachments = [];
+        for (const attachment of attachments) {
+            switch (attachment.state) {
+                case AttachmentState.QUEUED_UPLOAD:
+                    const uploaded = await this.uploadAttachment(attachment);
+                    updatedAttachments.push(uploaded);
+                    break;
+                case AttachmentState.QUEUED_DOWNLOAD:
+                    const downloaded = await this.downloadAttachment(attachment);
+                    updatedAttachments.push(downloaded);
+                    break;
+                case AttachmentState.QUEUED_DELETE:
+                    const deleted = await this.deleteAttachment(attachment);
+                    updatedAttachments.push(deleted);
+                    break;
+                default:
+                    break;
+            }
+        }
+        await context.saveAttachments(updatedAttachments);
+    }
+    /**
+     * Uploads an attachment from local storage to remote storage.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to upload
+     * @returns Updated attachment record with new state
+     * @throws Error if the attachment has no localUri
+     */
+    async uploadAttachment(attachment) {
+        this.logger.info(`Uploading attachment ${attachment.filename}`);
+        try {
+            if (attachment.localUri == null) {
+                throw new Error(`No localUri for attachment ${attachment.id}`);
+            }
+            const fileBlob = await this.localStorage.readFile(attachment.localUri);
+            await this.remoteStorage.uploadFile(fileBlob, attachment);
+            return {
+                ...attachment,
+                state: AttachmentState.SYNCED,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onUploadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Downloads an attachment from remote storage to local storage.
+     * Retrieves the file, converts to base64, and saves locally.
+     * On success, marks as SYNCED. On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to download
+     * @returns Updated attachment record with local URI and new state
+     */
+    async downloadAttachment(attachment) {
+        this.logger.info(`Downloading attachment ${attachment.filename}`);
+        try {
+            const fileData = await this.remoteStorage.downloadFile(attachment);
+            const localUri = this.localStorage.getLocalUri(attachment.filename);
+            await this.localStorage.saveFile(localUri, fileData);
+            return {
+                ...attachment,
+                state: AttachmentState.SYNCED,
+                localUri: localUri,
+                hasSynced: true
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDownloadError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Deletes an attachment from both remote and local storage.
+     * Removes the remote file, local file (if exists), and the attachment record.
+     * On failure, defers to error handler or archives.
+     *
+     * @param attachment - The attachment record to delete
+     * @returns Updated attachment record
+     */
+    async deleteAttachment(attachment) {
+        try {
+            await this.remoteStorage.deleteFile(attachment);
+            if (attachment.localUri) {
+                await this.localStorage.deleteFile(attachment.localUri);
+            }
+            await this.attachmentService.withContext(async (ctx) => {
+                await ctx.deleteAttachment(attachment.id);
+            });
+            return {
+                ...attachment,
+                state: AttachmentState.ARCHIVED
+            };
+        }
+        catch (error) {
+            const shouldRetry = (await this.errorHandler?.onDeleteError(attachment, error)) ?? true;
+            if (!shouldRetry) {
+                return {
+                    ...attachment,
+                    state: AttachmentState.ARCHIVED
+                };
+            }
+            return attachment;
+        }
+    }
+    /**
+     * Performs cleanup of archived attachments by removing their local files and records.
+     * Errors during local file deletion are logged but do not prevent record deletion.
+     */
+    async deleteArchivedAttachments(context) {
+        return await context.deleteArchivedAttachments(async (archivedAttachments) => {
+            for (const attachment of archivedAttachments) {
+                if (attachment.localUri) {
+                    try {
+                        await this.localStorage.deleteFile(attachment.localUri);
+                    }
+                    catch (error) {
+                        this.logger.error('Error deleting local file for archived attachment', error);
+                    }
+                }
+            }
+        });
+    }
+}
+//# sourceMappingURL=SyncingService.js.map

package/lib/attachments/SyncingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncingService.js","sourceRoot":"","sources":["../../src/attachments/SyncingService.ts"],"names":[],"mappings":"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"}

package/lib/attachments/WatchedAttachmentItem.d.ts

@@ -0,0 +1,17 @@
+/**
+ * WatchedAttachmentItem represents an attachment reference in your application's data model.
+ * Use either filename OR fileExtension (not both).
+ *
+ * @experimental
+ */
+export type WatchedAttachmentItem = {
+    id: string;
+    filename: string;
+    fileExtension?: never;
+    metaData?: string;
+} | {
+    id: string;
+    fileExtension: string;
+    filename?: never;
+    metaData?: string;
+};

package/lib/attachments/WatchedAttachmentItem.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=WatchedAttachmentItem.js.map

package/lib/attachments/WatchedAttachmentItem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WatchedAttachmentItem.js","sourceRoot":"","sources":["../../src/attachments/WatchedAttachmentItem.ts"],"names":[],"mappings":""}

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

@@ -1,8 +1,21 @@
+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 +24,40 @@ 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}.
  *
@@ -20,10 +66,12 @@ 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;
-};
+} | 'Rest';
 /**
  * A statement that the PowerSync client should use to insert or delete data into a table managed by the user.
  */
@@ -32,30 +80,17 @@ export type PendingStatement = {
     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.
- *
- * 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 declare 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);
-}
+};
+export {};

package/lib/db/schema/RawTable.js

@@ -1,33 +1,2 @@
-/**
- * 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 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;
-    }
-}
+export {};
 //# sourceMappingURL=RawTable.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"RawTable.js","sourceRoot":"","sources":["../../../src/db/schema/RawTable.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,QAAQ;IACnB;;;;;;OAMG;IACH,IAAI,CAAS;IACb,GAAG,CAAmB;IACtB,MAAM,CAAmB;IAEzB,YAAY,IAAY,EAAE,IAAkB;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF"}
+{"version":3,"file":"RawTable.js","sourceRoot":"","sources":["../../../src/db/schema/RawTable.ts"],"names":[],"mappings":""}

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

@@ -27,14 +27,14 @@ export declare class Schema<S extends SchemaType = SchemaType> {
     validate(): void;
     toJSON(): {
         tables: {
-            name: string;
-            view_name: string;
-            local_only: boolean;
-            insert_only: boolean;
+            local_only: boolean | undefined;
+            insert_only: boolean | undefined;
             include_old: any;
             include_old_only_when_changed: boolean;
-            include_metadata: boolean;
-            ignore_empty_update: boolean;
+            include_metadata: boolean | undefined;
+            ignore_empty_update: boolean | undefined;
+            name: string;
+            view_name: string;
             columns: {
                 name: string;
                 type: import("./Column.js").ColumnType | undefined;
@@ -48,7 +48,14 @@ export declare class Schema<S extends SchemaType = SchemaType> {
                 }[];
             }[];
         }[];
-        raw_tables: RawTable[];
+        raw_tables: unknown[];
     };
+    /**
+     * 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;
 }
 export {};

package/lib/db/schema/Schema.js

@@ -1,4 +1,4 @@
-import { RawTable } from './RawTable.js';
+import { encodeTableOptions } from './internal.js';
 /**
  * A schema is a collection of tables. It is used to define the structure of a database.
  */
@@ -43,7 +43,7 @@ export class Schema {
      */
     withRawTables(tables) {
         for (const [name, rawTableDefinition] of Object.entries(tables)) {
-            this.rawTables.push(new RawTable(name, rawTableDefinition));
+            this.rawTables.push({ name, ...rawTableDefinition });
         }
     }
     validate() {
@@ -54,8 +54,30 @@ export class Schema {
     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) {
+        const serialized = {
+            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;
+    }
 }
 //# sourceMappingURL=Schema.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../../src/db/schema/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAgB,MAAM,eAAe,CAAC;AASvD;;GAEG;AACH,MAAM,OAAO,MAAM;IACjB;;MAEE;IACO,KAAK,CAAqB;IAC1B,KAAK,CAAI;IACT,MAAM,CAAU;IAChB,SAAS,CAAa;IAE/B,YAAY,MAAmB;QAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B;;;;cAIE;YACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CACb,2KAA2K,CAC5K,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,4DAA4D;YAC5D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,WAAW,CAC7B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAC1F,CAAC;YACP,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,MAAoC;QAChD,KAAK,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;IAED,QAAQ;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC1C,UAAU,EAAE,IAAI,CAAC,SAAS;SAC3B,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"Schema.js","sourceRoot":"","sources":["../../../src/db/schema/Schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAUnD;;GAEG;AACH,MAAM,OAAO,MAAM;IACjB;;MAEE;IACO,KAAK,CAAqB;IAC1B,KAAK,CAAI;IACT,MAAM,CAAU;IAChB,SAAS,CAAa;IAE/B,YAAY,MAAmB;QAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B;;;;cAIE;YACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;oBACtB,MAAM,IAAI,KAAK,CACb,2KAA2K,CAC5K,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,4DAA4D;YAC5D,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,WAAW,CAC7B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAC1F,CAAC;YACP,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;IACtB,CAAC;IAED;;;;;;;;;OASG;IACH,aAAa,CAAC,MAAoC;QAChD,KAAK,MAAM,CAAC,IAAI,EAAE,kBAAkB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAChE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,kBAAkB,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,QAAQ;QACN,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,KAAK,CAAC,QAAQ,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED,MAAM;QACJ,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;YAC1C,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC;SACtD,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,KAAe;QACnC,MAAM,UAAU,GAAQ;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,KAAK,EAAE,KAAK,CAAC,KAAK;SACnB,CAAC;QACF,IAAI,QAAQ,IAAI,KAAK,EAAE,CAAC;YACtB,iGAAiG;YACjG,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,UAAU,CAAC,UAAU,GAAG,MAAM,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC;YACvD,UAAU,CAAC,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;YACjD,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;CACF"}

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

@@ -1,14 +1,19 @@
 import { Column, ColumnsType, ColumnType, ExtractColumnValueType } from './Column.js';
 import { Index } from './Index.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
@@ -132,14 +137,14 @@ export declare class Table<Columns extends ColumnsType = ColumnsType> {
     get validName(): boolean;
     validate(): void;
     toJSON(): {
-        name: string;
-        view_name: string;
-        local_only: boolean;
-        insert_only: boolean;
+        local_only: boolean | undefined;
+        insert_only: boolean | undefined;
         include_old: any;
         include_old_only_when_changed: boolean;
-        include_metadata: boolean;
-        ignore_empty_update: boolean;
+        include_metadata: boolean | undefined;
+        ignore_empty_update: boolean | undefined;
+        name: string;
+        view_name: string;
         columns: {
             name: string;
             type: ColumnType | undefined;

package/lib/db/schema/Table.js

@@ -1,6 +1,7 @@
 import { Column, ColumnType, MAX_AMOUNT_OF_COLUMNS } from './Column.js';
 import { Index } from './Index.js';
 import { IndexedColumn } from './IndexedColumn.js';
+import { encodeTableOptions } from './internal.js';
 export const DEFAULT_TABLE_OPTIONS = {
     indexes: [],
     insertOnly: false,
@@ -190,18 +191,12 @@ export class Table {
         }
     }
     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.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)
         };
     }
 }