Move query to package

src/main/kotlin/query/Count.kt

@@ -0,0 +1,49 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+import solutions.bitbadger.documents.query.byFields as byFieldsBase;
+
+/**
+ * Functions to count documents
+ */
+object Count {
+
+    /**
+     * Query to count all documents in a table
+     *
+     * @param tableName The table in which to count documents (may include schema)
+     * @return A query to count documents
+     */
+    fun all(tableName: String) =
+        "SELECT COUNT(*) AS it FROM $tableName"
+
+    /**
+     * Query to count documents matching the given fields
+     *
+     * @param tableName The table in which to count documents (may include schema)
+     * @param fields The field comparisons for the count
+     * @param howMatched How fields should be compared (optional, defaults to ALL)
+     * @return A query to count documents matching the given fields
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        byFieldsBase(all(tableName), fields, howMatched)
+
+    /**
+     * Query to count documents via JSON containment (PostgreSQL only)
+     *
+     * @param tableName The table in which to count documents (may include schema)
+     * @return A query to count documents via JSON containment
+     */
+    fun byContains(tableName: String) =
+        statementWhere(all(tableName), Where.jsonContains())
+
+    /**
+     * Query to count documents via a JSON path match (PostgreSQL only)
+     *
+     * @param tableName The table in which to count documents (may include schema)
+     * @return A query to count documents via a JSON path match
+     */
+    fun byJsonPath(tableName: String) =
+        statementWhere(all(tableName), Where.jsonPathMatches())
+}

src/main/kotlin/query/Definition.kt

@@ -0,0 +1,72 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Configuration
+import solutions.bitbadger.documents.Dialect
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldFormat
+
+/**
+ * Functions to create queries to define tables and indexes
+ */
+object Definition {
+
+    /**
+     * SQL statement to create a document table
+     *
+     * @param tableName The name of the table to create (may include schema)
+     * @param dataType The type of data for the column (`JSON`, `JSONB`, etc.)
+     * @return A query to create a document table
+     */
+    fun ensureTableFor(tableName: String, dataType: String) =
+        "CREATE TABLE IF NOT EXISTS $tableName (data $dataType NOT NULL)"
+
+    /**
+     * SQL statement to create a document table in the current dialect
+     *
+     * @param tableName The name of the table to create (may include schema)
+     * @return A query to create a document table
+     */
+    fun ensureTable(tableName: String) =
+        when (Configuration.dialect("create table creation query")) {
+            Dialect.POSTGRESQL -> ensureTableFor(tableName, "JSONB")
+            Dialect.SQLITE     -> ensureTableFor(tableName, "TEXT")
+        }
+
+    /**
+     * Split a schema and table name
+     *
+     * @param tableName The name of the table, possibly with a schema
+     * @return A pair with the first item as the schema and the second as the table name
+     */
+    private fun splitSchemaAndTable(tableName: String) =
+        tableName.split('.').let { if (it.size == 1) Pair("", tableName) else Pair(it[0], it[1]) }
+
+    /**
+     * SQL statement to create an index on one or more fields in a JSON document
+     *
+     * @param tableName The table on which an index should be created (may include schema)
+     * @param indexName The name of the index to be created
+     * @param fields One or more fields to include in the index
+     * @param dialect The SQL dialect to use when creating this index
+     * @return A query to create the field index
+     */
+    fun ensureIndexOn(tableName: String, indexName: String, fields: Collection<String>, dialect: Dialect): String {
+        val (_, tbl) = splitSchemaAndTable(tableName)
+        val jsonFields = fields.joinToString(", ") {
+            val parts = it.split(' ')
+            val direction = if (parts.size > 1) " ${parts[1]}" else ""
+            "(" + Field.nameToPath(parts[0], dialect, FieldFormat.SQL) + ")$direction"
+        }
+        return "CREATE INDEX IF NOT EXISTS idx_${tbl}_$indexName ON $tableName ($jsonFields)"
+    }
+
+    /**
+     * SQL statement to create a key index for a document table
+     *
+     * @param tableName The table on which a key index should be created (may include schema)
+     * @param dialect The SQL dialect to use when creating this index
+     * @return A query to create the key index
+     */
+    fun ensureKey(tableName: String, dialect: Dialect) =
+        ensureIndexOn(tableName, "key", listOf(Configuration.idField), dialect).replace("INDEX", "UNIQUE INDEX")
+}

