From db720515fab4cf1899a56c5dbf874d0ee46bb9b9 Mon Sep 17 00:00:00 2001
From: "Daniel J. Summers" <daniel@bitbadger.solutions>
Date: Tue, 25 Mar 2025 08:19:20 -0400
Subject: [PATCH] First cut of README; tweak kotlinx pom

---
 .idea/compiler.xml  |  2 +-
 README.md           | 52 ++++++++++++++++++++++++++++++++++++++++++++-
 src/kotlinx/pom.xml |  2 +-
 3 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/.idea/compiler.xml b/.idea/compiler.xml
index ea58415..0d99751 100644
--- a/.idea/compiler.xml
+++ b/.idea/compiler.xml
@@ -6,6 +6,7 @@
         <sourceOutputDir name="target/generated-sources/annotations" />
         <sourceTestOutputDir name="target/generated-test-sources/test-annotations" />
         <outputRelativeToContentRoot value="true" />
+        <module name="kotlin" />
         <module name="core" />
         <module name="groovy" />
         <module name="scala" />
@@ -19,7 +20,6 @@
       <module name="documents (2)" target="1.5" />
       <module name="java" target="17" />
       <module name="jvm" target="11" />
-      <module name="kotlin" target="17" />
       <module name="sqlite" target="1.8" />
     </bytecodeTargetLevel>
   </component>
diff --git a/README.md b/README.md
index 78c5f33..dac2e29 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,53 @@
 # solutions.bitbadger.documents
 
-Treat PostgreSQL and SQLite as document stores from Java and Kotlin
\ No newline at end of file
+Treat PostgreSQL and SQLite as document stores from Java, Kotlin, Scala, and Groovy
+
+## Examples
+
+```java
+// Retrieve (find) all orders (Java)
+public List<Order> findOrders(Connection conn) {
+    Find.all(/*table name*/ "order", /*type*/ Order.class, conn);
+}
+```
+
+```kotlin
+// Mark an order as fulfilled (Kotlin)
+fun markFulfilled(orderId: Long, conn: Connection) =
+    conn.patchById(
+        /*table name*/ "order",
+        /*document ID*/ orderId,
+        /*patch object*/ mapOf("fulfilled" to true)
+    )
+```
+
+```scala
+// Delete orders marked as obsolete (Scala)
+def deleteObsolete(Connection conn):
+  conn.deleteByFields(/*table name*/ "order",
+    /*field criteria*/ Field.equal("obsolete", true) :: Nil)
+```
+
+```groovy
+// Remove the pending status from multiple orders (Groovy)
+void clearPending(List<Long> orderIds, Connection conn) {
+    conn.removeFieldsByFields(/*table name*/ "order",
+            /*field criteria*/ List.of(Field.any("id", orderIds)),
+            /*fields to remove*/ List.of("pending"))
+}
+```
+
+## Packages / Modules
+
+* The `core` module provides the base implementation and can be used from any JVM language.
+  * The `solutions.bitbadger.documents` package contains support types like `Configuration` and `Field`.
+  * The `solutions.bitbadger.documents.java` package contains document access functions and serialization config.
+  * The `solutions.bitbadger.documents.java.extensions` package contains extensions on the JDBC `Connection` object, callable as extension methods from Kotlin or as static functions from other languages.
+
+* The `groovy` module packages the extension methods so that Groovy can access them. No other packages will need to be imported; they will show up on any `Connection` instance.
+
+* The `kotlinx` module utilizes the kotlinx-serialization project for its JSON serialization, which requires a different serializer and different function/method signatures (`inline fun <reified T> ...` vs. `fun <T> ...`).
+  * `solutions.bitbadger.documents.kotlinx` and `solutions.bitbadger.documents.kotlinx.extensions` packages expose a similar API to their `java` counterparts, but one designed to be consumed from Kotlin. Generally, document retrieval functions will require a generic parameter instead of a `Class<T>` parameter.  
+
+* The `scala` module extends `core` by utilizing Scala's implicit `ClassTag`s to remove the `Class[T]` parameter.
+  * `solutions.bitbadger.documents.scala` and `solutions.bitbadger.documents.scala.extensions` packages expose the same API as their `java` counterparts, utilizing Scala collections and `Option`s instead of Java collections and `Optional`s.
diff --git a/src/kotlinx/pom.xml b/src/kotlinx/pom.xml
index c0d6f73..272ec63 100644
--- a/src/kotlinx/pom.xml
+++ b/src/kotlinx/pom.xml
@@ -58,7 +58,7 @@
                     </execution>
                     <execution>
                         <id>test-compile</id>
-                        <phase>test-compile</phase>
+                        <phase>process-test-sources</phase>
                         <goals>
                             <goal>test-compile</goal>
                         </goals>