src/scala/src/test/scala/integration/JsonFunctions.scala

@@ -5,6 +5,7 @@ import solutions.bitbadger.documents.{Configuration, Dialect, Field, FieldMatch}
 import solutions.bitbadger.documents.scala.extensions.*
 import solutions.bitbadger.documents.scala.tests.TEST_TABLE
 
+import java.io.{PrintWriter, StringWriter}
 import scala.jdk.CollectionConverters.*
 
 /**
@@ -39,9 +40,7 @@ object JsonFunctions:
   private def docId(id: String): String =
     maybeJsonB(s"""{"id":"$id"""")
 
-  def allDefault(db: ThrowawayDatabase): Unit =
+  private def checkAllDefault(json: String): Unit =
-    JsonDocument.load(db)
-    val json = db.conn.jsonAll(TEST_TABLE)
     assertTrue(json.startsWith("["), s"JSON should start with '[' ($json)")
     Configuration.dialect() match
       case Dialect.SQLITE =>
@@ -50,7 +49,6 @@ object JsonFunctions:
         assertTrue(json.contains(JsonDocument.three), s"Document 'three' not found in JSON ($json)")
         assertTrue(json.contains(JsonDocument.four), s"Document 'four' not found in JSON ($json)")
         assertTrue(json.contains(JsonDocument.five), s"Document 'five' not found in JSON ($json)")
-
       case Dialect.POSTGRESQL =>
         assertTrue(json.contains(docId("one")), s"Document 'one' not found in JSON ($json)")
         assertTrue(json.contains(docId("two")), s"Document 'two' not found in JSON ($json)")
@@ -59,33 +57,82 @@ object JsonFunctions:
         assertTrue(json.contains(docId("five")), s"Document 'five' not found in JSON ($json)")
     assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
-  def allEmpty(db: ThrowawayDatabase): Unit =
+  def allDefault(db: ThrowawayDatabase): Unit =
-    assertEquals("[]", db.conn.jsonAll(TEST_TABLE), "There should have been no documents returned")
-
-  def byIdString (db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonById(TEST_TABLE, "two")
+    checkAllDefault(db.conn.jsonAll(TEST_TABLE))
+
+  def writeAllDefault(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonAll(TEST_TABLE, writer)
+    checkAllDefault(output.toString)
+
+  private def checkAllEmpty(json: String): Unit =
+    assertEquals("[]", json, "There should have been no documents returned")
+
+  def allEmpty(db: ThrowawayDatabase): Unit =
+    checkAllEmpty(db.conn.jsonAll(TEST_TABLE))
+
+  def writeAllEmpty(db: ThrowawayDatabase): Unit =
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonAll(TEST_TABLE, writer)
+    checkAllEmpty(output.toString)
+
+  private def checkByIdString(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.two, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("two")), s"An incorrect document was returned ($json)")
 
+  def byIdString(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkByIdString(db.conn.jsonById(TEST_TABLE, "two"))
+
+  def writeByIdString(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonById(TEST_TABLE, writer, "two")
+    checkByIdString(output.toString)
+
+  private def checkByIdNumber(json: String): Unit =
+    assertEquals(maybeJsonB("""{"key":18,"text":"howdy"}"""), json, "The document should have been found by numeric ID")
+
   def byIdNumber(db: ThrowawayDatabase): Unit =
     Configuration.idField = "key"
     try
       db.conn.insert(TEST_TABLE, NumIdDocument(18, "howdy"))
-      assertEquals(maybeJsonB("""{"key":18,"text":"howdy"}"""), db.conn.jsonById(TEST_TABLE, 18),
+      checkByIdNumber(db.conn.jsonById(TEST_TABLE, 18))
-        "The document should have been found by numeric ID")
     finally
       Configuration.idField = "id"
 
+  def writeByIdNumber(db: ThrowawayDatabase): Unit =
+    Configuration.idField = "key"
+    try
+      db.conn.insert(TEST_TABLE, NumIdDocument(18, "howdy"))
+      val output = StringWriter()
+      val writer = PrintWriter(output)
+      db.conn.writeJsonById(TEST_TABLE, writer, 18)
+      checkByIdNumber(output.toString)
+    finally
+      Configuration.idField = "id"
+
+  private def checkByIdNotFound(json: String): Unit =
+    assertEquals("{}", json, "There should have been no document returned")
+
   def byIdNotFound(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("{}", db.conn.jsonById(TEST_TABLE, "x"), "There should have been no document returned")
+    checkByIdNotFound(db.conn.jsonById(TEST_TABLE, "x"))
 
-  def byFieldsMatch (db: ThrowawayDatabase): Unit =
+  def writeByIdNotFound(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByFields(TEST_TABLE,
+    val output = StringWriter()
-      Field.any("value", ("blue" :: "purple" :: Nil).asJava) :: Field.exists("sub") :: Nil, Some(FieldMatch.ALL))
+    val writer = PrintWriter(output)
+    db.conn.writeJsonById(TEST_TABLE, writer, "x")
+    checkByIdNotFound(output.toString)
+
+  private def checkByFieldsMatch(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertEquals(s"[${JsonDocument.four}]", json, "The incorrect document was returned")
@@ -94,9 +141,20 @@ object JsonFunctions:
         assertTrue(json.contains(docId("four")), s"The incorrect document was returned ($json)")
         assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
-  def byFieldsMatchOrdered (db: ThrowawayDatabase): Unit =
+  def byFieldsMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByFields(TEST_TABLE, Field.equal("value", "purple") :: Nil, None, Field.named("id") :: Nil)
+    checkByFieldsMatch(db.conn.jsonByFields(TEST_TABLE,
+      Field.any("value", ("blue" :: "purple" :: Nil).asJava) :: Field.exists("sub") :: Nil, Some(FieldMatch.ALL)))
+
+  def writeByFieldsMatch(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer,
+      Field.any("value", ("blue" :: "purple" :: Nil).asJava) :: Field.exists("sub") :: Nil, Some(FieldMatch.ALL))
+    checkByFieldsMatch(output.toString)
+
+  private def checkByFieldsMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertEquals(s"[${JsonDocument.five},${JsonDocument.four}]", json, "The documents were not ordered correctly")
@@ -109,9 +167,19 @@ object JsonFunctions:
         assertTrue(fiveIdx < fourIdx, s"Document 'five' should have been before 'four' ($json)")
         assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
-  def byFieldsMatchNumIn (db: ThrowawayDatabase): Unit =
+  def byFieldsMatchOrdered(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByFields(TEST_TABLE, Field.any("numValue", (2 :: 4 :: 6 :: 8 :: Nil).asJava) :: Nil)
+    checkByFieldsMatchOrdered(db.conn.jsonByFields(TEST_TABLE, Field.equal("value", "purple") :: Nil, None,
+      Field.named("id") :: Nil))
+
+  def writeByFieldsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer, Field.equal("value", "purple") :: Nil, None, Field.named("id") :: Nil)
+    checkByFieldsMatchOrdered(output.toString)
+
+  private def checkByFieldsMatchNumIn(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertEquals(s"[${JsonDocument.three}]", json, "The incorrect document was returned")
@@ -120,28 +188,66 @@ object JsonFunctions:
         assertTrue(json.contains(docId("three")), s"The incorrect document was returned ($json)")
         assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
+  def byFieldsMatchNumIn(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkByFieldsMatchNumIn(db.conn.jsonByFields(TEST_TABLE,
+      Field.any("numValue", (2 :: 4 :: 6 :: 8 :: Nil).asJava) :: Nil))
+
+  def writeByFieldsMatchNumIn(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer, Field.any("numValue", (2 :: 4 :: 6 :: 8 :: Nil).asJava) :: Nil)
+    checkByFieldsMatchNumIn(output.toString)
+
+  private def checkByFieldsNoMatch(json: String): Unit =
+    assertEquals("[]", json, "There should have been no documents returned")
+
   def byFieldsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("[]", db.conn.jsonByFields(TEST_TABLE, Field.greater("numValue", 100) :: Nil),
+    checkByFieldsNoMatch(db.conn.jsonByFields(TEST_TABLE, Field.greater("numValue", 100) :: Nil))
-      "There should have been no documents returned")
 
-  def byFieldsMatchInArray (db: ThrowawayDatabase): Unit =
+  def writeByFieldsNoMatch(db: ThrowawayDatabase): Unit =
-    ArrayDocument.testDocuments.foreach { doc => db.conn.insert(TEST_TABLE, doc) }
+    JsonDocument.load(db)
-    val json = db.conn.jsonByFields(TEST_TABLE, Field.inArray("values", TEST_TABLE, ("c" :: Nil).asJava) :: Nil)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer, Field.greater("numValue", 100) :: Nil)
+    checkByFieldsNoMatch(output.toString)
+
+  private def checkByFieldsMatchInArray(json: String): Unit =
     assertTrue(json.startsWith("["), s"JSON should start with '[' ($json)")
     assertTrue(json.contains(docId("first")), s"The 'first' document was not found ($json)")
     assertTrue(json.contains(docId("second")), s"The 'second' document was not found ($json)")
     assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
+  def byFieldsMatchInArray(db: ThrowawayDatabase): Unit =
+    ArrayDocument.testDocuments.foreach { doc => db.conn.insert(TEST_TABLE, doc) }
+    checkByFieldsMatchInArray(db.conn.jsonByFields(TEST_TABLE,
+      Field.inArray("values", TEST_TABLE, ("c" :: Nil).asJava) :: Nil))
+
+  def writeByFieldsMatchInArray(db: ThrowawayDatabase): Unit =
+    ArrayDocument.testDocuments.foreach { doc => db.conn.insert(TEST_TABLE, doc) }
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer, Field.inArray("values", TEST_TABLE, ("c" :: Nil).asJava) :: Nil)
+    checkByFieldsMatchInArray(output.toString)
+
+  private def checkByFieldsNoMatchInArray(json: String): Unit =
+    assertEquals("[]", json, "There should have been no documents returned")
+
   def byFieldsNoMatchInArray(db: ThrowawayDatabase): Unit =
     ArrayDocument.testDocuments.foreach { doc => db.conn.insert(TEST_TABLE, doc) }
-    assertEquals("[]",
+    checkByFieldsNoMatchInArray(db.conn.jsonByFields(TEST_TABLE,
-      db.conn.jsonByFields(TEST_TABLE, Field.inArray("values", TEST_TABLE, ("j" :: Nil).asJava) :: Nil),
+      Field.inArray("values", TEST_TABLE, ("j" :: Nil).asJava) :: Nil))
-      "There should have been no documents returned")
 
-  def byContainsMatch (db: ThrowawayDatabase): Unit =
+  def writeByFieldsNoMatchInArray(db: ThrowawayDatabase): Unit =
-    JsonDocument.load(db)
+    ArrayDocument.testDocuments.foreach { doc => db.conn.insert(TEST_TABLE, doc) }
-    val json = db.conn.jsonByContains(TEST_TABLE, Map.Map1("value", "purple"))
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByFields(TEST_TABLE, writer, Field.inArray("values", TEST_TABLE, ("j" :: Nil).asJava) :: Nil)
+    checkByFieldsNoMatchInArray(output.toString)
+
+  private def checkByContainsMatch(json: String): Unit =
     assertTrue(json.startsWith("["), s"JSON should start with '[' ($json)")
     Configuration.dialect() match
       case Dialect.SQLITE =>
@@ -152,10 +258,18 @@ object JsonFunctions:
         assertTrue(json.contains(docId("five")), s"Document 'five' not found ($json)")
     assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
-  def byContainsMatchOrdered (db: ThrowawayDatabase): Unit =
+  def byContainsMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByContains(TEST_TABLE, Map.Map1("sub", Map.Map1("foo", "green")),
+    checkByContainsMatch(db.conn.jsonByContains(TEST_TABLE, Map.Map1("value", "purple")))
-      Field.named("value") :: Nil)
+
+  def writeByContainsMatch(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByContains(TEST_TABLE, writer, Map.Map1("value", "purple"))
+    checkByContainsMatch(output.toString)
+
+  private def checkByContainsMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertEquals(s"[${JsonDocument.two},${JsonDocument.four}]", json, "The documents were not ordered correctly")
@@ -168,14 +282,34 @@ object JsonFunctions:
         assertTrue(twoIdx < fourIdx, s"Document 'two' should have been before 'four' ($json)")
         assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
+  def byContainsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkByContainsMatchOrdered(db.conn.jsonByContains(TEST_TABLE, Map.Map1("sub", Map.Map1("foo", "green")),
+      Field.named("value") :: Nil))
+
+  def writeByContainsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByContains(TEST_TABLE, writer, Map.Map1("sub", Map.Map1("foo", "green")),
+      Field.named("value") :: Nil)
+    checkByContainsMatchOrdered(output.toString)
+
+  private def checkByContainsNoMatch(json: String): Unit =
+    assertEquals("[]", json, "There should have been no documents returned")
+
   def byContainsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("[]", db.conn.jsonByContains(TEST_TABLE, Map.Map1("value", "indigo")),
+    checkByContainsNoMatch(db.conn.jsonByContains(TEST_TABLE, Map.Map1("value", "indigo")))
-      "There should have been no documents returned")
 
-  def byJsonPathMatch (db: ThrowawayDatabase): Unit =
+  def writeByContainsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)")
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByContains(TEST_TABLE, writer, Map.Map1("value", "indigo"))
+    checkByContainsNoMatch(output.toString)
+
+  private def checkByJsonPathMatch(json: String): Unit =
     assertTrue(json.startsWith("["), s"JSON should start with '[' ($json)")
     Configuration.dialect() match
       case Dialect.SQLITE =>
@@ -186,9 +320,18 @@ object JsonFunctions:
         assertTrue(json.contains(docId("five")), s"Document 'five' not found ($json)")
     assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
-  def byJsonPathMatchOrdered (db: ThrowawayDatabase): Unit =
+  def byJsonPathMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)", Field.named("id") :: Nil)
+    checkByJsonPathMatch(db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)"))
+
+  def writeByJsonPathMatch(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 10)")
+    checkByJsonPathMatch(output.toString)
+
+  private def checkByJsonPathMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertEquals(s"[${JsonDocument.five},${JsonDocument.four}]", json, "The documents were not ordered correctly")
@@ -201,21 +344,48 @@ object JsonFunctions:
         assertTrue(fiveIdx < fourIdx, s"Document 'five' should have been before 'four' ($json)")
         assertTrue(json.endsWith("]"), s"JSON should end with ']' ($json)")
 
+  def byJsonPathMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkByJsonPathMatchOrdered(db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)", Field.named("id") :: Nil))
+
+  def writeByJsonPathMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 10)", Field.named("id") :: Nil)
+    checkByJsonPathMatchOrdered(output.toString)
+
+  private def checkByJsonPathNoMatch(json: String): Unit =
+    assertEquals("[]", json, "There should have been no documents returned")
+
   def byJsonPathNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("[]", db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 100)"),
+    checkByJsonPathNoMatch(db.conn.jsonByJsonPath(TEST_TABLE, "$.numValue ? (@ > 100)"))
-      "There should have been no documents returned")
 
-  def firstByFieldsMatchOne (db: ThrowawayDatabase): Unit =
+  def writeByJsonPathNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("value", "another") :: Nil)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 100)")
+    checkByJsonPathNoMatch(output.toString)
+
+  private def checkFirstByFieldsMatchOne(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.two, json, "The incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("two")), s"The incorrect document was returned ($json)")
 
-  def firstByFieldsMatchMany (db: ThrowawayDatabase): Unit =
+  def firstByFieldsMatchOne(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("sub.foo", "green") :: Nil)
+    checkFirstByFieldsMatchOne(db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("value", "another") :: Nil))
+
+  def writeFirstByFieldsMatchOne(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByFields(TEST_TABLE, writer, Field.equal("value", "another") :: Nil)
+    checkFirstByFieldsMatchOne(output.toString)
+
+  private def checkFirstByFieldsMatchMany(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertTrue(json.contains(JsonDocument.two) || json.contains(JsonDocument.four),
@@ -224,29 +394,65 @@ object JsonFunctions:
         assertTrue(json.contains(docId("two")) || json.contains(docId("four")),
           s"Expected document 'two' or 'four' ($json)")
 
-  def firstByFieldsMatchOrdered (db: ThrowawayDatabase): Unit =
+  def firstByFieldsMatchMany(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("sub.foo", "green") :: Nil, None,
+    checkFirstByFieldsMatchMany(db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("sub.foo", "green") :: Nil))
-      Field.named("n:numValue DESC") :: Nil)
+
+  def writeFirstByFieldsMatchMany(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByFields(TEST_TABLE, writer, Field.equal("sub.foo", "green") :: Nil)
+    checkFirstByFieldsMatchMany(output.toString)
+
+  private def checkFirstByFieldsMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.four, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("four")), s"An incorrect document was returned ($json)")
 
+  def firstByFieldsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkFirstByFieldsMatchOrdered(db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("sub.foo", "green") :: Nil, None,
+      Field.named("n:numValue DESC") :: Nil))
+
+  def writeFirstByFieldsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByFields(TEST_TABLE, writer, Field.equal("sub.foo", "green") :: Nil, None,
+      Field.named("n:numValue DESC") :: Nil)
+
+  private def checkFirstByFieldsNoMatch(json: String): Unit =
+    assertEquals("{}", json, "There should have been no document returned")
+
   def firstByFieldsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("{}", db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("value", "absent") :: Nil),
+    checkFirstByFieldsNoMatch(db.conn.jsonFirstByFields(TEST_TABLE, Field.equal("value", "absent") :: Nil))
-      "There should have been no document returned")
 
-  def firstByContainsMatchOne (db: ThrowawayDatabase): Unit =
+  def writeFirstByFieldsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "FIRST!"))
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByFields(TEST_TABLE, writer, Field.equal("value", "absent") :: Nil)
+    checkFirstByFieldsNoMatch(output.toString)
+
+  private def checkFirstByContainsMatchOne(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.one, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("one")), s"An incorrect document was returned ($json)")
 
-  def firstByContainsMatchMany (db: ThrowawayDatabase): Unit =
+  def firstByContainsMatchOne(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "purple"))
+    checkFirstByContainsMatchOne(db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "FIRST!")))
+
+  def writeFirstByContainsMatchOne(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByContains(TEST_TABLE, writer, Map.Map1("value", "FIRST!"))
+    checkFirstByContainsMatchOne(output.toString)
+
+  private def checkFirstByContainsMatchMany(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertTrue(json.contains(JsonDocument.four) || json.contains(JsonDocument.five),
@@ -255,29 +461,66 @@ object JsonFunctions:
         assertTrue(json.contains(docId("four")) || json.contains(docId("five")),
           s"Expected document 'four' or 'five' ($json)")
 
-  def firstByContainsMatchOrdered (db: ThrowawayDatabase): Unit =
+  def firstByContainsMatchMany(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "purple"),
+    checkFirstByContainsMatchMany(db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "purple")))
-      Field.named("sub.bar NULLS FIRST") :: Nil)
+
+  def writeFirstByContainsMatchMany(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByContains(TEST_TABLE, writer, Map.Map1("value", "purple"))
+    checkFirstByContainsMatchMany(output.toString)
+
+  private def checkFirstByContainsMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.five, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("five")), s"An incorrect document was returned ($json)")
 
+  def firstByContainsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkFirstByContainsMatchOrdered(db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "purple"),
+      Field.named("sub.bar NULLS FIRST") :: Nil))
+
+  def writeFirstByContainsMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByContains(TEST_TABLE, writer, Map.Map1("value", "purple"),
+      Field.named("sub.bar NULLS FIRST") :: Nil)
+    checkFirstByContainsMatchOrdered(output.toString)
+
+  private def checkFirstByContainsNoMatch(json: String): Unit =
+    assertEquals("{}", json, "There should have been no document returned")
+
   def firstByContainsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("{}", db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "indigo")),
+    checkFirstByContainsNoMatch(db.conn.jsonFirstByContains(TEST_TABLE, Map.Map1("value", "indigo")))
-      "There should have been no document returned")
 
-  def firstByJsonPathMatchOne (db: ThrowawayDatabase): Unit =
+  def writeFirstByContainsNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ == 10)")
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByContains(TEST_TABLE, writer, Map.Map1("value", "indigo"))
+    checkFirstByContainsNoMatch(output.toString)
+
+  private def checkFirstByJsonPathMatchOne(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.two, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("two")), s"An incorrect document was returned ($json)")
 
-  def firstByJsonPathMatchMany (db: ThrowawayDatabase): Unit =
+  def firstByJsonPathMatchOne(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)")
+    checkFirstByJsonPathMatchOne(db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ == 10)"))
+
+  def writeFirstByJsonPathMatchOne(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ == 10)")
+    checkFirstByJsonPathMatchOne(output.toString)
+
+  private def checkFirstByJsonPathMatchMany(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE =>
         assertTrue(json.contains(JsonDocument.four) || json.contains(JsonDocument.five),
@@ -286,14 +529,44 @@ object JsonFunctions:
         assertTrue(json.contains(docId("four")) || json.contains(docId("five")),
           s"Expected document 'four' or 'five' ($json)")
 
-  def firstByJsonPathMatchOrdered (db: ThrowawayDatabase): Unit =
+  def firstByJsonPathMatchMany(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    val json = db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)", Field.named("id DESC") :: Nil)
+    checkFirstByJsonPathMatchMany(db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)"))
+
+  def writeFirstByJsonPathMatchMany(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 10)")
+    checkFirstByJsonPathMatchMany(output.toString)
+
+  private def checkFirstByJsonPathMatchOrdered(json: String): Unit =
     Configuration.dialect() match
       case Dialect.SQLITE => assertEquals(JsonDocument.four, json, "An incorrect document was returned")
       case Dialect.POSTGRESQL => assertTrue(json.contains(docId("four")), s"An incorrect document was returned ($json)")
 
+  def firstByJsonPathMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    checkFirstByJsonPathMatchOrdered(db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 10)",
+      Field.named("id DESC") :: Nil))
+
+  def writeFirstByJsonPathMatchOrdered(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 10)", Field.named("id DESC") :: Nil)
+    checkFirstByJsonPathMatchOrdered(output.toString)
+
+  private def checkFirstByJsonPathNoMatch(json: String): Unit =
+    assertEquals("{}", json, "There should have been no document returned")
+
   def firstByJsonPathNoMatch(db: ThrowawayDatabase): Unit =
     JsonDocument.load(db)
-    assertEquals("{}", db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 100)"),
+    checkFirstByJsonPathNoMatch(db.conn.jsonFirstByJsonPath(TEST_TABLE, "$.numValue ? (@ > 100)"))
-      "There should have been no document returned")
+
+  def writeFirstByJsonPathNoMatch(db: ThrowawayDatabase): Unit =
+    JsonDocument.load(db)
+    val output = StringWriter()
+    val writer = PrintWriter(output)
+    db.conn.writeJsonFirstByJsonPath(TEST_TABLE, writer, "$.numValue ? (@ > 100)")
+    checkFirstByJsonPathNoMatch(output.toString)

src/scala/src/test/scala/integration/PostgreSQLJsonIT.scala

@@ -154,3 +154,148 @@ class PostgreSQLJsonIT:
   @DisplayName("firstByJsonPath returns null when no document matches")
   def firstByJsonPathNoMatch(): Unit =
     Using(PgDB()) { db => JsonFunctions.firstByJsonPathNoMatch(db) }
+
+  @Test
+  @DisplayName("writeAll retrieves all documents")
+  def writeAllDefault(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeAllDefault(db) }
+
+  @Test
+  @DisplayName("writeAll succeeds with an empty table")
+  def writeAllEmpty(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeAllEmpty(db) }
+
+  @Test
+  @DisplayName("writeById retrieves a document via a string ID")
+  def writeByIdString(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByIdString(db) }
+
+  @Test
+  @DisplayName("writeById retrieves a document via a numeric ID")
+  def writeByIdNumber(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByIdNumber(db) }
+
+  @Test
+  @DisplayName("writeById returns null when a matching ID is not found")
+  def writeByIdNotFound(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByIdNotFound(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents")
+  def writeByFieldsMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsMatch(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves ordered matching documents")
+  def writeByFieldsMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents with a numeric IN clause")
+  def writeByFieldsMatchNumIn(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsMatchNumIn(db) }
+
+  @Test
+  @DisplayName("writeByFields succeeds when no documents match")
+  def writeByFieldsNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents with an IN_ARRAY comparison")
+  def writeByFieldsMatchInArray(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsMatchInArray(db) }
+
+  @Test
+  @DisplayName("writeByFields succeeds when no documents match an IN_ARRAY comparison")
+  def writeByFieldsNoMatchInArray(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByFieldsNoMatchInArray(db) }
+
+  @Test
+  @DisplayName("writeByContains retrieves matching documents")
+  def writeByContainsMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByContainsMatch(db) }
+
+  @Test
+  @DisplayName("writeByContains retrieves ordered matching documents")
+  def writeByContainsMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByContainsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeByContains succeeds when no documents match")
+  def writeByContainsNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByContainsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeByJsonPath retrieves matching documents")
+  def writeByJsonPathMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByJsonPathMatch(db) }
+
+  @Test
+  @DisplayName("writeByJsonPath retrieves ordered matching documents")
+  def writeByJsonPathMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByJsonPathMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeByJsonPath succeeds when no documents match")
+  def writeByJsonPathNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeByJsonPathNoMatch(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document")
+  def writeFirstByFieldsMatchOne(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByFieldsMatchOne(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document among many")
+  def writeFirstByFieldsMatchMany(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByFieldsMatchMany(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document among many (ordered)")
+  def writeFirstByFieldsMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByFieldsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields returns null when no document matches")
+  def writeFirstByFieldsNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByFieldsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeFirstByContains retrieves a matching document")
+  def writeFirstByContainsMatchOne(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByContainsMatchOne(db) }
+
+  @Test
+  @DisplayName("writeFirstByContains retrieves a matching document among many")
+  def writeFirstByContainsMatchMany(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByContainsMatchMany(db) }
+
+  @Test
+  @DisplayName("writeFirstByContains retrieves a matching document among many (ordered)")
+  def writeFirstByContainsMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByContainsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeFirstByContains returns null when no document matches")
+  def writeFirstByContainsNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByContainsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeFirstByJsonPath retrieves a matching document")
+  def writeFirstByJsonPathMatchOne(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByJsonPathMatchOne(db) }
+
+  @Test
+  @DisplayName("writeFirstByJsonPath retrieves a matching document among many")
+  def writeFirstByJsonPathMatchMany(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByJsonPathMatchMany(db) }
+
+  @Test
+  @DisplayName("writeFirstByJsonPath retrieves a matching document among many (ordered)")
+  def writeFirstByJsonPathMatchOrdered(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByJsonPathMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeFirstByJsonPath returns null when no document matches")
+  def writeFirstByJsonPathNoMatch(): Unit =
+    Using(PgDB()) { db => JsonFunctions.writeFirstByJsonPathNoMatch(db) }

src/scala/src/test/scala/integration/SQLiteJsonIT.scala

@@ -110,3 +110,102 @@ class SQLiteJsonIT:
     Using(SQLiteDB()) { db =>
       assertThrows(classOf[DocumentException], () => JsonFunctions.firstByJsonPathMatchOne(db))
     }
+
+  @Test
+  @DisplayName("writeAll retrieves all documents")
+  def writeAllDefault(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeAllDefault(db) }
+
+  @Test
+  @DisplayName("writeAll succeeds with an empty table")
+  def writeAllEmpty(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeAllEmpty(db) }
+
+  @Test
+  @DisplayName("writeById retrieves a document via a string ID")
+  def writeByIdString(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByIdString(db) }
+
+  @Test
+  @DisplayName("writeById retrieves a document via a numeric ID")
+  def writeByIdNumber(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByIdNumber(db) }
+
+  @Test
+  @DisplayName("writeById returns null when a matching ID is not found")
+  def writeByIdNotFound(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByIdNotFound(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents")
+  def writeByFieldsMatch(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsMatch(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves ordered matching documents")
+  def writeByFieldsMatchOrdered(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents with a numeric IN clause")
+  def writeByFieldsMatchNumIn(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsMatchNumIn(db) }
+
+  @Test
+  @DisplayName("writeByFields succeeds when no documents match")
+  def writeByFieldsNoMatch(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeByFields retrieves matching documents with an IN_ARRAY comparison")
+  def writeByFieldsMatchInArray(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsMatchInArray(db) }
+
+  @Test
+  @DisplayName("writeByFields succeeds when no documents match an IN_ARRAY comparison")
+  def writeByFieldsNoMatchInArray(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeByFieldsNoMatchInArray(db) }
+
+  @Test
+  @DisplayName("writeByContains fails")
+  def writeByContainsFails(): Unit =
+    Using(SQLiteDB()) { db => assertThrows(classOf[DocumentException], () => JsonFunctions.writeByContainsMatch(db)) }
+
+  @Test
+  @DisplayName("writeByJsonPath fails")
+  def writeByJsonPathFails(): Unit =
+    Using(SQLiteDB()) { db => assertThrows(classOf[DocumentException], () => JsonFunctions.writeByJsonPathMatch(db)) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document")
+  def writeFirstByFieldsMatchOne(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeFirstByFieldsMatchOne(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document among many")
+  def writeFirstByFieldsMatchMany(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeFirstByFieldsMatchMany(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields retrieves a matching document among many (ordered)")
+  def writeFirstByFieldsMatchOrdered(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeFirstByFieldsMatchOrdered(db) }
+
+  @Test
+  @DisplayName("writeFirstByFields returns null when no document matches")
+  def writeFirstByFieldsNoMatch(): Unit =
+    Using(SQLiteDB()) { db => JsonFunctions.writeFirstByFieldsNoMatch(db) }
+
+  @Test
+  @DisplayName("writeFirstByContains fails")
+  def writeFirstByContainsFails(): Unit =
+    Using(SQLiteDB()) { db =>
+      assertThrows(classOf[DocumentException], () => JsonFunctions.writeFirstByContainsMatchOne(db))
+    }
+
+  @Test
+  @DisplayName("writeFirstByJsonPath fails")
+  def writeFirstByJsonPathFails(): Unit =
+    Using(SQLiteDB()) { db =>
+      assertThrows(classOf[DocumentException], () => JsonFunctions.writeFirstByJsonPathMatchOne(db))
+    }