src/Tests.CSharp/SqliteCSharpTests.cs

@@ -2,6 +2,7 @@
 using Expecto;
 using Microsoft.FSharp.Core;
 using BitBadger.Documents.Sqlite;
+using Microsoft.Data.Sqlite;
 
 namespace BitBadger.Documents.Tests.CSharp;
 
@@ -147,7 +148,7 @@ public static class SqliteCSharpTests
     /// <summary>
     /// Add the test documents to the database
     /// </summary>
-    internal static async Task LoadDocs()
+    private static async Task LoadDocs()
     {
         foreach (var doc in JsonDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
     }
@@ -169,11 +170,135 @@ public static class SqliteCSharpTests
         }
     });
 
+    /// <summary>Verify a JSON array begins with "[" and ends with "]"</summary>
+    private static void VerifyBeginEnd(string json)
+    {
+        Expect.stringStarts(json, "[", "The array should have started with `[`");
+        Expect.stringEnds(json, "]", "The array should have ended with `]`");
+    }
+
+    /// <summary>Verify an empty JSON array</summary>
+    private static void VerifyEmpty(string json)
+    {
+        Expect.equal(json, "[]", "There should be no documents returned");
+    }
+
+    /// <summary>Verify an empty JSON document</summary>
+    private static void VerifyNoDoc(string json)
+    {
+        Expect.equal(json, "{}", "There should be no document returned");
+    }
+
+    /// <summary>Set up a stream writer for a test</summary>
+    private static StreamWriter WriteStream(Stream stream)
+    {
+        StreamWriter writer = new(stream);
+        writer.AutoFlush = true;
+        return writer;
+    }
+
+    /// <summary>Get the text of the given stream</summary>
+    private static string StreamText(Stream stream)
+    {
+        stream.Position = 0L;
+        using StreamReader reader = new(stream);
+        return reader.ReadToEnd();
+    }
+
+    /// Verify the presence of any of the given documents in the given JSON
+    private static void VerifyAny(string json, IEnumerable<string> docs)
+    {
+        var theDocs = docs.ToList();
+        if (theDocs.Any(json.Contains)) return;
+        var anyDocs = string.Join(" | ", theDocs);
+        Expect.isTrue(false, $"Could not find any of |{anyDocs}| in {json}");
+    }
+
     /// <summary>
     /// Integration tests for the Custom module of the SQLite library
     /// </summary>
     private static readonly Test CustomTests = TestList("Custom",
     [
+        TestList("List",
+        [
+            TestCase("succeeds when data is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Custom.List(Query.Find(SqliteDb.TableName), Parameters.None,
+                    Results.FromData<JsonDocument>);
+                Expect.equal(docs.Count, 5, "There should have been 5 documents returned");
+            }),
+            TestCase("succeeds when data is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Custom.List(
+                    $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value", [new("@value", 100)],
+                    Results.FromData<JsonDocument>);
+                Expect.isEmpty(docs, "There should have been no documents returned");
+            })
+        ]),
+        TestList("JsonArray",
+        [
+            TestCase("succeeds when data is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var json = await Custom.JsonArray(Query.Find(SqliteDb.TableName), [], Results.JsonFromData);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, JsonDocument.One, "Document ID `one` should have been found");
+                Expect.stringContains(json, JsonDocument.Two,"Document ID `two` should have been found");
+                Expect.stringContains(json, JsonDocument.Three, "Document ID `three` should have been found");
+                Expect.stringContains(json, JsonDocument.Four, "Document ID `four` should have been found");
+                Expect.stringContains(json, JsonDocument.Five, "Document ID `five` should have been found");
+            }),
+            TestCase("succeeds when data is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                VerifyEmpty(await Custom.JsonArray(
+                    $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
+                    [new SqliteParameter("@value", 100)], Results.JsonFromData));
+            })
+        ]),
+        TestList("WriteJsonArray",
+        [
+            TestCase("succeeds when data is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Custom.WriteJsonArray(Query.Find(SqliteDb.TableName), [], writer, Results.JsonFromData);
+
+                var json = StreamText(stream);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, JsonDocument.One, "Document ID `one` should have been found");
+                Expect.stringContains(json, JsonDocument.Two,"Document ID `two` should have been found");
+                Expect.stringContains(json, JsonDocument.Three, "Document ID `three` should have been found");
+                Expect.stringContains(json, JsonDocument.Four, "Document ID `four` should have been found");
+                Expect.stringContains(json, JsonDocument.Five, "Document ID `five` should have been found");
+            }),
+            TestCase("succeeds when data is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Custom.WriteJsonArray(
+                    $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
+                    [new SqliteParameter("@value", 100)], writer, Results.JsonFromData);
+
+                VerifyEmpty(StreamText(stream));
+            })
+        ]),
         TestList("Single",
         [
             TestCase("succeeds when a row is found", async () =>
@@ -196,26 +321,24 @@ public static class SqliteCSharpTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-        TestList("List",
+        TestList("JsonSingle",
         [
-            TestCase("succeeds when data is found", async () =>
+            TestCase("succeeds when a row is found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                var docs = await Custom.List(Query.Find(SqliteDb.TableName), Parameters.None,
+                var json = await Custom.JsonSingle($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                    Results.FromData<JsonDocument>);
+                    [new SqliteParameter("@id", "one")], Results.JsonFromData);
-                Expect.equal(docs.Count, 5, "There should have been 5 documents returned");
+                Expect.equal(json, JsonDocument.One, "The JSON document is incorrect");
             }),
-            TestCase("succeeds when data is not found", async () =>
+            TestCase("succeeds when a row is not found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                var docs = await Custom.List(
+                VerifyNoDoc(await Custom.JsonSingle($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                    $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value", [new("@value", 100)],
+                    [new SqliteParameter("@id", "eighty")], Results.JsonFromData));
-                    Results.FromData<JsonDocument>);
-                Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
         TestList("NonQuery",
@@ -757,6 +880,485 @@ public static class SqliteCSharpTests
         ])
     ]);
 
+    /// Integration tests for the Json module of the SQLite library
+    private static readonly Test JsonTests = TestList("Json",
+    [
+        TestList("All",
+        [
+            TestCase("succeeds when there is data", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "one", Bar = "two" });
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "three", Bar = "four" });
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "five", Bar = "six" });
+
+                var json = await Json.All(SqliteDb.TableName);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, """{"Foo":"one","Bar":"two"}""", "The first document was not found");
+                Expect.stringContains(json, """{"Foo":"three","Bar":"four"}""", "The second document was not found");
+                Expect.stringContains(json, """{"Foo":"five","Bar":"six"}""", "The third document was not found");
+            }),
+            TestCase("succeeds when there is no data", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                VerifyEmpty(await Json.All(SqliteDb.TableName));
+            })
+        ]),
+        TestList("AllOrdered",
+        [
+            TestCase("succeeds when ordering numerically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(await Json.AllOrdered(SqliteDb.TableName, [Field.Named("n:NumValue")]),
+                    $"[{JsonDocument.One},{JsonDocument.Three},{JsonDocument.Two},{JsonDocument.Four},{JsonDocument.Five}]",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering numerically descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(await Json.AllOrdered(SqliteDb.TableName, [Field.Named("n:NumValue DESC")]),
+                    $"[{JsonDocument.Five},{JsonDocument.Four},{JsonDocument.Two},{JsonDocument.Three},{JsonDocument.One}]",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering alphabetically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(await Json.AllOrdered(SqliteDb.TableName, [Field.Named("Id DESC")]),
+                    $"[{JsonDocument.Two},{JsonDocument.Three},{JsonDocument.One},{JsonDocument.Four},{JsonDocument.Five}]",
+                    "The documents were not ordered correctly");
+            })
+        ]),
+        TestList("ById",
+        [
+            TestCase("succeeds when a document is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(await Json.ById(SqliteDb.TableName, "two"), JsonDocument.Two,
+                    "The incorrect document was returned");
+            }),
+            TestCase("succeeds when a document is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                VerifyNoDoc(await Json.ById(SqliteDb.TableName, "three hundred eighty-seven"));
+            })
+        ]),
+        TestList("ByFields",
+        [
+            TestCase("succeeds when documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var json = await Json.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Greater("NumValue", 15)]);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, JsonDocument.Four, "Document `four` should have been returned");
+                Expect.stringContains(json, JsonDocument.Five, "Document `five` should have been returned");
+            }),
+            TestCase("succeeds when documents are found using IN with numeric field", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.ByFields(SqliteDb.TableName, FieldMatch.All, [Field.In("NumValue", [2, 4, 6, 8])]),
+                    $"[{JsonDocument.Three}]", "There should have been one document returned");
+            }),
+            TestCase("succeeds when documents are not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                VerifyEmpty(await Json.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Greater("NumValue", 100)]));
+            }),
+            TestCase("succeeds for InArray when matching documents exist", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await Definition.EnsureTable(SqliteDb.TableName);
+                foreach (var doc in ArrayDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
+
+                var json = await Json.ByFields(SqliteDb.TableName, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["c"])]);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, """{"Id":"first","Values":["a","b","c"]}""",
+                    "Document `first` should have been returned");
+                Expect.stringContains(json, """{"Id":"second","Values":["c","d","e"]}""",
+                    "Document `second` should have been returned");
+            }),
+            TestCase("succeeds for InArray when no matching documents exist", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await Definition.EnsureTable(SqliteDb.TableName);
+                foreach (var doc in ArrayDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
+                VerifyEmpty(await Json.ByFields(SqliteDb.TableName, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["j"])]));
+            })
+        ]),
+        TestList("ByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.ByFieldsOrdered(SqliteDb.TableName, FieldMatch.Any, [Field.Greater("NumValue", 15)],
+                        [Field.Named("Id")]), $"[{JsonDocument.Five},{JsonDocument.Four}]",
+                    "Incorrect documents were returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.ByFieldsOrdered(SqliteDb.TableName, FieldMatch.Any, [Field.Greater("NumValue", 15)],
+                        [Field.Named("Id DESC")]), $"[{JsonDocument.Four},{JsonDocument.Five}]",
+                    "Incorrect documents were returned");
+            }),
+            TestCase("succeeds when sorting case-sensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.ByFieldsOrdered(SqliteDb.TableName, FieldMatch.All, [Field.LessOrEqual("NumValue", 10)],
+                        [Field.Named("Value")]),
+                    $"[{JsonDocument.Three},{JsonDocument.One},{JsonDocument.Two}]", "Documents not ordered correctly");
+            }),
+            TestCase("succeeds when sorting case-insensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.ByFieldsOrdered(SqliteDb.TableName, FieldMatch.All, [Field.LessOrEqual("NumValue", 10)],
+                        [Field.Named("i:Value")]),
+                    $"[{JsonDocument.Three},{JsonDocument.Two},{JsonDocument.One}]", "Documents not ordered correctly");
+            })
+        ]),
+        TestList("FirstByFields",
+        [
+            TestCase("succeeds when a document is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.FirstByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "another")]),
+                    JsonDocument.Two, "The incorrect document was returned");
+            }),
+            TestCase("succeeds when multiple documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var json = await Json.FirstByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")]);
+                Expect.notEqual(json, "{}", "There should have been a document returned");
+                VerifyAny(json, [JsonDocument.Two, JsonDocument.Four]);
+            }),
+            TestCase("succeeds when a document is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                VerifyNoDoc(await Json.FirstByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "absent")]));
+            })
+        ]),
+        TestList("FirstByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.FirstByFieldsOrdered(SqliteDb.TableName, FieldMatch.Any,
+                        [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar")]), JsonDocument.Two,
+                    "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+                Expect.equal(
+                    await Json.FirstByFieldsOrdered(SqliteDb.TableName, FieldMatch.Any,
+                        [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar DESC")]), JsonDocument.Four,
+                    "An incorrect document was returned");
+            })
+        ]),
+        TestList("WriteAll",
+        [
+            TestCase("succeeds when there is data", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "one", Bar = "two" });
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "three", Bar = "four" });
+                await Document.Insert(SqliteDb.TableName, new SubDocument { Foo = "five", Bar = "six" });
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteAll(SqliteDb.TableName, writer);
+                var json = StreamText(stream);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, """{"Foo":"one","Bar":"two"}""", "The first document was not found");
+                Expect.stringContains(json, """{"Foo":"three","Bar":"four"}""", "The second document was not found");
+                Expect.stringContains(json, """{"Foo":"five","Bar":"six"}""", "The third document was not found");
+            }),
+            TestCase("succeeds when there is no data", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteAll(SqliteDb.TableName, writer);
+                VerifyEmpty(StreamText(stream));
+            })
+        ]),
+        TestList("WriteAllOrdered",
+        [
+            TestCase("succeeds when ordering numerically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteAllOrdered(SqliteDb.TableName, writer, [Field.Named("n:NumValue")]);
+                Expect.equal(StreamText(stream),
+                    $"[{JsonDocument.One},{JsonDocument.Three},{JsonDocument.Two},{JsonDocument.Four},{JsonDocument.Five}]",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering numerically descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteAllOrdered(SqliteDb.TableName, writer, [Field.Named("n:NumValue DESC")]);
+                Expect.equal(StreamText(stream),
+                    $"[{JsonDocument.Five},{JsonDocument.Four},{JsonDocument.Two},{JsonDocument.Three},{JsonDocument.One}]",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering alphabetically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteAllOrdered(SqliteDb.TableName, writer, [Field.Named("Id DESC")]);
+                Expect.equal(StreamText(stream),
+                    $"[{JsonDocument.Two},{JsonDocument.Three},{JsonDocument.One},{JsonDocument.Four},{JsonDocument.Five}]",
+                    "The documents were not ordered correctly");
+            })
+        ]),
+        TestList("WriteById",
+        [
+            TestCase("succeeds when a document is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteById(SqliteDb.TableName, writer, "two");
+                Expect.equal(StreamText(stream), JsonDocument.Two, "The incorrect document was returned");
+            }),
+            TestCase("succeeds when a document is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteById(SqliteDb.TableName, writer, "three hundred eighty-seven");
+                VerifyNoDoc(StreamText(stream));
+            })
+        ]),
+        TestList("WriteByFields",
+        [
+            TestCase("succeeds when documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFields(SqliteDb.TableName, writer, FieldMatch.Any, [Field.Greater("NumValue", 15)]);
+                var json = StreamText(stream);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, JsonDocument.Four, "Document `four` should have been returned");
+                Expect.stringContains(json, JsonDocument.Five, "Document `five` should have been returned");
+            }),
+            TestCase("succeeds when documents are found using IN with numeric field", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFields(SqliteDb.TableName, writer, FieldMatch.All,
+                    [Field.In("NumValue", [2, 4, 6, 8])]);
+                Expect.equal(StreamText(stream), $"[{JsonDocument.Three}]",
+                    "There should have been one document returned");
+            }),
+            TestCase("succeeds when documents are not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFields(SqliteDb.TableName, writer, FieldMatch.Any, [Field.Greater("NumValue", 100)]);
+                VerifyEmpty(StreamText(stream));
+            }),
+            TestCase("succeeds for InArray when matching documents exist", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await Definition.EnsureTable(SqliteDb.TableName);
+                foreach (var doc in ArrayDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFields(SqliteDb.TableName, writer, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["c"])]);
+                var json = StreamText(stream);
+                VerifyBeginEnd(json);
+                Expect.stringContains(json, """{"Id":"first","Values":["a","b","c"]}""",
+                    "Document `first` should have been returned");
+                Expect.stringContains(json, """{"Id":"second","Values":["c","d","e"]}""",
+                    "Document `second` should have been returned");
+            }),
+            TestCase("succeeds for InArray when no matching documents exist", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await Definition.EnsureTable(SqliteDb.TableName);
+                foreach (var doc in ArrayDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFields(SqliteDb.TableName, writer, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["j"])]);
+                VerifyEmpty(StreamText(stream));
+            })
+        ]),
+        TestList("WriteByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id")]);
+                Expect.equal(StreamText(stream), $"[{JsonDocument.Five},{JsonDocument.Four}]",
+                    "Incorrect documents were returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id DESC")]);
+                Expect.equal(StreamText(stream), $"[{JsonDocument.Four},{JsonDocument.Five}]",
+                    "Incorrect documents were returned");
+            }),
+            TestCase("succeeds when sorting case-sensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.All,
+                    [Field.LessOrEqual("NumValue", 10)], [Field.Named("Value")]);
+                Expect.equal(StreamText(stream), $"[{JsonDocument.Three},{JsonDocument.One},{JsonDocument.Two}]",
+                    "Documents not ordered correctly");
+            }),
+            TestCase("succeeds when sorting case-insensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.All,
+                    [Field.LessOrEqual("NumValue", 10)], [Field.Named("i:Value")]);
+                Expect.equal(StreamText(stream), $"[{JsonDocument.Three},{JsonDocument.Two},{JsonDocument.One}]",
+                    "Documents not ordered correctly");
+            })
+        ]),
+        TestList("WriteFirstByFields",
+        [
+            TestCase("succeeds when a document is found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteFirstByFields(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Equal("Value", "another")]);
+                Expect.equal(StreamText(stream), JsonDocument.Two, "The incorrect document was returned");
+            }),
+            TestCase("succeeds when multiple documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteFirstByFields(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")]);
+                var json = StreamText(stream);
+                Expect.notEqual(json, "{}", "There should have been a document returned");
+                VerifyAny(json, [JsonDocument.Two, JsonDocument.Four]);
+            }),
+            TestCase("succeeds when a document is not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteFirstByFields(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Equal("Value", "absent")]);
+                VerifyNoDoc(StreamText(stream));
+            })
+        ]),
+        TestList("WriteFirstByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteFirstByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar")]);
+                Expect.equal(StreamText(stream), JsonDocument.Two, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                using MemoryStream stream = new();
+                await using var writer = WriteStream(stream);
+                await Json.WriteFirstByFieldsOrdered(SqliteDb.TableName, writer, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar DESC")]);
+                Expect.equal(StreamText(stream), JsonDocument.Four, "An incorrect document was returned");
+            })
+        ])
+    ]);
+
     /// <summary>
     /// Integration tests for the Update module of the SQLite library
     /// </summary>
