Add exists functions

src/main/kotlin/ConnectionExtensions.kt

@@ -127,7 +127,7 @@ inline fun <reified T> Connection.countByContains(tableName: String, criteria: T
     Count.byContains(tableName, criteria, this)
 
 /**
- * Count documents using a JSON containment query (PostgreSQL only)
+ * Count documents using a JSON Path match query (PostgreSQL only)
  *
  * @param tableName The name of the table in which documents should be counted
  * @param path The JSON path comparison to match
@@ -137,6 +137,51 @@ inline fun <reified T> Connection.countByContains(tableName: String, criteria: T
 fun Connection.countByJsonPath(tableName: String, path: String) =
     Count.byJsonPath(tableName, path, this)
 
+// ~~~ DOCUMENT EXISTENCE QUERIES ~~~
+
+/**
+ * Determine a document's existence by its ID
+ *
+ * @param tableName The name of the table in which document existence should be checked
+ * @param docId The ID of the document to be checked
+ * @return True if the document exists, false if not
+ */
+fun <TKey> Connection.existsById(tableName: String, docId: TKey) =
+    Exists.byId(tableName, docId, this)
+
+/**
+ * Determine document existence using a field comparison
+ *
+ * @param tableName The name of the table in which document existence should be checked
+ * @param fields The fields which should be compared
+ * @param howMatched How the fields should be matched
+ * @return True if any matching documents exist, false if not
+ */
+fun Connection.existsByFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+    Exists.byFields(tableName, fields, howMatched, this)
+
+/**
+ * Determine document existence using a JSON containment query (PostgreSQL only)
+ *
+ * @param tableName The name of the table in which document existence should be checked
+ * @param criteria The object for which JSON containment should be checked
+ * @return True if any matching documents exist, false if not
+ * @throws DocumentException If called on a SQLite connection
+ */
+inline fun <reified T> Connection.existsByContains(tableName: String, criteria: T) =
+    Exists.byContains(tableName, criteria, this)
+
+/**
+ * Determine document existence using a JSON Path match query (PostgreSQL only)
+ *
+ * @param tableName The name of the table in which document existence should be checked
+ * @param path The JSON path comparison to match
+ * @return True if any matching documents exist, false if not
+ * @throws DocumentException If called on a SQLite connection
+ */
+fun Connection.existsByJsonPath(tableName: String, path: String) =
+    Exists.byJsonPath(tableName, path, this)
+
 // ~~~ DOCUMENT RETRIEVAL QUERIES ~~~
 
 /**
@@ -189,7 +234,7 @@ inline fun <reified T> Connection.deleteByContains(tableName: String, criteria:
     Delete.byContains(tableName, criteria, this)
 
 /**
- * Delete documents using a JSON containment query (PostgreSQL only)
+ * Delete documents using a JSON Path match query (PostgreSQL only)
  *
  * @param tableName The name of the table from which documents should be deleted
  * @param path The JSON path comparison to match

src/main/kotlin/Count.kt

@@ -85,7 +85,7 @@ object Count {
         Configuration.dbConn().use { byContains(tableName, criteria, it) }
 
     /**
-     * Count documents using a JSON containment query (PostgreSQL only)
+     * Count documents using a JSON Path match query (PostgreSQL only)
      *
      * @param tableName The name of the table in which documents should be counted
      * @param path The JSON path comparison to match
@@ -101,7 +101,7 @@ object Count {
         )
 
     /**
-     * Count documents using a JSON containment query (PostgreSQL only)
+     * Count documents using a JSON Path match query (PostgreSQL only)
      *
      * @param tableName The name of the table in which documents should be counted
      * @param path The JSON path comparison to match

src/main/kotlin/Delete.kt

@@ -75,7 +75,7 @@ object Delete {
         Configuration.dbConn().use { byContains(tableName, criteria, it) }
 
     /**
-     * Delete documents using a JSON containment query (PostgreSQL only)
+     * Delete documents using a JSON Path match query (PostgreSQL only)
      *
      * @param tableName The name of the table from which documents should be deleted
      * @param path The JSON path comparison to match
@@ -86,7 +86,7 @@ object Delete {
         conn.customNonQuery(Delete.byJsonPath(tableName), listOf(Parameter(":path", ParameterType.STRING, path)))
 
     /**
-     * Delete documents using a JSON containment query (PostgreSQL only)
+     * Delete documents using a JSON Path match query (PostgreSQL only)
      *
      * @param tableName The name of the table from which documents should be deleted
      * @param path The JSON path comparison to match

src/main/kotlin/Exists.kt

@@ -0,0 +1,123 @@
+package solutions.bitbadger.documents
+
+import solutions.bitbadger.documents.query.Exists
+import java.sql.Connection
+
+/**
+ * Functions to determine whether documents exist
+ */
+object Exists {
+
+    /**
+     * Determine a document's existence by its ID
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param docId The ID of the document to be checked
+     * @param conn The connection on which the existence check should be executed
+     * @return True if the document exists, false if not
+     */
+    fun <TKey> byId(tableName: String, docId: TKey, conn: Connection) =
+        conn.customScalar(
+            Exists.byId(tableName, docId),
+            Parameters.addFields(listOf(Field.equal(Configuration.idField, docId, ":id"))),
+            Results::toExists
+        )
+
+    /**
+     * Determine a document's existence by its ID
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param docId The ID of the document to be checked
+     * @return True if the document exists, false if not
+     */
+    fun <TKey> byId(tableName: String, docId: TKey) =
+        Configuration.dbConn().use { byId(tableName, docId, it) }
+
+    /**
+     * Determine document existence using a field comparison
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param fields The fields which should be compared
+     * @param howMatched How the fields should be matched
+     * @param conn The connection on which the existence check should be executed
+     * @return True if any matching documents exist, false if not
+     */
+    fun byFields(
+        tableName: String,
+        fields: Collection<Field<*>>,
+        howMatched: FieldMatch? = null,
+        conn: Connection
+    ): Boolean {
+        val named = Parameters.nameFields(fields)
+        return conn.customScalar(
+            Exists.byFields(tableName, named, howMatched),
+            Parameters.addFields(named),
+            Results::toExists
+        )
+    }
+
+    /**
+     * Determine document existence using a field comparison
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param fields The fields which should be compared
+     * @param howMatched How the fields should be matched
+     * @return True if any matching documents exist, false if not
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        Configuration.dbConn().use { byFields(tableName, fields, howMatched, it) }
+
+    /**
+     * Determine document existence using a JSON containment query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param criteria The object for which JSON containment should be checked
+     * @param conn The connection on which the existence check should be executed
+     * @return True if any matching documents exist, false if not
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified T> byContains(tableName: String, criteria: T, conn: Connection) =
+        conn.customScalar(
+            Exists.byContains(tableName),
+            listOf(Parameters.json(":criteria", criteria)),
+            Results::toExists
+        )
+
+    /**
+     * Determine document existence using a JSON containment query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param criteria The object for which JSON containment should be checked
+     * @return True if any matching documents exist, false if not
+     * @throws DocumentException If called on a SQLite connection
+     */
+    inline fun <reified T> byContains(tableName: String, criteria: T) =
+        Configuration.dbConn().use { byContains(tableName, criteria, it) }
+
+    /**
+     * Determine document existence using a JSON Path match query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param path The JSON path comparison to match
+     * @param conn The connection on which the existence check should be executed
+     * @return True if any matching documents exist, false if not
+     * @throws DocumentException If called on a SQLite connection
+     */
+    fun byJsonPath(tableName: String, path: String, conn: Connection) =
+        conn.customScalar(
+            Exists.byJsonPath(tableName),
+            listOf(Parameter(":path", ParameterType.STRING, path)),
+            Results::toExists
+        )
+
+    /**
+     * Determine document existence using a JSON Path match query (PostgreSQL only)
+     *
+     * @param tableName The name of the table in which document existence should be checked
+     * @param path The JSON path comparison to match
+     * @return True if any matching documents exist, false if not
+     * @throws DocumentException If called on a SQLite connection
+     */
+    fun byJsonPath(tableName: String, path: String) =
+        Configuration.dbConn().use { byJsonPath(tableName, path, it) }
+}