Add patch functions

src/main/kotlin/ConnectionExtensions.kt

@@ -302,6 +302,60 @@ inline fun <reified TDoc> Connection.findFirstByJsonPath(
 ) =
     Find.firstByJsonPath<TDoc>(tableName, path, orderBy, this)
 
+// ~~~ DOCUMENT PATCH (PARTIAL UPDATE) QUERIES ~~~
+
+/**
+ * Patch a document by its ID
+ *
+ * @param tableName The name of the table in which a document should be patched
+ * @param docId The ID of the document to be patched
+ * @param patch The object whose properties should be replaced in the document
+ */
+inline fun <TKey, reified TPatch> Connection.patchById(tableName: String, docId: TKey, patch: TPatch) =
+    Patch.byId(tableName, docId, patch, this)
+
+/**
+ * Patch documents using a field comparison
+ *
+ * @param tableName The name of the table in which documents should be patched
+ * @param fields The fields which should be compared
+ * @param patch The object whose properties should be replaced in the document
+ * @param howMatched How the fields should be matched
+ */
+inline fun <reified TPatch> Connection.patchByFields(
+    tableName: String,
+    fields: Collection<Field<*>>,
+    patch: TPatch,
+    howMatched: FieldMatch? = null
+) =
+    Patch.byFields(tableName, fields, patch, howMatched, this)
+
+/**
+ * Patch documents using a JSON containment query (PostgreSQL only)
+ *
+ * @param tableName The name of the table in which documents should be patched
+ * @param criteria The object against which JSON containment should be checked
+ * @param patch The object whose properties should be replaced in the document
+ * @throws DocumentException If called on a SQLite connection
+ */
+inline fun <reified TContains, reified TPatch> Connection.patchByContains(
+    tableName: String,
+    criteria: TContains,
+    patch: TPatch
+) =
+    Patch.byContains(tableName, criteria, patch, this)
+
+/**
+ * Patch documents using a JSON Path match query (PostgreSQL only)
+ *
+ * @param tableName The name of the table in which documents should be patched
+ * @param path The JSON path comparison to match
+ * @param patch The object whose properties should be replaced in the document
+ * @throws DocumentException If called on a SQLite connection
+ */
+inline fun <reified TPatch> Connection.patchByJsonPath(tableName: String, path: String, patch: TPatch) =
+    Patch.byJsonPath(tableName, path, patch, this)
+
 // ~~~ DOCUMENT DELETION QUERIES ~~~
 
 /**

src/main/kotlin/Patch.kt

@@ -0,0 +1,135 @@
+package solutions.bitbadger.documents
+
+import solutions.bitbadger.documents.query.Patch
+import java.sql.Connection
+
+/**
+ * Functions to patch (partially update) documents
+ */
+object Patch {
+
+    /**
+     * Patch a document by its ID
+     *
+     * @param tableName The name of the table in which a document should be patched
+     * @param docId The ID of the document to be patched
+     * @param patch The object whose properties should be replaced in the document
+     * @param conn The connection on which the update should be executed
+     */
+    inline fun <TKey, reified TPatch> byId(tableName: String, docId: TKey, patch: TPatch, conn: Connection) =
+        conn.customNonQuery(
+            Patch.byId(tableName, docId),
+            Parameters.addFields(
+                listOf(Field.equal(Configuration.idField, docId, ":id")),
+                mutableListOf(Parameters.json(":data", patch))
+            )
+        )
+
+    /**
+     * Patch a document by its ID
+     *
+     * @param tableName The name of the table in which a document should be patched
+     * @param docId The ID of the document to be patched
+     * @param patch The object whose properties should be replaced in the document
+     */
+    inline fun <TKey, reified TPatch> byId(tableName: String, docId: TKey, patch: TPatch) =
+        Configuration.dbConn().use { byId(tableName, docId, patch, it) }
+
+    /**
+     * Patch documents using a field comparison
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param fields The fields which should be compared
+     * @param patch The object whose properties should be replaced in the document
+     * @param howMatched How the fields should be matched
+     * @param conn The connection on which the update should be executed
+     */
+    inline fun <reified TPatch> byFields(
+        tableName: String,
+        fields: Collection<Field<*>>,
+        patch: TPatch,
+        howMatched: FieldMatch? = null,
+        conn: Connection
+    ) {
+        val named = Parameters.nameFields(fields)
+        conn.customNonQuery(
+            Patch.byFields(tableName, named, howMatched), Parameters.addFields(
+                named,
+                mutableListOf(Parameters.json(":data", patch))
+            )
+        )
+    }
+
+    /**
+     * Patch documents using a field comparison
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param fields The fields which should be compared
+     * @param patch The object whose properties should be replaced in the document
+     * @param howMatched How the fields should be matched
+     */
+    inline fun <reified TPatch> byFields(
+        tableName: String,
+        fields: Collection<Field<*>>,
+        patch: TPatch,
+        howMatched: FieldMatch? = null
+    ) =
+        Configuration.dbConn().use { byFields(tableName, fields, patch, howMatched, it) }
+
+    /**
+     * Patch documents using a JSON containment query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param criteria The object against which JSON containment should be checked
+     * @param patch The object whose properties should be replaced in the document
+     * @param conn The connection on which the update should be executed
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified TContains, reified TPatch> byContains(
+        tableName: String,
+        criteria: TContains,
+        patch: TPatch,
+        conn: Connection
+    ) =
+        conn.customNonQuery(
+            Patch.byContains(tableName),
+            listOf(Parameters.json(":criteria", criteria), Parameters.json(":data", patch))
+        )
+
+    /**
+     * Patch documents using a JSON containment query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param criteria The object against which JSON containment should be checked
+     * @param patch The object whose properties should be replaced in the document
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified TContains, reified TPatch> byContains(tableName: String, criteria: TContains, patch: TPatch) =
+        Configuration.dbConn().use { byContains(tableName, criteria, patch, it) }
+
+    /**
+     * Patch documents using a JSON Path match query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param path The JSON path comparison to match
+     * @param patch The object whose properties should be replaced in the document
+     * @param conn The connection on which the update should be executed
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified TPatch> byJsonPath(tableName: String, path: String, patch: TPatch, conn: Connection) =
+        conn.customNonQuery(
+            Patch.byJsonPath(tableName),
+            listOf(Parameter(":path", ParameterType.STRING, path), Parameters.json(":data", patch))
+        )
+
+    /**
+     * Patch documents using a JSON Path match query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which documents should be patched
+     * @param path The JSON path comparison to match
+     * @param patch The object whose properties should be replaced in the document
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified TPatch> byJsonPath(tableName: String, path: String, patch: TPatch) =
+        Configuration.dbConn().use { byJsonPath(tableName, path, patch, it) }
+}