@@ -1006,6 +1608,7 @@ public static class SqliteCSharpTests
             CountTests,
             ExistsTests,
             FindTests,
+            JsonTests,
             UpdateTests,
             PatchTests,
             RemoveFieldsTests,

src/Tests.CSharp/Types.cs

@@ -30,6 +30,22 @@ public class JsonDocument
         new() { Id = "four", Value = "purple", NumValue = 17, Sub = new() { Foo = "green", Bar = "red" } },
         new() { Id = "five", Value = "purple", NumValue = 18 }
     ];
+
+    /// <summary>The JSON for document ID `one`</summary>
+    public static string One = """{"Id":"one","Value":"FIRST!","NumValue":0,"Sub":null}""";
+
+    /// <summary>The JSON for document ID `two`</summary>
+    public static string Two = """{"Id":"two","Value":"another","NumValue":10,"Sub":{"Foo":"green","Bar":"blue"}}""";
+
+    /// <summary>The JSON for document ID `three`</summary>
+    public static string Three = """{"Id":"three","Value":"","NumValue":4,"Sub":null}""";
+
+    /// <summary>The JSON for document ID `four`</summary>
+    public static string Four = """{"Id":"four","Value":"purple","NumValue":17,"Sub":{"Foo":"green","Bar":"red"}}""";
+
+    /// <summary>The JSON for document ID `five`</summary>
+    public static string Five = """{"Id":"five","Value":"purple","NumValue":18,"Sub":null}""";
+
 }
 
 public class ArrayDocument

src/Tests/SqliteExtensionTests.fs

@@ -48,7 +48,7 @@ let integrationTests =
             let theDocs = docs |> String.concat " | "
             Expect.isTrue false $"Could not find any of |{theDocs}| in {json}"
 
-    ftestList "Sqlite.Extensions" [
+    testList "Sqlite.Extensions" [
         testTask "ensureTable succeeds" {
             use! db   = SqliteDb.BuildDb()
             use  conn = Configuration.dbConn ()

src/Tests/SqliteTests.fs

@@ -1402,7 +1402,7 @@ let deleteTests = testList "Delete" [
 ]
 
 /// All tests for the SQLite library
-let all = ftestList "Sqlite" [
+let all = testList "Sqlite" [
     testList "Unit" [ queryTests; parametersTests ]
     testSequenced <| testList "Integration" [
         configurationTests