src/main/kotlin/query/Delete.kt

@@ -0,0 +1,61 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+import solutions.bitbadger.documents.query.byFields as byFieldsBase
+import solutions.bitbadger.documents.query.byId as byIdBase
+
+/**
+ * Functions to delete documents
+ */
+object Delete {
+
+    /**
+     * Query to delete documents from a table
+     *
+     * @param tableName The table in which documents should be deleted (may include schema)
+     * @param where The WHERE clause for the delete statement
+     * @return A query to delete documents
+     */
+    private fun delete(tableName: String) =
+        "DELETE FROM $tableName"
+
+    /**
+     * Query to delete a document by its ID
+     *
+     * @param tableName The table from which documents should be deleted (may include schema)
+     * @param docId The ID of the document (optional, used for type checking)
+     * @return A query to delete a document by its ID
+     */
+    fun <TKey> byId(tableName: String, docId: TKey? = null) =
+         byIdBase(delete(tableName), docId)
+
+    /**
+     * Query to delete documents matching the given fields
+     *
+     * @param tableName The table from which documents should be deleted (may include schema)
+     * @param fields The field comparisons for documents to be deleted
+     * @param howMatched How fields should be compared (optional, defaults to ALL)
+     * @return A query to delete documents matching for the given fields
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        byFieldsBase(delete(tableName), fields, howMatched)
+
+    /**
+     * Query to delete documents via JSON containment (PostgreSQL only)
+     *
+     * @param tableName The table from which documents should be deleted (may include schema)
+     * @return A query to delete documents via JSON containment
+     */
+    fun byContains(tableName: String) =
+        statementWhere(delete(tableName), Where.jsonContains())
+
+    /**
+     * Query to delete documents via a JSON path match (PostgreSQL only)
+     *
+     * @param tableName The table from which documents should be deleted (may include schema)
+     * @return A query to delete documents via a JSON path match
+     */
+    fun byJsonPath(tableName: String) =
+        statementWhere(delete(tableName), Where.jsonPathMatches())
+}

src/main/kotlin/query/Document.kt

@@ -0,0 +1,58 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.AutoId
+import solutions.bitbadger.documents.Configuration
+import solutions.bitbadger.documents.Dialect
+
+/**
+ * Functions for document-level operations
+ */
+object Document {
+
+    /**
+     * Query to insert a document
+     *
+     * @param tableName The table into which to insert (may include schema)
+     * @return A query to insert a document
+     */
+    fun insert(tableName: String, autoId: AutoId? = null): String {
+        val id = Configuration.idField
+        val values = when (Configuration.dialect("create INSERT statement")) {
+            Dialect.POSTGRESQL -> when (autoId ?: AutoId.DISABLED) {
+                AutoId.DISABLED      -> ":data"
+                AutoId.NUMBER        -> ":data::jsonb || ('{\"$id\":' || " +
+                        "(SELECT COALESCE(MAX((data->>'$id')::numeric), 0) + 1 " +
+                        "FROM $tableName) || '}')::jsonb"
+                AutoId.UUID          -> ":data::jsonb || '{\"$id\":\"${AutoId.generateUUID()}\"}'"
+                AutoId.RANDOM_STRING -> ":data::jsonb || '{\"$id\":\"${AutoId.generateRandomString()}\"}'"
+            }
+            Dialect.SQLITE -> when (autoId ?: AutoId.DISABLED) {
+                AutoId.DISABLED      -> ":data"
+                AutoId.NUMBER        -> "json_set(:data, '$.$id', " +
+                        "(SELECT coalesce(max(data->>'$id'), 0) + 1 FROM $tableName))"
+                AutoId.UUID          -> "json_set(:data, '$.$id', '${AutoId.generateUUID()}')"
+                AutoId.RANDOM_STRING -> "json_set(:data, '$.$id', '${AutoId.generateRandomString()}')"
+            }
+        }
+        return "INSERT INTO $tableName VALUES ($values)"
+    }
+
+    /**
+     * Query to save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
+     *
+     * @param tableName The table into which to save (may include schema)
+     * @return A query to save a document
+     */
+    fun save(tableName: String) =
+        insert(tableName, AutoId.DISABLED) +
+                " ON CONFLICT ((data->>'${Configuration.idField}')) DO UPDATE SET data = EXCLUDED.data"
+
+    /**
+     * Query to update (replace) a document (this query has no `WHERE` clause)
+     *
+     * @param tableName The table in which documents should be replaced (may include schema)
+     * @return A query to update documents
+     */
+    fun update(tableName: String) =
+        "UPDATE $tableName SET data = :data"
+}

