Rename options

Author: simolus3

core/src/commonIntegrationTest/kotlin/com/powersync/CrudTest.kt

@@ -1,9 +1,9 @@
 package com.powersync
 
 import com.powersync.db.schema.Column
-import com.powersync.db.schema.IncludeOldOptions
 import com.powersync.db.schema.Schema
 import com.powersync.db.schema.Table
+import com.powersync.db.schema.TrackPreviousValuesOptions
 import com.powersync.testutils.databaseTest
 import io.kotest.matchers.shouldBe
 import kotlin.test.Test
@@ -12,7 +12,7 @@ class CrudTest {
     @Test
     fun includeMetadata() =
         databaseTest {
-            database.updateSchema(Schema(Table("lists", listOf(Column.text("name")), includeMetadata = true)))
+            database.updateSchema(Schema(Table("lists", listOf(Column.text("name")), trackMetadata = true)))
 
             database.execute("INSERT INTO lists (id, name, _metadata) VALUES (uuid(), ?, ?)", listOf("entry", "so meta"))
             val batch = database.getNextCrudTransaction()
@@ -23,7 +23,9 @@ class CrudTest {
     fun includeOldValues() =
         databaseTest {
             database.updateSchema(
-                Schema(Table("lists", listOf(Column.text("name"), Column.text("content")), includeOld = IncludeOldOptions())),
+                Schema(
+                    Table("lists", listOf(Column.text("name"), Column.text("content")), trackPreviousValues = TrackPreviousValuesOptions()),
+                ),
             )
 
             database.execute("INSERT INTO lists (id, name, content) VALUES (uuid(), ?, ?)", listOf("entry", "content"))
@@ -42,7 +44,7 @@ class CrudTest {
                     Table(
                         "lists",
                         listOf(Column.text("name"), Column.text("content")),
-                        includeOld = IncludeOldOptions(columnFilter = listOf("name")),
+                        trackPreviousValues = TrackPreviousValuesOptions(columnFilter = listOf("name")),
                     ),
                 ),
             )
@@ -63,7 +65,7 @@ class CrudTest {
                     Table(
                         "lists",
                         listOf(Column.text("name"), Column.text("content")),
-                        includeOld = IncludeOldOptions(onlyWhenChanged = true),
+                        trackPreviousValues = TrackPreviousValuesOptions(onlyWhenChanged = true),
                     ),
                 ),
             )
@@ -79,7 +81,7 @@ class CrudTest {
     @Test
     fun ignoreEmptyUpdate() =
         databaseTest {
-            database.updateSchema(Schema(Table("lists", listOf(Column.text("name"), Column.text("content")), ignoreEmptyUpdate = true)))
+            database.updateSchema(Schema(Table("lists", listOf(Column.text("name"), Column.text("content")), ignoreEmptyUpdates = true)))
 
             database.execute("INSERT INTO lists (id, name, content) VALUES (uuid(), ?, ?)", listOf("entry", "content"))
             database.execute("DELETE FROM ps_crud")

core/src/commonMain/kotlin/com/powersync/db/crud/CrudEntry.kt

@@ -1,5 +1,7 @@
 package com.powersync.db.crud
 
+import com.powersync.PowerSyncDatabase
+import com.powersync.db.schema.Table
 import com.powersync.utils.JsonUtil
 import kotlinx.serialization.json.contentOrNull
 import kotlinx.serialization.json.jsonObject
@@ -37,6 +39,14 @@ public data class CrudEntry(
      * This may change in the future.
      */
     val transactionId: Int?,
+    /**
+     * User-defined metadata that can be attached to writes.
+     *
+     * This is the value the `_metadata` column had when the write to the database was made,
+     * allowing backend connectors to e.g. identify a write and treat it specially.
+     *
+     * Note that the `_metadata` column is only available when [Table.trackMetadata] is enabled.
+     */
     val metadata: String? = null,
     /**
      * Data associated with the change.
@@ -48,6 +58,12 @@ public data class CrudEntry(
      * For DELETE, this is null.
      */
     val opData: Map<String, String?>?,
+    /**
+     * Previous values before this change.
+     *
+     * These values can be tracked for `UPDATE` statements when [Table.trackPreviousValues] is
+     * enabled.
+     */
     val oldData: Map<String, String?>? = null,
 ) {
     public companion object {

core/src/commonMain/kotlin/com/powersync/db/schema/Table.kt

@@ -41,18 +41,18 @@ public data class Table(
      *  Whether to add a hidden `_metadata` column that will be enabled for updates to attach custom
      *  information about writes that will be reported through [CrudEntry.metadata].
      */
-    val includeMetadata: Boolean = false,
+    val trackMetadata: Boolean = false,
     /**
      * When set to a non-null value, track old values of columns for [CrudEntry.oldData].
      *
-     * See [IncludeOldOptions] for details.
+     * See [TrackPreviousValuesOptions] for details.
      */
-    val includeOld: IncludeOldOptions? = null,
+    val trackPreviousValues: TrackPreviousValuesOptions? = null,
     /**
      * Whether an `UPDATE` statement that doesn't change any values should be ignored when creating
      * CRUD entries.
      */
-    val ignoreEmptyUpdate: Boolean = false,
+    val ignoreEmptyUpdates: Boolean = false,
 ) {
     init {
         /**
@@ -101,9 +101,9 @@ public data class Table(
             name: String,
             columns: List<Column>,
             viewName: String? = null,
-            ignoreEmptyUpdate: Boolean = false,
-            includeMetadata: Boolean = false,
-            includeOld: IncludeOldOptions? = null,
+            ignoreEmptyUpdates: Boolean = false,
+            trackMetadata: Boolean = false,
+            trackPreviousValues: TrackPreviousValuesOptions? = null,
         ): Table =
             Table(
                 name,
@@ -112,9 +112,9 @@ public data class Table(
                 localOnly = false,
                 insertOnly = true,
                 viewNameOverride = viewName,
-                ignoreEmptyUpdate = ignoreEmptyUpdate,
-                includeMetadata = includeMetadata,
-                includeOld = includeOld,
+                ignoreEmptyUpdates = ignoreEmptyUpdates,
+                trackMetadata = trackMetadata,
+                trackPreviousValues = trackPreviousValues,
             )
     }
 
@@ -161,10 +161,10 @@ public data class Table(
             throw AssertionError("Invalid characters in view name: $viewNameOverride")
         }
 
-        check(!localOnly || !includeMetadata) {
+        check(!localOnly || !trackMetadata) {
             "Can't track metadata for local-only tables."
         }
-        check(!localOnly || includeOld == null) {
+        check(!localOnly || trackPreviousValues == null) {
             "Can't track old values for local-only tables."
         }
 
@@ -223,7 +223,7 @@ public data class Table(
  *
  * These options are enabled by passing them to a non-local [Table] constructor.
  */
-public data class IncludeOldOptions(
+public data class TrackPreviousValuesOptions(
     /**
      * A filter of column names for which updates should be tracked.
      *
@@ -268,10 +268,10 @@ internal fun Table.toSerializable(): SerializableTable =
             localOnly = localOnly,
             insertOnly = insertOnly,
             viewName = viewName,
-            ignoreEmptyUpdate = ignoreEmptyUpdate,
-            includeMetadata = includeMetadata,
+            ignoreEmptyUpdate = ignoreEmptyUpdates,
+            includeMetadata = trackMetadata,
             includeOld =
-                includeOld?.let {
+                trackPreviousValues?.let {
                     if (it.columnFilter != null) {
                         buildJsonArray {
                             for (column in it.columnFilter) {
@@ -282,6 +282,6 @@ internal fun Table.toSerializable(): SerializableTable =
                         JsonPrimitive(true)
                     }
                 } ?: JsonPrimitive(false),
-            includeOldOnlyWhenChanged = includeOld?.onlyWhenChanged ?: false,
+            includeOldOnlyWhenChanged = trackPreviousValues?.onlyWhenChanged ?: false,
         )
     }

core/src/commonTest/kotlin/com/powersync/db/schema/TableTest.kt

@@ -192,15 +192,15 @@ class TableTest {
 
     @Test
     fun testValidationLocalOnlyWithMetadata() {
-        val table = Table("foo", listOf(Column.text("bar")), localOnly = true, includeMetadata = true)
+        val table = Table("foo", listOf(Column.text("bar")), localOnly = true, trackMetadata = true)
 
         val exception = shouldThrow<IllegalStateException> { table.validate() }
         exception.message shouldBe "Can't track metadata for local-only tables."
     }
 
     @Test
     fun testValidationLocalOnlyWithIncludeOld() {
-        val table = Table("foo", listOf(Column.text("bar")), localOnly = true, includeOld = IncludeOldOptions())
+        val table = Table("foo", listOf(Column.text("bar")), localOnly = true, trackPreviousValues = TrackPreviousValuesOptions())
 
         val exception = shouldThrow<IllegalStateException> { table.validate() }
         exception.message shouldBe "Can't track old values for local-only tables."
@@ -211,20 +211,20 @@ class TableTest {
         fun serialize(table: Table): JsonObject =
             JsonUtil.json.encodeToJsonElement(serializer<SerializableTable>(), table.toSerializable()) as JsonObject
 
-        serialize(Table("foo", emptyList(), includeMetadata = true))["include_metadata"]!!.jsonPrimitive.boolean shouldBe true
-        serialize(Table("foo", emptyList(), ignoreEmptyUpdate = true))["ignore_empty_update"]!!.jsonPrimitive.boolean shouldBe true
+        serialize(Table("foo", emptyList(), trackMetadata = true))["include_metadata"]!!.jsonPrimitive.boolean shouldBe true
+        serialize(Table("foo", emptyList(), ignoreEmptyUpdates = true))["ignore_empty_update"]!!.jsonPrimitive.boolean shouldBe true
 
-        serialize(Table("foo", emptyList(), includeOld = IncludeOldOptions())).let {
+        serialize(Table("foo", emptyList(), trackPreviousValues = TrackPreviousValuesOptions())).let {
             it["include_old"]!!.jsonPrimitive.boolean shouldBe true
             it["include_old_only_when_changed"]!!.jsonPrimitive.boolean shouldBe false
         }
 
-        serialize(Table("foo", emptyList(), includeOld = IncludeOldOptions(columnFilter = listOf("foo", "bar")))).let {
+        serialize(Table("foo", emptyList(), trackPreviousValues = TrackPreviousValuesOptions(columnFilter = listOf("foo", "bar")))).let {
             it["include_old"]!!.jsonArray.map { e -> e.jsonPrimitive.content } shouldBe listOf("foo", "bar")
             it["include_old_only_when_changed"]!!.jsonPrimitive.boolean shouldBe false
         }
 
-        serialize(Table("foo", emptyList(), includeOld = IncludeOldOptions(onlyWhenChanged = true))).let {
+        serialize(Table("foo", emptyList(), trackPreviousValues = TrackPreviousValuesOptions(onlyWhenChanged = true))).let {
             it["include_old"]!!.jsonPrimitive.boolean shouldBe true
             it["include_old_only_when_changed"]!!.jsonPrimitive.boolean shouldBe true
         }