src/main/kotlin/query/Exists.kt

@@ -0,0 +1,59 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+
+/**
+ * Functions to check for document existence
+ */
+object Exists {
+
+    /**
+     * Query to check for document existence in a table
+     *
+     * @param tableName The table in which existence should be checked (may include schema)
+     * @param where The `WHERE` clause with the existence criteria
+     * @return A query to check document existence
+     */
+    private fun exists(tableName: String, where: String) =
+        "SELECT EXISTS (SELECT 1 FROM $tableName WHERE $where) AS it"
+
+    /**
+     * Query to check for document existence by ID
+     *
+     * @param tableName The table in which existence should be checked (may include schema)
+     * @param docId The ID of the document (optional, used for type checking)
+     * @return A query to determine document existence by ID
+     */
+    fun <TKey> byId(tableName: String, docId: TKey? = null) =
+        exists(tableName, Where.byId(docId = docId))
+
+    /**
+     * Query to check for document existence matching the given fields
+     *
+     * @param tableName The table in which existence should be checked (may include schema)
+     * @param fields The field comparisons for the existence check
+     * @param howMatched How fields should be compared (optional, defaults to ALL)
+     * @return A query to determine document existence for the given fields
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        exists(tableName, Where.byFields(fields, howMatched))
+
+    /**
+     * Query to check for document existence via JSON containment (PostgreSQL only)
+     *
+     * @param tableName The table in which existence should be checked (may include schema)
+     * @return A query to determine document existence via JSON containment
+     */
+    fun byContains(tableName: String) =
+        exists(tableName, Where.jsonContains())
+
+    /**
+     * Query to check for document existence via a JSON path match (PostgreSQL only)
+     *
+     * @param tableName The table in which existence should be checked (may include schema)
+     * @return A query to determine document existence via a JSON path match
+     */
+    fun byJsonPath(tableName: String) =
+        exists(tableName, Where.jsonPathMatches())
+}

src/main/kotlin/query/Find.kt

@@ -0,0 +1,60 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+import solutions.bitbadger.documents.query.byId as byIdBase
+import solutions.bitbadger.documents.query.byFields as byFieldsBase
+
+/**
+ * Functions to retrieve documents
+ */
+object Find {
+
+    /**
+     * Query to retrieve all documents from a table
+     *
+     * @param tableName The table from which documents should be retrieved (may include schema)
+     * @return A query to retrieve documents
+     */
+    fun all(tableName: String) =
+        "SELECT data FROM $tableName"
+
+    /**
+     * Query to retrieve a document by its ID
+     *
+     * @param tableName The table from which documents should be retrieved (may include schema)
+     * @param docId The ID of the document (optional, used for type checking)
+     * @return A query to retrieve a document by its ID
+     */
+    fun <TKey> byId(tableName: String, docId: TKey? = null) =
+        byIdBase(all(tableName), docId)
+
+    /**
+     * Query to retrieve documents matching the given fields
+     *
+     * @param tableName The table from which documents should be retrieved (may include schema)
+     * @param fields The field comparisons for matching documents to retrieve
+     * @param howMatched How fields should be compared (optional, defaults to ALL)
+     * @return A query to retrieve documents matching the given fields
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        byFieldsBase(all(tableName), fields, howMatched)
+
+    /**
+     * Query to retrieve documents via JSON containment (PostgreSQL only)
+     *
+     * @param tableName The table from which documents should be retrieved (may include schema)
+     * @return A query to retrieve documents via JSON containment
+     */
+    fun byContains(tableName: String) =
+        statementWhere(all(tableName), Where.jsonContains())
+
+    /**
+     * Query to retrieve documents via a JSON path match (PostgreSQL only)
+     *
+     * @param tableName The table from which documents should be retrieved (may include schema)
+     * @return A query to retrieve documents via a JSON path match
+     */
+    fun byJsonPath(tableName: String) =
+        statementWhere(all(tableName), Where.jsonPathMatches())
+}

src/main/kotlin/query/Patch.kt

@@ -0,0 +1,65 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Configuration
+import solutions.bitbadger.documents.Dialect
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+import solutions.bitbadger.documents.query.byFields as byFieldsBase
+import solutions.bitbadger.documents.query.byId as byIdBase
+
+/**
+ * Functions to create queries to patch (partially update) JSON documents
+ */
+object Patch {
+
+    /**
+     * Create an `UPDATE` statement to patch documents
+     *
+     * @param tableName The table to be updated
+     * @return A query to patch documents
+     */
+    private fun patch(tableName: String) =
+        when (Configuration.dialect("create patch query")) {
+            Dialect.POSTGRESQL -> "data || :data"
+            Dialect.SQLITE -> "json_patch(data, json(:data))"
+        }.let { "UPDATE $tableName SET data = $it" }
+
+    /**
+     * A query to patch (partially update) a JSON document by its ID
+     *
+     * @param tableName The name of the table where the document is stored
+     * @param docId The ID of the document to be updated (optional, used for type checking)
+     * @return A query to patch a JSON document by its ID
+     */
+    fun <TKey> byId(tableName: String, docId: TKey? = null) =
+        byIdBase(patch(tableName), docId)
+
+    /**
+     * A query to patch (partially update) a JSON document using field match criteria
+     *
+     * @param tableName The name of the table where the documents are stored
+     * @param fields The field criteria
+     * @param howMatched How the fields should be matched (optional, defaults to `ALL`)
+     * @return A query to patch JSON documents by field match criteria
+     */
+    fun byFields(tableName: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        byFieldsBase(patch(tableName), fields, howMatched)
+
+    /**
+     * A query to patch (partially update) a JSON document by JSON containment (PostgreSQL only)
+     *
+     * @param tableName The name of the table where the document is stored
+     * @return A query to patch JSON documents by JSON containment
+     */
+    fun <TKey> byContains(tableName: String) =
+        statementWhere(patch(tableName), Where.jsonContains())
+
+    /**
+     * A query to patch (partially update) a JSON document by JSON path match (PostgreSQL only)
+     *
+     * @param tableName The name of the table where the document is stored
+     * @return A query to patch JSON documents by JSON path match
+     */
+    fun <TKey> byJsonPath(tableName: String) =
+        statementWhere(patch(tableName), Where.jsonPathMatches())
+}

src/main/kotlin/query/Query.kt

@@ -0,0 +1,75 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.Dialect
+import solutions.bitbadger.documents.Field
+import solutions.bitbadger.documents.FieldMatch
+
+// ~~~ TOP-LEVEL FUNCTIONS FOR THE QUERY PACKAGE ~~~
+
+/**
+ * Combine a query (`SELECT`, `UPDATE`, etc.) and a `WHERE` clause
+ *
+ * @param statement The first part of the statement
+ * @param where The `WHERE` clause for the statement
+ * @return The two parts of the query combined with `WHERE`
+ */
+fun statementWhere(statement: String, where: String) =
+    "$statement WHERE $where"
+
+/**
+ * Create a query by a document's ID
+ *
+ * @param statement The SQL statement to be run against a document by its ID
+ * @param docId The ID of the document targeted
+ * @returns A query addressing a document by its ID
+ */
+fun <TKey> byId(statement: String, docId: TKey) =
+    statementWhere(statement, Where.byId(docId = docId))
+
+/**
+ * Create a query on JSON fields
+ *
+ * @param statement The SQL statement to be run against matching fields
+ * @param fields The field conditions to be matched
+ * @param howMatched Whether to match any or all of the field conditions (optional; default ALL)
+ * @return A query addressing documents by field matching conditions
+ */
+fun byFields(statement: String, fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+    statementWhere(statement, Where.byFields(fields, howMatched))
+
+/**
+ * Create an `ORDER BY` clause for the given fields
+ *
+ * @param fields One or more fields by which to order
+ * @param dialect The SQL dialect for the generated clause
+ * @return An `ORDER BY` clause for the given fields
+ */
+fun orderBy(fields: Collection<Field<*>>, dialect: Dialect): String {
+    if (fields.isEmpty()) return ""
+    val orderFields = fields.joinToString(", ") {
+        val (field, direction) =
+            if (it.name.indexOf(' ') > -1) {
+                val parts = it.name.split(' ')
+                Pair(Field.named(parts[0]), " " + parts.drop(1).joinToString(" "))
+            } else {
+                Pair<Field<*>, String?>(it, null)
+            }
+        val path = when {
+            field.name.startsWith("n:") -> Field.named(field.name.substring(2)).let { fld ->
+                when (dialect) {
+                    Dialect.POSTGRESQL -> "(${fld.path(dialect)})::numeric"
+                    Dialect.SQLITE -> fld.path(dialect)
+                }
+            }
+            field.name.startsWith("i:") ->  Field.named(field.name.substring(2)).path(dialect).let { p ->
+                when (dialect) {
+                    Dialect.POSTGRESQL -> "LOWER($p)"
+                    Dialect.SQLITE -> "$p COLLATE NOCASE"
+                }
+            }
+            else -> field.path(dialect)
+        }
+        "$path${direction ?: ""}"
+    }
+    return " ORDER BY $orderFields"
+}

src/main/kotlin/query/Where.kt

@@ -0,0 +1,54 @@
+package solutions.bitbadger.documents.query
+
+import solutions.bitbadger.documents.*
+
+/**
+ * Functions to create `WHERE` clause fragments
+ */
+object Where {
+
+    /**
+     * Create a `WHERE` clause fragment to query by one or more fields
+     *
+     * @param fields The fields to be queried
+     * @param howMatched How the fields should be matched (optional, defaults to `ALL`)
+     * @return A `WHERE` clause fragment to match the given fields
+     */
+    fun byFields(fields: Collection<Field<*>>, howMatched: FieldMatch? = null) =
+        fields.joinToString(" ${(howMatched ?: FieldMatch.ALL).sql} ") { it.toWhere() }
+
+    /**
+     * Create a `WHERE` clause fragment to retrieve a document by its ID
+     *
+     * @param parameterName The parameter name to use for the ID placeholder (optional, defaults to ":id")
+     * @param docId The ID value (optional; used for type determinations, string assumed if not provided)
+     */
+    fun <TKey> byId(parameterName: String = ":id", docId: TKey? = null) =
+        byFields(listOf(Field.equal(Configuration.idField, docId ?: "", parameterName)))
+
+    /**
+     * Create a `WHERE` clause fragment to implement a JSON containment query (PostgreSQL only)
+     *
+     * @param parameterName The parameter name to use for the JSON placeholder (optional, defaults to ":criteria")
+     * @return A `WHERE` clause fragment to implement a JSON containment criterion
+     * @throws DocumentException If called against a SQLite database
+     */
+    fun jsonContains(parameterName: String = ":criteria") =
+        when (Configuration.dialect("create containment WHERE clause")) {
+            Dialect.POSTGRESQL -> "data @> $parameterName"
+            Dialect.SQLITE     -> throw DocumentException("JSON containment is not supported")
+        }
+
+    /**
+     * Create a `WHERE` clause fragment to implement a JSON path match query (PostgreSQL only)
+     *
+     * @param parameterName The parameter name to use for the placeholder (optional, defaults to ":path")
+     * @return A `WHERE` clause fragment to implement a JSON path match criterion
+     * @throws DocumentException If called against a SQLite database
+     */
+    fun jsonPathMatches(parameterName: String = ":path") =
+        when (Configuration.dialect("create JSON path match WHERE clause")) {
+            Dialect.POSTGRESQL -> "jsonb_path_exists(data, $parameterName::jsonpath)"
+            Dialect.SQLITE     -> throw DocumentException("JSON path match is not supported")
+        }
+}