Final tweaks for v4 (#9)

- Add .NET 9, PostgreSQL 17 support
- Drop .NET 6, PostgreSQL 12 support
- Finalize READMEs

Reviewed-on: #9

.gitignore

@@ -396,3 +396,7 @@ FodyWeavers.xsd
 
 # JetBrains Rider
 *.sln.iml
+**/.idea
+
+# Test run files
+src/*-tests.txt

src/Common/BitBadger.Documents.Common.fsproj

@@ -13,7 +13,9 @@
 
   <ItemGroup>
     <PackageReference Include="FSharp.SystemTextJson" Version="1.3.13" />
-    <PackageReference Update="FSharp.Core" Version="8.0.300" />
+    <PackageReference Update="FSharp.Core" Version="9.0.100" />
+    <PackageReference Include="System.Text.Encodings.Web" Version="9.0.0" />
+    <PackageReference Include="System.Text.Json" Version="9.0.0" />
   </ItemGroup>
 
 </Project>

src/Common/Library.fs

@@ -1,38 +1,57 @@
 namespace BitBadger.Documents
 
-/// The types of logical operations available for JSON fields
-[<Struct>]
-type Op =
-    /// Equals (=)
-    | EQ
-    /// Greater Than (>)
-    | GT
-    /// Greater Than or Equal To (>=)
-    | GE
-    /// Less Than (<)
-    | LT
-    /// Less Than or Equal To (<=)
-    | LE
-    /// Not Equal to (<>)
-    | NE
-    /// Between (BETWEEN)
-    | BT
-    /// Exists (IS NOT NULL)
-    | EX
-    /// Does Not Exist (IS NULL)
-    | NEX
+open System.Security.Cryptography
 
-    override this.ToString() =
+/// The types of comparisons available for JSON fields
+type Comparison =
+    
+    /// Equals (=)
+    | Equal of Value: obj
+    
+    /// Greater Than (>)
+    | Greater of Value: obj
+    
+    /// Greater Than or Equal To (>=)
+    | GreaterOrEqual of Value: obj
+    
+    /// Less Than (<)
+    | Less of Value: obj
+    
+    /// Less Than or Equal To (<=)
+    | LessOrEqual of Value: obj 
+    
+    /// Not Equal to (<>)
+    | NotEqual of Value: obj
+    
+    /// Between (BETWEEN)
+    | Between of Min: obj * Max: obj
+    
+    /// In (IN)
+    | In of Values: obj seq
+    
+    /// In Array (PostgreSQL: |?, SQLite: EXISTS / json_each / IN)
+    | InArray of Table: string * Values: obj seq
+    
+    /// Exists (IS NOT NULL)
+    | Exists
+    
+    /// Does Not Exist (IS NULL)
+    | NotExists
+    
+    /// Get the operator SQL for this comparison
+    member this.OpSql =
         match this with
-        | EQ -> "="
-        | GT -> ">"
-        | GE -> ">="
-        | LT -> "<"
-        | LE -> "<="
-        | NE -> "<>"
-        | BT -> "BETWEEN"
-        | EX -> "IS NOT NULL"
-        | NEX -> "IS NULL"
+        | Equal _ -> "="
+        | Greater _ -> ">"
+        | GreaterOrEqual _ -> ">="
+        | Less _ -> "<"
+        | LessOrEqual _ -> "<="
+        | NotEqual _ -> "<>"
+        | Between _ -> "BETWEEN"
+        | In _ -> "IN"
+        | InArray _ -> "?|" // PostgreSQL only; SQL needs a subquery for this 
+        | Exists -> "IS NOT NULL"
+        | NotExists -> "IS NULL"
 
 
 /// The dialect in which a command should be rendered
@@ -41,16 +60,26 @@ type Dialect =
     | PostgreSQL
     | SQLite
 
+
+/// The format in which an element of a JSON field should be extracted 
+[<Struct>]
+type FieldFormat =
+    
+    /// Use ->> or #>>; extracts a text (PostgreSQL) or SQL (SQLite) value
+    | AsSql
+    
+    /// Use -> or #>; extracts a JSONB (PostgreSQL) or JSON (SQLite) value
+    | AsJson
+
+
 /// Criteria for a field WHERE clause
 type Field = {
+    
     /// The name of the field
     Name: string
     
-    /// The operation by which the field will be compared
-    Op: Op
-    
-    /// The value of the field
-    Value: obj
+    /// The comparison for the field
+    Comparison: Comparison
     
     /// The name of the parameter for this field
     ParameterName: string option
@@ -59,52 +88,105 @@ type Field = {
     Qualifier: string option
 } with
     
+    /// Create a comparison against a field
+    static member Where name (comparison: Comparison) =
+        { Name = name; Comparison = comparison; ParameterName = None; Qualifier = None }
+    
     /// Create an equals (=) field criterion
-    static member EQ name (value: obj) =
-        { Name = name; Op = EQ; Value = value; ParameterName = None; Qualifier = None }
+    static member Equal<'T> name (value: 'T) =
+        Field.Where name (Equal value)
+    
+    /// Create an equals (=) field criterion (alias)
+    static member EQ<'T> name (value: 'T) = Field.Equal name value
     
     /// Create a greater than (>) field criterion
-    static member GT name (value: obj) =
-        { Name = name; Op = GT; Value = value; ParameterName = None; Qualifier = None }
+    static member Greater<'T> name (value: 'T) =
+        Field.Where name (Greater value)
+    
+    /// Create a greater than (>) field criterion (alias)
+    static member GT<'T> name (value: 'T) = Field.Greater name value
     
     /// Create a greater than or equal to (>=) field criterion
-    static member GE name (value: obj) =
-        { Name = name; Op = GE; Value = value; ParameterName = None; Qualifier = None }
+    static member GreaterOrEqual<'T> name (value: 'T) =
+        Field.Where name (GreaterOrEqual value)
+    
+    /// Create a greater than or equal to (>=) field criterion (alias)
+    static member GE<'T> name (value: 'T) = Field.GreaterOrEqual name value
     
     /// Create a less than (<) field criterion
-    static member LT name (value: obj) =
-        { Name = name; Op = LT; Value = value; ParameterName = None; Qualifier = None }
+    static member Less<'T> name (value: 'T) =
+        Field.Where name (Less value)
+    
+    /// Create a less than (<) field criterion (alias)
+    static member LT<'T> name (value: 'T) = Field.Less name value
     
     /// Create a less than or equal to (<=) field criterion
-    static member LE name (value: obj) =
-        { Name = name; Op = LE; Value = value; ParameterName = None; Qualifier = None }
+    static member LessOrEqual<'T> name (value: 'T) =
+        Field.Where name (LessOrEqual value)
+    
+    /// Create a less than or equal to (<=) field criterion (alias)
+    static member LE<'T> name (value: 'T) = Field.LessOrEqual name value
     
     /// Create a not equals (<>) field criterion
-    static member NE name (value: obj) =
-        { Name = name; Op = NE; Value = value; ParameterName = None; Qualifier = None }
+    static member NotEqual<'T> name (value: 'T) =
+        Field.Where name (NotEqual value)
     
-    /// Create a BETWEEN field criterion
-    static member BT name (min: obj) (max: obj) =
-        { Name = name; Op = BT; Value = [ min; max ]; ParameterName = None; Qualifier = None }
+    /// Create a not equals (<>) field criterion (alias)
+    static member NE<'T> name (value: 'T) = Field.NotEqual name value
+    
+    /// Create a Between field criterion
+    static member Between<'T> name (min: 'T) (max: 'T) =
+        Field.Where name (Between(min, max))
+    
+    /// Create a Between field criterion (alias)
+    static member BT<'T> name (min: 'T) (max: 'T) = Field.Between name min max
+    
+    /// Create an In field criterion
+    static member In<'T> name (values: 'T seq) =
+        Field.Where name (In (Seq.map box values))
+    
+    /// Create an In field criterion (alias)
+    static member IN<'T> name (values: 'T seq) = Field.In name values
+    
+    /// Create an InArray field criterion
+    static member InArray<'T> name tableName (values: 'T seq) =
+        Field.Where name (InArray(tableName, Seq.map box values))
     
     /// Create an exists (IS NOT NULL) field criterion
-    static member EX name =
-        { Name = name; Op = EX; Value = obj (); ParameterName = None; Qualifier = None }
+    static member Exists name =
+        Field.Where name Exists
+    
+    /// Create an exists (IS NOT NULL) field criterion (alias)
+    static member EX name = Field.Exists name
     
     /// Create a not exists (IS NULL) field criterion
-    static member NEX name =
-        { Name = name; Op = NEX; Value = obj (); ParameterName = None; Qualifier = None }
+    static member NotExists name =
+        Field.Where name NotExists
+    
+    /// Create a not exists (IS NULL) field criterion (alias)
+    static member NEX name = Field.NotExists name
     
     /// Transform a field name (a.b.c) to a path for the given SQL dialect
-    static member NameToPath (name: string) dialect =
+    static member NameToPath (name: string) dialect format =
         let path =
             if name.Contains '.' then
                 match dialect with
-                | PostgreSQL -> "#>>'{" + String.concat "," (name.Split '.') + "}'"
-                | SQLite -> "->>'" + String.concat "'->>'" (name.Split '.') + "'"
-            else $"->>'{name}'"
+                | PostgreSQL ->
+                    (match format with AsJson -> "#>" | AsSql -> "#>>")
+                        + "'{" + String.concat "," (name.Split '.') + "}'"
+                | SQLite ->
+                    let parts = name.Split '.'
+                    let last  = Array.last parts
+                    let final = (match format with AsJson -> "'->'" | AsSql -> "'->>'") + $"{last}'"
+                    "->'" + String.concat "'->'" (Array.truncate (Array.length parts - 1) parts) + final
+            else
+                match format with AsJson -> $"->'{name}'" | AsSql -> $"->>'{name}'"
         $"data{path}"
     
+    /// Create a field with a given name, but no other properties filled (op will be EQ, value will be "")
+    static member Named name =
+        Field.Where name (Equal "")
+    
     /// Specify the name of the parameter for this field
     member this.WithParameterName name =
         { this with ParameterName = Some name }
@@ -114,15 +196,18 @@ type Field = {
         { this with Qualifier = Some alias }
 
     /// Get the qualified path to the field
-    member this.Path dialect =
-        (this.Qualifier |> Option.map (fun q -> $"{q}.") |> Option.defaultValue "") + Field.NameToPath this.Name dialect
+    member this.Path dialect format =
+        (this.Qualifier |> Option.map (fun q -> $"{q}.") |> Option.defaultValue "")
+            + Field.NameToPath this.Name dialect format
 
 
 /// How fields should be matched
 [<Struct>]
 type FieldMatch =
+    
     /// Any field matches (OR)
     | Any
+    
     /// All fields match (AND)
     | All
     
@@ -133,6 +218,7 @@ type FieldMatch =
 
 /// Derive parameter names (each instance wraps a counter to uniquely name anonymous fields)
 type ParameterName() =
+    
     /// The counter for the next field value
     let mutable currentIdx = -1
     
@@ -145,6 +231,65 @@ type ParameterName() =
             $"@field{currentIdx}"
 
 
+/// Automatically-generated document ID strategies
+[<Struct>]
+type AutoId =
+    
+    /// No automatic IDs will be generated
+    | Disabled
+    
+    /// Generate a MAX-plus-1 numeric value for documents
+    | Number
+    
+    /// Generate a GUID for each document (as a lowercase, no-dashes, 32-character string)
+    | Guid
+    
+    /// Generate a random string of hexadecimal characters for each document
+    | RandomString
+with
+    /// Generate a GUID string
+    static member GenerateGuid() =
+        System.Guid.NewGuid().ToString "N"
+    
+    /// Generate a string of random hexadecimal characters
+    static member GenerateRandomString(length: int) =
+        RandomNumberGenerator.GetHexString(length, lowercase = true)
+    
+    /// Does the given document need an automatic ID generated?
+    static member NeedsAutoId<'T> strategy (document: 'T) idProp =
+        match strategy with
+        | Disabled -> false
+        | _ ->
+            let prop = document.GetType().GetProperty idProp
+            if isNull prop then invalidOp $"{idProp} not found in document"
+            else
+                match strategy with
+                | Number ->
+                    if prop.PropertyType = typeof<int8> then
+                        let value = prop.GetValue document :?> int8
+                        value = int8 0
+                    elif prop.PropertyType = typeof<int16> then
+                        let value = prop.GetValue document :?> int16
+                        value = int16 0
+                    elif prop.PropertyType = typeof<int> then
+                        let value = prop.GetValue document :?> int
+                        value = 0
+                    elif prop.PropertyType = typeof<int64> then
+                        let value = prop.GetValue document :?> int64
+                        value = int64 0
+                    else invalidOp "Document ID was not a number; cannot auto-generate a Number ID"
+                | Guid | RandomString ->
+                    if prop.PropertyType = typeof<string> then
+                        let value =
+                            prop.GetValue document
+                            |> Option.ofObj
+                            |> Option.map (fun it -> it :?> string)
+                            |> Option.defaultValue ""
+                        value = ""
+                    else invalidOp "Document ID was not a string; cannot auto-generate GUID or random string"
+                | Disabled -> false
+
+
 /// The required document serialization implementation
 type IDocumentSerializer =
     
@@ -196,7 +341,7 @@ module Configuration =
         serializerValue
     
     /// The serialized name of the ID field for documents
-    let mutable idFieldValue = "Id"
+    let mutable private idFieldValue = "Id"
     
     /// Specify the name of the ID field for documents
     [<CompiledName "UseIdField">]
@@ -208,6 +353,32 @@ module Configuration =
     let idField () =
         idFieldValue
     
+    /// The automatic ID strategy used by the library
+    let mutable private autoIdValue = Disabled
+    
+    /// Specify the automatic ID generation strategy used by the library
+    [<CompiledName "UseAutoIdStrategy">]
+    let useAutoIdStrategy it =
+        autoIdValue <- it
+    
+    /// Retrieve the currently configured automatic ID generation strategy
+    [<CompiledName "AutoIdStrategy">]
+    let autoIdStrategy () =
+        autoIdValue
+    
+    /// The length of automatically generated random strings
+    let mutable private idStringLengthValue = 16
+    
+    /// Specify the length of automatically generated random strings
+    [<CompiledName "UseIdStringLength">]
+    let useIdStringLength length =
+        idStringLengthValue <- length
+    
+    /// Retrieve the currently configured length of automatically generated random strings
+    [<CompiledName "IdStringLength">]
+    let idStringLength () =
+        idStringLengthValue
+
 
 /// Query construction functions
 [<RequireQualifiedAccess>]
@@ -241,7 +412,7 @@ module Query =
                     let parts = it.Split ' '
                     let fieldName = if Array.length parts = 1 then it else parts[0]
                     let direction = if Array.length parts < 2 then "" else $" {parts[1]}"
-                    $"({Field.NameToPath fieldName dialect}){direction}")
+                    $"({Field.NameToPath fieldName dialect AsSql}){direction}")
                 |> String.concat ", "
             $"CREATE INDEX IF NOT EXISTS idx_{tbl}_%s{indexName} ON {tableName} ({jsonFields})"
 
@@ -292,3 +463,28 @@ module Query =
     [<System.Obsolete "Use Find instead">]
     let selectFromTable tableName =
         find tableName
+    
+    /// Create an ORDER BY clause for the given fields
+    [<CompiledName "OrderBy">]
+    let orderBy fields dialect =
+        if Seq.isEmpty fields then ""
+        else
+            fields
+            |> Seq.map (fun it ->
+                if it.Name.Contains ' ' then
+                    let parts = it.Name.Split ' '
+                    { it with Name = parts[0] }, Some $""" {parts |> Array.skip 1 |> String.concat " "}"""
+                else it, None)
+            |> Seq.map (fun (field, direction) ->
+                if field.Name.StartsWith "n:" then
+                    let f = { field with Name = field.Name[2..] }
+                    match dialect with
+                    | PostgreSQL -> $"({f.Path PostgreSQL AsSql})::numeric"
+                    | SQLite -> f.Path SQLite AsSql
+                elif field.Name.StartsWith "i:" then
+                    let p = { field with Name = field.Name[2..] }.Path dialect AsSql
+                    match dialect with PostgreSQL ->  $"LOWER({p})" | SQLite -> $"{p} COLLATE NOCASE"
+                else field.Path dialect AsSql
+                |> function path -> path + defaultArg direction "")
+            |> String.concat ", "
+            |> function it -> $" ORDER BY {it}"

src/Common/README.md

@@ -7,6 +7,7 @@ This package provides common definitions and functionality for `BitBadger.Docume
 ## Features
 
 - Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Automatically generate IDs for documents (numeric IDs, GUIDs, or random strings)
 - Addresses documents via ID and via comparison on any field (for PostgreSQL, also via equality on any property by using JSON containment, or via condition on any property using JSON Path queries)
 - Accesses documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
 - Uses `Task`-based async for all data access functions

src/Directory.Build.props

@@ -1,12 +1,19 @@
 <Project>
   <PropertyGroup>
-    <TargetFrameworks>net6.0;net8.0</TargetFrameworks>
+    <TargetFrameworks>net8.0;net9.0</TargetFrameworks>
     <DebugType>embedded</DebugType>
     <GenerateDocumentationFile>false</GenerateDocumentationFile>
-    <AssemblyVersion>3.1.0.0</AssemblyVersion>
-    <FileVersion>3.1.0.0</FileVersion>
-    <VersionPrefix>3.1.0</VersionPrefix>
-    <PackageReleaseNotes>Add BT (between) operator; drop .NET 7 support</PackageReleaseNotes>
+    <AssemblyVersion>4.0.0.0</AssemblyVersion>
+    <FileVersion>4.0.0.0</FileVersion>
+    <VersionPrefix>4.0.0</VersionPrefix>
+    <PackageReleaseNotes>From v3.1: (see project site for breaking changes and compatibility)
+- Change ByField to ByFields
+- Support dot-access to nested document fields
+- Add Find*Ordered functions/methods
+- Add case-insensitive ordering (as of rc2)
+- Preserve additional ORDER BY qualifiers (as of rc3)
+- Add In / InArray comparisons (as of rc4)
+- Field construction functions are generic (as of rc5)</PackageReleaseNotes>
     <Authors>danieljsummers</Authors>
     <Company>Bit Badger Solutions</Company>
     <PackageReadmeFile>README.md</PackageReadmeFile>

src/Postgres/BitBadger.Documents.Postgres.fsproj

@@ -8,13 +8,15 @@
   <ItemGroup>
     <Compile Include="Library.fs" />
     <Compile Include="Extensions.fs" />
+    <Compile Include="Compat.fs" />
     <None Include="README.md" Pack="true" PackagePath="\" />
     <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Npgsql.FSharp" Version="5.7.0" />
-    <PackageReference Update="FSharp.Core" Version="8.0.300" />
+    <PackageReference Include="Npgsql" Version="9.0.2" />
+    <PackageReference Include="Npgsql.FSharp" Version="8.0.0" />
+    <PackageReference Update="FSharp.Core" Version="9.0.100" />
   </ItemGroup>
 
   <ItemGroup>

src/Postgres/Compat.fs

@@ -0,0 +1,270 @@
+namespace BitBadger.Documents.Postgres.Compat
+
+open BitBadger.Documents
+open BitBadger.Documents.Postgres
+
+[<AutoOpen>]
+module Parameters =
+    
+    /// Create a JSON field parameter
+    [<CompiledName "AddField">]
+    [<System.Obsolete "Use addFieldParams (F#) / AddFields (C#) instead ~ will be removed in v4.1">]
+    let addFieldParam name field parameters =
+        addFieldParams [ { field with ParameterName = Some name } ] parameters
+
+    /// Append JSON field name parameters for the given field names to the given parameters
+    [<CompiledName "FieldName">]
+    [<System.Obsolete "Use fieldNameParams (F#) / FieldNames (C#) instead ~ will be removed in v4.1">]
+    let fieldNameParam fieldNames =
+        fieldNameParams fieldNames
+
+
+[<RequireQualifiedAccess>]
+module Query =
+    
+    /// Create a WHERE clause fragment to implement a comparison on a field in a JSON document
+    [<CompiledName "WhereByField">]
+    [<System.Obsolete "Use WhereByFields instead ~ will be removed in v4.1">]
+    let whereByField field paramName =
+        Query.whereByFields Any [ { field with ParameterName = Some paramName } ]
+
+
+module WithProps =
+    
+    [<RequireQualifiedAccess>]
+    module Count =
+        
+        /// Count matching documents using a JSON field comparison (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field sqlProps =
+            WithProps.Count.byFields tableName Any [ field ] sqlProps
+    
+    [<RequireQualifiedAccess>]
+    module Exists =
+        
+        /// Determine if a document exists using a JSON field comparison (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field sqlProps =
+            WithProps.Exists.byFields tableName Any [ field ] sqlProps
+    
+    [<RequireQualifiedAccess>]
+    module Find =
+        
+        /// Retrieve documents matching a JSON field comparison (->> =)
+        [<CompiledName "FSharpByField">]
+        [<System.Obsolete "Use byFields instead ~ will be removed in v4.1">]
+        let byField<'TDoc> tableName field sqlProps =
+            WithProps.Find.byFields<'TDoc> tableName Any [ field ] sqlProps
+        
+        /// Retrieve documents matching a JSON field comparison (->> =)
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let ByField<'TDoc>(tableName, field, sqlProps) =
+            WithProps.Find.ByFields<'TDoc>(tableName, Any, Seq.singleton field, sqlProps)
+        
+        /// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
+        [<CompiledName "FSharpFirstByField">]
+        [<System.Obsolete "Use firstByFields instead ~ will be removed in v4.1">]
+        let firstByField<'TDoc> tableName field sqlProps =
+            WithProps.Find.firstByFields<'TDoc> tableName Any [ field ] sqlProps
+        
+        /// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
+        [<System.Obsolete "Use FirstByFields instead ~ will be removed in v4.1">]
+        let FirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, field, sqlProps) =
+            WithProps.Find.FirstByFields<'TDoc>(tableName, Any, Seq.singleton field, sqlProps)
+    
+    [<RequireQualifiedAccess>]
+    module Patch =
+        
+        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field (patch: 'TPatch) sqlProps =
+            WithProps.Patch.byFields tableName Any [ field ] patch sqlProps
+    
+    [<RequireQualifiedAccess>]
+    module RemoveFields =
+        
+        /// Remove fields from documents via a comparison on a JSON field in the document
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field fieldNames sqlProps =
+            WithProps.RemoveFields.byFields tableName Any [ field ] fieldNames sqlProps
+    
+    [<RequireQualifiedAccess>]
+    module Delete =
+        
+        /// Delete documents by matching a JSON field comparison query (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field sqlProps =
+            WithProps.Delete.byFields tableName Any [ field ] sqlProps
+
+
+[<RequireQualifiedAccess>]
+module Count =
+    
+    /// Count matching documents using a JSON field comparison (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Count.byFields tableName Any [ field ]
+
+
+[<RequireQualifiedAccess>]
+module Exists =
+    
+    /// Determine if a document exists using a JSON field comparison (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Exists.byFields tableName Any [ field ]
+
+
+[<RequireQualifiedAccess>]
+module Find =
+    
+    /// Retrieve documents matching a JSON field comparison (->> =)
+    [<CompiledName "FSharpByField">]
+    [<System.Obsolete "Use byFields instead ~ will be removed in v4.1">]
+    let byField<'TDoc> tableName field =
+        Find.byFields<'TDoc> tableName Any [ field ]
+    
+    /// Retrieve documents matching a JSON field comparison (->> =)
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let ByField<'TDoc>(tableName, field) =
+        Find.ByFields<'TDoc>(tableName, Any, Seq.singleton field)
+    
+    /// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
+    [<CompiledName "FSharpFirstByField">]
+    [<System.Obsolete "Use firstByFields instead ~ will be removed in v4.1">]
+    let firstByField<'TDoc> tableName field =
+        Find.firstByFields<'TDoc> tableName Any [ field ]
+    
+    /// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
+    [<System.Obsolete "Use FirstByFields instead ~ will be removed in v4.1">]
+    let FirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, field) =
+        Find.FirstByFields<'TDoc>(tableName, Any, Seq.singleton field)
+
+
+[<RequireQualifiedAccess>]
+module Patch =
+    
+    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field (patch: 'TPatch) =
+        Patch.byFields tableName Any [ field ] patch
+
+
+[<RequireQualifiedAccess>]
+module RemoveFields =
+    
+    /// Remove fields from documents via a comparison on a JSON field in the document
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field fieldNames =
+        RemoveFields.byFields tableName Any [ field ] fieldNames
+
+
+[<RequireQualifiedAccess>]
+module Delete =
+    
+    /// Delete documents by matching a JSON field comparison query (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Delete.byFields tableName Any [ field ]
+
+
+open Npgsql
+
+/// F# Extensions for the NpgsqlConnection type
+[<AutoOpen>]
+module Extensions =
+    
+    type NpgsqlConnection with
+        
+        /// Count matching documents using a JSON field comparison query (->> =)
+        [<System.Obsolete "Use countByFields instead ~ will be removed in v4.1">]
+        member conn.countByField tableName field =
+            conn.countByFields tableName Any [ field ]
+        
+        /// Determine if documents exist using a JSON field comparison query (->> =)
+        [<System.Obsolete "Use existsByFields instead ~ will be removed in v4.1">]
+        member conn.existsByField tableName field =
+            conn.existsByFields tableName Any [ field ]
+        
+        /// Retrieve documents matching a JSON field comparison query (->> =)
+        [<System.Obsolete "Use findByFields instead ~ will be removed in v4.1">]
+        member conn.findByField<'TDoc> tableName field =
+            conn.findByFields<'TDoc> tableName Any [ field ]
+        
+        /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
+        [<System.Obsolete "Use findFirstByFields instead ~ will be removed in v4.1">]
+        member conn.findFirstByField<'TDoc> tableName field =
+            conn.findFirstByFields<'TDoc> tableName Any [ field ]
+        
+        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+        [<System.Obsolete "Use patchByFields instead ~ will be removed in v4.1">]
+        member conn.patchByField tableName field (patch: 'TPatch) =
+            conn.patchByFields tableName Any [ field ] patch
+        
+        /// Remove fields from documents via a comparison on a JSON field in the document
+        [<System.Obsolete "Use removeFieldsByFields instead ~ will be removed in v4.1">]
+        member conn.removeFieldsByField tableName field fieldNames =
+            conn.removeFieldsByFields tableName Any [ field ] fieldNames
+        
+        /// Delete documents by matching a JSON field comparison query (->> =)
+        [<System.Obsolete "Use deleteByFields instead ~ will be removed in v4.1">]
+        member conn.deleteByField tableName field =
+            conn.deleteByFields tableName Any [ field ]
+
+
+open System.Runtime.CompilerServices
+open Npgsql.FSharp
+
+type NpgsqlConnectionCSharpCompatExtensions =
+    
+    /// Count matching documents using a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use CountByFields instead ~ will be removed in v4.1">]
+    static member inline CountByField(conn, tableName, field) =
+        WithProps.Count.byFields tableName Any [ field ] (Sql.existingConnection conn)
+    
+    /// Determine if documents exist using a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use ExistsByFields instead ~ will be removed in v4.1">]
+    static member inline ExistsByField(conn, tableName, field) =
+        WithProps.Exists.byFields tableName Any [ field ] (Sql.existingConnection conn)
+    
+    /// Retrieve documents matching a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use FindByFields instead ~ will be removed in v4.1">]
+    static member inline FindByField<'TDoc>(conn, tableName, field) =
+        WithProps.Find.ByFields<'TDoc>(tableName, Any, [ field ], Sql.existingConnection conn)
+    
+    /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
+    [<Extension>]
+    [<System.Obsolete "Use FindFirstByFields instead ~ will be removed in v4.1">]
+    static member inline FindFirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(conn, tableName, field) =
+        WithProps.Find.FirstByFields<'TDoc>(tableName, Any, [ field ], Sql.existingConnection conn)
+    
+    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use PatchByFields instead ~ will be removed in v4.1">]
+    static member inline PatchByField(conn, tableName, field, patch: 'TPatch) =
+        WithProps.Patch.byFields tableName Any [ field ] patch (Sql.existingConnection conn)
+    
+    /// Remove fields from documents via a comparison on a JSON field in the document
+    [<Extension>]
+    [<System.Obsolete "Use RemoveFieldsByFields instead ~ will be removed in v4.1">]
+    static member inline RemoveFieldsByField(conn, tableName, field, fieldNames) =
+        WithProps.RemoveFields.byFields tableName Any [ field ] fieldNames (Sql.existingConnection conn)
+    
+    /// Delete documents by matching a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use DeleteByFields instead ~ will be removed in v4.1">]
+    static member inline DeleteByField(conn, tableName, field) =
+        WithProps.Delete.byFields tableName Any [ field ] (Sql.existingConnection conn)

src/Postgres/Extensions.fs

@@ -1,6 +1,5 @@
 namespace BitBadger.Documents.Postgres
 
-open BitBadger.Documents
 open Npgsql
 open Npgsql.FSharp
 
@@ -54,11 +53,6 @@ module Extensions =
         member conn.countByFields tableName howMatched fields =
             WithProps.Count.byFields tableName howMatched fields (Sql.existingConnection conn)
         
-        /// Count matching documents using a JSON field comparison query (->> =)
-        [<System.Obsolete "Use countByFields instead; will be removed in v4">]
-        member conn.countByField tableName field =
-            conn.countByFields tableName Any [ field ]
-        
         /// Count matching documents using a JSON containment query (@>)
         member conn.countByContains tableName criteria =
             WithProps.Count.byContains tableName criteria (Sql.existingConnection conn)
@@ -75,11 +69,6 @@ module Extensions =
         member conn.existsByFields tableName howMatched fields =
             WithProps.Exists.byFields tableName howMatched fields (Sql.existingConnection conn)
         
-        /// Determine if documents exist using a JSON field comparison query (->> =)
-        [<System.Obsolete "Use existsByFields instead; will be removed in v4">]
-        member conn.existsByField tableName field =
-            conn.existsByFields tableName Any [ field ]
-        
         /// Determine if documents exist using a JSON containment query (@>)
         member conn.existsByContains tableName criteria =
             WithProps.Exists.byContains tableName criteria (Sql.existingConnection conn)
@@ -92,6 +81,10 @@ module Extensions =
         member conn.findAll<'TDoc> tableName =
             WithProps.Find.all<'TDoc> tableName (Sql.existingConnection conn)
 
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        member conn.findAllOrdered<'TDoc> tableName orderFields =
+            WithProps.Find.allOrdered<'TDoc> tableName orderFields (Sql.existingConnection conn)
+
         /// Retrieve a document by its ID; returns None if not found
         member conn.findById<'TKey, 'TDoc> tableName docId =
             WithProps.Find.byId<'TKey, 'TDoc> tableName docId (Sql.existingConnection conn)
@@ -100,36 +93,56 @@ module Extensions =
         member conn.findByFields<'TDoc> tableName howMatched fields =
             WithProps.Find.byFields<'TDoc> tableName howMatched fields (Sql.existingConnection conn)
         
-        /// Retrieve documents matching a JSON field comparison query (->> =)
-        [<System.Obsolete "Use findByFields instead; will be removed in v4">]
-        member conn.findByField<'TDoc> tableName field =
-            conn.findByFields<'TDoc> tableName Any [ field ]
+        /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the
+        /// document
+        member conn.findByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+            WithProps.Find.byFieldsOrdered<'TDoc>
+                tableName howMatched queryFields orderFields (Sql.existingConnection conn)
         
         /// Retrieve documents matching a JSON containment query (@>)
         member conn.findByContains<'TDoc> tableName (criteria: obj) =
             WithProps.Find.byContains<'TDoc> tableName criteria (Sql.existingConnection conn)
 
+        /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+        member conn.findByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields =
+            WithProps.Find.byContainsOrdered<'TDoc> tableName criteria orderFields (Sql.existingConnection conn)
+
         /// Retrieve documents matching a JSON Path match query (@?)
         member conn.findByJsonPath<'TDoc> tableName jsonPath =
             WithProps.Find.byJsonPath<'TDoc> tableName jsonPath (Sql.existingConnection conn)
         
+        /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
+        member conn.findByJsonPathOrdered<'TDoc> tableName jsonPath orderFields =
+            WithProps.Find.byJsonPathOrdered<'TDoc> tableName jsonPath orderFields (Sql.existingConnection conn)
+        
         /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
         member conn.findFirstByFields<'TDoc> tableName howMatched fields =
             WithProps.Find.firstByFields<'TDoc> tableName howMatched fields (Sql.existingConnection conn)
         
-        /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
-        [<System.Obsolete "Use findFirstByFields instead; will be removed in v4">]
-        member conn.findFirstByField<'TDoc> tableName field =
-            conn.findFirstByFields<'TDoc> tableName Any [ field ]
+        /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in
+        /// the document; returns None if not found
+        member conn.findFirstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+            WithProps.Find.firstByFieldsOrdered<'TDoc>
+                tableName howMatched queryFields orderFields (Sql.existingConnection conn)
         
         /// Retrieve the first document matching a JSON containment query (@>); returns None if not found
         member conn.findFirstByContains<'TDoc> tableName (criteria: obj) =
             WithProps.Find.firstByContains<'TDoc> tableName criteria (Sql.existingConnection conn)
 
+        /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the
+        /// document; returns None if not found
+        member conn.findFirstByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields =
+            WithProps.Find.firstByContainsOrdered<'TDoc> tableName criteria orderFields (Sql.existingConnection conn)
+
         /// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
         member conn.findFirstByJsonPath<'TDoc> tableName jsonPath =
             WithProps.Find.firstByJsonPath<'TDoc> tableName jsonPath (Sql.existingConnection conn)
         
+        /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the
+        /// document; returns None if not found
+        member conn.findFirstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields =
+            WithProps.Find.firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields (Sql.existingConnection conn)
+        
         /// Update an entire document by its ID
         member conn.updateById tableName (docId: 'TKey) (document: 'TDoc) =
             WithProps.Update.byId tableName docId document (Sql.existingConnection conn)
@@ -146,11 +159,6 @@ module Extensions =
         member conn.patchByFields tableName howMatched fields (patch: 'TPatch) =
             WithProps.Patch.byFields tableName howMatched fields patch (Sql.existingConnection conn)
         
-        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
-        [<System.Obsolete "Use patchByFields instead; will be removed in v4">]
-        member conn.patchByField tableName field (patch: 'TPatch) =
-            conn.patchByFields tableName Any [ field ] patch
-        
         /// Patch documents using a JSON containment query in the WHERE clause (@>)
         member conn.patchByContains tableName (criteria: 'TCriteria) (patch: 'TPatch) =
             WithProps.Patch.byContains tableName criteria patch (Sql.existingConnection conn)
@@ -167,11 +175,6 @@ module Extensions =
         member conn.removeFieldsByFields tableName howMatched fields fieldNames =
             WithProps.RemoveFields.byFields tableName howMatched fields fieldNames (Sql.existingConnection conn)
         
-        /// Remove fields from documents via a comparison on a JSON field in the document
-        [<System.Obsolete "Use removeFieldsByFields instead; will be removed in v4">]
-        member conn.removeFieldsByField tableName field fieldNames =
-            conn.removeFieldsByFields tableName Any [ field ] fieldNames
-        
         /// Remove fields from documents via a JSON containment query (@>)
         member conn.removeFieldsByContains tableName (criteria: 'TContains) fieldNames =
             WithProps.RemoveFields.byContains tableName criteria fieldNames (Sql.existingConnection conn)
@@ -187,11 +190,6 @@ module Extensions =
         member conn.deleteByFields tableName howMatched fields =
             WithProps.Delete.byFields tableName howMatched fields (Sql.existingConnection conn)
         
-        /// Delete documents by matching a JSON field comparison query (->> =)
-        [<System.Obsolete "Use deleteByFields instead; will be removed in v4">]
-        member conn.deleteByField tableName field =
-            conn.deleteByFields tableName Any [ field ]
-        
         /// Delete documents by matching a JSON containment query (@>)
         member conn.deleteByContains tableName (criteria: 'TContains) =
             WithProps.Delete.byContains tableName criteria (Sql.existingConnection conn)
@@ -213,7 +211,7 @@ type NpgsqlConnectionCSharpExtensions =
 
     /// Execute a query that returns one or no results; returns None if not found
     [<Extension>]
-    static member inline CustomSingle<'TDoc when 'TDoc: null>(
+    static member inline CustomSingle<'TDoc when 'TDoc: null and 'TDoc: not struct>(
             conn, query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
         WithProps.Custom.Single<'TDoc>(query, parameters, mapFunc, Sql.existingConnection conn)
 
@@ -263,12 +261,6 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline CountByFields(conn, tableName, howMatched, fields) =
         WithProps.Count.byFields tableName howMatched fields (Sql.existingConnection conn)
     
-    /// Count matching documents using a JSON field comparison query (->> =)
-    [<Extension>]
-    [<System.Obsolete "Use CountByFields instead; will be removed in v4">]
-    static member inline CountByField(conn, tableName, field) =
-        conn.CountByFields(tableName, Any, [ field ])
-    
     /// Count matching documents using a JSON containment query (@>)
     [<Extension>]
     static member inline CountByContains(conn, tableName, criteria: 'TCriteria) =
@@ -289,12 +281,6 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline ExistsByFields(conn, tableName, howMatched, fields) =
         WithProps.Exists.byFields tableName howMatched fields (Sql.existingConnection conn)
     
-    /// Determine if documents exist using a JSON field comparison query (->> =)
-    [<Extension>]
-    [<System.Obsolete "Use ExistsByFields instead; will be removed in v4">]
-    static member inline ExistsByField(conn, tableName, field) =
-        conn.ExistsByFields(tableName, Any, [ field ])
-    
     /// Determine if documents exist using a JSON containment query (@>)
     [<Extension>]
     static member inline ExistsByContains(conn, tableName, criteria: 'TCriteria) =
@@ -310,9 +296,14 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline FindAll<'TDoc>(conn, tableName) =
         WithProps.Find.All<'TDoc>(tableName, Sql.existingConnection conn)
 
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    [<Extension>]
+    static member inline FindAllOrdered<'TDoc>(conn, tableName, orderFields) =
+        WithProps.Find.AllOrdered<'TDoc>(tableName, orderFields, Sql.existingConnection conn)
+
     /// Retrieve a document by its ID; returns None if not found
     [<Extension>]
-    static member inline FindById<'TKey, 'TDoc when 'TDoc: null>(conn, tableName, docId: 'TKey) =
+    static member inline FindById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(conn, tableName, docId: 'TKey) =
         WithProps.Find.ById<'TKey, 'TDoc>(tableName, docId, Sql.existingConnection conn)
 
     /// Retrieve documents matching a JSON field comparison query (->> =)
@@ -320,43 +311,71 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline FindByFields<'TDoc>(conn, tableName, howMatched, fields) =
         WithProps.Find.ByFields<'TDoc>(tableName, howMatched, fields, Sql.existingConnection conn)
     
-    /// Retrieve documents matching a JSON field comparison query (->> =)
+    /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the document
     [<Extension>]
-    [<System.Obsolete "Use FindByFields instead; will be removed in v4">]
-    static member inline FindByField<'TDoc>(conn, tableName, field) =
-        conn.FindByFields<'TDoc>(tableName, Any, [ field ])
+    static member inline FindByFieldsOrdered<'TDoc>(conn, tableName, howMatched, queryFields, orderFields) =
+        WithProps.Find.ByFieldsOrdered<'TDoc>(
+            tableName, howMatched, queryFields, orderFields, Sql.existingConnection conn)
     
     /// Retrieve documents matching a JSON containment query (@>)
     [<Extension>]
     static member inline FindByContains<'TDoc>(conn, tableName, criteria: obj) =
         WithProps.Find.ByContains<'TDoc>(tableName, criteria, Sql.existingConnection conn)
 
+    /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+    [<Extension>]
+    static member inline FindByContainsOrdered<'TDoc>(conn, tableName, criteria: obj, orderFields) =
+        WithProps.Find.ByContainsOrdered<'TDoc>(tableName, criteria, orderFields, Sql.existingConnection conn)
+
     /// Retrieve documents matching a JSON Path match query (@?)
     [<Extension>]
     static member inline FindByJsonPath<'TDoc>(conn, tableName, jsonPath) =
         WithProps.Find.ByJsonPath<'TDoc>(tableName, jsonPath, Sql.existingConnection conn)
     
-    /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
+    /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
     [<Extension>]
-    static member inline FindFirstByFields<'TDoc when 'TDoc: null>(conn, tableName, howMatched, fields) =
-        WithProps.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, Sql.existingConnection conn)
+    static member inline FindByJsonPathOrdered<'TDoc>(conn, tableName, jsonPath, orderFields) =
+        WithProps.Find.ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, Sql.existingConnection conn)
     
     /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
     [<Extension>]
-    [<System.Obsolete "Use FindFirstByFields instead; will be removed in v4">]
-    static member inline FindFirstByField<'TDoc when 'TDoc: null>(conn, tableName, field) =
-        conn.FindFirstByFields<'TDoc>(tableName, Any, [ field ])
+    static member inline FindFirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, howMatched, fields) =
+        WithProps.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, Sql.existingConnection conn)
+    
+    /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in the
+    /// document; returns null if not found
+    [<Extension>]
+    static member inline FindFirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, howMatched, queryFields, orderFields) =
+        WithProps.Find.FirstByFieldsOrdered<'TDoc>(
+            tableName, howMatched, queryFields, orderFields, Sql.existingConnection conn)
     
     /// Retrieve the first document matching a JSON containment query (@>); returns None if not found
     [<Extension>]
-    static member inline FindFirstByContains<'TDoc when 'TDoc: null>(conn, tableName, criteria: obj) =
+    static member inline FindFirstByContains<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, criteria: obj) =
         WithProps.Find.FirstByContains<'TDoc>(tableName, criteria, Sql.existingConnection conn)
 
+    /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the document;
+    /// returns None if not found
+    [<Extension>]
+    static member inline FindFirstByContainsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, criteria: obj, orderFields) =
+        WithProps.Find.FirstByContainsOrdered<'TDoc>(tableName, criteria, orderFields, Sql.existingConnection conn)
+
     /// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
     [<Extension>]
-    static member inline FindFirstByJsonPath<'TDoc when 'TDoc: null>(conn, tableName, jsonPath) =
+    static member inline FindFirstByJsonPath<'TDoc when 'TDoc: null and 'TDoc: not struct>(conn, tableName, jsonPath) =
         WithProps.Find.FirstByJsonPath<'TDoc>(tableName, jsonPath, Sql.existingConnection conn)
     
+    /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the document;
+    /// returns None if not found
+    [<Extension>]
+    static member inline FindFirstByJsonPathOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, jsonPath, orderFields) =
+        WithProps.Find.FirstByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, Sql.existingConnection conn)
+    
     /// Update an entire document by its ID
     [<Extension>]
     static member inline UpdateById(conn, tableName, docId: 'TKey, document: 'TDoc) =
@@ -377,12 +396,6 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline PatchByFields(conn, tableName, howMatched, fields, patch: 'TPatch) =
         WithProps.Patch.byFields tableName howMatched fields patch (Sql.existingConnection conn)
     
-    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
-    [<Extension>]
-    [<System.Obsolete "Use PatchByFields instead; will be removed in v4">]
-    static member inline PatchByField(conn, tableName, field, patch: 'TPatch) =
-        conn.PatchByFields(tableName, Any, [ field ], patch)
-    
     /// Patch documents using a JSON containment query in the WHERE clause (@>)
     [<Extension>]
     static member inline PatchByContains(conn, tableName, criteria: 'TCriteria, patch: 'TPatch) =
@@ -403,12 +416,6 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline RemoveFieldsByFields(conn, tableName, howMatched, fields, fieldNames) =
         WithProps.RemoveFields.byFields tableName howMatched fields fieldNames (Sql.existingConnection conn)
     
-    /// Remove fields from documents via a comparison on a JSON field in the document
-    [<Extension>]
-    [<System.Obsolete "Use RemoveFieldsByFields instead; will be removed in v4">]
-    static member inline RemoveFieldsByField(conn, tableName, field, fieldNames) =
-        conn.RemoveFieldsByFields(tableName, Any, [ field ], fieldNames)
-        
     /// Remove fields from documents via a JSON containment query (@>)
     [<Extension>]
     static member inline RemoveFieldsByContains(conn, tableName, criteria: 'TContains, fieldNames) =
@@ -429,12 +436,6 @@ type NpgsqlConnectionCSharpExtensions =
     static member inline DeleteByFields(conn, tableName, howMatched, fields) =
         WithProps.Delete.byFields tableName howMatched fields (Sql.existingConnection conn)
     
-    /// Delete documents by matching a JSON field comparison query (->> =)
-    [<Extension>]
-    [<System.Obsolete "Use DeleteByFields instead; will be removed in v4">]
-    static member inline DeleteByField(conn, tableName, field) =
-        conn.DeleteByFields(tableName, Any, [ field ])
-    
     /// Delete documents by matching a JSON containment query (@>)
     [<Extension>]
     static member inline DeleteByContains(conn, tableName, criteria: 'TContains) =

src/Postgres/Library.fs

@@ -3,8 +3,10 @@
 /// The type of index to generate for the document
 [<Struct>]
 type DocumentIndex =
+    
     /// A GIN index with standard operations (all operators supported)
     | Full
+    
     /// A GIN index with JSONPath operations (optimized for @>, @?, @@ operators)
     | Optimized
 
@@ -36,6 +38,7 @@ open Npgsql.FSharp
 /// Helper functions
 [<AutoOpen>]
 module private Helpers =
+    
     /// Shorthand to retrieve the data source as SqlProps
     let internal fromDataSource () =
         Configuration.dataSource () |> Sql.fromDataSource
@@ -87,41 +90,36 @@ module Parameters =
         fields
         |> Seq.map (fun it ->
             seq {
-                match it.Op with
-                | EX | NEX -> ()
-                | BT ->
+                match it.Comparison with
+                | Exists | NotExists -> ()
+                | Between (min, max) ->
                     let p = name.Derive it.ParameterName
-                    let values = it.Value :?> obj list
-                    yield ($"{p}min",
-                           parameterFor (List.head values) (fun v -> Sql.parameter (NpgsqlParameter($"{p}min", v))))
-                    yield ($"{p}max",
-                           parameterFor (List.last values) (fun v -> Sql.parameter (NpgsqlParameter($"{p}max", v))))
-                | _ ->
+                    yield ($"{p}min", parameterFor min (fun v -> Sql.parameter (NpgsqlParameter($"{p}min", v))))
+                    yield ($"{p}max", parameterFor max (fun v -> Sql.parameter (NpgsqlParameter($"{p}max", v))))
+                | In values ->
                     let p = name.Derive it.ParameterName
-                    yield (p, parameterFor it.Value (fun v -> Sql.parameter (NpgsqlParameter(p, v)))) })
+                    yield!
+                        values
+                        |> Seq.mapi (fun idx v ->
+                            let paramName = $"{p}_{idx}" 
+                            paramName, Sql.parameter (NpgsqlParameter(paramName, v)))
+                | InArray (_, values) ->
+                    let p = name.Derive it.ParameterName
+                    yield (p, Sql.stringArray (values |> Seq.map string |> Array.ofSeq))
+                | Equal v | Greater v | GreaterOrEqual v | Less v | LessOrEqual v | NotEqual v ->
+                    let p = name.Derive it.ParameterName
+                    yield (p, parameterFor v (fun l -> Sql.parameter (NpgsqlParameter(p, l)))) })
         |> Seq.collect id
         |> Seq.append parameters
         |> Seq.toList
         |> Seq.ofList
 
-    /// Create a JSON field parameter
-    [<CompiledName "AddField">]
-    [<System.Obsolete "Use addFieldParams (F#) / AddFields (C#) instead; will be removed in v4">]
-    let addFieldParam name field parameters =
-        addFieldParams [ { field with ParameterName = Some name } ] parameters
-    
     /// Append JSON field name parameters for the given field names to the given parameters
     [<CompiledName "FieldNames">]
     let fieldNameParams (fieldNames: string seq) =
         if Seq.length fieldNames = 1 then "@name", Sql.string (Seq.head fieldNames)
         else "@name", Sql.stringArray (Array.ofSeq fieldNames)
     
-    /// Append JSON field name parameters for the given field names to the given parameters
-    [<CompiledName "FieldName">]
-    [<System.Obsolete "Use fieldNameParams (F#) / FieldNames (C#) instead; will be removed in v4">]
-    let fieldNameParam fieldNames =
-        fieldNameParams fieldNames
-
     /// An empty parameter sequence
     [<CompiledName "None">]
     let noParams =
@@ -143,23 +141,28 @@ module Query =
             | _ -> false
         fields
         |> Seq.map (fun it ->
-            match it.Op with
-            | EX | NEX -> $"{it.Path PostgreSQL} {it.Op}"
+            match it.Comparison with
+            | Exists | NotExists -> $"{it.Path PostgreSQL AsSql} {it.Comparison.OpSql}"
+            | InArray _ -> $"{it.Path PostgreSQL AsJson} {it.Comparison.OpSql} {name.Derive it.ParameterName}"
             | _ ->
                 let p            = name.Derive it.ParameterName
                 let param, value =
-                    match it.Op with
-                    | BT -> $"{p}min AND {p}max", (it.Value :?> obj list)[0]
-                    | _  -> p, it.Value
+                    match it.Comparison with
+                    | Between (min, _) -> $"{p}min AND {p}max", min
+                    | In values ->
+                        let paramNames = values |> Seq.mapi (fun idx _ -> $"{p}_{idx}") |> String.concat ", "
+                        $"({paramNames})", defaultArg (Seq.tryHead values) (obj ())
+                    | Equal v | Greater v | GreaterOrEqual v | Less v | LessOrEqual v | NotEqual v  -> p, v
+                    | _ -> p, ""
                 if isNumeric value then
-                    $"({it.Path PostgreSQL})::numeric {it.Op} {param}"
-                else $"{it.Path PostgreSQL} {it.Op} {param}")
+                    $"({it.Path PostgreSQL AsSql})::numeric {it.Comparison.OpSql} {param}"
+                else $"{it.Path PostgreSQL AsSql} {it.Comparison.OpSql} {param}")
         |> String.concat $" {howMatched} "
 
     /// Create a WHERE clause fragment to implement an ID-based query
     [<CompiledName "WhereById">]
     let whereById<'TKey> (docId: 'TKey) =
-        whereByFields Any [ { Field.EQ (Configuration.idField ()) docId with ParameterName = Some "@id" } ]
+        whereByFields Any [ { Field.Equal (Configuration.idField ()) docId with ParameterName = Some "@id" } ]
     
     /// Table and index definition queries
     module Definition =
@@ -272,7 +275,7 @@ module WithProps =
         }
 
         /// Execute a query that returns one or no results; returns null if not found
-        let Single<'TDoc when 'TDoc: null>(
+        let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>(
                 query, parameters, mapFunc: System.Func<RowReader, 'TDoc>, sqlProps) = backgroundTask {
             let! result = single<'TDoc> query parameters mapFunc.Invoke sqlProps
             return Option.toObj result
@@ -324,7 +327,23 @@ module WithProps =
         /// Insert a new document
         [<CompiledName "Insert">]
         let insert<'TDoc> tableName (document: 'TDoc) sqlProps =
-            Custom.nonQuery (Query.insert tableName) [ jsonParam "@data" document ] sqlProps
+            let query =
+                match Configuration.autoIdStrategy () with 
+                | Disabled -> Query.insert tableName
+                | strategy ->
+                    let idField   = Configuration.idField ()
+                    let dataParam =
+                        if AutoId.NeedsAutoId strategy document idField then
+                            match strategy with
+                            | Number ->
+                                $"' || (SELECT COALESCE(MAX((data->>'{idField}')::numeric), 0) + 1 FROM {tableName}) || '"
+                            | Guid -> $"\"{AutoId.GenerateGuid()}\""
+                            | RandomString -> $"\"{AutoId.GenerateRandomString(Configuration.idStringLength ())}\""
+                            | Disabled -> "@data"
+                            |> function it -> $"""@data::jsonb || ('{{"{idField}":{it}}}')::jsonb"""
+                        else "@data"
+                    (Query.insert tableName).Replace("@data", dataParam)
+            Custom.nonQuery query [ jsonParam "@data" document ] sqlProps
 
         /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
         [<CompiledName "Save">]
@@ -407,13 +426,23 @@ module WithProps =
         let All<'TDoc>(tableName, sqlProps) =
             Custom.List<'TDoc>(Query.find tableName, [], fromData<'TDoc>, sqlProps)
 
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        [<CompiledName "FSharpAllOrdered">]
+        let allOrdered<'TDoc> tableName orderFields sqlProps =
+            Custom.list<'TDoc> (Query.find tableName + Query.orderBy orderFields PostgreSQL) [] fromData<'TDoc> sqlProps
+
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        let AllOrdered<'TDoc>(tableName, orderFields, sqlProps) =
+            Custom.List<'TDoc>(
+                Query.find tableName + Query.orderBy orderFields PostgreSQL, [], fromData<'TDoc>, sqlProps)
+
         /// Retrieve a document by its ID (returns None if not found)
         [<CompiledName "FSharpById">]
         let byId<'TKey, 'TDoc> tableName (docId: 'TKey) sqlProps =
             Custom.single (Query.byId (Query.find tableName) docId) [ idParam docId ] fromData<'TDoc> sqlProps
 
         /// Retrieve a document by its ID (returns null if not found)
-        let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId: 'TKey, sqlProps) =
+        let ById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, docId: 'TKey, sqlProps) =
             Custom.Single<'TDoc>(
                 Query.byId (Query.find tableName) docId, [ idParam docId ], fromData<'TDoc>, sqlProps)
 
@@ -426,12 +455,6 @@ module WithProps =
                 fromData<'TDoc>
                 sqlProps
         
-        /// Retrieve documents matching a JSON field comparison (->> =)
-        [<CompiledName "FSharpByField">]
-        [<System.Obsolete "Use byFields instead; will be removed in v4">]
-        let byField<'TDoc> tableName field sqlProps =
-            byFields<'TDoc> tableName Any [ field ] sqlProps
-        
         /// Retrieve documents matching JSON field comparisons (->> =)
         let ByFields<'TDoc>(tableName, howMatched, fields, sqlProps) =
             Custom.List<'TDoc>(
@@ -440,10 +463,22 @@ module WithProps =
                 fromData<'TDoc>,
                 sqlProps)
         
-        /// Retrieve documents matching a JSON field comparison (->> =)
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let ByField<'TDoc>(tableName, field, sqlProps) =
-            ByFields<'TDoc>(tableName, Any, Seq.singleton field, sqlProps)
+        /// Retrieve documents matching JSON field comparisons (->> =) ordered by the given fields in the document
+        [<CompiledName "FSharpByFieldsOrdered">]
+        let byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields sqlProps =
+            Custom.list<'TDoc>
+                (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL)
+                (addFieldParams queryFields [])
+                fromData<'TDoc>
+                sqlProps
+        
+        /// Retrieve documents matching JSON field comparisons (->> =) ordered by the given fields in the document
+        let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, sqlProps) =
+            Custom.List<'TDoc>(
+                Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields PostgreSQL,
+                addFieldParams queryFields [],
+                fromData<'TDoc>,
+                sqlProps)
         
         /// Retrieve documents matching a JSON containment query (@>)
         [<CompiledName "FSharpByContains">]
@@ -459,6 +494,23 @@ module WithProps =
                 fromData<'TDoc>,
                 sqlProps)
 
+        /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+        [<CompiledName "FSharpByContainsOrdered">]
+        let byContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps =
+            Custom.list<'TDoc>
+                (Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
+                [ jsonParam "@criteria" criteria ]
+                fromData<'TDoc>
+                sqlProps
+
+        /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+        let ByContainsOrdered<'TDoc>(tableName, criteria: obj, orderFields, sqlProps) =
+            Custom.List<'TDoc>(
+                Query.byContains (Query.find tableName) + Query.orderBy orderFields PostgreSQL,
+                [ jsonParam "@criteria" criteria ],
+                fromData<'TDoc>,
+                sqlProps)
+
         /// Retrieve documents matching a JSON Path match query (@?)
         [<CompiledName "FSharpByJsonPath">]
         let byJsonPath<'TDoc> tableName jsonPath sqlProps =
@@ -473,6 +525,23 @@ module WithProps =
                 fromData<'TDoc>,
                 sqlProps)
         
+        /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
+        [<CompiledName "FSharpByJsonPathOrdered">]
+        let byJsonPathOrdered<'TDoc> tableName jsonPath orderFields sqlProps =
+            Custom.list<'TDoc>
+                (Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL)
+                [ "@path", Sql.string jsonPath ]
+                fromData<'TDoc>
+                sqlProps
+        
+        /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
+        let ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, sqlProps) =
+            Custom.List<'TDoc>(
+                Query.byPathMatch (Query.find tableName) + Query.orderBy orderFields PostgreSQL,
+                [ "@path", Sql.string jsonPath ],
+                fromData<'TDoc>,
+                sqlProps)
+        
         /// Retrieve the first document matching JSON field comparisons (->> =); returns None if not found
         [<CompiledName "FSharpFirstByFields">]
         let firstByFields<'TDoc> tableName howMatched fields sqlProps =
@@ -482,24 +551,33 @@ module WithProps =
                 fromData<'TDoc>
                 sqlProps
         
-        /// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
-        [<CompiledName "FSharpFirstByField">]
-        [<System.Obsolete "Use firstByFields instead; will be removed in v4">]
-        let firstByField<'TDoc> tableName field sqlProps =
-            firstByFields<'TDoc> tableName Any [ field ] sqlProps
-            
         /// Retrieve the first document matching JSON field comparisons (->> =); returns null if not found
-        let FirstByFields<'TDoc when 'TDoc: null>(tableName, howMatched, fields, sqlProps) =
+        let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields, sqlProps) =
             Custom.Single<'TDoc>(
                 $"{Query.byFields (Query.find tableName) howMatched fields} LIMIT 1",
                 addFieldParams fields [],
                 fromData<'TDoc>,
                 sqlProps)
         
-        /// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
-        [<System.Obsolete "Use FirstByFields instead; will be removed in v4">]
-        let FirstByField<'TDoc when 'TDoc: null>(tableName, field, sqlProps) =
-            FirstByFields<'TDoc>(tableName, Any, Seq.singleton field, sqlProps)
+        /// Retrieve the first document matching JSON field comparisons (->> =) ordered by the given fields in the
+        /// document; returns None if not found
+        [<CompiledName "FSharpFirstByFieldsOrdered">]
+        let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields sqlProps =
+            Custom.single<'TDoc>
+                $"{Query.byFields (Query.find tableName) howMatched queryFields}{Query.orderBy orderFields PostgreSQL} LIMIT 1"
+                (addFieldParams queryFields [])
+                fromData<'TDoc>
+                sqlProps
+        
+        /// Retrieve the first document matching JSON field comparisons (->> =) ordered by the given fields in the
+        /// document; returns null if not found
+        let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+                tableName, howMatched, queryFields, orderFields, sqlProps) =
+            Custom.Single<'TDoc>(
+                $"{Query.byFields (Query.find tableName) howMatched queryFields}{Query.orderBy orderFields PostgreSQL} LIMIT 1",
+                addFieldParams queryFields [],
+                fromData<'TDoc>,
+                sqlProps)
         
         /// Retrieve the first document matching a JSON containment query (@>); returns None if not found
         [<CompiledName "FSharpFirstByContains">]
@@ -511,13 +589,33 @@ module WithProps =
                 sqlProps
 
         /// Retrieve the first document matching a JSON containment query (@>); returns null if not found
-        let FirstByContains<'TDoc when 'TDoc: null>(tableName, criteria: obj, sqlProps) =
+        let FirstByContains<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, criteria: obj, sqlProps) =
             Custom.Single<'TDoc>(
                 $"{Query.byContains (Query.find tableName)} LIMIT 1",
                 [ jsonParam "@criteria" criteria ],
                 fromData<'TDoc>,
                 sqlProps)
 
+        /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the
+        /// document; returns None if not found
+        [<CompiledName "FSharpFirstByContainsOrdered">]
+        let firstByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields sqlProps =
+            Custom.single<'TDoc>
+                $"{Query.byContains (Query.find tableName)}{Query.orderBy orderFields PostgreSQL} LIMIT 1"
+                [ jsonParam "@criteria" criteria ]
+                fromData<'TDoc>
+                sqlProps
+
+        /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the
+        /// document; returns null if not found
+        let FirstByContainsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+                tableName, criteria: obj, orderFields, sqlProps) =
+            Custom.Single<'TDoc>(
+                $"{Query.byContains (Query.find tableName)}{Query.orderBy orderFields PostgreSQL} LIMIT 1",
+                [ jsonParam "@criteria" criteria ],
+                fromData<'TDoc>,
+                sqlProps)
+
         /// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
         [<CompiledName "FSharpFirstByJsonPath">]
         let firstByJsonPath<'TDoc> tableName jsonPath sqlProps =
@@ -528,13 +626,33 @@ module WithProps =
                 sqlProps
 
         /// Retrieve the first document matching a JSON Path match query (@?); returns null if not found
-        let FirstByJsonPath<'TDoc when 'TDoc: null>(tableName, jsonPath, sqlProps) =
+        let FirstByJsonPath<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, jsonPath, sqlProps) =
             Custom.Single<'TDoc>(
                 $"{Query.byPathMatch (Query.find tableName)} LIMIT 1",
                 [ "@path", Sql.string jsonPath ],
                 fromData<'TDoc>,
                 sqlProps)
 
+        /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the
+        /// document; returns None if not found
+        [<CompiledName "FSharpFirstByJsonPathOrdered">]
+        let firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields sqlProps =
+            Custom.single<'TDoc>
+                $"{Query.byPathMatch (Query.find tableName)}{Query.orderBy orderFields PostgreSQL} LIMIT 1"
+                [ "@path", Sql.string jsonPath ]
+                fromData<'TDoc>
+                sqlProps
+
+        /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the
+        /// document; returns null if not found
+        let FirstByJsonPathOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+                tableName, jsonPath, orderFields, sqlProps) =
+            Custom.Single<'TDoc>(
+                $"{Query.byPathMatch (Query.find tableName)}{Query.orderBy orderFields PostgreSQL} LIMIT 1",
+                [ "@path", Sql.string jsonPath ],
+                fromData<'TDoc>,
+                sqlProps)
+
     /// Commands to update documents
     [<RequireQualifiedAccess>]
     module Update =
@@ -572,12 +690,6 @@ module WithProps =
                 (addFieldParams fields [ jsonParam "@data" patch ])
                 sqlProps
         
-        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let byField tableName field (patch: 'TPatch) sqlProps =
-            byFields tableName Any [ field ] patch sqlProps
-        
         /// Patch documents using a JSON containment query in the WHERE clause (@>)
         [<CompiledName "ByContains">]
         let byContains tableName (criteria: 'TContains) (patch: 'TPatch) sqlProps =
@@ -612,12 +724,6 @@ module WithProps =
                 (addFieldParams fields [ fieldNameParams fieldNames ])
                 sqlProps
         
-        /// Remove fields from documents via a comparison on a JSON field in the document
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use byFields instead; will be removed in v4">]
-        let byField tableName field fieldNames sqlProps =
-            byFields tableName Any [ field ] fieldNames sqlProps
-        
         /// Remove fields from documents via a JSON containment query (@>)
         [<CompiledName "ByContains">]
         let byContains tableName (criteria: 'TContains) fieldNames sqlProps =
@@ -649,12 +755,6 @@ module WithProps =
             Custom.nonQuery
                 (Query.byFields (Query.delete tableName) howMatched fields) (addFieldParams fields []) sqlProps
         
-        /// Delete documents by matching a JSON field comparison query (->> =)
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let byField tableName field sqlProps =
-            byFields tableName Any [ field ] sqlProps
-        
         /// Delete documents by matching a JSON contains query (@>)
         [<CompiledName "ByContains">]
         let byContains tableName (criteria: 'TCriteria) sqlProps =
@@ -685,7 +785,8 @@ module Custom =
         WithProps.Custom.single<'TDoc> query parameters mapFunc (fromDataSource ())
 
     /// Execute a query that returns one or no results; returns null if not found
-    let Single<'TDoc when 'TDoc: null>(query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
+    let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            query, parameters, mapFunc: System.Func<RowReader, 'TDoc>) =
         WithProps.Custom.Single<'TDoc>(query, parameters, mapFunc, fromDataSource ())
 
     /// Execute a query that returns no results
@@ -752,12 +853,6 @@ module Count =
     let byFields tableName howMatched fields =
         WithProps.Count.byFields tableName howMatched fields (fromDataSource ())
     
-    /// Count matching documents using a JSON field comparison query (->> =)
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]
-    
     /// Count matching documents using a JSON containment query (@>)
     [<CompiledName "ByContains">]
     let byContains tableName criteria =
@@ -783,12 +878,6 @@ module Exists =
     let byFields tableName howMatched fields =
         WithProps.Exists.byFields tableName howMatched fields (fromDataSource ())
     
-    /// Determine if documents exist using a JSON field comparison query (->> =)
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]
-    
     /// Determine if documents exist using a JSON containment query (@>)
     [<CompiledName "ByContains">]
     let byContains tableName criteria =
@@ -813,13 +902,22 @@ module Find =
     let All<'TDoc> tableName =
         WithProps.Find.All<'TDoc>(tableName, fromDataSource ())
 
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    [<CompiledName "FSharpAllOrdered">]
+    let allOrdered<'TDoc> tableName orderFields =
+        WithProps.Find.allOrdered<'TDoc> tableName orderFields (fromDataSource ())
+
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    let AllOrdered<'TDoc> tableName orderFields =
+        WithProps.Find.AllOrdered<'TDoc>(tableName, orderFields, fromDataSource ())
+
     /// Retrieve a document by its ID; returns None if not found
     [<CompiledName "FSharpById">]
     let byId<'TKey, 'TDoc> tableName docId =
         WithProps.Find.byId<'TKey, 'TDoc> tableName docId (fromDataSource ())
 
     /// Retrieve a document by its ID; returns null if not found
-    let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId: 'TKey) =
+    let ById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, docId: 'TKey) =
         WithProps.Find.ById<'TKey, 'TDoc>(tableName, docId, fromDataSource ())
 
     /// Retrieve documents matching a JSON field comparison query (->> =)
@@ -827,20 +925,18 @@ module Find =
     let byFields<'TDoc> tableName howMatched fields =
         WithProps.Find.byFields<'TDoc> tableName howMatched fields (fromDataSource ())
     
-    /// Retrieve documents matching a JSON field comparison query (->> =)
-    [<CompiledName "FSharpByField">]
-    [<System.Obsolete "Use byFields instead; will be removed in v4">]
-    let byField<'TDoc> tableName field =
-        byFields<'TDoc> tableName Any [ field ]
-    
     /// Retrieve documents matching a JSON field comparison query (->> =)
     let ByFields<'TDoc>(tableName, howMatched, fields) =
         WithProps.Find.ByFields<'TDoc>(tableName, howMatched, fields, fromDataSource ())
     
-    /// Retrieve documents matching a JSON field comparison query (->> =)
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let ByField<'TDoc>(tableName, field) =
-        ByFields<'TDoc>(tableName, Any, Seq.singleton field)
+    /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the document
+    [<CompiledName "FSharpByFieldsOrdered">]
+    let byFieldsOrdered<'TDoc> tableName howMatched queryField orderFields =
+        WithProps.Find.byFieldsOrdered<'TDoc> tableName howMatched queryField orderFields (fromDataSource ())
+    
+    /// Retrieve documents matching a JSON field comparison query (->> =) ordered by the given fields in the document
+    let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields) =
+        WithProps.Find.ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, fromDataSource ())
     
     /// Retrieve documents matching a JSON containment query (@>)
     [<CompiledName "FSharpByContains">]
@@ -851,6 +947,15 @@ module Find =
     let ByContains<'TDoc>(tableName, criteria: obj) =
         WithProps.Find.ByContains<'TDoc>(tableName, criteria, fromDataSource ())
 
+    /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+    [<CompiledName "FSharpByContainsOrdered">]
+    let byContainsOrdered<'TDoc> tableName (criteria: obj) orderFields =
+        WithProps.Find.byContainsOrdered<'TDoc> tableName criteria orderFields (fromDataSource ())
+
+    /// Retrieve documents matching a JSON containment query (@>) ordered by the given fields in the document
+    let ByContainsOrdered<'TDoc>(tableName, criteria: obj, orderFields) =
+        WithProps.Find.ByContainsOrdered<'TDoc>(tableName, criteria, orderFields, fromDataSource ())
+
     /// Retrieve documents matching a JSON Path match query (@?)
     [<CompiledName "FSharpByJsonPath">]
     let byJsonPath<'TDoc> tableName jsonPath =
@@ -860,25 +965,35 @@ module Find =
     let ByJsonPath<'TDoc>(tableName, jsonPath) =
         WithProps.Find.ByJsonPath<'TDoc>(tableName, jsonPath, fromDataSource ())
     
+    /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
+    [<CompiledName "FSharpByJsonPathOrdered">]
+    let byJsonPathOrdered<'TDoc> tableName jsonPath orderFields =
+        WithProps.Find.byJsonPathOrdered<'TDoc> tableName jsonPath orderFields (fromDataSource ())
+    
+    /// Retrieve documents matching a JSON Path match query (@?) ordered by the given fields in the document
+    let ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields) =
+        WithProps.Find.ByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, fromDataSource ())
+    
     /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
     [<CompiledName "FSharpFirstByFields">]
     let firstByFields<'TDoc> tableName howMatched fields =
         WithProps.Find.firstByFields<'TDoc> tableName howMatched fields (fromDataSource ())
     
-    /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
-    [<CompiledName "FSharpFirstByField">]
-    [<System.Obsolete "Use firstByFields instead; will be removed in v4">]
-    let firstByField<'TDoc> tableName field =
-        firstByFields<'TDoc> tableName Any [ field ]
-    
     /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
-    let FirstByFields<'TDoc when 'TDoc: null>(tableName, howMatched, fields) =
+    let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields) =
         WithProps.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, fromDataSource ())
     
-    /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
-    [<System.Obsolete "Use FirstByFields instead; will be removed in v4">]
-    let FirstByField<'TDoc when 'TDoc: null>(tableName, field) =
-        FirstByFields<'TDoc>(tableName, Any, Seq.singleton field)
+    /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in the
+    /// document; returns None if not found
+    [<CompiledName "FSharpFirstByFieldsOrdered">]
+    let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+        WithProps.Find.firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields (fromDataSource ())
+    
+    /// Retrieve the first document matching a JSON field comparison query (->> =) ordered by the given fields in the
+    /// document; returns null if not found
+    let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            tableName, howMatched, queryFields, orderFields) =
+        WithProps.Find.FirstByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, fromDataSource ())
     
     /// Retrieve the first document matching a JSON containment query (@>); returns None if not found
     [<CompiledName "FSharpFirstByContains">]
@@ -886,18 +1001,40 @@ module Find =
         WithProps.Find.firstByContains<'TDoc> tableName criteria (fromDataSource ())
 
     /// Retrieve the first document matching a JSON containment query (@>); returns null if not found
-    let FirstByContains<'TDoc when 'TDoc: null>(tableName, criteria: obj) =
+    let FirstByContains<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, criteria: obj) =
         WithProps.Find.FirstByContains<'TDoc>(tableName, criteria, fromDataSource ())
 
+    /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the document;
+    /// returns None if not found
+    [<CompiledName "FSharpFirstByContainsOrdered">]
+    let firstByContainsOrdered<'TDoc> tableName (criteria: obj) orderFields =
+        WithProps.Find.firstByContainsOrdered<'TDoc> tableName criteria orderFields (fromDataSource ())
+
+    /// Retrieve the first document matching a JSON containment query (@>) ordered by the given fields in the document;
+    /// returns null if not found
+    let FirstByContainsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, criteria: obj, orderFields) =
+        WithProps.Find.FirstByContainsOrdered<'TDoc>(tableName, criteria, orderFields, fromDataSource ())
+
     /// Retrieve the first document matching a JSON Path match query (@?); returns None if not found
     [<CompiledName "FSharpFirstByJsonPath">]
     let firstByJsonPath<'TDoc> tableName jsonPath =
         WithProps.Find.firstByJsonPath<'TDoc> tableName jsonPath (fromDataSource ())
 
     /// Retrieve the first document matching a JSON Path match query (@?); returns null if not found
-    let FirstByJsonPath<'TDoc when 'TDoc: null>(tableName, jsonPath) =
+    let FirstByJsonPath<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, jsonPath) =
         WithProps.Find.FirstByJsonPath<'TDoc>(tableName, jsonPath, fromDataSource ())
 
+    /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the document;
+    /// returns None if not found
+    [<CompiledName "FSharpFirstByJsonPathOrdered">]
+    let firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields =
+        WithProps.Find.firstByJsonPathOrdered<'TDoc> tableName jsonPath orderFields (fromDataSource ())
+
+    /// Retrieve the first document matching a JSON Path match query (@?) ordered by the given fields in the document;
+    /// returns null if not found
+    let FirstByJsonPathOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, jsonPath, orderFields) =
+        WithProps.Find.FirstByJsonPathOrdered<'TDoc>(tableName, jsonPath, orderFields, fromDataSource ())
+
 
 /// Commands to update documents
 [<RequireQualifiedAccess>]
@@ -932,12 +1069,6 @@ module Patch =
     let byFields tableName howMatched fields (patch: 'TPatch) =
         WithProps.Patch.byFields tableName howMatched fields patch (fromDataSource ())
     
-    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field (patch: 'TPatch) =
-        byFields tableName Any [ field ] patch
-    
     /// Patch documents using a JSON containment query in the WHERE clause (@>)
     [<CompiledName "ByContains">]
     let byContains tableName (criteria: 'TCriteria) (patch: 'TPatch) =
@@ -963,12 +1094,6 @@ module RemoveFields =
     let byFields tableName howMatched fields fieldNames =
         WithProps.RemoveFields.byFields tableName howMatched fields fieldNames (fromDataSource ())
     
-    /// Remove fields from documents via a comparison on a JSON field in the document
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use byFields instead; will be removed in v4">]
-    let byField tableName field fieldNames =
-        byFields tableName Any [ field ] fieldNames
-    
     /// Remove fields from documents via a JSON containment query (@>)
     [<CompiledName "ByContains">]
     let byContains tableName (criteria: 'TContains) fieldNames =
@@ -994,12 +1119,6 @@ module Delete =
     let byFields tableName howMatched fields =
         WithProps.Delete.byFields tableName howMatched fields (fromDataSource ())
     
-    /// Delete documents by matching a JSON field comparison query (->> =)
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]
-    
     /// Delete documents by matching a JSON containment query (@>)
     [<CompiledName "ByContains">]
     let byContains tableName (criteria: 'TContains) =

src/Postgres/README.md

@@ -5,11 +5,16 @@ This package provides a lightweight document library backed by [PostgreSQL](http
 ## Features
 
 - Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Automatically generate IDs for documents (numeric IDs, GUIDs, or random strings)
 - Address documents via ID, via comparison on any field, via equality on any property (using JSON containment, on a likely indexed field), or via condition on any property (using JSON Path queries)
 - Access documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
 - Use `Task`-based async for all data access functions
 - Use building blocks for more complex queries
 
+## Upgrading from v3
+
+There is a breaking API change for `ByField` (C#) / `byField` (F#), along with a compatibility namespace that can mitigate the impact of these changes. See [the migration guide](https://bitbadger.solutions/open-source/relational-documents/upgrade-from-v3-to-v4.html) for full details.
+
 ## Getting Started
 
 Once the package is installed, the library needs a data source. Construct an `NpgsqlDataSource` instance, and provide it to the library:
@@ -66,7 +71,7 @@ var customer = await Find.ById<string, Customer>("customer", "123");
 // Find.byId type signature is string -> 'TKey -> Task<'TDoc option>
 let! customer = Find.byId<string, Customer> "customer" "123"
 ```
-_(keys are treated as strings in the database)_
+_(keys are treated as strings or numbers depending on their defintion; however, they are indexed as strings)_
 
 Count customers in Atlanta (using JSON containment):
 

src/Sqlite/BitBadger.Documents.Sqlite.fsproj

@@ -8,13 +8,14 @@
   <ItemGroup>
     <Compile Include="Library.fs" />
     <Compile Include="Extensions.fs" />
+    <Compile Include="Compat.fs" />
     <None Include="README.md" Pack="true" PackagePath="\" />
     <None Include="..\icon.png" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>
-    <PackageReference Include="Microsoft.Data.Sqlite" Version="8.0.6" />
-    <PackageReference Update="FSharp.Core" Version="8.0.300" />
+    <PackageReference Include="Microsoft.Data.Sqlite" Version="9.0.0" />
+    <PackageReference Update="FSharp.Core" Version="9.0.100" />
   </ItemGroup>
 
   <ItemGroup>

src/Sqlite/Compat.fs

@@ -0,0 +1,269 @@
+namespace BitBadger.Documents.Sqlite.Compat
+
+open BitBadger.Documents
+open BitBadger.Documents.Sqlite
+
+[<AutoOpen>]
+module Parameters =
+    
+    /// Create a JSON field parameter
+    [<CompiledName "AddField">]
+    [<System.Obsolete "Use addFieldParams (F#) / AddFields (C#) instead ~ will be removed in v4.1">]
+    let addFieldParam name field parameters =
+        addFieldParams [ { field with ParameterName = Some name } ] parameters
+
+    /// Append JSON field name parameters for the given field names to the given parameters
+    [<CompiledName "FieldName">]
+    [<System.Obsolete "Use fieldNameParams (F#) / FieldNames (C#) instead ~ will be removed in v4.1">]
+    let fieldNameParam fieldNames =
+        fieldNameParams fieldNames
+
+
+[<RequireQualifiedAccess>]
+module Query =
+    
+    /// Create a WHERE clause fragment to implement a comparison on a field in a JSON document
+    [<CompiledName "WhereByField">]
+    [<System.Obsolete "Use WhereByFields instead ~ will be removed in v4.1">]
+    let whereByField field paramName =
+        Query.whereByFields Any [ { field with ParameterName = Some paramName } ]
+
+
+module WithConn =
+    
+    [<RequireQualifiedAccess>]
+    module Count =
+        
+        /// Count matching documents using a JSON field comparison (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field conn =
+            WithConn.Count.byFields tableName Any [ field ] conn
+    
+    [<RequireQualifiedAccess>]
+    module Exists =
+        
+        /// Determine if a document exists using a JSON field comparison (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field conn =
+            WithConn.Exists.byFields tableName Any [ field ] conn
+    
+    [<RequireQualifiedAccess>]
+    module Find =
+        
+        /// Retrieve documents matching a JSON field comparison (->> =)
+        [<CompiledName "FSharpByField">]
+        [<System.Obsolete "Use byFields instead ~ will be removed in v4.1">]
+        let byField<'TDoc> tableName field conn =
+            WithConn.Find.byFields<'TDoc> tableName Any [ field ] conn
+        
+        /// Retrieve documents matching a JSON field comparison (->> =)
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let ByField<'TDoc>(tableName, field, conn) =
+            WithConn.Find.ByFields<'TDoc>(tableName, Any, Seq.singleton field, conn)
+        
+        /// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
+        [<CompiledName "FSharpFirstByField">]
+        [<System.Obsolete "Use firstByFields instead ~ will be removed in v4.1">]
+        let firstByField<'TDoc> tableName field conn =
+            WithConn.Find.firstByFields<'TDoc> tableName Any [ field ] conn
+        
+        /// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
+        [<System.Obsolete "Use FirstByFields instead ~ will be removed in v4.1">]
+        let FirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, field, conn) =
+            WithConn.Find.FirstByFields<'TDoc>(tableName, Any, Seq.singleton field, conn)
+    
+    [<RequireQualifiedAccess>]
+    module Patch =
+        
+        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field (patch: 'TPatch) conn =
+            WithConn.Patch.byFields tableName Any [ field ] patch conn
+    
+    [<RequireQualifiedAccess>]
+    module RemoveFields =
+        
+        /// Remove fields from documents via a comparison on a JSON field in the document
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field fieldNames conn =
+            WithConn.RemoveFields.byFields tableName Any [ field ] fieldNames conn
+    
+    [<RequireQualifiedAccess>]
+    module Delete =
+        
+        /// Delete documents by matching a JSON field comparison query (->> =)
+        [<CompiledName "ByField">]
+        [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+        let byField tableName field conn =
+            WithConn.Delete.byFields tableName Any [ field ] conn
+
+
+[<RequireQualifiedAccess>]
+module Count =
+    
+    /// Count matching documents using a JSON field comparison (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Count.byFields tableName Any [ field ]
+
+
+[<RequireQualifiedAccess>]
+module Exists =
+    
+    /// Determine if a document exists using a JSON field comparison (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Exists.byFields tableName Any [ field ]
+
+
+[<RequireQualifiedAccess>]
+module Find =
+    
+    /// Retrieve documents matching a JSON field comparison (->> =)
+    [<CompiledName "FSharpByField">]
+    [<System.Obsolete "Use byFields instead ~ will be removed in v4.1">]
+    let byField<'TDoc> tableName field =
+        Find.byFields<'TDoc> tableName Any [ field ]
+    
+    /// Retrieve documents matching a JSON field comparison (->> =)
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let ByField<'TDoc>(tableName, field) =
+        Find.ByFields<'TDoc>(tableName, Any, Seq.singleton field)
+    
+    /// Retrieve the first document matching a JSON field comparison (->> =); returns None if not found
+    [<CompiledName "FSharpFirstByField">]
+    [<System.Obsolete "Use firstByFields instead ~ will be removed in v4.1">]
+    let firstByField<'TDoc> tableName field =
+        Find.firstByFields<'TDoc> tableName Any [ field ]
+    
+    /// Retrieve the first document matching a JSON field comparison (->> =); returns null if not found
+    [<System.Obsolete "Use FirstByFields instead ~ will be removed in v4.1">]
+    let FirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, field) =
+        Find.FirstByFields<'TDoc>(tableName, Any, Seq.singleton field)
+
+
+[<RequireQualifiedAccess>]
+module Patch =
+    
+    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field (patch: 'TPatch) =
+        Patch.byFields tableName Any [ field ] patch
+
+
+[<RequireQualifiedAccess>]
+module RemoveFields =
+    
+    /// Remove fields from documents via a comparison on a JSON field in the document
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field fieldNames =
+        RemoveFields.byFields tableName Any [ field ] fieldNames
+
+
+[<RequireQualifiedAccess>]
+module Delete =
+    
+    /// Delete documents by matching a JSON field comparison query (->> =)
+    [<CompiledName "ByField">]
+    [<System.Obsolete "Use ByFields instead ~ will be removed in v4.1">]
+    let byField tableName field =
+        Delete.byFields tableName Any [ field ]
+
+
+open Microsoft.Data.Sqlite
+
+/// F# Extensions for the NpgsqlConnection type
+[<AutoOpen>]
+module Extensions =
+    
+    type SqliteConnection with
+        
+        /// Count matching documents using a JSON field comparison query (->> =)
+        [<System.Obsolete "Use countByFields instead ~ will be removed in v4.1">]
+        member conn.countByField tableName field =
+            conn.countByFields tableName Any [ field ]
+        
+        /// Determine if documents exist using a JSON field comparison query (->> =)
+        [<System.Obsolete "Use existsByFields instead ~ will be removed in v4.1">]
+        member conn.existsByField tableName field =
+            conn.existsByFields tableName Any [ field ]
+        
+        /// Retrieve documents matching a JSON field comparison query (->> =)
+        [<System.Obsolete "Use findByFields instead ~ will be removed in v4.1">]
+        member conn.findByField<'TDoc> tableName field =
+            conn.findByFields<'TDoc> tableName Any [ field ]
+        
+        /// Retrieve the first document matching a JSON field comparison query (->> =); returns None if not found
+        [<System.Obsolete "Use findFirstByFields instead ~ will be removed in v4.1">]
+        member conn.findFirstByField<'TDoc> tableName field =
+            conn.findFirstByFields<'TDoc> tableName Any [ field ]
+        
+        /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+        [<System.Obsolete "Use patchByFields instead ~ will be removed in v4.1">]
+        member conn.patchByField tableName field (patch: 'TPatch) =
+            conn.patchByFields tableName Any [ field ] patch
+        
+        /// Remove fields from documents via a comparison on a JSON field in the document
+        [<System.Obsolete "Use removeFieldsByFields instead ~ will be removed in v4.1">]
+        member conn.removeFieldsByField tableName field fieldNames =
+            conn.removeFieldsByFields tableName Any [ field ] fieldNames
+        
+        /// Delete documents by matching a JSON field comparison query (->> =)
+        [<System.Obsolete "Use deleteByFields instead ~ will be removed in v4.1">]
+        member conn.deleteByField tableName field =
+            conn.deleteByFields tableName Any [ field ]
+
+
+open System.Runtime.CompilerServices
+
+type SqliteConnectionCSharpCompatExtensions =
+    
+    /// Count matching documents using a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use CountByFields instead ~ will be removed in v4.1">]
+    static member inline CountByField(conn, tableName, field) =
+        WithConn.Count.byFields tableName Any [ field ] conn
+    
+    /// Determine if documents exist using a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use ExistsByFields instead ~ will be removed in v4.1">]
+    static member inline ExistsByField(conn, tableName, field) =
+        WithConn.Exists.byFields tableName Any [ field ] conn
+    
+    /// Retrieve documents matching a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use FindByFields instead ~ will be removed in v4.1">]
+    static member inline FindByField<'TDoc>(conn, tableName, field) =
+        WithConn.Find.ByFields<'TDoc>(tableName, Any, [ field ], conn)
+    
+    /// Retrieve the first document matching a JSON field comparison query (->> =); returns null if not found
+    [<Extension>]
+    [<System.Obsolete "Use FindFirstByFields instead ~ will be removed in v4.1">]
+    static member inline FindFirstByField<'TDoc when 'TDoc: null and 'TDoc: not struct>(conn, tableName, field) =
+        WithConn.Find.FirstByFields<'TDoc>(tableName, Any, [ field ], conn)
+    
+    /// Patch documents using a JSON field comparison query in the WHERE clause (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use PatchByFields instead ~ will be removed in v4.1">]
+    static member inline PatchByField(conn, tableName, field, patch: 'TPatch) =
+        WithConn.Patch.byFields tableName Any [ field ] patch conn
+    
+    /// Remove fields from documents via a comparison on a JSON field in the document
+    [<Extension>]
+    [<System.Obsolete "Use RemoveFieldsByFields instead ~ will be removed in v4.1">]
+    static member inline RemoveFieldsByField(conn, tableName, field, fieldNames) =
+        WithConn.RemoveFields.byFields tableName Any [ field ] fieldNames conn
+    
+    /// Delete documents by matching a JSON field comparison query (->> =)
+    [<Extension>]
+    [<System.Obsolete "Use DeleteByFields instead ~ will be removed in v4.1">]
+    static member inline DeleteByField(conn, tableName, field) =
+        WithConn.Delete.byFields tableName Any [ field ] conn

src/Sqlite/Extensions.fs

@@ -1,6 +1,5 @@
 namespace BitBadger.Documents.Sqlite
 
-open BitBadger.Documents
 open Microsoft.Data.Sqlite
 
 /// F# extensions for the SqliteConnection type
@@ -35,11 +34,11 @@ module Extensions =
         
         /// Insert a new document
         member conn.insert<'TDoc> tableName (document: 'TDoc) =
-            WithConn.insert<'TDoc> tableName document conn
+            WithConn.Document.insert<'TDoc> tableName document conn
 
         /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
         member conn.save<'TDoc> tableName (document: 'TDoc) =
-            WithConn.save tableName document conn
+            WithConn.Document.save tableName document conn
 
         /// Count all documents in a table
         member conn.countAll tableName =
@@ -49,11 +48,6 @@ module Extensions =
         member conn.countByFields tableName howMatched fields =
             WithConn.Count.byFields tableName howMatched fields conn
         
-        /// Count matching documents using a comparison on a JSON field
-        [<System.Obsolete "Use countByFields instead; will be removed in v4">]
-        member conn.countByField tableName field =
-            conn.countByFields tableName Any [ field ]
-        
         /// Determine if a document exists for the given ID
         member conn.existsById tableName (docId: 'TKey) =
             WithConn.Exists.byId tableName docId conn
@@ -62,15 +56,14 @@ module Extensions =
         member conn.existsByFields tableName howMatched fields =
             WithConn.Exists.byFields tableName howMatched fields conn
         
-        /// Determine if a document exists using a comparison on a JSON field
-        [<System.Obsolete "Use existsByFields instead; will be removed in v4">]
-        member conn.existsByField tableName field =
-            conn.existsByFields tableName Any [ field ]
-
         /// Retrieve all documents in the given table
         member conn.findAll<'TDoc> tableName =
             WithConn.Find.all<'TDoc> tableName conn
 
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        member conn.findAllOrdered<'TDoc> tableName orderFields =
+            WithConn.Find.allOrdered<'TDoc> tableName orderFields conn
+
         /// Retrieve a document by its ID
         member conn.findById<'TKey, 'TDoc> tableName (docId: 'TKey) =
             WithConn.Find.byId<'TKey, 'TDoc> tableName docId conn
@@ -79,19 +72,18 @@ module Extensions =
         member conn.findByFields<'TDoc> tableName howMatched fields =
             WithConn.Find.byFields<'TDoc> tableName howMatched fields conn
         
-        /// Retrieve documents via a comparison on a JSON field
-        [<System.Obsolete "Use findByFields instead; will be removed in v4">]
-        member conn.findByField<'TDoc> tableName field =
-            conn.findByFields<'TDoc> tableName Any [ field ]
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
+        member conn.findByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+            WithConn.Find.byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn
         
         /// Retrieve documents via a comparison on JSON fields, returning only the first result
         member conn.findFirstByFields<'TDoc> tableName howMatched fields =
             WithConn.Find.firstByFields<'TDoc> tableName howMatched fields conn
         
-        /// Retrieve documents via a comparison on a JSON field, returning only the first result
-        [<System.Obsolete "Use findFirstByFields instead; will be removed in v4">]
-        member conn.findFirstByField<'TDoc> tableName field =
-            conn.findFirstByFields<'TDoc> tableName Any [ field ]
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning
+        /// only the first result
+        member conn.findFirstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+            WithConn.Find.firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn
         
         /// Update an entire document by its ID
         member conn.updateById tableName (docId: 'TKey) (document: 'TDoc) =
@@ -109,11 +101,6 @@ module Extensions =
         member conn.patchByFields tableName howMatched fields (patch: 'TPatch) =
             WithConn.Patch.byFields tableName howMatched fields patch conn
         
-        /// Patch documents using a comparison on a JSON field
-        [<System.Obsolete "Use patchByFields instead; will be removed in v4">]
-        member conn.patchByField tableName field (patch: 'TPatch) =
-            conn.patchByFields tableName Any [ field ] patch
-
         /// Remove fields from a document by the document's ID
         member conn.removeFieldsById tableName (docId: 'TKey) fieldNames =
             WithConn.RemoveFields.byId tableName docId fieldNames conn
@@ -122,11 +109,6 @@ module Extensions =
         member conn.removeFieldsByFields tableName howMatched fields fieldNames =
             WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn
         
-        /// Remove a field from a document via a comparison on a JSON field in the document
-        [<System.Obsolete "Use removeFieldsByFields instead; will be removed in v4">]
-        member conn.removeFieldsByField tableName field fieldNames =
-            conn.removeFieldsByFields tableName Any [ field ] fieldNames
-        
         /// Delete a document by its ID
         member conn.deleteById tableName (docId: 'TKey) =
             WithConn.Delete.byId tableName docId conn
@@ -135,11 +117,6 @@ module Extensions =
         member conn.deleteByFields tableName howMatched fields =
             WithConn.Delete.byFields tableName howMatched fields conn
 
-        /// Delete documents by matching a comparison on a JSON field
-        [<System.Obsolete "Use deleteByFields instead; will be removed in v4">]
-        member conn.deleteByField tableName field =
-            conn.deleteByFields tableName Any [ field ]
-
 
 open System.Runtime.CompilerServices
 
@@ -153,7 +130,7 @@ type SqliteConnectionCSharpExtensions =
 
     /// Execute a query that returns one or no results
     [<Extension>]
-    static member inline CustomSingle<'TDoc when 'TDoc: null>(
+    static member inline CustomSingle<'TDoc when 'TDoc: null and 'TDoc: not struct>(
             conn, query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>) =
         WithConn.Custom.Single<'TDoc>(query, parameters, mapFunc, conn)
     
@@ -181,12 +158,12 @@ type SqliteConnectionCSharpExtensions =
     /// Insert a new document
     [<Extension>]
     static member inline Insert<'TDoc>(conn, tableName, document: 'TDoc) =
-        WithConn.insert<'TDoc> tableName document conn
+        WithConn.Document.insert<'TDoc> tableName document conn
 
     /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
     [<Extension>]
     static member inline Save<'TDoc>(conn, tableName, document: 'TDoc) =
-        WithConn.save<'TDoc> tableName document conn
+        WithConn.Document.save<'TDoc> tableName document conn
 
     /// Count all documents in a table
     [<Extension>]
@@ -198,12 +175,6 @@ type SqliteConnectionCSharpExtensions =
     static member inline CountByFields(conn, tableName, howMatched, fields) =
         WithConn.Count.byFields tableName howMatched fields conn
     
-    /// Count matching documents using a comparison on a JSON field
-    [<Extension>]
-    [<System.Obsolete "Use CountByFields instead; will be removed in v4">]
-    static member inline CountByField(conn, tableName, field) =
-        conn.CountByFields(tableName, Any, [ field ])
-
     /// Determine if a document exists for the given ID
     [<Extension>]
     static member inline ExistsById<'TKey>(conn, tableName, docId: 'TKey) =
@@ -214,20 +185,19 @@ type SqliteConnectionCSharpExtensions =
     static member inline ExistsByFields(conn, tableName, howMatched, fields) =
         WithConn.Exists.byFields tableName howMatched fields conn
     
-    /// Determine if a document exists using a comparison on a JSON field
-    [<Extension>]
-    [<System.Obsolete "Use ExistsByFields instead; will be removed in v4">]
-    static member inline ExistsByField(conn, tableName, field) =
-        conn.ExistsByFields(tableName, Any, [ field ])
-    
     /// Retrieve all documents in the given table
     [<Extension>]
     static member inline FindAll<'TDoc>(conn, tableName) =
         WithConn.Find.All<'TDoc>(tableName, conn)
 
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    [<Extension>]
+    static member inline FindAllOrdered<'TDoc>(conn, tableName, orderFields) =
+        WithConn.Find.AllOrdered<'TDoc>(tableName, orderFields, conn)
+
     /// Retrieve a document by its ID
     [<Extension>]
-    static member inline FindById<'TKey, 'TDoc when 'TDoc: null>(conn, tableName, docId: 'TKey) =
+    static member inline FindById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(conn, tableName, docId: 'TKey) =
         WithConn.Find.ById<'TKey, 'TDoc>(tableName, docId, conn)
 
     /// Retrieve documents via a comparison on JSON fields
@@ -235,22 +205,23 @@ type SqliteConnectionCSharpExtensions =
     static member inline FindByFields<'TDoc>(conn, tableName, howMatched, fields) =
         WithConn.Find.ByFields<'TDoc>(tableName, howMatched, fields, conn)
     
-    /// Retrieve documents via a comparison on a JSON field
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
     [<Extension>]
-    [<System.Obsolete "Use FindByFields instead; will be removed in v4">]
-    static member inline FindByField<'TDoc>(conn, tableName, field) =
-        conn.FindByFields<'TDoc>(tableName, Any, [ field ])
+    static member inline FindByFieldsOrdered<'TDoc>(conn, tableName, howMatched, queryFields, orderFields) =
+        WithConn.Find.ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, conn)
     
     /// Retrieve documents via a comparison on JSON fields, returning only the first result
     [<Extension>]
-    static member inline FindFirstByFields<'TDoc when 'TDoc: null>(conn, tableName, howMatched, fields) =
+    static member inline FindFirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, howMatched, fields) =
         WithConn.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, conn)
     
-    /// Retrieve documents via a comparison on a JSON field, returning only the first result
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning only
+    /// the first result
     [<Extension>]
-    [<System.Obsolete "Use FindFirstByFields instead; will be removed in v4">]
-    static member inline FindFirstByField<'TDoc when 'TDoc: null>(conn, tableName, field) =
-        conn.FindFirstByFields<'TDoc>(tableName, Any, [ field ])
+    static member inline FindFirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            conn, tableName, howMatched, queryFields, orderFields) =
+        WithConn.Find.FirstByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, conn)
     
     /// Update an entire document by its ID
     [<Extension>]
@@ -272,12 +243,6 @@ type SqliteConnectionCSharpExtensions =
     static member inline PatchByFields<'TPatch>(conn, tableName, howMatched, fields, patch: 'TPatch) =
         WithConn.Patch.byFields tableName howMatched fields patch conn
     
-    /// Patch documents using a comparison on a JSON field
-    [<Extension>]
-    [<System.Obsolete "Use PatchByFields instead; will be removed in v4">]
-    static member inline PatchByField<'TPatch>(conn, tableName, field, patch: 'TPatch) =
-        conn.PatchByFields(tableName, Any, [ field ], patch)
-
     /// Remove fields from a document by the document's ID
     [<Extension>]
     static member inline RemoveFieldsById<'TKey>(conn, tableName, docId: 'TKey, fieldNames) =
@@ -288,12 +253,6 @@ type SqliteConnectionCSharpExtensions =
     static member inline RemoveFieldsByFields(conn, tableName, howMatched, fields, fieldNames) =
         WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn
     
-    /// Remove fields from documents via a comparison on a JSON field in the document
-    [<Extension>]
-    [<System.Obsolete "Use RemoveFieldsByFields instead; will be removed in v4">]
-    static member inline RemoveFieldsByField(conn, tableName, field, fieldNames) =
-        conn.RemoveFieldsByFields(tableName, Any, [ field ], fieldNames)
-    
     /// Delete a document by its ID
     [<Extension>]
     static member inline DeleteById<'TKey>(conn, tableName, docId: 'TKey) =
@@ -303,9 +262,3 @@ type SqliteConnectionCSharpExtensions =
     [<Extension>]
     static member inline DeleteByFields(conn, tableName, howMatched, fields) =
         WithConn.Delete.byFields tableName howMatched fields conn
-    
-    /// Delete documents by matching a comparison on a JSON field
-    [<Extension>]
-    [<System.Obsolete "Use DeleteByFields instead; will be removed in v4">]
-    static member inline DeleteByField(conn, tableName, field) =
-        conn.DeleteByFields(tableName, Any, [ field ])

src/Sqlite/Library.fs

@@ -37,18 +37,26 @@ module Query =
         let name = ParameterName()
         fields
         |> Seq.map (fun it ->
-            match it.Op with
-            | EX | NEX -> $"{it.Path SQLite} {it.Op}"
-            | BT ->
+            match it.Comparison with
+            | Exists | NotExists -> $"{it.Path SQLite AsSql} {it.Comparison.OpSql}"
+            | Between _ ->
                 let p = name.Derive it.ParameterName
-                $"{it.Path SQLite} {it.Op} {p}min AND {p}max"
-            | _ -> $"{it.Path SQLite} {it.Op} {name.Derive it.ParameterName}")
+                $"{it.Path SQLite AsSql} {it.Comparison.OpSql} {p}min AND {p}max"
+            | In values ->
+                let p          = name.Derive it.ParameterName
+                let paramNames = values |> Seq.mapi (fun idx _ -> $"{p}_{idx}") |> String.concat ", "
+                $"{it.Path SQLite AsSql} {it.Comparison.OpSql} ({paramNames})"
+            | InArray (table, values) ->
+                let p          = name.Derive it.ParameterName
+                let paramNames = values |> Seq.mapi (fun idx _ -> $"{p}_{idx}") |> String.concat ", "
+                $"EXISTS (SELECT 1 FROM json_each({table}.data, '$.{it.Name}') WHERE value IN ({paramNames}))"
+            | _ -> $"{it.Path SQLite AsSql} {it.Comparison.OpSql} {name.Derive it.ParameterName}")
         |> String.concat $" {howMatched} "
 
     /// Create a WHERE clause fragment to implement an ID-based query
     [<CompiledName "WhereById">]
     let whereById paramName =
-        whereByFields Any [ { Field.EQ (Configuration.idField ()) 0 with ParameterName = Some paramName } ]
+        whereByFields Any [ { Field.Equal (Configuration.idField ()) 0 with ParameterName = Some paramName } ]
     
     /// Create an UPDATE statement to patch documents
     [<CompiledName "Patch">]
@@ -66,7 +74,7 @@ module Query =
     let byId<'TKey> statement (docId: 'TKey) =
         Query.statementWhere
             statement
-            (whereByFields Any [ { Field.EQ (Configuration.idField ()) docId with ParameterName = Some "@id" } ])
+            (whereByFields Any [ { Field.Equal (Configuration.idField ()) docId with ParameterName = Some "@id" } ])
     
     /// Create a query on JSON fields
     [<CompiledName "ByFields">]
@@ -103,14 +111,16 @@ module Parameters =
         fields
         |> Seq.map (fun it ->
             seq {
-                match it.Op with
-                | EX | NEX -> ()
-                | BT ->
+                match it.Comparison with
+                | Exists | NotExists -> ()
+                | Between (min, max) ->
                     let p = name.Derive it.ParameterName
-                    let values = it.Value :?> obj list
-                    yield SqliteParameter($"{p}min", List.head values)
-                    yield SqliteParameter($"{p}max", List.last values)
-                | _ -> yield SqliteParameter(name.Derive it.ParameterName, it.Value) })
+                    yield! [ SqliteParameter($"{p}min", min); SqliteParameter($"{p}max", max) ]
+                | In values | InArray (_, values) ->
+                    let p = name.Derive it.ParameterName
+                    yield! values |> Seq.mapi (fun idx v -> SqliteParameter($"{p}_{idx}", v))
+                | Equal v | Greater v | GreaterOrEqual v | Less v | LessOrEqual v | NotEqual v ->
+                    yield SqliteParameter(name.Derive it.ParameterName, v) })
         |> Seq.collect id
         |> Seq.append parameters
         |> Seq.toList
@@ -143,7 +153,7 @@ module Results =
     /// Create a domain item from a document, specifying the field in which the document is found
     [<CompiledName "FromDocument">]
     let fromDocument<'TDoc> field (rdr: SqliteDataReader) : 'TDoc =
-        Configuration.serializer().Deserialize<'TDoc>(rdr.GetString(rdr.GetOrdinal(field)))
+        Configuration.serializer().Deserialize<'TDoc>(rdr.GetString(rdr.GetOrdinal field))
 
     /// Create a domain item from a document
     [<CompiledName "FromData">]
@@ -211,7 +221,7 @@ module WithConn =
         }
         
         /// Execute a query that returns one or no results (returns null if not found)
-        let Single<'TDoc when 'TDoc: null>(
+        let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>(
                 query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>, conn
             ) = backgroundTask {
             let! result = single<'TDoc> query parameters mapFunc.Invoke conn
@@ -258,10 +268,29 @@ module WithConn =
         let ensureFieldIndex tableName indexName fields conn =
             Custom.nonQuery (Query.Definition.ensureIndexOn tableName indexName fields SQLite) [] conn
 
+    /// Commands to add documents
+    [<AutoOpen>]
+    module Document =
+        
         /// Insert a new document
         [<CompiledName "Insert">]
         let insert<'TDoc> tableName (document: 'TDoc) conn =
-        Custom.nonQuery (Query.insert tableName) [ jsonParam "@data" document ] conn
+            let query =
+                match Configuration.autoIdStrategy () with 
+                | Disabled -> Query.insert tableName
+                | strategy ->
+                    let idField   = Configuration.idField ()
+                    let dataParam =
+                        if AutoId.NeedsAutoId strategy document idField then
+                            match strategy with
+                            | Number -> $"(SELECT coalesce(max(data->>'{idField}'), 0) + 1 FROM {tableName})"
+                            | Guid -> $"'{AutoId.GenerateGuid()}'"
+                            | RandomString -> $"'{AutoId.GenerateRandomString(Configuration.idStringLength ())}'"
+                            | Disabled -> "@data"
+                            |> function it -> $"json_set(@data, '$.{idField}', {it})"
+                        else "@data"
+                    (Query.insert tableName).Replace("@data", dataParam)
+            Custom.nonQuery query [ jsonParam "@data" document ] conn
         
         /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
         [<CompiledName "Save">]
@@ -314,13 +343,22 @@ module WithConn =
         let All<'TDoc>(tableName, conn) =
             Custom.List(Query.find tableName, [], fromData<'TDoc>, conn)
 
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        [<CompiledName "FSharpAllOrdered">]
+        let allOrdered<'TDoc> tableName orderFields conn =
+            Custom.list<'TDoc> (Query.find tableName + Query.orderBy orderFields SQLite) [] fromData<'TDoc> conn
+
+        /// Retrieve all documents in the given table ordered by the given fields in the document
+        let AllOrdered<'TDoc>(tableName, orderFields, conn) =
+            Custom.List(Query.find tableName + Query.orderBy orderFields SQLite, [], fromData<'TDoc>, conn)
+
         /// Retrieve a document by its ID (returns None if not found)
         [<CompiledName "FSharpById">]
         let byId<'TKey, 'TDoc> tableName (docId: 'TKey) conn =
             Custom.single<'TDoc> (Query.byId (Query.find tableName) docId) [ idParam docId ] fromData<'TDoc> conn
 
         /// Retrieve a document by its ID (returns null if not found)
-        let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId: 'TKey, conn) =
+        let ById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, docId: 'TKey, conn) =
             Custom.Single<'TDoc>(Query.byId (Query.find tableName) docId, [ idParam docId ], fromData<'TDoc>, conn)
         
         /// Retrieve documents via a comparison on JSON fields
@@ -332,12 +370,6 @@ module WithConn =
                 fromData<'TDoc>
                 conn 
         
-        /// Retrieve documents via a comparison on a JSON field
-        [<CompiledName "FSharpByField">]
-        [<System.Obsolete "Use byFields instead; will be removed in v4">]
-        let byField<'TDoc> tableName field conn =
-            byFields<'TDoc> tableName Any [ field ] conn
-        
         /// Retrieve documents via a comparison on JSON fields
         let ByFields<'TDoc>(tableName, howMatched, fields, conn) =
             Custom.List<'TDoc>(
@@ -346,10 +378,22 @@ module WithConn =
                 fromData<'TDoc>,
                 conn) 
         
-        /// Retrieve documents via a comparison on a JSON field
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let ByField<'TDoc>(tableName, field, conn) =
-            ByFields<'TDoc>(tableName, Any, [ field ], conn)
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
+        [<CompiledName "FSharpByFieldsOrdered">]
+        let byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn =
+            Custom.list<'TDoc>
+                (Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields SQLite)
+                (addFieldParams queryFields [])
+                fromData<'TDoc>
+                conn 
+        
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
+        let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, conn) =
+            Custom.List<'TDoc>(
+                Query.byFields (Query.find tableName) howMatched queryFields + Query.orderBy orderFields SQLite,
+                addFieldParams queryFields [],
+                fromData<'TDoc>,
+                conn) 
         
         /// Retrieve documents via a comparison on JSON fields, returning only the first result
         [<CompiledName "FSharpFirstByFields">]
@@ -360,24 +404,33 @@ module WithConn =
                 fromData<'TDoc>
                 conn
         
-        /// Retrieve documents via a comparison on a JSON field, returning only the first result
-        [<CompiledName "FSharpFirstByField">]
-        [<System.Obsolete "Use firstByFields instead; will be removed in v4">]
-        let firstByField<'TDoc> tableName field conn =
-            firstByFields<'TDoc> tableName Any [ field ] conn
-        
         /// Retrieve documents via a comparison on JSON fields, returning only the first result
-        let FirstByFields<'TDoc when 'TDoc: null>(tableName, howMatched, fields, conn) =
+        let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields, conn) =
             Custom.Single(
                 $"{Query.byFields (Query.find tableName) howMatched fields} LIMIT 1",
                 addFieldParams fields [],
                 fromData<'TDoc>,
                 conn)
     
-        /// Retrieve documents via a comparison on a JSON field, returning only the first result
-        [<System.Obsolete "Use FirstByFields instead; will be removed in v4">]
-        let FirstByField<'TDoc when 'TDoc: null>(tableName, field, conn) =
-            FirstByFields(tableName, Any, [ field ], conn)
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning
+        /// only the first result
+        [<CompiledName "FSharpFirstByFieldsOrdered">]
+        let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn =
+            Custom.single
+                $"{Query.byFields (Query.find tableName) howMatched queryFields}{Query.orderBy orderFields SQLite} LIMIT 1"
+                (addFieldParams queryFields [])
+                fromData<'TDoc>
+                conn
+        
+        /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning
+        /// only the first result
+        let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+                tableName, howMatched, queryFields, orderFields, conn) =
+            Custom.Single(
+                $"{Query.byFields (Query.find tableName) howMatched queryFields}{Query.orderBy orderFields SQLite} LIMIT 1",
+                addFieldParams queryFields [],
+                fromData<'TDoc>,
+                conn)
     
     /// Commands to update documents
     [<RequireQualifiedAccess>]
@@ -418,12 +471,6 @@ module WithConn =
                 (addFieldParams fields [ jsonParam "@data" patch ])
                 conn
     
-        /// Patch documents using a comparison on a JSON field
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let byField tableName field (patch: 'TPatch) conn =
-            byFields tableName Any [ field ] patch conn
-
     /// Commands to remove fields from documents
     [<RequireQualifiedAccess>]
     module RemoveFields =
@@ -446,12 +493,6 @@ module WithConn =
                 (addFieldParams fields nameParams)
                 conn
     
-        /// Remove fields from documents via a comparison on a JSON field in the document
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let byField tableName field fieldNames conn =
-            byFields tableName Any [ field ] fieldNames conn
-    
     /// Commands to delete documents
     [<RequireQualifiedAccess>]
     module Delete =
@@ -466,12 +507,6 @@ module WithConn =
         let byFields tableName howMatched fields conn =
             Custom.nonQuery (Query.byFields (Query.delete tableName) howMatched fields) (addFieldParams fields []) conn
 
-        /// Delete documents by matching a comparison on a JSON field
-        [<CompiledName "ByField">]
-        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-        let byField tableName field conn =
-            byFields tableName Any [ field ] conn
-
 
 /// Commands to execute custom SQL queries
 [<RequireQualifiedAccess>]
@@ -495,7 +530,8 @@ module Custom =
         WithConn.Custom.single<'TDoc> query parameters mapFunc conn
 
     /// Execute a query that returns one or no results (returns null if not found)
-    let Single<'TDoc when 'TDoc: null>(query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>) =
+    let Single<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>) =
         use conn = Configuration.dbConn ()
         WithConn.Custom.Single<'TDoc>(query, parameters, mapFunc, conn)
 
@@ -516,6 +552,7 @@ module Custom =
         use conn = Configuration.dbConn ()
         WithConn.Custom.Scalar<'T>(query, parameters, mapFunc, conn)
 
+
 /// Functions to create tables and indexes
 [<RequireQualifiedAccess>]
 module Definition =
@@ -532,6 +569,7 @@ module Definition =
         use conn = Configuration.dbConn ()
         WithConn.Definition.ensureFieldIndex tableName indexName fields conn
 
+
 /// Document insert/save functions
 [<AutoOpen>]
 module Document =
@@ -540,13 +578,14 @@ module Document =
     [<CompiledName "Insert">]
     let insert<'TDoc> tableName (document: 'TDoc) =
         use conn = Configuration.dbConn ()
-        WithConn.insert tableName document conn
+        WithConn.Document.insert tableName document conn
 
     /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
     [<CompiledName "Save">]
     let save<'TDoc> tableName (document: 'TDoc) =
         use conn = Configuration.dbConn ()
-        WithConn.save tableName document conn
+        WithConn.Document.save tableName document conn
+
 
 /// Commands to count documents
 [<RequireQualifiedAccess>]
@@ -564,11 +603,6 @@ module Count =
         use conn = Configuration.dbConn ()
         WithConn.Count.byFields tableName howMatched fields conn
 
-    /// Count matching documents using a comparison on a JSON field
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]
 
 /// Commands to determine if documents exist
 [<RequireQualifiedAccess>]
@@ -586,11 +620,6 @@ module Exists =
         use conn = Configuration.dbConn ()
         WithConn.Exists.byFields tableName howMatched fields conn
 
-    /// Determine if a document exists using a comparison on a JSON field
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]
 
 /// Commands to determine if documents exist
 [<RequireQualifiedAccess>]
@@ -607,6 +636,17 @@ module Find =
         use conn = Configuration.dbConn ()
         WithConn.Find.All<'TDoc>(tableName, conn)
 
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    [<CompiledName "FSharpAllOrdered">]
+    let allOrdered<'TDoc> tableName orderFields =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.allOrdered<'TDoc> tableName orderFields conn
+
+    /// Retrieve all documents in the given table ordered by the given fields in the document
+    let AllOrdered<'TDoc> tableName orderFields =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.AllOrdered<'TDoc>(tableName, orderFields, conn)
+
     /// Retrieve a document by its ID (returns None if not found)
     [<CompiledName "FSharpById">]
     let byId<'TKey, 'TDoc> tableName docId =
@@ -614,7 +654,7 @@ module Find =
         WithConn.Find.byId<'TKey, 'TDoc> tableName docId conn
 
     /// Retrieve a document by its ID (returns null if not found)
-    let ById<'TKey, 'TDoc when 'TDoc: null>(tableName, docId) =
+    let ById<'TKey, 'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, docId) =
         use conn = Configuration.dbConn ()
         WithConn.Find.ById<'TKey, 'TDoc>(tableName, docId, conn)
 
@@ -624,21 +664,21 @@ module Find =
         use conn = Configuration.dbConn ()
         WithConn.Find.byFields<'TDoc> tableName howMatched fields conn
     
-    /// Retrieve documents via a comparison on a JSON field
-    [<CompiledName "FSharpByField">]
-    [<System.Obsolete "Use byFields instead; will be removed in v4">]
-    let byField<'TDoc> tableName field =
-        byFields tableName Any [ field ]
-    
     /// Retrieve documents via a comparison on JSON fields
     let ByFields<'TDoc>(tableName, howMatched, fields) =
         use conn = Configuration.dbConn ()
         WithConn.Find.ByFields<'TDoc>(tableName, howMatched, fields, conn)
     
-    /// Retrieve documents via a comparison on a JSON field
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let ByField<'TDoc>(tableName, field) =
-        ByFields<'TDoc>(tableName, Any, [ field ])
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
+    [<CompiledName "FSharpByFieldsOrdered">]
+    let byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.byFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn
+    
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document
+    let ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields) =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.ByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, conn)
     
     /// Retrieve documents via a comparison on JSON fields, returning only the first result
     [<CompiledName "FSharpFirstByFields">]
@@ -646,21 +686,25 @@ module Find =
         use conn = Configuration.dbConn ()
         WithConn.Find.firstByFields<'TDoc> tableName howMatched fields conn
     
-    /// Retrieve documents via a comparison on a JSON field, returning only the first result
-    [<CompiledName "FSharpFirstByField">]
-    [<System.Obsolete "Use firstByFields instead; will be removed in v4">]
-    let firstByField<'TDoc> tableName field =
-        firstByFields<'TDoc> tableName Any [ field ]
-    
     /// Retrieve documents via a comparison on JSON fields, returning only the first result
-    let FirstByFields<'TDoc when 'TDoc: null>(tableName, howMatched, fields) =
+    let FirstByFields<'TDoc when 'TDoc: null and 'TDoc: not struct>(tableName, howMatched, fields) =
         use conn = Configuration.dbConn ()
         WithConn.Find.FirstByFields<'TDoc>(tableName, howMatched, fields, conn)
 
-    /// Retrieve documents via a comparison on a JSON field, returning only the first result
-    [<System.Obsolete "Use FirstByFields instead; will be removed in v4">]
-    let FirstByField<'TDoc when 'TDoc: null>(tableName, field) =
-        FirstByFields<'TDoc>(tableName, Any, [ field ])
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning only
+    /// the first result
+    [<CompiledName "FSharpFirstByFieldsOrdered">]
+    let firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn
+    
+    /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning only
+    /// the first result
+    let FirstByFieldsOrdered<'TDoc when 'TDoc: null and 'TDoc: not struct>(
+            tableName, howMatched, queryFields, orderFields) =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.FirstByFieldsOrdered<'TDoc>(tableName, howMatched, queryFields, orderFields, conn)
+
 
 /// Commands to update documents
 [<RequireQualifiedAccess>]
@@ -683,6 +727,7 @@ module Update =
         use conn = Configuration.dbConn ()
         WithConn.Update.ByFunc(tableName, idFunc, document, conn)
 
+
 /// Commands to patch (partially update) documents
 [<RequireQualifiedAccess>]
 module Patch =
@@ -699,11 +744,6 @@ module Patch =
         use conn = Configuration.dbConn ()
         WithConn.Patch.byFields tableName howMatched fields patch conn
 
-    /// Patch documents using a comparison on a JSON field in the WHERE clause
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field (patch: 'TPatch) =
-        byFields tableName Any [ field ] patch
 
 /// Commands to remove fields from documents
 [<RequireQualifiedAccess>]
@@ -721,11 +761,6 @@ module RemoveFields =
         use conn = Configuration.dbConn ()
         WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn
 
-    /// Remove field from documents via a comparison on a JSON field in the document
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field fieldNames =
-        byFields tableName Any [ field ] fieldNames
 
 /// Commands to delete documents
 [<RequireQualifiedAccess>]
@@ -742,9 +777,3 @@ module Delete =
     let byFields tableName howMatched fields =
         use conn = Configuration.dbConn ()
         WithConn.Delete.byFields tableName howMatched fields conn
-    
-    /// Delete documents by matching a comparison on a JSON field
-    [<CompiledName "ByField">]
-    [<System.Obsolete "Use ByFields instead; will be removed in v4">]
-    let byField tableName field =
-        byFields tableName Any [ field ]

src/Sqlite/README.md

@@ -5,11 +5,16 @@ This package provides a lightweight document library backed by [SQLite](https://
 ## Features
 
 - Select, insert, update, save (upsert), delete, count, and check existence of documents, and create tables and indexes for these documents
+- Automatically generate IDs for documents (numeric IDs, GUIDs, or random strings)
 - Address documents via ID or via comparison on any field
 - Access documents as your domain models (<abbr title="Plain Old CLR Objects">POCO</abbr>s)
 - Use `Task`-based async for all data access functions
 - Use building blocks for more complex queries
 
+## Upgrading from v3
+
+There is a breaking API change for `ByField` (C#) / `byField` (F#), along with a compatibility namespace that can mitigate the impact of these changes. See [the migration guide](https://bitbadger.solutions/open-source/relational-documents/upgrade-from-v3-to-v4.html) for full details.
+
 ## Getting Started
 
 Once the package is installed, the library needs a connection string. Once it has been obtained / constructed, provide it to the library:
@@ -72,28 +77,28 @@ Count customers in Atlanta:
 
 ```csharp
 // C#; parameters are table name, field, operator, and value
-// Count.ByField type signature is Func<string, Field, Task<long>>
-var customerCount = await Count.ByField("customer", Field.EQ("City", "Atlanta"));
+// Count.ByFields type signature is Func<string, FieldMatch, IEnumerable<Field>, Task<long>>
+var customerCount = await Count.ByFields("customer", FieldMatch.Any, [Field.Equal("City", "Atlanta")]);
 ```
 
 ```fsharp
 // F#
-// Count.byField type signature is string -> Field -> Task<int64>
-let! customerCount = Count.byField "customer" (Field.EQ "City" "Atlanta")
+// Count.byFields type signature is string -> FieldMatch -> Field seq -> Task<int64>
+let! customerCount = Count.byFields "customer" Any [ Field.Equal "City" "Atlanta" ]
 ```
 
 Delete customers in Chicago: _(no offense, Second City; just an example...)_
 
 ```csharp
 // C#; parameters are same as above, except return is void
-// Delete.ByField type signature is Func<string, Field, Task>
-await Delete.ByField("customer", Field.EQ("City", "Chicago"));
+// Delete.ByFields type signature is Func<string, FieldMatch, IEnumerable<Field>, Task>
+await Delete.ByFields("customer", FieldMatch.Any, [Field.Equal("City", "Chicago")]);
 ```
 
 ```fsharp
 // F#
-// Delete.byField type signature is string -> string -> Op -> obj -> Task<unit>
-do! Delete.byField "customer" (Field.EQ "City" "Chicago")
+// Delete.byFields type signature is string -> FieldMatch -> Field seq -> Task<unit>
+do! Delete.byFields "customer" Any [ Field.Equal "City" "Chicago" ]
 ```
 
 ## More Information

src/Tests.CSharp/CommonCSharpTests.cs

@@ -1,6 +1,5 @@
 using Expecto.CSharp;
 using Expecto;
-using Microsoft.FSharp.Collections;
 using Microsoft.FSharp.Core;
 
 namespace BitBadger.Documents.Tests.CSharp;
@@ -22,13 +21,407 @@ internal class TestSerializer : IDocumentSerializer
 public static class CommonCSharpTests
 {
     /// <summary>
-    /// Unit tests
+    /// Unit tests for the OpSql property of the Comparison discriminated union
     /// </summary>
-    [Tests]
-    public static readonly Test Unit = TestList("Common.C# Unit",
+    private static readonly Test OpTests = TestList("Comparison.OpSql",
     [
-        TestSequenced(
-            TestList("Configuration",
+        TestCase("Equal succeeds", () =>
+        {
+            Expect.equal(Comparison.NewEqual("").OpSql, "=", "The Equals SQL was not correct");
+        }),
+        TestCase("Greater succeeds", () =>
+        {
+            Expect.equal(Comparison.NewGreater("").OpSql, ">", "The Greater SQL was not correct");
+        }),
+        TestCase("GreaterOrEqual succeeds", () =>
+        {
+            Expect.equal(Comparison.NewGreaterOrEqual("").OpSql, ">=", "The GreaterOrEqual SQL was not correct");
+        }),
+        TestCase("Less succeeds", () =>
+        {
+            Expect.equal(Comparison.NewLess("").OpSql, "<", "The Less SQL was not correct");
+        }),
+        TestCase("LessOrEqual succeeds", () =>
+        {
+            Expect.equal(Comparison.NewLessOrEqual("").OpSql, "<=", "The LessOrEqual SQL was not correct");
+        }),
+        TestCase("NotEqual succeeds", () =>
+        {
+            Expect.equal(Comparison.NewNotEqual("").OpSql, "<>", "The NotEqual SQL was not correct");
+        }),
+        TestCase("Between succeeds", () =>
+        {
+            Expect.equal(Comparison.NewBetween("", "").OpSql, "BETWEEN", "The Between SQL was not correct");
+        }),
+        TestCase("In succeeds", () =>
+        {
+            Expect.equal(Comparison.NewIn([]).OpSql, "IN", "The In SQL was not correct");
+        }),
+        TestCase("InArray succeeds", () =>
+        {
+            Expect.equal(Comparison.NewInArray("", []).OpSql, "?|", "The InArray SQL was not correct");
+        }),
+        TestCase("Exists succeeds", () =>
+        {
+            Expect.equal(Comparison.Exists.OpSql, "IS NOT NULL", "The Exists SQL was not correct");
+        }),
+        TestCase("NotExists succeeds", () =>
+        {
+            Expect.equal(Comparison.NotExists.OpSql, "IS NULL", "The NotExists SQL was not correct");
+        })
+    ]);
+
+    /// <summary>
+    /// Unit tests for the Field class
+    /// </summary>
+    private static readonly Test FieldTests = TestList("Field",
+    [
+        TestCase("Equal succeeds", () =>
+        {
+            var field = Field.Equal("Test", 14);
+            Expect.equal(field.Name, "Test", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewEqual(14), "Comparison incorrect");
+        }),
+        TestCase("Greater succeeds", () =>
+        {
+            var field = Field.Greater("Great", "night");
+            Expect.equal(field.Name, "Great", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewGreater("night"), "Comparison incorrect");
+        }),
+        TestCase("GreaterOrEqual succeeds", () =>
+        {
+            var field = Field.GreaterOrEqual("Nice", 88L);
+            Expect.equal(field.Name, "Nice", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewGreaterOrEqual(88L), "Comparison incorrect");
+        }),
+        TestCase("Less succeeds", () =>
+        {
+            var field = Field.Less("Lesser", "seven");
+            Expect.equal(field.Name, "Lesser", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewLess("seven"), "Comparison incorrect");
+        }),
+        TestCase("LessOrEqual succeeds", () =>
+        {
+            var field = Field.LessOrEqual("Nobody", "KNOWS");
+            Expect.equal(field.Name, "Nobody", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewLessOrEqual("KNOWS"), "Comparison incorrect");
+        }),
+        TestCase("NotEqual succeeds", () =>
+        {
+            var field = Field.NotEqual("Park", "here");
+            Expect.equal(field.Name, "Park", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewNotEqual("here"), "Comparison incorrect");
+        }),
+        TestCase("Between succeeds", () =>
+        {
+            var field = Field.Between("Age", 18, 49);
+            Expect.equal(field.Name, "Age", "Field name incorrect");
+            Expect.equal(field.Comparison, Comparison.NewBetween(18, 49), "Comparison incorrect");
+        }),
+        TestCase("In succeeds", () =>
+        {
+            var field = Field.In("Here", [8, 16, 32]);
+            Expect.equal(field.Name, "Here", "Field name incorrect");
+            Expect.isTrue(field.Comparison.IsIn, "Comparison incorrect");
+            Expect.sequenceEqual(((Comparison.In)field.Comparison).Values, [8, 16, 32], "Value incorrect");
+        }),
+        TestCase("InArray succeeds", () =>
+        {
+            var field = Field.InArray("ArrayField", "table", ["x", "y", "z"]);
+            Expect.equal(field.Name, "ArrayField", "Field name incorrect");
+            Expect.isTrue(field.Comparison.IsInArray, "Comparison incorrect");
+            var it = (Comparison.InArray)field.Comparison;
+            Expect.equal(it.Table, "table", "Table name incorrect");
+            Expect.sequenceEqual(it.Values, ["x", "y", "z"], "Value incorrect");
+        }),
+        TestCase("Exists succeeds", () =>
+        {
+            var field = Field.Exists("Groovy");
+            Expect.equal(field.Name, "Groovy", "Field name incorrect");
+            Expect.isTrue(field.Comparison.IsExists, "Comparison incorrect");
+        }),
+        TestCase("NotExists succeeds", () =>
+        {
+            var field = Field.NotExists("Rad");
+            Expect.equal(field.Name, "Rad", "Field name incorrect");
+            Expect.isTrue(field.Comparison.IsNotExists, "Comparison incorrect");
+        }),
+        TestList("NameToPath",
+        [
+            TestCase("succeeds for PostgreSQL and a simple name", () =>
+            {
+                Expect.equal("data->>'Simple'", Field.NameToPath("Simple", Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "Path not constructed correctly");
+            }),
+            TestCase("succeeds for SQLite and a simple name", () =>
+            {
+                Expect.equal("data->>'Simple'", Field.NameToPath("Simple", Dialect.SQLite, FieldFormat.AsSql),
+                    "Path not constructed correctly");
+            }),
+            TestCase("succeeds for PostgreSQL and a nested name", () =>
+            {
+                Expect.equal("data#>>'{A,Long,Path,to,the,Property}'",
+                    Field.NameToPath("A.Long.Path.to.the.Property", Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "Path not constructed correctly");
+            }),
+            TestCase("succeeds for SQLite and a nested name", () =>
+            {
+                Expect.equal("data->'A'->'Long'->'Path'->'to'->'the'->>'Property'",
+                    Field.NameToPath("A.Long.Path.to.the.Property", Dialect.SQLite, FieldFormat.AsSql),
+                    "Path not constructed correctly");
+            })
+        ]),
+        TestCase("WithParameterName succeeds", () =>
+        {
+            var field = Field.Equal("Bob", "Tom").WithParameterName("@name");
+            Expect.isSome(field.ParameterName, "The parameter name should have been filled");
+            Expect.equal("@name", field.ParameterName.Value, "The parameter name is incorrect");
+        }),
+        TestCase("WithQualifier succeeds", () =>
+        {
+            var field = Field.Equal("Bill", "Matt").WithQualifier("joe");
+            Expect.isSome(field.Qualifier, "The table qualifier should have been filled");
+            Expect.equal("joe", field.Qualifier.Value, "The table qualifier is incorrect");
+        }),
+        TestList("Path",
+        [
+            TestCase("succeeds for a PostgreSQL single field with no qualifier", () =>
+            {
+                var field = Field.GreaterOrEqual("SomethingCool", 18);
+                Expect.equal("data->>'SomethingCool'", field.Path(Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "The PostgreSQL path is incorrect");
+            }),
+            TestCase("succeeds for a PostgreSQL single field with a qualifier", () =>
+            {
+                var field = Field.Less("SomethingElse", 9).WithQualifier("this");
+                Expect.equal("this.data->>'SomethingElse'", field.Path(Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "The PostgreSQL path is incorrect");
+            }),
+            TestCase("succeeds for a PostgreSQL nested field with no qualifier", () =>
+            {
+                var field = Field.Equal("My.Nested.Field", "howdy");
+                Expect.equal("data#>>'{My,Nested,Field}'", field.Path(Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "The PostgreSQL path is incorrect");
+            }),
+            TestCase("succeeds for a PostgreSQL nested field with a qualifier", () =>
+            {
+                var field = Field.Equal("Nest.Away", "doc").WithQualifier("bird");
+                Expect.equal("bird.data#>>'{Nest,Away}'", field.Path(Dialect.PostgreSQL, FieldFormat.AsSql),
+                    "The PostgreSQL path is incorrect");
+            }),
+            TestCase("succeeds for a SQLite single field with no qualifier", () =>
+            {
+                var field = Field.GreaterOrEqual("SomethingCool", 18);
+                Expect.equal("data->>'SomethingCool'", field.Path(Dialect.SQLite, FieldFormat.AsSql),
+                    "The SQLite path is incorrect");
+            }),
+            TestCase("succeeds for a SQLite single field with a qualifier", () =>
+            {
+                var field = Field.Less("SomethingElse", 9).WithQualifier("this");
+                Expect.equal("this.data->>'SomethingElse'", field.Path(Dialect.SQLite, FieldFormat.AsSql),
+                    "The SQLite path is incorrect");
+            }),
+            TestCase("succeeds for a SQLite nested field with no qualifier", () =>
+            {
+                var field = Field.Equal("My.Nested.Field", "howdy");
+                Expect.equal("data->'My'->'Nested'->>'Field'", field.Path(Dialect.SQLite, FieldFormat.AsSql),
+                    "The SQLite path is incorrect");
+            }),
+            TestCase("succeeds for a SQLite nested field with a qualifier", () =>
+            {
+                var field = Field.Equal("Nest.Away", "doc").WithQualifier("bird");
+                Expect.equal("bird.data->'Nest'->>'Away'", field.Path(Dialect.SQLite, FieldFormat.AsSql),
+                    "The SQLite path is incorrect");
+            })
+        ])
+    ]);
+
+    /// <summary>
+    /// Unit tests for the FieldMatch enum
+    /// </summary>
+    private static readonly Test FieldMatchTests = TestList("FieldMatch.ToString",
+    [
+        TestCase("succeeds for Any", () =>
+        {
+            Expect.equal(FieldMatch.Any.ToString(), "OR", "SQL for Any is incorrect");
+        }),
+        TestCase("succeeds for All", () =>
+        {
+            Expect.equal(FieldMatch.All.ToString(), "AND", "SQL for All is incorrect");
+        })
+    ]);
+
+    /// <summary>
+    /// Unit tests for the ParameterName class
+    /// </summary>
+    private static readonly Test ParameterNameTests = TestList("ParameterName.Derive",
+    [
+        TestCase("succeeds with existing name", () =>
+        {
+            ParameterName name = new();
+            Expect.equal(name.Derive(FSharpOption<string>.Some("@taco")), "@taco", "Name should have been @taco");
+            Expect.equal(name.Derive(FSharpOption<string>.None), "@field0",
+                "Counter should not have advanced for named field");
+        }),
+        TestCase("Derive succeeds with non-existent name", () =>
+        {
+            ParameterName name = new();
+            Expect.equal(name.Derive(FSharpOption<string>.None), "@field0",
+                "Anonymous field name should have been returned");
+            Expect.equal(name.Derive(FSharpOption<string>.None), "@field1",
+                "Counter should have advanced from previous call");
+            Expect.equal(name.Derive(FSharpOption<string>.None), "@field2",
+                "Counter should have advanced from previous call");
+            Expect.equal(name.Derive(FSharpOption<string>.None), "@field3",
+                "Counter should have advanced from previous call");
+        })
+    ]);
+
+    /// <summary>
+    /// Unit tests for the AutoId enum
+    /// </summary>
+    private static readonly Test AutoIdTests = TestList("AutoId",
+    [
+        TestCase("GenerateGuid succeeds", () =>
+        {
+            var autoId = AutoId.GenerateGuid();
+            Expect.isNotNull(autoId, "The GUID auto-ID should not have been null");
+            Expect.stringHasLength(autoId, 32, "The GUID auto-ID should have been 32 characters long");
+            Expect.equal(autoId, autoId.ToLowerInvariant(), "The GUID auto-ID should have been lowercase");
+        }),
+        TestCase("GenerateRandomString succeeds", () =>
+        {
+            foreach (var length in (int[]) [6, 8, 12, 20, 32, 57, 64])
+            {
+                var autoId = AutoId.GenerateRandomString(length);
+                Expect.isNotNull(autoId, $"Random string ({length}) should not have been null");
+                Expect.stringHasLength(autoId, length, $"Random string should have been {length} characters long");
+                Expect.equal(autoId, autoId.ToLowerInvariant(),
+                    $"Random string ({length}) should have been lowercase");
+            }
+        }),
+        TestList("NeedsAutoId",
+        [
+            TestCase("succeeds when no auto ID is configured", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Disabled, new object(), "id"),
+                    "Disabled auto-ID never needs an automatic ID");
+            }),
+            TestCase("fails for any when the ID property is not found", () =>
+            {
+                try
+                {
+                    _ = AutoId.NeedsAutoId(AutoId.Number, new { Key = "" }, "Id");
+                    Expect.isTrue(false, "Non-existent ID property should have thrown an exception");
+                }
+                catch (InvalidOperationException)
+                {
+                    // pass
+                }
+            }),
+            TestCase("succeeds for byte when the ID is zero", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.Number, new { Id = (sbyte)0 }, "Id"),
+                    "Zero ID should have returned true");
+            }),
+            TestCase("succeeds for byte when the ID is non-zero", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Number, new { Id = (sbyte)4 }, "Id"),
+                    "Non-zero ID should have returned false");
+            }),
+            TestCase("succeeds for short when the ID is zero", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.Number, new { Id = (short)0 }, "Id"),
+                    "Zero ID should have returned true");
+            }),
+            TestCase("succeeds for short when the ID is non-zero", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Number, new { Id = (short)7 }, "Id"),
+                    "Non-zero ID should have returned false");
+            }),
+            TestCase("succeeds for int when the ID is zero", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.Number, new { Id = 0 }, "Id"),
+                    "Zero ID should have returned true");
+            }),
+            TestCase("succeeds for int when the ID is non-zero", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Number, new { Id = 32 }, "Id"),
+                    "Non-zero ID should have returned false");
+            }),
+            TestCase("succeeds for long when the ID is zero", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.Number, new { Id = 0L }, "Id"),
+                    "Zero ID should have returned true");
+            }),
+            TestCase("succeeds for long when the ID is non-zero", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Number, new { Id = 80L }, "Id"),
+                    "Non-zero ID should have returned false");
+            }),
+            TestCase("fails for number when the ID is not a number", () =>
+            {
+                try
+                {
+                    _ = AutoId.NeedsAutoId(AutoId.Number, new { Id = "" }, "Id");
+                    Expect.isTrue(false, "Numeric ID against a string should have thrown an exception");
+                }
+                catch (InvalidOperationException)
+                {
+                    // pass
+                }
+            }),
+            TestCase("succeeds for GUID when the ID is blank", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.Guid, new { Id = "" }, "Id"),
+                    "Blank ID should have returned true");
+            }),
+            TestCase("succeeds for GUID when the ID is filled", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.Guid, new { Id = "abc" }, "Id"),
+                    "Filled ID should have returned false");
+            }),
+            TestCase("fails for GUID when the ID is not a string", () =>
+            {
+                try
+                {
+                    _ = AutoId.NeedsAutoId(AutoId.Guid, new { Id = 8 }, "Id");
+                    Expect.isTrue(false, "String ID against a number should have thrown an exception");
+                }
+                catch (InvalidOperationException)
+                {
+                    // pass
+                }
+            }),
+            TestCase("succeeds for RandomString when the ID is blank", () =>
+            {
+                Expect.isTrue(AutoId.NeedsAutoId(AutoId.RandomString, new { Id = "" }, "Id"),
+                    "Blank ID should have returned true");
+            }),
+            TestCase("succeeds for RandomString when the ID is filled", () =>
+            {
+                Expect.isFalse(AutoId.NeedsAutoId(AutoId.RandomString, new { Id = "x" }, "Id"),
+                    "Filled ID should have returned false");
+            }),
+            TestCase("fails for RandomString when the ID is not a string", () =>
+            {
+                try
+                {
+                    _ = AutoId.NeedsAutoId(AutoId.RandomString, new { Id = 33 }, "Id");
+                    Expect.isTrue(false, "String ID against a number should have thrown an exception");
+                }
+                catch (InvalidOperationException)
+                {
+                    // pass
+                }
+            })
+        ])
+    ]);
+    
+    /// <summary>
+    /// Unit tests for the Configuration static class
+    /// </summary>
+    private static readonly Test ConfigurationTests = TestList("Configuration",
     [
         TestCase("UseSerializer succeeds", () =>
         {
@@ -70,207 +463,41 @@ public static class CommonCSharpTests
             {
                 Configuration.UseIdField("Id");
             }
+        }),
+        TestCase("UseAutoIdStrategy / AutoIdStrategy succeeds", () =>
+        {
+            try
+            {
+                Expect.equal(Configuration.AutoIdStrategy(), AutoId.Disabled,
+                    "The default auto-ID strategy was incorrect");
+                Configuration.UseAutoIdStrategy(AutoId.Guid);
+                Expect.equal(Configuration.AutoIdStrategy(), AutoId.Guid,
+                    "The auto-ID strategy was not set correctly");
+            }
+            finally
+            {
+                Configuration.UseAutoIdStrategy(AutoId.Disabled);
+            }
+        }),
+        TestCase("UseIdStringLength / IdStringLength succeeds", () =>
+        {
+            try
+            {
+                Expect.equal(Configuration.IdStringLength(), 16, "The default ID string length was incorrect");
+                Configuration.UseIdStringLength(33);
+                Expect.equal(Configuration.IdStringLength(), 33, "The ID string length was not set correctly");
+            }
+            finally
+            {
+                Configuration.UseIdStringLength(16);
+            }
         })
-            ])),
-        TestList("Op",
-        [
-            TestCase("EQ succeeds", () =>
-            {
-                Expect.equal(Op.EQ.ToString(), "=", "The equals operator was not correct");
-            }),
-            TestCase("GT succeeds", () =>
-            {
-                Expect.equal(Op.GT.ToString(), ">", "The greater than operator was not correct");
-            }),
-            TestCase("GE succeeds", () =>
-            {
-                Expect.equal(Op.GE.ToString(), ">=", "The greater than or equal to operator was not correct");
-            }),
-            TestCase("LT succeeds", () =>
-            {
-                Expect.equal(Op.LT.ToString(), "<", "The less than operator was not correct");
-            }),
-            TestCase("LE succeeds", () =>
-            {
-                Expect.equal(Op.LE.ToString(), "<=", "The less than or equal to operator was not correct");
-            }),
-            TestCase("NE succeeds", () =>
-            {
-                Expect.equal(Op.NE.ToString(), "<>", "The not equal to operator was not correct");
-            }),
-            TestCase("BT succeeds", () =>
-            {
-                Expect.equal(Op.BT.ToString(), "BETWEEN", "The \"between\" operator was not correct");
-            }),
-            TestCase("EX succeeds", () =>
-            {
-                Expect.equal(Op.EX.ToString(), "IS NOT NULL", "The \"exists\" operator was not correct");
-            }),
-            TestCase("NEX succeeds", () =>
-            {
-                Expect.equal(Op.NEX.ToString(), "IS NULL", "The \"not exists\" operator was not correct");
-            })
-        ]),
-        TestList("Field",
-        [
-            TestCase("EQ succeeds", () =>
-            {
-                var field = Field.EQ("Test", 14);
-                Expect.equal(field.Name, "Test", "Field name incorrect");
-                Expect.equal(field.Op, Op.EQ, "Operator incorrect");
-                Expect.equal(field.Value, 14, "Value incorrect");
-            }),
-            TestCase("GT succeeds", () =>
-            {
-                var field = Field.GT("Great", "night");
-                Expect.equal(field.Name, "Great", "Field name incorrect");
-                Expect.equal(field.Op, Op.GT, "Operator incorrect");
-                Expect.equal(field.Value, "night", "Value incorrect");
-            }),
-            TestCase("GE succeeds", () =>
-            {
-                var field = Field.GE("Nice", 88L);
-                Expect.equal(field.Name, "Nice", "Field name incorrect");
-                Expect.equal(field.Op, Op.GE, "Operator incorrect");
-                Expect.equal(field.Value, 88L, "Value incorrect");
-            }),
-            TestCase("LT succeeds", () =>
-            {
-                var field = Field.LT("Lesser", "seven");
-                Expect.equal(field.Name, "Lesser", "Field name incorrect");
-                Expect.equal(field.Op, Op.LT, "Operator incorrect");
-                Expect.equal(field.Value, "seven", "Value incorrect");
-            }),
-            TestCase("LE succeeds", () =>
-            {
-                var field = Field.LE("Nobody", "KNOWS");
-                Expect.equal(field.Name, "Nobody", "Field name incorrect");
-                Expect.equal(field.Op, Op.LE, "Operator incorrect");
-                Expect.equal(field.Value, "KNOWS", "Value incorrect");
-            }),
-            TestCase("NE succeeds", () =>
-            {
-                var field = Field.NE("Park", "here");
-                Expect.equal(field.Name, "Park", "Field name incorrect");
-                Expect.equal(field.Op, Op.NE, "Operator incorrect");
-                Expect.equal(field.Value, "here", "Value incorrect");
-            }),
-            TestCase("BT succeeds", () =>
-            {
-                var field = Field.BT("Age", 18, 49);
-                Expect.equal(field.Name, "Age", "Field name incorrect");
-                Expect.equal(field.Op, Op.BT, "Operator incorrect");
-                Expect.equal(((FSharpList<object>)field.Value).ToArray(), [18, 49], "Value incorrect");
-            }),
-            TestCase("EX succeeds", () =>
-            {
-                var field = Field.EX("Groovy");
-                Expect.equal(field.Name, "Groovy", "Field name incorrect");
-                Expect.equal(field.Op, Op.EX, "Operator incorrect");
-            }),
-            TestCase("NEX succeeds", () =>
-            {
-                var field = Field.NEX("Rad");
-                Expect.equal(field.Name, "Rad", "Field name incorrect");
-                Expect.equal(field.Op, Op.NEX, "Operator incorrect");
-            }),
-            TestCase("WithParameterName succeeds", () =>
-            {
-                var field = Field.EQ("Bob", "Tom").WithParameterName("@name");
-                Expect.isSome(field.ParameterName, "The parameter name should have been filled");
-                Expect.equal("@name", field.ParameterName.Value, "The parameter name is incorrect");
-            }),
-            TestCase("WithQualifier succeeds", () =>
-            {
-                var field = Field.EQ("Bill", "Matt").WithQualifier("joe");
-                Expect.isSome(field.Qualifier, "The table qualifier should have been filled");
-                Expect.equal("joe", field.Qualifier.Value, "The table qualifier is incorrect");
-            }),
-            TestList("Path",
-            [
-                TestCase("succeeds for a PostgreSQL single field with no qualifier", () =>
-                {
-                    var field = Field.GE("SomethingCool", 18);
-                    Expect.equal("data->>'SomethingCool'", field.Path(Dialect.PostgreSQL),
-                        "The PostgreSQL path is incorrect");
-                }),
-                TestCase("succeeds for a PostgreSQL single field with a qualifier", () =>
-                {
-                    var field = Field.LT("SomethingElse", 9).WithQualifier("this");
-                    Expect.equal("this.data->>'SomethingElse'", field.Path(Dialect.PostgreSQL),
-                        "The PostgreSQL path is incorrect");
-                }),
-                TestCase("succeeds for a PostgreSQL nested field with no qualifier", () =>
-                {
-                    var field = Field.EQ("My.Nested.Field", "howdy");
-                    Expect.equal("data#>>'{My,Nested,Field}'", field.Path(Dialect.PostgreSQL),
-                        "The PostgreSQL path is incorrect");
-                }),
-                TestCase("succeeds for a PostgreSQL nested field with a qualifier", () =>
-                {
-                    var field = Field.EQ("Nest.Away", "doc").WithQualifier("bird");
-                    Expect.equal("bird.data#>>'{Nest,Away}'", field.Path(Dialect.PostgreSQL),
-                        "The PostgreSQL path is incorrect");
-                }),
-                TestCase("succeeds for a SQLite single field with no qualifier", () =>
-                {
-                    var field = Field.GE("SomethingCool", 18);
-                    Expect.equal("data->>'SomethingCool'", field.Path(Dialect.SQLite), "The SQLite path is incorrect");
-                }),
-                TestCase("succeeds for a SQLite single field with a qualifier", () =>
-                {
-                    var field = Field.LT("SomethingElse", 9).WithQualifier("this");
-                    Expect.equal("this.data->>'SomethingElse'", field.Path(Dialect.SQLite),
-                        "The SQLite path is incorrect");
-                }),
-                TestCase("succeeds for a SQLite nested field with no qualifier", () =>
-                {
-                    var field = Field.EQ("My.Nested.Field", "howdy");
-                    Expect.equal("data->>'My'->>'Nested'->>'Field'", field.Path(Dialect.SQLite),
-                        "The SQLite path is incorrect");
-                }),
-                TestCase("succeeds for a SQLite nested field with a qualifier", () =>
-                {
-                    var field = Field.EQ("Nest.Away", "doc").WithQualifier("bird");
-                    Expect.equal("bird.data->>'Nest'->>'Away'", field.Path(Dialect.SQLite),
-                        "The SQLite path is incorrect");
-                })
-            ])
-        ]),
-        TestList("FieldMatch.ToString",
-        [
-            TestCase("succeeds for Any", () =>
-            {
-                Expect.equal(FieldMatch.Any.ToString(), "OR", "SQL for Any is incorrect");
-            }),
-            TestCase("succeeds for All", () =>
-            {
-                Expect.equal(FieldMatch.All.ToString(), "AND", "SQL for All is incorrect");
-            })
-        ]),
-        TestList("ParameterName.Derive",
-        [
-            TestCase("succeeds with existing name", () =>
-            {
-                ParameterName name = new();
-                Expect.equal(name.Derive(FSharpOption<string>.Some("@taco")), "@taco", "Name should have been @taco");
-                Expect.equal(name.Derive(FSharpOption<string>.None), "@field0",
-                    "Counter should not have advanced for named field");
-            }),
-            TestCase("Derive succeeds with non-existent name", () =>
-            {
-                ParameterName name = new();
-                Expect.equal(name.Derive(FSharpOption<string>.None), "@field0",
-                    "Anonymous field name should have been returned");
-                Expect.equal(name.Derive(FSharpOption<string>.None), "@field1",
-                    "Counter should have advanced from previous call");
-                Expect.equal(name.Derive(FSharpOption<string>.None), "@field2",
-                    "Counter should have advanced from previous call");
-                Expect.equal(name.Derive(FSharpOption<string>.None), "@field3",
-                    "Counter should have advanced from previous call");
-            })
-        ]),
-        TestList("Query",
+    ]);
+
+    /// <summary>
+    /// Unit tests for the Query static class
+    /// </summary>
+    private static readonly Test QueryTests = TestList("Query",
     [
         TestCase("StatementWhere succeeds", () =>
         {
@@ -305,7 +532,7 @@ public static class CommonCSharpTests
                 {
                     Expect.equal(
                         Query.Definition.EnsureIndexOn("test.table", "gibberish",
-                                new[] { "taco", "guac DESC", "salsa ASC" }, Dialect.SQLite),
+                            ["taco", "guac DESC", "salsa ASC"], Dialect.SQLite),
                         "CREATE INDEX IF NOT EXISTS idx_table_gibberish ON test.table "
                             + "((data->>'taco'), (data->>'guac') DESC, (data->>'salsa') ASC)",
                         "CREATE INDEX for multiple field statement incorrect");
@@ -321,7 +548,7 @@ public static class CommonCSharpTests
                 {
                     Expect.equal(
                         Query.Definition.EnsureIndexOn("tbl", "nest", ["a.b.c"], Dialect.SQLite),
-                            "CREATE INDEX IF NOT EXISTS idx_tbl_nest ON tbl ((data->>'a'->>'b'->>'c'))",
+                        "CREATE INDEX IF NOT EXISTS idx_tbl_nest ON tbl ((data->'a'->'b'->>'c'))",
                         "CREATE INDEX for nested SQLite field incorrect");
                 })
             ])
@@ -356,7 +583,83 @@ public static class CommonCSharpTests
         TestCase("Delete succeeds", () =>
         {
             Expect.equal(Query.Delete("tbl"), "DELETE FROM tbl", "Delete query not correct");
+        }),
+        TestList("OrderBy",
+        [
+            TestCase("succeeds for no fields", () =>
+            {
+                Expect.equal(Query.OrderBy([], Dialect.PostgreSQL), "", "Order By should have been blank (PostgreSQL)");
+                Expect.equal(Query.OrderBy([], Dialect.SQLite), "", "Order By should have been blank (SQLite)");
+            }),
+            TestCase("succeeds for PostgreSQL with one field and no direction", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("TestField")], Dialect.PostgreSQL),
+                    " ORDER BY data->>'TestField'", "Order By not constructed correctly");
+            }),
+            TestCase("succeeds for SQLite with one field and no direction", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("TestField")], Dialect.SQLite),
+                    " ORDER BY data->>'TestField'", "Order By not constructed correctly");
+            }),
+            TestCase("succeeds for PostgreSQL with multiple fields and direction", () =>
+            {
+                Expect.equal(
+                    Query.OrderBy(
+                        [
+                            Field.Named("Nested.Test.Field DESC"), Field.Named("AnotherField"),
+                            Field.Named("It DESC")
+                        ], Dialect.PostgreSQL),
+                    " ORDER BY data#>>'{Nested,Test,Field}' DESC, data->>'AnotherField', data->>'It' DESC",
+                    "Order By not constructed correctly");
+            }),
+            TestCase("succeeds for SQLite with multiple fields and direction", () =>
+            {
+                Expect.equal(
+                    Query.OrderBy(
+                        [
+                            Field.Named("Nested.Test.Field DESC"), Field.Named("AnotherField"),
+                            Field.Named("It DESC")
+                        ], Dialect.SQLite),
+                    " ORDER BY data->'Nested'->'Test'->>'Field' DESC, data->>'AnotherField', data->>'It' DESC",
+                    "Order By not constructed correctly");
+            }),
+            TestCase("succeeds for PostgreSQL numeric fields", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("n:Test")], Dialect.PostgreSQL),
+                    " ORDER BY (data->>'Test')::numeric", "Order By not constructed correctly for numeric field");
+            }),
+            TestCase("succeeds for SQLite numeric fields", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("n:Test")], Dialect.SQLite), " ORDER BY data->>'Test'",
+                    "Order By not constructed correctly for numeric field");
+            }),
+            TestCase("succeeds for PostgreSQL case-insensitive ordering", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("i:Test.Field DESC NULLS FIRST")], Dialect.PostgreSQL),
+                    " ORDER BY LOWER(data#>>'{Test,Field}') DESC NULLS FIRST",
+                    "Order By not constructed correctly for case-insensitive field");
+            }),
+            TestCase("succeeds for SQLite case-insensitive ordering", () =>
+            {
+                Expect.equal(Query.OrderBy([Field.Named("i:Test.Field ASC NULLS LAST")], Dialect.SQLite),
+                    " ORDER BY data->'Test'->>'Field' COLLATE NOCASE ASC NULLS LAST",
+                    "Order By not constructed correctly for case-insensitive field");
             })
         ])
     ]);
+    
+    /// <summary>
+    /// Unit tests
+    /// </summary>
+    [Tests]
+    public static readonly Test Unit = TestList("Common.C# Unit",
+    [
+        OpTests,
+        FieldTests,
+        FieldMatchTests,
+        ParameterNameTests,
+        AutoIdTests,
+        QueryTests,
+        TestSequenced(ConfigurationTests)
+    ]);
 }

src/Tests.CSharp/PostgresCSharpExtensionTests.cs

@@ -41,7 +41,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var docs = await conn.CustomList(Query.SelectFromTable(PostgresDb.TableName), Parameters.None,
+                var docs = await conn.CustomList(Query.Find(PostgresDb.TableName), Parameters.None,
                     Results.FromData<JsonDocument>);
                 Expect.equal(docs.Count, 5, "There should have been 5 documents returned");
             }),
@@ -53,7 +53,7 @@ public class PostgresCSharpExtensionTests
 
                 var docs = await conn.CustomList(
                     $"SELECT data FROM {PostgresDb.TableName} WHERE data @? @path::jsonpath",
-                    new[] { Tuple.Create("@path", Sql.@string("$.NumValue ? (@ > 100)")) },
+                    [Tuple.Create("@path", Sql.@string("$.NumValue ? (@ > 100)"))],
                     Results.FromData<JsonDocument>);
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
@@ -67,7 +67,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
 
                 var doc = await conn.CustomSingle($"SELECT data FROM {PostgresDb.TableName} WHERE data ->> 'Id' = @id",
-                    new[] { Tuple.Create("@id", Sql.@string("one")) }, Results.FromData<JsonDocument>);
+                    [Tuple.Create("@id", Sql.@string("one"))], Results.FromData<JsonDocument>);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc.Id, "one", "The incorrect document was returned");
             }),
@@ -78,7 +78,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
 
                 var doc = await conn.CustomSingle($"SELECT data FROM {PostgresDb.TableName} WHERE data ->> 'Id' = @id",
-                    new[] { Tuple.Create("@id", Sql.@string("eighty")) }, Results.FromData<JsonDocument>);
+                    [Tuple.Create("@id", Sql.@string("eighty"))], Results.FromData<JsonDocument>);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
@@ -102,7 +102,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
 
                 await conn.CustomNonQuery($"DELETE FROM {PostgresDb.TableName} WHERE data @? @path::jsonpath",
-                    new[] { Tuple.Create("@path", Sql.@string("$.NumValue ? (@ > 100)")) });
+                    [Tuple.Create("@path", Sql.@string("$.NumValue ? (@ > 100)"))]);
         
                 var remaining = await conn.CountAll(PostgresDb.TableName);
                 Expect.equal(remaining, 5, "There should be 5 documents remaining in the table");
@@ -119,55 +119,61 @@ public class PostgresCSharpExtensionTests
         {
             await using var db = PostgresDb.BuildDb();
             await using var conn = MkConn(db);
-            var tableExists = () => conn.CustomScalar(
-                "SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'ensured') AS it", Parameters.None,
-                Results.ToExists);
-            var keyExists = () => conn.CustomScalar(
-                "SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_key') AS it", Parameters.None,
-                Results.ToExists);
 
-            var exists = await tableExists();
-            var alsoExists = await keyExists();
+            var exists = await TableExists();
+            var alsoExists = await KeyExists();
             Expect.isFalse(exists, "The table should not exist already");
             Expect.isFalse(alsoExists, "The key index should not exist already");
 
             await conn.EnsureTable("ensured");
-            exists = await tableExists();
-            alsoExists = await keyExists();
+            exists = await TableExists();
+            alsoExists = await KeyExists();
             Expect.isTrue(exists, "The table should now exist");
             Expect.isTrue(alsoExists, "The key index should now exist");
+            return;
+
+            Task<bool> KeyExists() =>
+                conn.CustomScalar("SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_key') AS it",
+                    Parameters.None, Results.ToExists);
+            Task<bool> TableExists() =>
+                conn.CustomScalar("SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'ensured') AS it",
+                    Parameters.None, Results.ToExists);
         }),
         TestCase("EnsureDocumentIndex succeeds", async () =>
         {
             await using var db = PostgresDb.BuildDb();
             await using var conn = MkConn(db);
-            var indexExists = () => conn.CustomScalar(
-                "SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_document') AS it", Parameters.None,
-                Results.ToExists);
 
-            var exists = await indexExists();
+            var exists = await IndexExists();
             Expect.isFalse(exists, "The index should not exist already");
 
             await conn.EnsureTable("ensured");
             await conn.EnsureDocumentIndex("ensured", DocumentIndex.Optimized);
-            exists = await indexExists();
+            exists = await IndexExists();
             Expect.isTrue(exists, "The index should now exist");
+            return;
+
+            Task<bool> IndexExists() =>
+                conn.CustomScalar("SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_document') AS it",
+                    Parameters.None, Results.ToExists);
         }),
         TestCase("EnsureFieldIndex succeeds", async () =>
         {
             await using var db = PostgresDb.BuildDb();
             await using var conn = MkConn(db);
-            var indexExists = () => conn.CustomScalar(
-                "SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_test') AS it", Parameters.None,
-                Results.ToExists);
 
-            var exists = await indexExists();
+            var exists = await IndexExists();
             Expect.isFalse(exists, "The index should not exist already");
 
             await conn.EnsureTable("ensured");
-            await conn.EnsureFieldIndex("ensured", "test", new[] { "Id", "Category" });
-            exists = await indexExists();
+            await conn.EnsureFieldIndex("ensured", "test", ["Id", "Category"]);
+            exists = await IndexExists();
             Expect.isTrue(exists, "The index should now exist");
+            return;
+
+            Task<bool> IndexExists() =>
+                conn.CustomScalar("SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = 'idx_ensured_test') AS it",
+                    Parameters.None, Results.ToExists);
         }),
         TestList("Insert",
         [
@@ -199,7 +205,7 @@ public class PostgresCSharpExtensionTests
                 }
             })
         ]),
-        TestList("save",
+        TestList("Save",
         [
             TestCase("succeeds when a document is inserted", async () =>
             {
@@ -240,17 +246,16 @@ public class PostgresCSharpExtensionTests
             var theCount = await conn.CountAll(PostgresDb.TableName);
             Expect.equal(theCount, 5, "There should have been 5 matching documents");
         }),
-#pragma warning disable CS0618
-        TestCase("CountByField succeeds", async () =>
+        TestCase("CountByFields succeeds", async () =>
         {
             await using var db = PostgresDb.BuildDb();
             await using var conn = MkConn(db);
             await LoadDocs();
 
-            var theCount = await conn.CountByField(PostgresDb.TableName, Field.EQ("Value", "purple"));
+            var theCount = await conn.CountByFields(PostgresDb.TableName, FieldMatch.Any,
+                [Field.Equal("Value", "purple")]);
             Expect.equal(theCount, 2, "There should have been 2 matching documents");
         }),
-#pragma warning restore CS0618
         TestCase("CountByContains succeeds", async () =>
         {
             await using var db = PostgresDb.BuildDb();
@@ -290,7 +295,6 @@ public class PostgresCSharpExtensionTests
                 Expect.isFalse(exists, "There should not have been an existing document");
             })
         ]),
-#pragma warning disable CS0618
         TestList("ExistsByField",
         [
             TestCase("succeeds when documents exist", async () =>
@@ -299,7 +303,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var exists = await conn.ExistsByField(PostgresDb.TableName, Field.EX("Sub"));
+                var exists = await conn.ExistsByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Exists("Sub")]);
                 Expect.isTrue(exists, "There should have been existing documents");
             }),
             TestCase("succeeds when documents do not exist", async () =>
@@ -308,11 +312,11 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var exists = await conn.ExistsByField(PostgresDb.TableName, Field.EQ("NumValue", "six"));
+                var exists =
+                    await conn.ExistsByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", "six")]);
                 Expect.isFalse(exists, "There should not have been existing documents");
             })
         ]),
-#pragma warning restore CS0618
         TestList("ExistsByContains",
         [
             TestCase("succeeds when documents exist", async () =>
@@ -377,6 +381,44 @@ public class PostgresCSharpExtensionTests
                 Expect.isEmpty(results, "There should have been no documents returned");
             })
         ]),
+        TestList("FindAllOrdered",
+        [
+            TestCase("succeeds when ordering numerically", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var results =
+                    await conn.FindAllOrdered<JsonDocument>(PostgresDb.TableName, [Field.Named("n:NumValue")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "one|three|two|four|five",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering numerically descending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var results =
+                    await conn.FindAllOrdered<JsonDocument>(PostgresDb.TableName, [Field.Named("n:NumValue DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "five|four|two|three|one",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering alphabetically", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var results = await conn.FindAllOrdered<JsonDocument>(PostgresDb.TableName, [Field.Named("Id DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "two|three|one|four|five",
+                    "The documents were not ordered correctly");
+            })
+        ]),
         TestList("FindById",
         [
             TestCase("succeeds when a document is found", async () =>
@@ -399,8 +441,7 @@ public class PostgresCSharpExtensionTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("FindByField",
+        TestList("FindByFields",
         [
             TestCase("succeeds when documents are found", async () =>
             {
@@ -408,7 +449,8 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var docs = await conn.FindByField<JsonDocument>(PostgresDb.TableName, Field.EQ("Value", "another"));
+                var docs = await conn.FindByFields<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "another")]);
                 Expect.equal(docs.Count, 1, "There should have been one document returned");
             }),
             TestCase("succeeds when documents are not found", async () =>
@@ -417,11 +459,38 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var docs = await conn.FindByField<JsonDocument>(PostgresDb.TableName, Field.EQ("Value", "mauve"));
+                var docs = await conn.FindByFields<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "mauve")]);
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
-#pragma warning restore CS0618
+        TestList("FindByFieldsOrdered",
+        [
+            TestCase("succeeds when documents are found", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByFieldsOrdered<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "purple")], [Field.Named("Id")]);
+                Expect.hasLength(docs, 2, "There should have been two document returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "five|four",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when documents are not found", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByFieldsOrdered<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "purple")], [Field.Named("Id DESC")]);
+                Expect.hasLength(docs, 2, "There should have been two document returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "four|five",
+                    "The documents were not ordered correctly");
+            })
+        ]),
         TestList("FindByContains",
         [
             TestCase("succeeds when documents are found", async () =>
@@ -444,6 +513,34 @@ public class PostgresCSharpExtensionTests
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
+        TestList("FindByContainsOrdered",
+        [
+            // Id = two, Sub.Bar = blue; Id = four, Sub.Bar = red
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByContainsOrdered<JsonDocument>(PostgresDb.TableName,
+                    new { Sub = new { Foo = "green" } }, [Field.Named("Sub.Bar")]);
+                Expect.hasLength(docs, 2, "There should have been two documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "two|four",
+                    "Documents not ordered correctly");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByContainsOrdered<JsonDocument>(PostgresDb.TableName,
+                    new { Sub = new { Foo = "green" } }, [Field.Named("Sub.Bar DESC")]);
+                Expect.hasLength(docs, 2, "There should have been two documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "four|two",
+                    "Documents not ordered correctly");
+            })
+        ]),
         TestList("FindByJsonPath",
         [
             TestCase("succeeds when documents are found", async () =>
@@ -465,8 +562,35 @@ public class PostgresCSharpExtensionTests
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("FindFirstByField",
+        TestList("FindByJsonPathOrdered",
+        [
+            // Id = one, NumValue = 0; Id = two, NumValue = 10; Id = three, NumValue = 4
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByJsonPathOrdered<JsonDocument>(PostgresDb.TableName, "$.NumValue ? (@ < 15)",
+                    [Field.Named("n:NumValue")]);
+                Expect.hasLength(docs, 3, "There should have been 3 documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "one|three|two",
+                    "Documents not ordered correctly");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var docs = await conn.FindByJsonPathOrdered<JsonDocument>(PostgresDb.TableName, "$.NumValue ? (@ < 15)",
+                    [Field.Named("n:NumValue DESC")]);
+                Expect.hasLength(docs, 3, "There should have been 3 documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "two|three|one",
+                    "Documents not ordered correctly");
+            })
+        ]),
+        TestList("FindFirstByFields",
         [
             TestCase("succeeds when a document is found", async () =>
             {
@@ -474,7 +598,8 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(PostgresDb.TableName, Field.EQ("Value", "another"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "another")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc.Id, "two", "The incorrect document was returned");
             }),
@@ -484,9 +609,10 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(PostgresDb.TableName, Field.EQ("Value", "purple"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "purple")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
-                Expect.contains(new[] { "five", "four" }, doc.Id, "An incorrect document was returned");
+                Expect.contains(["five", "four"], doc.Id, "An incorrect document was returned");
             }),
             TestCase("succeeds when a document is not found", async () =>
             {
@@ -494,11 +620,36 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(PostgresDb.TableName, Field.EQ("Value", "absent"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "absent")]);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-#pragma warning restore CS0618
+        TestList("FindFirstByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByFieldsOrdered<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "purple")], [Field.Named("Id")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("five", doc.Id, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when a document is not found", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByFieldsOrdered<JsonDocument>(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "purple")], [Field.Named("Id DESC")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("four", doc.Id, "An incorrect document was returned");
+            })
+        ]),
         TestList("FindFirstByContains",
         [
             TestCase("succeeds when a document is found", async () =>
@@ -520,7 +671,7 @@ public class PostgresCSharpExtensionTests
                 var doc = await conn.FindFirstByContains<JsonDocument>(PostgresDb.TableName,
                     new { Sub = new { Foo = "green" } });
                 Expect.isNotNull(doc, "There should have been a document returned");
-                Expect.contains(new[] { "two", "four" }, doc.Id, "An incorrect document was returned");
+                Expect.contains(["two", "four"], doc.Id, "An incorrect document was returned");
             }),
             TestCase("succeeds when a document is not found", async () =>
             {
@@ -532,6 +683,31 @@ public class PostgresCSharpExtensionTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
+        TestList("FindFirstByContainsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByContainsOrdered<JsonDocument>(PostgresDb.TableName,
+                    new { Sub = new { Foo = "green" } }, [Field.Named("Value")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("two", doc.Id, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByContainsOrdered<JsonDocument>(PostgresDb.TableName,
+                    new { Sub = new { Foo = "green" } }, [Field.Named("Value DESC")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("four", doc.Id, "An incorrect document was returned");
+            })
+        ]),
         TestList("FindFirstByJsonPath",
         [
             TestCase("succeeds when a document is found", async () =>
@@ -554,7 +730,7 @@ public class PostgresCSharpExtensionTests
                 var doc = await conn.FindFirstByJsonPath<JsonDocument>(PostgresDb.TableName,
                     "$.Sub.Foo ? (@ == \"green\")");
                 Expect.isNotNull(doc, "There should have been a document returned");
-                Expect.contains(new[] { "two", "four" }, doc.Id, "An incorrect document was returned");
+                Expect.contains(["two", "four"], doc.Id, "An incorrect document was returned");
             }),
             TestCase("succeeds when a document is not found", async () =>
             {
@@ -566,6 +742,31 @@ public class PostgresCSharpExtensionTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
+        TestList("FindFirstByJsonPathOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByJsonPathOrdered<JsonDocument>(PostgresDb.TableName,
+                    "$.Sub.Foo ? (@ == \"green\")", [Field.Named("Sub.Bar")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("two", doc.Id, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = PostgresDb.BuildDb();
+                await using var conn = MkConn(db);
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByJsonPathOrdered<JsonDocument>(PostgresDb.TableName,
+                    "$.Sub.Foo ? (@ == \"green\")", [Field.Named("Sub.Bar DESC")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("four", doc.Id, "An incorrect document was returned");
+            })
+        ]),
         TestList("UpdateById",
         [
             TestCase("succeeds when a document is updated", async () =>
@@ -650,8 +851,7 @@ public class PostgresCSharpExtensionTests
                 await conn.PatchById(PostgresDb.TableName, "test", new { Foo = "green" });
             })
         ]),
-#pragma warning disable CS0618
-        TestList("PatchByField",
+        TestList("PatchByFields",
         [
             TestCase("succeeds when a document is updated", async () =>
             {
@@ -659,8 +859,10 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.PatchByField(PostgresDb.TableName, Field.EQ("Value", "purple"), new { NumValue = 77 });
-                var after = await conn.CountByField(PostgresDb.TableName, Field.EQ("NumValue", "77"));
+                await conn.PatchByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("Value", "purple")],
+                    new { NumValue = 77 });
+                var after = await conn.CountByFields(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.Equal("NumValue", 77)]);
                 Expect.equal(after, 2, "There should have been 2 documents returned");
             }),
             TestCase("succeeds when no document is updated", async () =>
@@ -671,10 +873,10 @@ public class PostgresCSharpExtensionTests
                 Expect.equal(before, 0, "There should have been no documents returned");
                 
                 // This not raising an exception is the test
-                await conn.PatchByField(PostgresDb.TableName, Field.EQ("Value", "burgundy"), new { Foo = "green" });
+                await conn.PatchByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("Value", "burgundy")],
+                    new { Foo = "green" });
             })
         ]),
-#pragma warning restore CS0618
         TestList("PatchByContains",
         [
             TestCase("succeeds when a document is updated", async () =>
@@ -729,7 +931,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsById(PostgresDb.TableName, "two", new[] { "Sub", "Value" });
+                await conn.RemoveFieldsById(PostgresDb.TableName, "two", ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "two");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -741,7 +943,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsById(PostgresDb.TableName, "two", new[] { "Sub" });
+                await conn.RemoveFieldsById(PostgresDb.TableName, "two", ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "two");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.notEqual(updated.Value, "", "The string value should not have been removed");
@@ -754,7 +956,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsById(PostgresDb.TableName, "two", new[] { "AFieldThatIsNotThere" });
+                await conn.RemoveFieldsById(PostgresDb.TableName, "two", ["AFieldThatIsNotThere"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -762,11 +964,10 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsById(PostgresDb.TableName, "two", new[] { "Value" });
+                await conn.RemoveFieldsById(PostgresDb.TableName, "two", ["Value"]);
             })
         ]),
-#pragma warning disable CS0618
-        TestList("RemoveFieldsByField",
+        TestList("RemoveFieldsByFields",
         [
             TestCase("succeeds when multiple fields are removed", async () =>
             {
@@ -774,8 +975,8 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByField(PostgresDb.TableName, Field.EQ("NumValue", "17"),
-                    new[] { "Sub", "Value" });
+                await conn.RemoveFieldsByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", "17")],
+                    ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -787,7 +988,8 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByField(PostgresDb.TableName, Field.EQ("NumValue", "17"), new[] { "Sub" });
+                await conn.RemoveFieldsByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", "17")],
+                    ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.notEqual(updated.Value, "", "The string value should not have been removed");
@@ -800,7 +1002,8 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByField(PostgresDb.TableName, Field.EQ("NumValue", "17"), new[] { "Nothing" });
+                await conn.RemoveFieldsByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", "17")],
+                    ["Nothing"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -808,11 +1011,10 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByField(PostgresDb.TableName, Field.NE("Abracadabra", "apple"),
-                    new[] { "Value" });
+                await conn.RemoveFieldsByFields(PostgresDb.TableName, FieldMatch.Any,
+                    [Field.NotEqual("Abracadabra", "apple")], ["Value"]);
             })
         ]),
-#pragma warning restore CS0618
         TestList("RemoveFieldsByContains",
         [
             TestCase("succeeds when multiple fields are removed", async () =>
@@ -821,8 +1023,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 },
-                    new[] { "Sub", "Value" });
+                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 }, ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -834,7 +1035,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 }, new[] { "Sub" });
+                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 }, ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.notEqual(updated.Value, "", "The string value should not have been removed");
@@ -847,7 +1048,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 }, new[] { "Nothing" });
+                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { NumValue = 17 }, ["Nothing"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -855,8 +1056,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { Abracadabra = "apple" },
-                    new[] { "Value" });
+                await conn.RemoveFieldsByContains(PostgresDb.TableName, new { Abracadabra = "apple" }, ["Value"]);
             })
         ]),
         TestList("RemoveFieldsByJsonPath",
@@ -867,8 +1067,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)",
-                    new[] { "Sub", "Value" });
+                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)", ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -880,7 +1079,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)", new[] { "Sub" });
+                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)", ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(PostgresDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.notEqual(updated.Value, "", "The string value should not have been removed");
@@ -893,7 +1092,7 @@ public class PostgresCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)", new[] { "Nothing" });
+                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.NumValue ? (@ == 17)", ["Nothing"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -901,8 +1100,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.Abracadabra ? (@ == \"apple\")",
-                    new[] { "Value" });
+                await conn.RemoveFieldsByJsonPath(PostgresDb.TableName, "$.Abracadabra ? (@ == \"apple\")", ["Value"]);
             })
         ]),
         TestList("DeleteById",
@@ -928,8 +1126,7 @@ public class PostgresCSharpExtensionTests
                 Expect.equal(remaining, 5, "There should have been 5 documents remaining");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("DeleteByField",
+        TestList("DeleteByFields",
         [
             TestCase("succeeds when documents are deleted", async () =>
             {
@@ -937,7 +1134,7 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.DeleteByField(PostgresDb.TableName, Field.NE("Value", "purple"));
+                await conn.DeleteByFields(PostgresDb.TableName, FieldMatch.Any, [Field.NotEqual("Value", "purple")]);
                 var remaining = await conn.CountAll(PostgresDb.TableName);
                 Expect.equal(remaining, 2, "There should have been 2 documents remaining");
             }),
@@ -947,12 +1144,11 @@ public class PostgresCSharpExtensionTests
                 await using var conn = MkConn(db);
                 await LoadDocs();
 
-                await conn.DeleteByField(PostgresDb.TableName, Field.EQ("Value", "crimson"));
+                await conn.DeleteByFields(PostgresDb.TableName, FieldMatch.Any, [Field.Equal("Value", "crimson")]);
                 var remaining = await conn.CountAll(PostgresDb.TableName);
                 Expect.equal(remaining, 5, "There should have been 5 documents remaining");
             })
         ]),
-#pragma warning restore CS0618
         TestList("DeleteByContains",
         [
             TestCase("succeeds when documents are deleted", async () =>

src/Tests.CSharp/PostgresDb.cs

@@ -1,4 +1,3 @@
-using BitBadger.Documents.Postgres;
 using Npgsql;
 using Npgsql.FSharp;
 using ThrowawayDb.Postgres;

src/Tests.CSharp/SqliteCSharpExtensionTests.cs

@@ -1,6 +1,5 @@
 using Expecto.CSharp;
 using Expecto;
-using Microsoft.Data.Sqlite;
 using BitBadger.Documents.Sqlite;
 
 namespace BitBadger.Documents.Tests.CSharp;
@@ -29,7 +28,7 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
 
                 var doc = await conn.CustomSingle($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                    new[] { Parameters.Id("one") }, Results.FromData<JsonDocument>);
+                    [Parameters.Id("one")], Results.FromData<JsonDocument>);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc!.Id, "one", "The incorrect document was returned");
             }),
@@ -40,7 +39,7 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
 
                 var doc = await conn.CustomSingle($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                    new[] { Parameters.Id("eighty") }, Results.FromData<JsonDocument>);
+                    [Parameters.Id("eighty")], Results.FromData<JsonDocument>);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
@@ -52,7 +51,7 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var docs = await conn.CustomList(Query.SelectFromTable(SqliteDb.TableName), Parameters.None,
+                var docs = await conn.CustomList(Query.Find(SqliteDb.TableName), Parameters.None,
                     Results.FromData<JsonDocument>);
                 Expect.equal(docs.Count, 5, "There should have been 5 documents returned");
             }),
@@ -63,8 +62,8 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
 
                 var docs = await conn.CustomList(
-                    $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
-                    new[] { new SqliteParameter("@value", 100) }, Results.FromData<JsonDocument>);
+                    $"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");
             })
         ]),
@@ -88,7 +87,7 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
 
                 await conn.CustomNonQuery($"DELETE FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
-                    new[] { new SqliteParameter("@value", 100) });
+                    [new("@value", 100)]);
 
                 var remaining = await conn.CountAll(SqliteDb.TableName);
                 Expect.equal(remaining, 5L, "There should be 5 documents remaining in the table");
@@ -107,38 +106,41 @@ public static class SqliteCSharpExtensionTests
             await using var db = await SqliteDb.BuildDb();
             await using var conn = Sqlite.Configuration.DbConn();
 
-            Func<string, ValueTask<bool>> itExists = async name =>
-                await conn.CustomScalar(
-                    $"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = @name) AS it",
-                    new SqliteParameter[] { new("@name", name) }, Results.ToExists);
-
-            var exists = await itExists("ensured");
-            var alsoExists = await itExists("idx_ensured_key");
+            var exists = await ItExists("ensured");
+            var alsoExists = await ItExists("idx_ensured_key");
             Expect.isFalse(exists, "The table should not exist already");
             Expect.isFalse(alsoExists, "The key index should not exist already");
 
             await conn.EnsureTable("ensured");
 
-            exists = await itExists("ensured");
-            alsoExists = await itExists("idx_ensured_key");
+            exists = await ItExists("ensured");
+            alsoExists = await ItExists("idx_ensured_key");
             Expect.isTrue(exists, "The table should now exist");
             Expect.isTrue(alsoExists, "The key index should now exist");
+            return;
+
+            Task<bool> ItExists(string name) =>
+                conn.CustomScalar($"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = @name) AS it",
+                    [new("@name", name)], Results.ToExists);
         }),
         TestCase("EnsureFieldIndex succeeds", async () =>
         {
             await using var db = await SqliteDb.BuildDb();
             await using var conn = Sqlite.Configuration.DbConn();
-            var indexExists = () => conn.CustomScalar(
-                $"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = 'idx_ensured_test') AS it",
-                Parameters.None, Results.ToExists);
 
-            var exists = await indexExists();
+            var exists = await IndexExists();
             Expect.isFalse(exists, "The index should not exist already");
 
             await conn.EnsureTable("ensured");
-            await conn.EnsureFieldIndex("ensured", "test", new[] { "Id", "Category" });
-            exists = await indexExists();
+            await conn.EnsureFieldIndex("ensured", "test", ["Id", "Category"]);
+            exists = await IndexExists();
             Expect.isTrue(exists, "The index should now exist");
+            return;
+
+            Task<bool> IndexExists() =>
+                conn.CustomScalar(
+                    $"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = 'idx_ensured_test') AS it",
+                    Parameters.None, Results.ToExists);
         }),
         TestList("Insert",
         [
@@ -213,17 +215,16 @@ public static class SqliteCSharpExtensionTests
             var theCount = await conn.CountAll(SqliteDb.TableName);
             Expect.equal(theCount, 5L, "There should have been 5 matching documents");
         }),
-#pragma warning disable CS0618
         TestCase("CountByField succeeds", async () =>
         {
             await using var db = await SqliteDb.BuildDb();
             await using var conn = Sqlite.Configuration.DbConn();
             await LoadDocs();
 
-            var theCount = await conn.CountByField(SqliteDb.TableName, Field.EQ("Value", "purple"));
+            var theCount = await conn.CountByFields(SqliteDb.TableName, FieldMatch.Any,
+                [Field.Equal("Value", "purple")]);
             Expect.equal(theCount, 2L, "There should have been 2 matching documents");
         }),
-#pragma warning restore CS0618
         TestList("ExistsById",
         [
             TestCase("succeeds when a document exists", async () =>
@@ -245,8 +246,7 @@ public static class SqliteCSharpExtensionTests
                 Expect.isFalse(exists, "There should not have been an existing document");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("ExistsByField",
+        TestList("ExistsByFields",
         [
             TestCase("succeeds when documents exist", async () =>
             {
@@ -254,7 +254,8 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var exists = await conn.ExistsByField(SqliteDb.TableName, Field.GE("NumValue", 10));
+                var exists = await conn.ExistsByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.GreaterOrEqual("NumValue", 10)]);
                 Expect.isTrue(exists, "There should have been existing documents");
             }),
             TestCase("succeeds when no matching documents exist", async () =>
@@ -263,11 +264,11 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var exists = await conn.ExistsByField(SqliteDb.TableName, Field.EQ("Nothing", "none"));
+                var exists =
+                    await conn.ExistsByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Nothing", "none")]);
                 Expect.isFalse(exists, "There should not have been any existing documents");
             })
         ]),
-#pragma warning restore CS0618
         TestList("FindAll",
         [
             TestCase("succeeds when there is data", async () =>
@@ -290,6 +291,43 @@ public static class SqliteCSharpExtensionTests
                 Expect.isEmpty(results, "There should have been no documents returned");
             })
         ]),
+        TestList("FindAllOrdered",
+        [
+            TestCase("succeeds when ordering numerically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var results = await conn.FindAllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("n:NumValue")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "one|three|two|four|five",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering numerically descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var results =
+                    await conn.FindAllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("n:NumValue DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "five|four|two|three|one",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering alphabetically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var results = await conn.FindAllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("Id DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "two|three|one|four|five",
+                    "The documents were not ordered correctly");
+            })
+        ]),
         TestList("FindById",
         [
             TestCase("succeeds when a document is found", async () =>
@@ -312,8 +350,7 @@ public static class SqliteCSharpExtensionTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("FindByField",
+        TestList("FindByFields",
         [
             TestCase("succeeds when documents are found", async () =>
             {
@@ -321,7 +358,8 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var docs = await conn.FindByField<JsonDocument>(SqliteDb.TableName, Field.GT("NumValue", 15));
+                var docs = await conn.FindByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)]);
                 Expect.equal(docs.Count, 2, "There should have been two documents returned");
             }),
             TestCase("succeeds when documents are not found", async () =>
@@ -330,11 +368,37 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var docs = await conn.FindByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "mauve"));
+                var docs = await conn.FindByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "mauve")]);
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
-        TestList("FindFirstByField",
+        TestList("ByFieldsOrdered",
+        [
+            TestCase("succeeds when documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var docs = await conn.FindByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id")]);
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "five|four",
+                    "There should have been two documents returned");
+            }),
+            TestCase("succeeds when documents are not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var docs = await conn.FindByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id DESC")]);
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "four|five",
+                    "There should have been two documents returned");
+            })
+        ]),
+        TestList("FindFirstByFields",
         [
             TestCase("succeeds when a document is found", async () =>
             {
@@ -342,7 +406,8 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "another"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "another")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc!.Id, "two", "The incorrect document was returned");
             }),
@@ -352,9 +417,10 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Sub.Foo", "green"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
-                Expect.contains(new[] { "two", "four" }, doc!.Id, "An incorrect document was returned");
+                Expect.contains(["two", "four"], doc!.Id, "An incorrect document was returned");
             }),
             TestCase("succeeds when a document is not found", async () =>
             {
@@ -362,11 +428,36 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                var doc = await conn.FindFirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "absent"));
+                var doc = await conn.FindFirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "absent")]);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-#pragma warning restore CS0618
+        TestList("FindFirstByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("two", doc!.Id, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await using var conn = Sqlite.Configuration.DbConn();
+                await LoadDocs();
+
+                var doc = await conn.FindFirstByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar DESC")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("four", doc!.Id, "An incorrect document was returned");
+            })
+        ]),
         TestList("UpdateById",
         [
             TestCase("succeeds when a document is updated", async () =>
@@ -450,8 +541,7 @@ public static class SqliteCSharpExtensionTests
                 await conn.PatchById(SqliteDb.TableName, "test", new { Foo = "green" });
             })
         ]),
-#pragma warning disable CS0618
-        TestList("PatchByField",
+        TestList("PatchByFields",
         [
             TestCase("succeeds when a document is updated", async () =>
             {
@@ -459,8 +549,9 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                await conn.PatchByField(SqliteDb.TableName, Field.EQ("Value", "purple"), new { NumValue = 77 });
-                var after = await conn.CountByField(SqliteDb.TableName, Field.EQ("NumValue", 77));
+                await conn.PatchByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "purple")],
+                    new { NumValue = 77 });
+                var after = await conn.CountByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 77)]);
                 Expect.equal(after, 2L, "There should have been 2 documents returned");
             }),
             TestCase("succeeds when no document is updated", async () =>
@@ -471,10 +562,10 @@ public static class SqliteCSharpExtensionTests
                 Expect.isEmpty(before, "There should have been no documents returned");
 
                 // This not raising an exception is the test
-                await conn.PatchByField(SqliteDb.TableName, Field.EQ("Value", "burgundy"), new { Foo = "green" });
+                await conn.PatchByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "burgundy")],
+                    new { Foo = "green" });
             })
         ]),
-#pragma warning restore CS0618
         TestList("RemoveFieldsById",
         [
             TestCase("succeeds when fields are removed", async () =>
@@ -483,7 +574,7 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                await conn.RemoveFieldsById(SqliteDb.TableName, "two", new[] { "Sub", "Value" });
+                await conn.RemoveFieldsById(SqliteDb.TableName, "two", ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(SqliteDb.TableName, "two");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -496,7 +587,7 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsById(SqliteDb.TableName, "two", new[] { "AFieldThatIsNotThere" });
+                await conn.RemoveFieldsById(SqliteDb.TableName, "two", ["AFieldThatIsNotThere"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -504,11 +595,10 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsById(SqliteDb.TableName, "two", new[] { "Value" });
+                await conn.RemoveFieldsById(SqliteDb.TableName, "two", ["Value"]);
             })
         ]),
-#pragma warning disable CS0618
-        TestList("RemoveFieldsByField",
+        TestList("RemoveFieldsByFields",
         [
             TestCase("succeeds when a field is removed", async () =>
             {
@@ -516,7 +606,8 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                await conn.RemoveFieldsByField(SqliteDb.TableName, Field.EQ("NumValue", 17), new[] { "Sub" });
+                await conn.RemoveFieldsByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 17)],
+                    ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(SqliteDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.isNull(updated.Sub, "The sub-document should have been removed");
@@ -528,7 +619,8 @@ public static class SqliteCSharpExtensionTests
                 await LoadDocs();
                     
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByField(SqliteDb.TableName, Field.EQ("NumValue", 17), new[] { "Nothing" });
+                await conn.RemoveFieldsByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 17)],
+                    ["Nothing"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
@@ -536,10 +628,10 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 
                 // This not raising an exception is the test
-                await conn.RemoveFieldsByField(SqliteDb.TableName, Field.NE("Abracadabra", "apple"), new[] { "Value" });
+                await conn.RemoveFieldsByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.NotEqual("Abracadabra", "apple")], ["Value"]);
             })
         ]),
-#pragma warning restore CS0618
         TestList("DeleteById",
         [
             TestCase("succeeds when a document is deleted", async () =>
@@ -563,8 +655,7 @@ public static class SqliteCSharpExtensionTests
                 Expect.equal(remaining, 5L, "There should have been 5 documents remaining");
             })
         ]),
-#pragma warning disable CS0618
-        TestList("DeleteByField",
+        TestList("DeleteByFields",
         [
             TestCase("succeeds when documents are deleted", async () =>
             {
@@ -572,7 +663,7 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                await conn.DeleteByField(SqliteDb.TableName, Field.NE("Value", "purple"));
+                await conn.DeleteByFields(SqliteDb.TableName, FieldMatch.Any, [Field.NotEqual("Value", "purple")]);
                 var remaining = await conn.CountAll(SqliteDb.TableName);
                 Expect.equal(remaining, 2L, "There should have been 2 documents remaining");
             }),
@@ -582,12 +673,11 @@ public static class SqliteCSharpExtensionTests
                 await using var conn = Sqlite.Configuration.DbConn();
                 await LoadDocs();
 
-                await conn.DeleteByField(SqliteDb.TableName, Field.EQ("Value", "crimson"));
+                await conn.DeleteByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "crimson")]);
                 var remaining = await conn.CountAll(SqliteDb.TableName);
                 Expect.equal(remaining, 5L, "There should have been 5 documents remaining");
             })
         ]),
-#pragma warning restore CS0618
         TestCase("Clean up database", () => Sqlite.Configuration.UseConnectionString("data source=:memory:"))
     ]);
 }

src/Tests.CSharp/SqliteCSharpTests.cs

@@ -1,6 +1,5 @@
 using Expecto.CSharp;
 using Expecto;
-using Microsoft.Data.Sqlite;
 using Microsoft.FSharp.Core;
 using BitBadger.Documents.Sqlite;
 
@@ -14,11 +13,9 @@ using static Runner;
 public static class SqliteCSharpTests
 {
     /// <summary>
-    /// Unit tests for the SQLite library
+    /// Unit tests for the Query module of the SQLite library
     /// </summary>
-    private static readonly Test Unit = TestList("Unit",
-    [
-        TestList("Query",
+    private static readonly Test QueryTests = TestList("Query",
     [
         TestList("WhereByFields",
         [
@@ -26,41 +23,54 @@ public static class SqliteCSharpTests
             {
                 Expect.equal(
                     Sqlite.Query.WhereByFields(FieldMatch.Any,
-                            [Field.GT("theField", 0).WithParameterName("@test")]),
+                        [Field.Greater("theField", 0).WithParameterName("@test")]),
                     "data->>'theField' > @test", "WHERE clause not correct");
             }),
             TestCase("succeeds for a single field when an existence operator is passed", () =>
             {
-                    Expect.equal(Sqlite.Query.WhereByFields(FieldMatch.Any, [Field.NEX("thatField")]),
+                Expect.equal(Sqlite.Query.WhereByFields(FieldMatch.Any, [Field.NotExists("thatField")]),
                     "data->>'thatField' IS NULL", "WHERE clause not correct");
             }),
             TestCase("succeeds for a single field when a between operator is passed", () =>
             {
                 Expect.equal(
                     Sqlite.Query.WhereByFields(FieldMatch.All,
-                            [Field.BT("aField", 50, 99).WithParameterName("@range")]),
+                        [Field.Between("aField", 50, 99).WithParameterName("@range")]),
                     "data->>'aField' BETWEEN @rangemin AND @rangemax", "WHERE clause not correct");
             }),
             TestCase("succeeds for all multiple fields with logical operators", () =>
             {
                 Expect.equal(
                     Sqlite.Query.WhereByFields(FieldMatch.All,
-                            [Field.EQ("theFirst", "1"), Field.EQ("numberTwo", "2")]),
+                        [Field.Equal("theFirst", "1"), Field.Equal("numberTwo", "2")]),
                     "data->>'theFirst' = @field0 AND data->>'numberTwo' = @field1", "WHERE clause not correct");
             }),
             TestCase("succeeds for any multiple fields with an existence operator", () =>
             {
                 Expect.equal(
-                        Sqlite.Query.WhereByFields(FieldMatch.Any, [Field.NEX("thatField"), Field.GE("thisField", 18)]),
+                    Sqlite.Query.WhereByFields(FieldMatch.Any,
+                        [Field.NotExists("thatField"), Field.GreaterOrEqual("thisField", 18)]),
                     "data->>'thatField' IS NULL OR data->>'thisField' >= @field0", "WHERE clause not correct");
             }),
             TestCase("succeeds for all multiple fields with between operators", () =>
             {
                 Expect.equal(
                     Sqlite.Query.WhereByFields(FieldMatch.All,
-                            [Field.BT("aField", 50, 99), Field.BT("anotherField", "a", "b")]),
+                        [Field.Between("aField", 50, 99), Field.Between("anotherField", "a", "b")]),
                     "data->>'aField' BETWEEN @field0min AND @field0max AND data->>'anotherField' BETWEEN @field1min AND @field1max",
                     "WHERE clause not correct");
+            }),
+            TestCase("succeeds for a field with an In comparison", () =>
+            {
+                Expect.equal(Sqlite.Query.WhereByFields(FieldMatch.All, [Field.In("this", ["a", "b", "c"])]),
+                    "data->>'this' IN (@field0_0, @field0_1, @field0_2)", "WHERE clause not correct");
+            }),
+            TestCase("succeeds for a field with an InArray comparison", () =>
+            {
+                Expect.equal(
+                    Sqlite.Query.WhereByFields(FieldMatch.All, [Field.InArray("this", "the_table", ["a", "b"])]),
+                    "EXISTS (SELECT 1 FROM json_each(the_table.data, '$.this') WHERE value IN (@field0_0, @field0_1))",
+                    "WHERE clause not correct");
             })
         ]),
         TestCase("WhereById succeeds", () =>
@@ -80,12 +90,11 @@ public static class SqliteCSharpTests
         }),
         TestCase("ById succeeds", () =>
         {
-                Expect.equal(Sqlite.Query.ById("test", "14"), "test WHERE data->>'Id' = @id",
-                    "By-ID query not correct");
+            Expect.equal(Sqlite.Query.ById("test", "14"), "test WHERE data->>'Id' = @id", "By-ID query not correct");
         }),
         TestCase("ByFields succeeds", () =>
         {
-                Expect.equal(Sqlite.Query.ByFields("unit", FieldMatch.Any, [Field.GT("That", 14)]),
+            Expect.equal(Sqlite.Query.ByFields("unit", FieldMatch.Any, [Field.Greater("That", 14)]),
                 "unit WHERE data->>'That' > @field0", "By-Field query not correct");
         }),
         TestCase("Definition.EnsureTable succeeds", () =>
@@ -93,8 +102,12 @@ public static class SqliteCSharpTests
             Expect.equal(Sqlite.Query.Definition.EnsureTable("tbl"),
                 "CREATE TABLE IF NOT EXISTS tbl (data TEXT NOT NULL)", "CREATE TABLE statement not correct");
         })
-        ]),
-        TestList("Parameters",
+    ]);
+
+    /// <summary>
+    /// Unit tests for the Parameters module of the SQLite library
+    /// </summary>
+    private static readonly Test ParametersTests = TestList("Parameters",
     [
         TestCase("Id succeeds", () =>
         {
@@ -111,7 +124,7 @@ public static class SqliteCSharpTests
 #pragma warning disable CS0618
         TestCase("AddField succeeds when adding a parameter", () =>
         {
-                var paramList = Parameters.AddField("@field", Field.EQ("it", 99), []).ToList();
+            var paramList = Parameters.AddField("@field", Field.Equal("it", 99), []).ToList();
             Expect.hasLength(paramList, 1, "There should have been a parameter added");
             var theParam = paramList[0];
             Expect.equal(theParam.ParameterName, "@field", "The parameter name is incorrect");
@@ -119,7 +132,7 @@ public static class SqliteCSharpTests
         }),
         TestCase("AddField succeeds when not adding a parameter", () =>
         {
-                var paramSeq = Parameters.AddField("@it", Field.EX("Coffee"), []);
+            var paramSeq = Parameters.AddField("@it", Field.Exists("Coffee"), []);
             Expect.isEmpty(paramSeq, "There should not have been any parameters added");
         }),
 #pragma warning restore CS0618
@@ -127,30 +140,22 @@ public static class SqliteCSharpTests
         {
             Expect.isEmpty(Parameters.None, "The parameter list should have been empty");
         })
-        ])
-        // Results are exhaustively executed in the context of other tests
     ]);
     
-    private static readonly List<JsonDocument> TestDocuments =
-    [
-        new() { Id = "one", Value = "FIRST!", NumValue = 0 },
-        new() { Id = "two", Value = "another", NumValue = 10, Sub = new() { Foo = "green", Bar = "blue" } },
-        new() { Id = "three", Value = "", NumValue = 4 },
-        new() { Id = "four", Value = "purple", NumValue = 17, Sub = new() { Foo = "green", Bar = "red" } },
-        new() { Id = "five", Value = "purple", NumValue = 18 }
-    ];
+    // Results are exhaustively executed in the context of other tests
     
     /// <summary>
     /// Add the test documents to the database
     /// </summary>
     internal static async Task LoadDocs()
     {
-        foreach (var doc in TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
+        foreach (var doc in JsonDocument.TestDocuments) await Document.Insert(SqliteDb.TableName, doc);
     }
 
-    private static readonly Test Integration = TestList("Integration",
-    [
-        TestCase("Configuration.UseConnectionString succeeds", () =>
+    /// <summary>
+    /// Integration tests for the Configuration module of the SQLite library
+    /// </summary>
+    private static readonly Test ConfigurationTests = TestCase("Configuration.UseConnectionString succeeds", () =>
     {
         try
         {
@@ -162,8 +167,12 @@ public static class SqliteCSharpTests
         {
             Sqlite.Configuration.UseConnectionString("Data Source=:memory:");
         }
-        }),
-        TestList("Custom",
+    });
+
+    /// <summary>
+    /// Integration tests for the Custom module of the SQLite library
+    /// </summary>
+    private static readonly Test CustomTests = TestList("Custom",
     [
         TestList("Single",
         [
@@ -173,7 +182,7 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 var doc = await Custom.Single($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                        new[] { Parameters.Id("one") }, Results.FromData<JsonDocument>);
+                    [Parameters.Id("one")], Results.FromData<JsonDocument>);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc!.Id, "one", "The incorrect document was returned");
             }),
@@ -183,7 +192,7 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 var doc = await Custom.Single($"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'Id' = @id",
-                        new[] { Parameters.Id("eighty") }, Results.FromData<JsonDocument>);
+                    [Parameters.Id("eighty")], Results.FromData<JsonDocument>);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
@@ -194,7 +203,7 @@ public static class SqliteCSharpTests
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var docs = await Custom.List(Query.SelectFromTable(SqliteDb.TableName), Parameters.None,
+                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");
             }),
@@ -204,8 +213,8 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 var docs = await Custom.List(
-                        $"SELECT data FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
-                        new[] { new SqliteParameter("@value", 100) }, Results.FromData<JsonDocument>);
+                    $"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");
             })
         ]),
@@ -227,7 +236,7 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 await Custom.NonQuery($"DELETE FROM {SqliteDb.TableName} WHERE data ->> 'NumValue' > @value",
-                        new[] { new SqliteParameter("@value", 100) });
+                    [new("@value", 100)]);
 
                 var remaining = await Count.All(SqliteDb.TableName);
                 Expect.equal(remaining, 5L, "There should be 5 documents remaining in the table");
@@ -240,8 +249,12 @@ public static class SqliteCSharpTests
             var nbr = await Custom.Scalar("SELECT 5 AS test_value", Parameters.None, rdr => rdr.GetInt32(0));
             Expect.equal(nbr, 5, "The query should have returned the number 5");
         })
-        ]),
-        TestList("Definition",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Definition module of the SQLite library
+    /// </summary>
+    private static readonly Test DefinitionTests = TestList("Definition",
     [
         TestCase("EnsureTable succeeds", async () =>
         {
@@ -262,9 +275,8 @@ public static class SqliteCSharpTests
 
             async ValueTask<bool> ItExists(string name)
             {
-                    return await Custom.Scalar(
-                        $"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = @name) AS it",
-                        new SqliteParameter[] { new("@name", name) }, Results.ToExists);
+                return await Custom.Scalar($"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = @name) AS it",
+                    [new("@name", name)], Results.ToExists);
             }
         }),
         TestCase("EnsureFieldIndex succeeds", async () =>
@@ -275,7 +287,7 @@ public static class SqliteCSharpTests
             Expect.isFalse(exists, "The index should not exist already");
 
             await Definition.EnsureTable("ensured");
-                await Definition.EnsureFieldIndex("ensured", "test", new[] { "Id", "Category" });
+            await Definition.EnsureFieldIndex("ensured", "test", ["Id", "Category"]);
             exists = await IndexExists();
             Expect.isTrue(exists, "The index should now exist");
             return;
@@ -284,8 +296,14 @@ public static class SqliteCSharpTests
                 $"SELECT EXISTS (SELECT 1 FROM {SqliteDb.Catalog} WHERE name = 'idx_ensured_test') AS it",
                 Parameters.None, Results.ToExists);
         })
-        ]),
-        TestList("Document.Insert",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Document module of the SQLite library
+    /// </summary>
+    private static readonly Test DocumentTests = TestList("Document",
+    [
+        TestList("Insert",
         [
             TestCase("succeeds", async () =>
             {
@@ -310,9 +328,86 @@ public static class SqliteCSharpTests
                 {
                     // This is what is supposed to happen
                 }
+            }),
+            TestCase("succeeds when adding a numeric auto ID", async () =>
+            {
+                try
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.Number);
+                    Configuration.UseIdField("Key");
+                    await using var db = await SqliteDb.BuildDb();
+                    var before = await Count.All(SqliteDb.TableName);
+                    Expect.equal(before, 0L, "There should be no documents in the table");
+
+                    await Document.Insert(SqliteDb.TableName, new NumIdDocument { Text = "one" });
+                    await Document.Insert(SqliteDb.TableName, new NumIdDocument { Text = "two" });
+                    await Document.Insert(SqliteDb.TableName, new NumIdDocument { Key = 77, Text = "three" });
+                    await Document.Insert(SqliteDb.TableName, new NumIdDocument { Text = "four" });
+
+                    var after = await Find.AllOrdered<NumIdDocument>(SqliteDb.TableName, [Field.Named("Key")]);
+                    Expect.hasLength(after, 4, "There should have been 4 documents returned");
+                    Expect.sequenceEqual(after.Select(x => x.Key), [1, 2, 77, 78],
+                        "The IDs were not generated correctly");
+                }
+                finally
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.Disabled);
+                    Configuration.UseIdField("Id");
+                }
+            }),
+            TestCase("succeeds when adding a GUID auto ID", async () =>
+            {
+                try
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.Guid);
+                    await using var db = await SqliteDb.BuildDb();
+                    var before = await Count.All(SqliteDb.TableName);
+                    Expect.equal(before, 0L, "There should be no documents in the table");
+
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "one" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "two" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Id = "abc123", Value = "three" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "four" });
+
+                    var after = await Find.All<JsonDocument>(SqliteDb.TableName);
+                    Expect.hasLength(after, 4, "There should have been 4 documents returned");
+                    Expect.equal(after.Count(x => x.Id.Length == 32), 3, "Three of the IDs should have been GUIDs");
+                    Expect.equal(after.Count(x => x.Id == "abc123"), 1, "The provided ID should have been used as-is");
+                }
+                finally
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.Disabled);
+                }
+            }),
+            TestCase("succeeds when adding a RandomString auto ID", async () =>
+            {
+                try
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.RandomString);
+                    Configuration.UseIdStringLength(44);
+                    await using var db = await SqliteDb.BuildDb();
+                    var before = await Count.All(SqliteDb.TableName);
+                    Expect.equal(before, 0L, "There should be no documents in the table");
+
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "one" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "two" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Id = "abc123", Value = "three" });
+                    await Document.Insert(SqliteDb.TableName, new JsonDocument { Value = "four" });
+
+                    var after = await Find.All<JsonDocument>(SqliteDb.TableName);
+                    Expect.hasLength(after, 4, "There should have been 4 documents returned");
+                    Expect.equal(after.Count(x => x.Id.Length == 44), 3,
+                        "Three of the IDs should have been 44-character random strings");
+                    Expect.equal(after.Count(x => x.Id == "abc123"), 1, "The provided ID should have been used as-is");
+                }
+                finally
+                {
+                    Configuration.UseAutoIdStrategy(AutoId.Disabled);
+                    Configuration.UseIdStringLength(16);
+                }
             })
         ]),
-        TestList("Document.Save",
+        TestList("Save",
         [
             TestCase("succeeds when a document is inserted", async () =>
             {
@@ -344,8 +439,13 @@ public static class SqliteCSharpTests
                 Expect.equal(after!.Id, "test", "The updated document is not correct");
                 Expect.isNull(after.Sub, "There should not have been a sub-document in the updated document");
             })
-        ]),
-        TestList("Count",
+        ])
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Count module of the SQLite library
+    /// </summary>
+    private static readonly Test CountTests = TestList("Count",
     [
         TestCase("All succeeds", async () =>
         {
@@ -355,26 +455,33 @@ public static class SqliteCSharpTests
             var theCount = await Count.All(SqliteDb.TableName);
             Expect.equal(theCount, 5L, "There should have been 5 matching documents");
         }),
-#pragma warning disable CS0618
-            TestCase("ByField succeeds for numeric range", async () =>
+        TestList("ByFields",
+        [
+            TestCase("succeeds for numeric range", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                var theCount = await Count.ByField(SqliteDb.TableName, Field.BT("NumValue", 10, 20));
+                var theCount = await Count.ByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Between("NumValue", 10, 20)]);
                 Expect.equal(theCount, 3L, "There should have been 3 matching documents");
             }),
-            TestCase("ByField succeeds for non-numeric range", async () =>
+            TestCase("succeeds for non-numeric range", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                var theCount = await Count.ByField(SqliteDb.TableName, Field.BT("Value", "aardvark", "apple"));
+                var theCount = await Count.ByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Between("Value", "aardvark", "apple")]);
                 Expect.equal(theCount, 1L, "There should have been 1 matching document");
             })
-#pragma warning restore CS0618
-        ]),
-        TestList("Exists",
+        ])
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Exists module of the SQLite library
+    /// </summary>
+    private static readonly Test ExistsTests = TestList("Exists",
     [
         TestList("ById",
         [
@@ -395,15 +502,15 @@ public static class SqliteCSharpTests
                 Expect.isFalse(exists, "There should not have been an existing document");
             })
         ]),
-#pragma warning disable CS0618
-            TestList("ByField",
+        TestList("ByFields",
         [
             TestCase("succeeds when documents exist", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var exists = await Exists.ByField(SqliteDb.TableName, Field.GE("NumValue", 10));
+                var exists = await Exists.ByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.GreaterOrEqual("NumValue", 10)]);
                 Expect.isTrue(exists, "There should have been existing documents");
             }),
             TestCase("succeeds when no matching documents exist", async () =>
@@ -411,13 +518,17 @@ public static class SqliteCSharpTests
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var exists = await Exists.ByField(SqliteDb.TableName, Field.EQ("Nothing", "none"));
+                var exists = await Exists.ByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Nothing", "none")]);
                 Expect.isFalse(exists, "There should not have been any existing documents");
             })
         ])
-#pragma warning restore CS0618
-        ]),
-        TestList("Find",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Find module of the SQLite library
+    /// </summary>
+    private static readonly Test FindTests = TestList("Find",
     [
         TestList("All",
         [
@@ -439,6 +550,39 @@ public static class SqliteCSharpTests
                 Expect.isEmpty(results, "There should have been no documents returned");
             })
         ]),
+        TestList("AllOrdered",
+        [
+            TestCase("succeeds when ordering numerically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var results = await Find.AllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("n:NumValue")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "one|three|two|four|five",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering numerically descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var results = await Find.AllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("n:NumValue DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "five|four|two|three|one",
+                    "The documents were not ordered correctly");
+            }),
+            TestCase("succeeds when ordering alphabetically", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var results = await Find.AllOrdered<JsonDocument>(SqliteDb.TableName, [Field.Named("Id DESC")]);
+                Expect.hasLength(results, 5, "There should have been 5 documents returned");
+                Expect.equal(string.Join('|', results.Select(x => x.Id)), "two|three|one|four|five",
+                    "The documents were not ordered correctly");
+            })
+        ]),
         TestList("ById",
         [
             TestCase("succeeds when a document is found", async () =>
@@ -459,34 +603,112 @@ public static class SqliteCSharpTests
                 Expect.isNull(doc, "There should not have been a document returned");
             })
         ]),
-#pragma warning disable CS0618
-            TestList("ByField",
+        TestList("ByFields",
         [
             TestCase("succeeds when documents are found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var docs = await Find.ByField<JsonDocument>(SqliteDb.TableName, Field.GT("NumValue", 15));
+                var docs = await Find.ByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)]);
                 Expect.equal(docs.Count, 2, "There should have been two documents returned");
             }),
+            TestCase("succeeds when documents are found using IN with numeric field", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Find.ByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.All,
+                    [Field.In("NumValue", [2, 4, 6, 8])]);
+                Expect.hasLength(docs, 1, "There should have been one document returned");
+            }),
             TestCase("succeeds when documents are not found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var docs = await Find.ByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "mauve"));
+                var docs = await Find.ByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "mauve")]);
+                Expect.isEmpty(docs, "There should have been no documents returned");
+            }),
+            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 docs = await Find.ByFields<ArrayDocument>(SqliteDb.TableName, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["c"])]);
+                Expect.hasLength(docs, 2, "There should have been two document 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);
+
+                var docs = await Find.ByFields<ArrayDocument>(SqliteDb.TableName, FieldMatch.All,
+                    [Field.InArray("Values", SqliteDb.TableName, ["j"])]);
                 Expect.isEmpty(docs, "There should have been no documents returned");
             })
         ]),
-            TestList("FirstByField",
+        TestList("ByFieldsOrdered",
+        [
+            TestCase("succeeds when documents are found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Find.ByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id")]);
+                Expect.hasLength(docs, 2, "There should have been two documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "five|four",
+                    "The documents were not sorted correctly");
+            }),
+            TestCase("succeeds when documents are not found", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Find.ByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Greater("NumValue", 15)], [Field.Named("Id DESC")]);
+                Expect.hasLength(docs, 2, "There should have been two documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "four|five",
+                    "The documents were not sorted correctly");
+            }),
+            TestCase("succeeds when sorting case-sensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Find.ByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.LessOrEqual("NumValue", 10)], [Field.Named("Value")]);
+                Expect.hasLength(docs, 3, "There should have been three documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "three|one|two",
+                    "The documents were not sorted correctly");
+            }),
+            TestCase("succeeds when sorting case-insensitively", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var docs = await Find.ByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.LessOrEqual("NumValue", 10)], [Field.Named("i:Value")]);
+                Expect.hasLength(docs, 3, "There should have been three documents returned");
+                Expect.equal(string.Join('|', docs.Select(x => x.Id)), "three|two|one",
+                    "The documents were not sorted correctly");
+            })
+        ]),
+        TestList("FirstByFields",
         [
             TestCase("succeeds when a document is found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var doc = await Find.FirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "another"));
+                var doc = await Find.FirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "another")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
                 Expect.equal(doc!.Id, "two", "The incorrect document was returned");
             }),
@@ -495,22 +717,50 @@ public static class SqliteCSharpTests
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var doc = await Find.FirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Sub.Foo", "green"));
+                var doc = await Find.FirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")]);
                 Expect.isNotNull(doc, "There should have been a document returned");
-                    Expect.contains(new[] { "two", "four" }, doc!.Id, "An incorrect document was returned");
+                Expect.contains(["two", "four"], doc!.Id, "An incorrect document was returned");
             }),
             TestCase("succeeds when a document is not found", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    var doc = await Find.FirstByField<JsonDocument>(SqliteDb.TableName, Field.EQ("Value", "absent"));
+                var doc = await Find.FirstByFields<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Value", "absent")]);
                 Expect.isNull(doc, "There should not have been a document returned");
             })
-            ])
-#pragma warning restore CS0618
         ]),
-        TestList("Update",
+        TestList("FirstByFieldsOrdered",
+        [
+            TestCase("succeeds when sorting ascending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var doc = await Find.FirstByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("two", doc!.Id, "An incorrect document was returned");
+            }),
+            TestCase("succeeds when sorting descending", async () =>
+            {
+                await using var db = await SqliteDb.BuildDb();
+                await LoadDocs();
+
+                var doc = await Find.FirstByFieldsOrdered<JsonDocument>(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.Equal("Sub.Foo", "green")], [Field.Named("Sub.Bar DESC")]);
+                Expect.isNotNull(doc, "There should have been a document returned");
+                Expect.equal("four", doc!.Id, "An incorrect document was returned");
+            })
+        ])
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Update module of the SQLite library
+    /// </summary>
+    private static readonly Test UpdateTests = TestList("Update",
     [
         TestList("ById",
         [
@@ -568,8 +818,12 @@ public static class SqliteCSharpTests
                     new JsonDocument { Id = "one", Value = "le un", NumValue = 1 });
             })
         ]),
-        ]),
-        TestList("Patch",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Patch module of the SQLite library
+    /// </summary>
+    private static readonly Test PatchTests = TestList("Patch",
     [
         TestList("ById",
         [
@@ -595,16 +849,16 @@ public static class SqliteCSharpTests
                 await Patch.ById(SqliteDb.TableName, "test", new { Foo = "green" });
             })
         ]),
-#pragma warning disable CS0618
-            TestList("ByField",
+        TestList("ByFields",
         [
             TestCase("succeeds when a document is updated", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    await Patch.ByField(SqliteDb.TableName, Field.EQ("Value", "purple"), new { NumValue = 77 });
-                    var after = await Count.ByField(SqliteDb.TableName, Field.EQ("NumValue", 77));
+                await Patch.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "purple")],
+                    new { NumValue = 77 });
+                var after = await Count.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 77)]);
                 Expect.equal(after, 2L, "There should have been 2 documents returned");
             }),
             TestCase("succeeds when no document is updated", async () =>
@@ -615,12 +869,16 @@ public static class SqliteCSharpTests
                 Expect.isEmpty(before, "There should have been no documents returned");
 
                 // This not raising an exception is the test
-                    await Patch.ByField(SqliteDb.TableName, Field.EQ("Value", "burgundy"), new { Foo = "green" });
+                await Patch.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("Value", "burgundy")],
+                    new { Foo = "green" });
             })
         ])
-#pragma warning restore CS0618
-        ]),
-        TestList("RemoveFields",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the RemoveFields module of the SQLite library
+    /// </summary>
+    private static readonly Test RemoveFieldsTests = TestList("RemoveFields",
     [
         TestList("ById",
         [
@@ -629,7 +887,7 @@ public static class SqliteCSharpTests
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    await RemoveFields.ById(SqliteDb.TableName, "two", new[] { "Sub", "Value" });
+                await RemoveFields.ById(SqliteDb.TableName, "two", ["Sub", "Value"]);
                 var updated = await Find.ById<string, JsonDocument>(SqliteDb.TableName, "two");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.equal(updated.Value, "", "The string value should have been removed");
@@ -641,25 +899,24 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 // This not raising an exception is the test
-                    await RemoveFields.ById(SqliteDb.TableName, "two", new[] { "AFieldThatIsNotThere" });
+                await RemoveFields.ById(SqliteDb.TableName, "two", ["AFieldThatIsNotThere"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
 
                 // This not raising an exception is the test
-                    await RemoveFields.ById(SqliteDb.TableName, "two", new[] { "Value" });
+                await RemoveFields.ById(SqliteDb.TableName, "two", ["Value"]);
             })
         ]),
-#pragma warning disable CS0618
-            TestList("ByField",
+        TestList("ByFields",
         [
             TestCase("succeeds when a field is removed", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    await RemoveFields.ByField(SqliteDb.TableName, Field.EQ("NumValue", 17), new[] { "Sub" });
+                await RemoveFields.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 17)], ["Sub"]);
                 var updated = await Find.ById<string, JsonDocument>(SqliteDb.TableName, "four");
                 Expect.isNotNull(updated, "The updated document should have been retrieved");
                 Expect.isNull(updated.Sub, "The sub-document should have been removed");
@@ -670,19 +927,24 @@ public static class SqliteCSharpTests
                 await LoadDocs();
 
                 // This not raising an exception is the test
-                    await RemoveFields.ByField(SqliteDb.TableName, Field.EQ("NumValue", 17), new[] { "Nothing" });
+                await RemoveFields.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.Equal("NumValue", 17)],
+                    ["Nothing"]);
             }),
             TestCase("succeeds when no document is matched", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
 
                 // This not raising an exception is the test
-                    await RemoveFields.ByField(SqliteDb.TableName, Field.NE("Abracadabra", "apple"), new[] { "Value" });
+                await RemoveFields.ByFields(SqliteDb.TableName, FieldMatch.Any,
+                    [Field.NotEqual("Abracadabra", "apple")], ["Value"]);
             })
         ])
-#pragma warning restore CS0618
-        ]),
-        TestList("Delete",
+    ]);
+
+    /// <summary>
+    /// Integration tests for the Delete module of the SQLite library
+    /// </summary>
+    private static readonly Test DeleteTests = TestList("Delete",
     [
         TestList("ById",
         [
@@ -705,15 +967,14 @@ public static class SqliteCSharpTests
                 Expect.equal(remaining, 5L, "There should have been 5 documents remaining");
             })
         ]),
-#pragma warning disable CS0618
-            TestList("ByField",
+        TestList("ByFields",
         [
             TestCase("succeeds when documents are deleted", async () =>
             {
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    await Delete.ByField(SqliteDb.TableName, Field.NE("Value", "purple"));
+                await Delete.ByFields(SqliteDb.TableName, FieldMatch.Any, [Field.NotEqual("Value", "purple")]);
                 var remaining = await Count.All(SqliteDb.TableName);
                 Expect.equal(remaining, 2L, "There should have been 2 documents remaining");
             }),
@@ -722,19 +983,34 @@ public static class SqliteCSharpTests
                 await using var db = await SqliteDb.BuildDb();
                 await LoadDocs();
 
-                    await Delete.ByField(SqliteDb.TableName, Field.EQ("Value", "crimson"));
+                await Delete.ByFields(SqliteDb.TableName, FieldMatch.All, [Field.Equal("Value", "crimson")]);
                 var remaining = await Count.All(SqliteDb.TableName);
                 Expect.equal(remaining, 5L, "There should have been 5 documents remaining");
             })
         ])
-#pragma warning restore CS0618
-        ]),
-        TestCase("Clean up database", () => Sqlite.Configuration.UseConnectionString("data source=:memory:"))
     ]);
     
     /// <summary>
     /// All tests for SQLite C# functions and methods
     /// </summary>
     [Tests]
-    public static readonly Test All = TestList("Sqlite.C#", [Unit, TestSequenced(Integration)]);
+    public static readonly Test All = TestList("Sqlite.C#",
+    [
+        TestList("Unit", [QueryTests, ParametersTests]),
+        TestSequenced(TestList("Integration",
+        [
+            ConfigurationTests,
+            CustomTests,
+            DefinitionTests,
+            DocumentTests,
+            CountTests,
+            ExistsTests,
+            FindTests,
+            UpdateTests,
+            PatchTests,
+            RemoveFieldsTests,
+            DeleteTests,
+            TestCase("Clean up database", () => Sqlite.Configuration.UseConnectionString("data source=:memory:"))
+        ]))
+    ]);
 }

src/Tests.CSharp/Types.cs

@@ -1,5 +1,11 @@
 namespace BitBadger.Documents.Tests.CSharp;
 
+public class NumIdDocument
+{
+    public int Key { get; set; } = 0;
+    public string Text { get; set; } = "";
+}
+
 public class SubDocument
 {
     public string Foo { get; set; } = "";
@@ -12,4 +18,32 @@ public class JsonDocument
     public string Value { get; set; } = "";
     public int NumValue { get; set; } = 0;
     public SubDocument? Sub { get; set; } = null;
+    
+    /// <summary>
+    /// A set of documents used for integration tests
+    /// </summary>
+    public static readonly List<JsonDocument> TestDocuments =
+    [
+        new() { Id = "one", Value = "FIRST!", NumValue = 0 },
+        new() { Id = "two", Value = "another", NumValue = 10, Sub = new() { Foo = "green", Bar = "blue" } },
+        new() { Id = "three", Value = "", NumValue = 4 },
+        new() { Id = "four", Value = "purple", NumValue = 17, Sub = new() { Foo = "green", Bar = "red" } },
+        new() { Id = "five", Value = "purple", NumValue = 18 }
+    ];
+}
+
+public class ArrayDocument
+{
+    public string Id { get; set; } = "";
+    public string[] Values { get; set; } = [];
+
+    /// <summary>
+    /// A set of documents used for integration tests
+    /// </summary>
+    public static readonly List<ArrayDocument> TestDocuments =
+    [
+        new() { Id = "first", Values = ["a", "b", "c"] },
+        new() { Id = "second", Values = ["c", "d", "e"] },
+        new() { Id = "third", Values = ["x", "y", "z"] }
+    ];
 }

src/Tests/BitBadger.Documents.Tests.fsproj

@@ -2,11 +2,12 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
+    <NoWarn>1182</NoWarn>
   </PropertyGroup>
 
   <ItemGroup>
-    <Compile Include="CommonTests.fs" />
     <Compile Include="Types.fs" />
+    <Compile Include="CommonTests.fs" />
     <Compile Include="PostgresTests.fs" />
     <Compile Include="PostgresExtensionTests.fs" />
     <Compile Include="SqliteTests.fs" />
@@ -16,7 +17,7 @@
 
   <ItemGroup>
     <PackageReference Include="Expecto" Version="10.2.1" />
-    <PackageReference Update="FSharp.Core" Version="8.0.300" />
+    <PackageReference Update="FSharp.Core" Version="9.0.100" />
   </ItemGroup>
 
   <ItemGroup>

src/Tests/CommonTests.fs

@@ -6,156 +6,196 @@ open Expecto
 /// Test table name
 let tbl = "test_table"
 
-/// Tests which do not hit the database
-let all =
-    testList "Common" [
-        testList "Op" [
-            test "EQ succeeds" {
-                Expect.equal (string EQ) "=" "The equals operator was not correct"
+/// Unit tests for the Op DU
+let comparisonTests = testList "Comparison.OpSql" [
+    test "Equal succeeds" {
+        Expect.equal (Equal "").OpSql "=" "The Equals SQL was not correct"
     }
-            test "GT succeeds" {
-                Expect.equal (string GT) ">" "The greater than operator was not correct"
+    test "Greater succeeds" {
+        Expect.equal (Greater "").OpSql ">" "The Greater SQL was not correct"
     }
-            test "GE succeeds" {
-                Expect.equal (string GE) ">=" "The greater than or equal to operator was not correct"
+    test "GreaterOrEqual succeeds" {
+        Expect.equal (GreaterOrEqual "").OpSql ">=" "The GreaterOrEqual SQL was not correct"
     }
-            test "LT succeeds" {
-                Expect.equal (string LT) "<" "The less than operator was not correct"
+    test "Less succeeds" {
+        Expect.equal (Less "").OpSql "<" "The Less SQL was not correct"
     }
-            test "LE succeeds" {
-                Expect.equal (string LE) "<=" "The less than or equal to operator was not correct"
+    test "LessOrEqual succeeds" {
+        Expect.equal (LessOrEqual "").OpSql "<=" "The LessOrEqual SQL was not correct"
     }
-            test "NE succeeds" {
-                Expect.equal (string NE) "<>" "The not equal to operator was not correct"
+    test "NotEqual succeeds" {
+        Expect.equal (NotEqual "").OpSql "<>" "The NotEqual SQL was not correct"
     }
-            test "BT succeeds" {
-                Expect.equal (string BT) "BETWEEN" """The "between" operator was not correct"""
+    test "Between succeeds" {
+        Expect.equal (Between("", "")).OpSql "BETWEEN" "The Between SQL was not correct"
     }
-            test "EX succeeds" {
-                Expect.equal (string EX) "IS NOT NULL" """The "exists" operator was not correct"""
+    test "In succeeds" {
+        Expect.equal (In []).OpSql "IN" "The In SQL was not correct"
     }
-            test "NEX succeeds" {
-                Expect.equal (string NEX) "IS NULL" """The "not exists" operator was not correct"""
+    test "InArray succeeds" {
+        Expect.equal (InArray("", [])).OpSql "?|" "The InArray SQL was not correct"
+    }
+    test "Exists succeeds" {
+        Expect.equal Exists.OpSql "IS NOT NULL" "The Exists SQL was not correct"
+    }
+    test "NotExists succeeds" {
+        Expect.equal NotExists.OpSql "IS NULL" "The NotExists SQL was not correct"
     }
 ]
-        testList "Field" [
-            test "EQ succeeds" {
-                let field = Field.EQ "Test" 14
+
+/// Unit tests for the Field class
+let fieldTests = testList "Field" [
+    test "Equal succeeds" {
+        let field = Field.Equal "Test" 14
         Expect.equal field.Name "Test" "Field name incorrect"
-                Expect.equal field.Op EQ "Operator incorrect"
-                Expect.equal field.Value 14 "Value incorrect"
+        Expect.equal field.Comparison (Equal 14) "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "GT succeeds" {
-                let field = Field.GT "Great" "night"
+    test "Greater succeeds" {
+        let field = Field.Greater "Great" "night"
         Expect.equal field.Name "Great" "Field name incorrect"
-                Expect.equal field.Op GT "Operator incorrect"
-                Expect.equal field.Value "night" "Value incorrect"
+        Expect.equal field.Comparison (Greater "night") "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "GE succeeds" {
-                let field = Field.GE "Nice" 88L
+    test "GreaterOrEqual succeeds" {
+        let field = Field.GreaterOrEqual "Nice" 88L
         Expect.equal field.Name "Nice" "Field name incorrect"
-                Expect.equal field.Op GE "Operator incorrect"
-                Expect.equal field.Value 88L "Value incorrect"
+        Expect.equal field.Comparison (GreaterOrEqual 88L) "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "LT succeeds" {
-                let field = Field.LT "Lesser" "seven"
+    test "Less succeeds" {
+        let field = Field.Less "Lesser" "seven"
         Expect.equal field.Name "Lesser" "Field name incorrect"
-                Expect.equal field.Op LT "Operator incorrect"
-                Expect.equal field.Value "seven" "Value incorrect"
+        Expect.equal field.Comparison (Less "seven") "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "LE succeeds" {
-                let field = Field.LE "Nobody" "KNOWS";
+    test "LessOrEqual succeeds" {
+        let field = Field.LessOrEqual "Nobody" "KNOWS";
         Expect.equal field.Name "Nobody" "Field name incorrect"
-                Expect.equal field.Op LE "Operator incorrect"
-                Expect.equal field.Value "KNOWS" "Value incorrect"
+        Expect.equal field.Comparison (LessOrEqual "KNOWS") "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "NE succeeds" {
-                let field = Field.NE "Park" "here"
+    test "NotEqual succeeds" {
+        let field = Field.NotEqual "Park" "here"
         Expect.equal field.Name "Park" "Field name incorrect"
-                Expect.equal field.Op NE "Operator incorrect"
-                Expect.equal field.Value "here" "Value incorrect"
+        Expect.equal field.Comparison (NotEqual "here") "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "BT succeeds" {
-                let field = Field.BT "Age" 18 49
+    test "Between succeeds" {
+        let field = Field.Between "Age" 18 49
         Expect.equal field.Name "Age" "Field name incorrect"
-                Expect.equal field.Op BT "Operator incorrect"
-                Expect.sequenceEqual (field.Value :?> obj list) [ 18; 49 ] "Value incorrect"
+        Expect.equal field.Comparison (Between(18, 49)) "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "EX succeeds" {
-                let field = Field.EX "Groovy"
+    test "In succeeds" {
+        let field = Field.In "Here" [| 8; 16; 32 |]
+        Expect.equal field.Name "Here" "Field name incorrect"
+        match field.Comparison with
+        | In values -> Expect.equal (List.ofSeq values) [ box 8; box 16; box 32 ] "Comparison incorrect"
+        | it -> Expect.isTrue false $"Expected In, received %A{it}"
+        Expect.isNone field.ParameterName "The default parameter name should be None"
+        Expect.isNone field.Qualifier "The default table qualifier should be None"
+    }
+    test "InArray succeeds" {
+        let field = Field.InArray "ArrayField" "table" [| "z" |]
+        Expect.equal field.Name "ArrayField" "Field name incorrect"
+        match field.Comparison with
+        | InArray (table, values) ->
+            Expect.equal table "table" "Comparison table incorrect"
+            Expect.equal (List.ofSeq values) [ box "z" ] "Comparison values incorrect"
+        | it -> Expect.isTrue false $"Expected InArray, received %A{it}"
+        Expect.isNone field.ParameterName "The default parameter name should be None"
+        Expect.isNone field.Qualifier "The default table qualifier should be None"
+    }
+    test "Exists succeeds" {
+        let field = Field.Exists "Groovy"
         Expect.equal field.Name "Groovy" "Field name incorrect"
-                Expect.equal field.Op EX "Operator incorrect"
+        Expect.equal field.Comparison Exists "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
-            test "NEX succeeds" {
-                let field = Field.NEX "Rad"
+    test "NotExists succeeds" {
+        let field = Field.NotExists "Rad"
         Expect.equal field.Name "Rad" "Field name incorrect"
-                Expect.equal field.Op NEX "Operator incorrect"
+        Expect.equal field.Comparison NotExists "Comparison incorrect"
         Expect.isNone field.ParameterName "The default parameter name should be None"
         Expect.isNone field.Qualifier "The default table qualifier should be None"
     }
+    testList "NameToPath" [
+        test "succeeds for PostgreSQL and a simple name" {
+            Expect.equal "data->>'Simple'" (Field.NameToPath "Simple" PostgreSQL AsSql) "Path not constructed correctly"
+        }
+        test "succeeds for SQLite and a simple name" {
+            Expect.equal "data->>'Simple'" (Field.NameToPath "Simple" SQLite AsSql) "Path not constructed correctly"
+        }
+        test "succeeds for PostgreSQL and a nested name" {
+            Expect.equal
+                "data#>>'{A,Long,Path,to,the,Property}'"
+                (Field.NameToPath "A.Long.Path.to.the.Property" PostgreSQL AsSql)
+                "Path not constructed correctly"
+        }
+        test "succeeds for SQLite and a nested name" {
+            Expect.equal
+                "data->'A'->'Long'->'Path'->'to'->'the'->>'Property'"
+                (Field.NameToPath "A.Long.Path.to.the.Property" SQLite AsSql)
+                "Path not constructed correctly"
+        }
+    ]
     test "WithParameterName succeeds" {
-                let field = (Field.EQ "Bob" "Tom").WithParameterName "@name"
+        let field = (Field.Equal "Bob" "Tom").WithParameterName "@name"
         Expect.isSome field.ParameterName "The parameter name should have been filled"
         Expect.equal "@name" field.ParameterName.Value "The parameter name is incorrect"
     }
     test "WithQualifier succeeds" {
-                let field = (Field.EQ "Bill" "Matt").WithQualifier "joe"
+        let field = (Field.Equal "Bill" "Matt").WithQualifier "joe"
         Expect.isSome field.Qualifier "The table qualifier should have been filled"
         Expect.equal "joe" field.Qualifier.Value "The table qualifier is incorrect"
     }
     testList "Path" [
         test "succeeds for a PostgreSQL single field with no qualifier" {
-                    let field = Field.GE "SomethingCool" 18
-                    Expect.equal "data->>'SomethingCool'" (field.Path PostgreSQL) "The PostgreSQL path is incorrect"
+            let field = Field.GreaterOrEqual "SomethingCool" 18
+            Expect.equal "data->>'SomethingCool'" (field.Path PostgreSQL AsSql) "The PostgreSQL path is incorrect"
         }
         test "succeeds for a PostgreSQL single field with a qualifier" {
-                    let field = { Field.LT "SomethingElse" 9 with Qualifier = Some "this" }
-                    Expect.equal
-                        "this.data->>'SomethingElse'" (field.Path PostgreSQL) "The PostgreSQL path is incorrect"
+            let field = { Field.Less "SomethingElse" 9 with Qualifier = Some "this" }
+            Expect.equal "this.data->>'SomethingElse'" (field.Path PostgreSQL AsSql) "The PostgreSQL path is incorrect"
         }
         test "succeeds for a PostgreSQL nested field with no qualifier" {
-                    let field = Field.EQ "My.Nested.Field" "howdy"
-                    Expect.equal "data#>>'{My,Nested,Field}'" (field.Path PostgreSQL) "The PostgreSQL path is incorrect"
+            let field = Field.Equal "My.Nested.Field" "howdy"
+            Expect.equal "data#>>'{My,Nested,Field}'" (field.Path PostgreSQL AsSql) "The PostgreSQL path is incorrect"
         }
         test "succeeds for a PostgreSQL nested field with a qualifier" {
-                    let field = { Field.EQ "Nest.Away" "doc" with Qualifier = Some "bird" } 
-                    Expect.equal "bird.data#>>'{Nest,Away}'" (field.Path PostgreSQL) "The PostgreSQL path is incorrect"
+            let field = { Field.Equal "Nest.Away" "doc" with Qualifier = Some "bird" } 
+            Expect.equal "bird.data#>>'{Nest,Away}'" (field.Path PostgreSQL AsSql) "The PostgreSQL path is incorrect"
         }
         test "succeeds for a SQLite single field with no qualifier" {
-                    let field = Field.GE "SomethingCool" 18
-                    Expect.equal "data->>'SomethingCool'" (field.Path SQLite) "The SQLite path is incorrect"
+            let field = Field.GreaterOrEqual "SomethingCool" 18
+            Expect.equal "data->>'SomethingCool'" (field.Path SQLite AsSql) "The SQLite path is incorrect"
         }
         test "succeeds for a SQLite single field with a qualifier" {
-                    let field = { Field.LT "SomethingElse" 9 with Qualifier = Some "this" }
-                    Expect.equal "this.data->>'SomethingElse'" (field.Path SQLite) "The SQLite path is incorrect"
+            let field = { Field.Less "SomethingElse" 9 with Qualifier = Some "this" }
+            Expect.equal "this.data->>'SomethingElse'" (field.Path SQLite AsSql) "The SQLite path is incorrect"
         }
         test "succeeds for a SQLite nested field with no qualifier" {
-                    let field = Field.EQ "My.Nested.Field" "howdy"
-                    Expect.equal "data->>'My'->>'Nested'->>'Field'" (field.Path SQLite) "The SQLite path is incorrect"
+            let field = Field.Equal "My.Nested.Field" "howdy"
+            Expect.equal "data->'My'->'Nested'->>'Field'" (field.Path SQLite AsSql) "The SQLite path is incorrect"
         }
         test "succeeds for a SQLite nested field with a qualifier" {
-                    let field = { Field.EQ "Nest.Away" "doc" with Qualifier = Some "bird" } 
-                    Expect.equal "bird.data->>'Nest'->>'Away'" (field.Path SQLite) "The SQLite path is incorrect"
+            let field = { Field.Equal "Nest.Away" "doc" with Qualifier = Some "bird" } 
+            Expect.equal "bird.data->'Nest'->>'Away'" (field.Path SQLite AsSql) "The SQLite path is incorrect"
         }
     ]
 ]
-        testList "FieldMatch.ToString" [
+
+/// Unit tests for the FieldMatch DU
+let fieldMatchTests = testList "FieldMatch.ToString" [
     test "succeeds for Any" {
         Expect.equal (string Any) "OR" "SQL for Any is incorrect"
     }
@@ -163,7 +203,9 @@ let all =
         Expect.equal (string All) "AND" "SQL for All is incorrect"
     }
 ]
-        testList "ParameterName.Derive" [
+
+/// Unit tests for the ParameterName class
+let parameterNameTests = testList "ParameterName.Derive" [
     test "succeeds with existing name" {
         let name = ParameterName()
         Expect.equal (name.Derive(Some "@taco")) "@taco" "Name should have been @taco"
@@ -177,7 +219,136 @@ let all =
         Expect.equal (name.Derive None) "@field3" "Counter should have advanced from previous call"
     }
 ]
-        testList "Query" [
+
+/// Unit tests for the AutoId DU
+let autoIdTests = testList "AutoId" [
+    test "GenerateGuid succeeds" {
+        let autoId = AutoId.GenerateGuid()
+        Expect.isNotNull autoId "The GUID auto-ID should not have been null"
+        Expect.stringHasLength autoId 32 "The GUID auto-ID should have been 32 characters long"
+        Expect.equal autoId (autoId.ToLowerInvariant ()) "The GUID auto-ID should have been lowercase"
+    }
+    test "GenerateRandomString succeeds" {
+        [ 6; 8; 12; 20; 32; 57; 64 ]
+        |> List.iter (fun length ->
+            let autoId = AutoId.GenerateRandomString length
+            Expect.isNotNull autoId $"Random string ({length}) should not have been null"
+            Expect.stringHasLength autoId length $"Random string should have been {length} characters long"
+            Expect.equal autoId (autoId.ToLowerInvariant ()) $"Random string ({length}) should have been lowercase")
+    }
+    testList "NeedsAutoId" [
+        test "succeeds when no auto ID is configured" {
+            Expect.isFalse (AutoId.NeedsAutoId Disabled (obj ()) "id") "Disabled auto-ID never needs an automatic ID"
+        }
+        test "fails for any when the ID property is not found" {
+            Expect.throwsT<System.InvalidOperationException>
+                (fun () -> AutoId.NeedsAutoId Number {| Key = "" |} "Id" |> ignore)
+                "Non-existent ID property should have thrown an exception"
+        }
+        test "succeeds for byte when the ID is zero" {
+            Expect.isTrue (AutoId.NeedsAutoId Number {| Id = int8 0 |} "Id") "Zero ID should have returned true"
+        }
+        test "succeeds for byte when the ID is non-zero" {
+            Expect.isFalse (AutoId.NeedsAutoId Number {| Id = int8 4 |} "Id") "Non-zero ID should have returned false"
+        }
+        test "succeeds for short when the ID is zero" {
+            Expect.isTrue (AutoId.NeedsAutoId Number {| Id = int16 0 |} "Id") "Zero ID should have returned true"
+        }
+        test "succeeds for short when the ID is non-zero" {
+            Expect.isFalse (AutoId.NeedsAutoId Number {| Id = int16 7 |} "Id") "Non-zero ID should have returned false"
+        }
+        test "succeeds for int when the ID is zero" {
+            Expect.isTrue (AutoId.NeedsAutoId Number {| Id = 0 |} "Id") "Zero ID should have returned true"
+        }
+        test "succeeds for int when the ID is non-zero" {
+            Expect.isFalse (AutoId.NeedsAutoId Number {| Id = 32 |} "Id") "Non-zero ID should have returned false"
+        }
+        test "succeeds for long when the ID is zero" {
+            Expect.isTrue (AutoId.NeedsAutoId Number {| Id = 0L |} "Id") "Zero ID should have returned true"
+        }
+        test "succeeds for long when the ID is non-zero" {
+            Expect.isFalse (AutoId.NeedsAutoId Number {| Id = 80L |} "Id") "Non-zero ID should have returned false"
+        }
+        test "fails for number when the ID is not a number" {
+            Expect.throwsT<System.InvalidOperationException>
+                (fun () -> AutoId.NeedsAutoId Number {| Id = "" |} "Id" |> ignore)
+                "Numeric ID against a string should have thrown an exception"
+        }
+        test "succeeds for GUID when the ID is blank" {
+            Expect.isTrue (AutoId.NeedsAutoId Guid {| Id = "" |} "Id") "Blank ID should have returned true"
+        }
+        test "succeeds for GUID when the ID is filled" {
+            Expect.isFalse (AutoId.NeedsAutoId Guid {| Id = "abc" |} "Id") "Filled ID should have returned false"
+        }
+        test "fails for GUID when the ID is not a string" {
+            Expect.throwsT<System.InvalidOperationException>
+                (fun () -> AutoId.NeedsAutoId Guid {| Id = 8 |} "Id" |> ignore)
+                "String ID against a number should have thrown an exception"
+        }
+        test "succeeds for RandomString when the ID is blank" {
+            Expect.isTrue (AutoId.NeedsAutoId RandomString {| Id = "" |} "Id") "Blank ID should have returned true"
+        }
+        test "succeeds for RandomString when the ID is filled" {
+            Expect.isFalse (AutoId.NeedsAutoId RandomString {| Id = "x" |} "Id") "Filled ID should have returned false"
+        }
+        test "fails for RandomString when the ID is not a string" {
+            Expect.throwsT<System.InvalidOperationException>
+                (fun () -> AutoId.NeedsAutoId RandomString {| Id = 33 |} "Id" |> ignore)
+                "String ID against a number should have thrown an exception"
+        }
+    ]
+]
+
+/// Unit tests for the Configuration module
+let configurationTests = testList "Configuration" [
+    test "useSerializer succeeds" {
+        try
+            Configuration.useSerializer
+                { new IDocumentSerializer with
+                    member _.Serialize<'T>(it: 'T) : string = """{"Overridden":true}"""
+                    member _.Deserialize<'T>(it: string) : 'T = Unchecked.defaultof<'T>
+                }
+            
+            let serialized = Configuration.serializer().Serialize {| Foo = "howdy"; Bar = "bye" |}
+            Expect.equal serialized """{"Overridden":true}""" "Specified serializer was not used"
+            
+            let deserialized = Configuration.serializer().Deserialize<obj> """{"Something":"here"}"""
+            Expect.isNull deserialized "Specified serializer should have returned null"
+        finally
+            Configuration.useSerializer DocumentSerializer.``default``
+    }
+    test "serializer returns configured serializer" {
+        Expect.isTrue (obj.ReferenceEquals(DocumentSerializer.``default``, Configuration.serializer ()))
+            "Serializer should have been the same"
+    }
+    test "useIdField / idField succeeds" {
+        try
+            Expect.equal (Configuration.idField ()) "Id" "The default configured ID field was incorrect"
+            Configuration.useIdField "id"
+            Expect.equal (Configuration.idField ()) "id" "useIdField did not set the ID field"
+        finally
+            Configuration.useIdField "Id"
+    }
+    test "useAutoIdStrategy / autoIdStrategy succeeds" {
+        try
+            Expect.equal (Configuration.autoIdStrategy ()) Disabled "The default auto-ID strategy was incorrect"
+            Configuration.useAutoIdStrategy Guid
+            Expect.equal (Configuration.autoIdStrategy ()) Guid "The auto-ID strategy was not set correctly"
+        finally
+            Configuration.useAutoIdStrategy Disabled
+    }
+    test "useIdStringLength / idStringLength succeeds" {
+        try
+            Expect.equal (Configuration.idStringLength ()) 16 "The default ID string length was incorrect"
+            Configuration.useIdStringLength 33
+            Expect.equal (Configuration.idStringLength ()) 33 "The ID string length was not set correctly"
+        finally
+            Configuration.useIdStringLength 16
+    }
+]
+
+/// Unit tests for the Query module
+let queryTests = testList "Query" [
     test "statementWhere succeeds" {
         Expect.equal (Query.statementWhere "x" "y") "x WHERE y" "Statements not combined correctly"
     }
@@ -221,7 +392,7 @@ let all =
             test "succeeds for nested SQLite field" {
                 Expect.equal
                     (Query.Definition.ensureIndexOn tbl "nest" [ "a.b.c" ] SQLite)
-                            $"CREATE INDEX IF NOT EXISTS idx_{tbl}_nest ON {tbl} ((data->>'a'->>'b'->>'c'))"
+                    $"CREATE INDEX IF NOT EXISTS idx_{tbl}_nest ON {tbl} ((data->'a'->'b'->>'c'))"
                     "CREATE INDEX for nested SQLite field incorrect"
             }
         ]
@@ -253,5 +424,73 @@ let all =
     test "delete succeeds" {
         Expect.equal (Query.delete tbl) $"DELETE FROM {tbl}" "Delete query not correct"
     }
+    testList "orderBy" [
+        test "succeeds for no fields" {
+            Expect.equal (Query.orderBy [] PostgreSQL) "" "Order By should have been blank (PostgreSQL)"
+            Expect.equal (Query.orderBy [] SQLite) "" "Order By should have been blank (SQLite)"
+        }
+        test "succeeds for PostgreSQL with one field and no direction" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "TestField" ] PostgreSQL)
+                " ORDER BY data->>'TestField'"
+                "Order By not constructed correctly"
+        }
+        test "succeeds for SQLite with one field and no direction" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "TestField" ] SQLite)
+                " ORDER BY data->>'TestField'"
+                "Order By not constructed correctly"
+        }
+        test "succeeds for PostgreSQL with multiple fields and direction" {
+            Expect.equal
+                (Query.orderBy
+                     [ Field.Named "Nested.Test.Field DESC"; Field.Named "AnotherField"; Field.Named "It DESC" ]
+                     PostgreSQL)
+                " ORDER BY data#>>'{Nested,Test,Field}' DESC, data->>'AnotherField', data->>'It' DESC"
+                "Order By not constructed correctly"
+        }
+        test "succeeds for SQLite with multiple fields and direction" {
+            Expect.equal
+                (Query.orderBy
+                     [ Field.Named "Nested.Test.Field DESC"; Field.Named "AnotherField"; Field.Named "It DESC" ]
+                     SQLite)
+                " ORDER BY data->'Nested'->'Test'->>'Field' DESC, data->>'AnotherField', data->>'It' DESC"
+                "Order By not constructed correctly"
+        }
+        test "succeeds for PostgreSQL numeric fields" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "n:Test" ] PostgreSQL)
+                " ORDER BY (data->>'Test')::numeric"
+                "Order By not constructed correctly for numeric field"
+        }
+        test "succeeds for SQLite numeric fields" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "n:Test" ] SQLite)
+                " ORDER BY data->>'Test'"
+                "Order By not constructed correctly for numeric field"
+        }
+        test "succeeds for PostgreSQL case-insensitive ordering" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "i:Test.Field DESC NULLS FIRST" ] PostgreSQL)
+                " ORDER BY LOWER(data#>>'{Test,Field}') DESC NULLS FIRST"
+                "Order By not constructed correctly for case-insensitive field"
+        }
+        test "succeeds for SQLite case-insensitive ordering" {
+            Expect.equal
+                (Query.orderBy [ Field.Named "i:Test.Field ASC NULLS LAST" ] SQLite)
+                " ORDER BY data->'Test'->>'Field' COLLATE NOCASE ASC NULLS LAST"
+                "Order By not constructed correctly for case-insensitive field"
+        }
     ]
 ]
+
+/// Tests which do not hit the database
+let all = testList "Common" [
+    comparisonTests
+    fieldTests
+    fieldMatchTests
+    parameterNameTests
+    autoIdTests
+    queryTests
+    testSequenced configurationTests
+]

src/Tests/PostgresExtensionTests.fs

@@ -7,8 +7,6 @@ open Expecto
 open Npgsql
 open Types
 
-#nowarn "0044"
-
 /// Open a connection to the throwaway database
 let private mkConn (db: ThrowawayPostgresDb) =
     let conn = new NpgsqlConnection(db.ConnectionString)
@@ -27,7 +25,7 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! docs = conn.customList (Query.selectFromTable PostgresDb.TableName) [] fromData<JsonDocument>
+                let! docs = conn.customList (Query.find PostgresDb.TableName) [] fromData<JsonDocument>
                 Expect.equal (List.length docs) 5 "There should have been 5 documents returned"
             }
             testTask "succeeds when data is not found" {
@@ -211,12 +209,12 @@ let integrationTests =
             let! theCount = conn.countAll PostgresDb.TableName
             Expect.equal theCount 5 "There should have been 5 matching documents"
         }
-        testTask "countByField succeeds" {
+        testTask "countByFields succeeds" {
             use db   = PostgresDb.BuildDb()
             use conn = mkConn db
             do! loadDocs conn
             
-            let! theCount = conn.countByField PostgresDb.TableName (Field.EQ "Value" "purple")
+            let! theCount = conn.countByFields PostgresDb.TableName Any [ Field.Equal "Value" "purple" ]
             Expect.equal theCount 2 "There should have been 2 matching documents"
         }
         testTask "countByContains succeeds" {
@@ -253,13 +251,13 @@ let integrationTests =
                 Expect.isFalse exists "There should not have been an existing document"
             }
         ]
-        testList "existsByField" [
+        testList "existsByFields" [
             testTask "succeeds when documents exist" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! exists = conn.existsByField PostgresDb.TableName (Field.EX "Sub")
+                let! exists = conn.existsByFields PostgresDb.TableName Any [ Field.Exists "Sub" ]
                 Expect.isTrue exists "There should have been existing documents"
             }
             testTask "succeeds when documents do not exist" {
@@ -267,7 +265,7 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! exists = conn.existsByField PostgresDb.TableName (Field.EQ "NumValue" "six")
+                let! exists = conn.existsByFields PostgresDb.TableName Any [ Field.Equal "NumValue" "six" ]
                 Expect.isFalse exists "There should not have been existing documents"
             }
         ]
@@ -317,12 +315,10 @@ let integrationTests =
                 do! conn.insert PostgresDb.TableName { Foo = "five"; Bar = "six" }
 
                 let! results = conn.findAll<SubDocument> PostgresDb.TableName
-                let expected = [
-                    { Foo = "one"; Bar = "two" }
-                    { Foo = "three"; Bar = "four" }
-                    { Foo = "five"; Bar = "six" }
-                ]
-                Expect.equal results expected "There should have been 3 documents returned"
+                Expect.equal
+                    results
+                    [ { Foo = "one"; Bar = "two" }; { Foo = "three"; Bar = "four" }; { Foo = "five"; Bar = "six" } ]
+                    "There should have been 3 documents returned"
             }
             testTask "succeeds when there is no data" {
                 use  db      = PostgresDb.BuildDb()
@@ -331,6 +327,44 @@ let integrationTests =
                 Expect.equal results [] "There should have been no documents returned"
             }
         ]
+        testList "findAllOrdered" [
+            testTask "succeeds when ordering numerically" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+                
+                let! results = conn.findAllOrdered<JsonDocument> PostgresDb.TableName [ Field.Named "n:NumValue" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "one|three|two|four|five"
+                    "The documents were not ordered correctly"
+            }
+            testTask "succeeds when ordering numerically descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+                
+                let! results = conn.findAllOrdered<JsonDocument> PostgresDb.TableName [ Field.Named "n:NumValue DESC" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "five|four|two|three|one"
+                    "The documents were not ordered correctly"
+            }
+            testTask "succeeds when ordering alphabetically" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+                
+                let! results = conn.findAllOrdered<JsonDocument> PostgresDb.TableName [ Field.Named "Id DESC" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "two|three|one|four|five"
+                    "The documents were not ordered correctly"
+            }
+        ]
         testList "findById" [
             testTask "succeeds when a document is found" {
                 use db   = PostgresDb.BuildDb()
@@ -350,13 +384,13 @@ let integrationTests =
                 Expect.isNone doc "There should not have been a document returned"
             }
         ]
-        testList "findByField" [
+        testList "findByFields" [
             testTask "succeeds when documents are found" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! docs = conn.findByField<JsonDocument> PostgresDb.TableName (Field.EQ "Value" "another")
+                let! docs = conn.findByFields<JsonDocument> PostgresDb.TableName Any [ Field.Equal "Value" "another" ]
                 Expect.equal (List.length docs) 1 "There should have been one document returned"
             }
             testTask "succeeds when documents are not found" {
@@ -364,10 +398,36 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! docs = conn.findByField<JsonDocument> PostgresDb.TableName (Field.EQ "Value" "mauve")
+                let! docs = conn.findByFields<JsonDocument> PostgresDb.TableName Any [ Field.Equal "Value" "mauve" ]
                 Expect.isEmpty docs "There should have been no documents returned"
             }
         ]
+        testList "findByFieldsOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByFieldsOrdered<JsonDocument>
+                        PostgresDb.TableName All [ Field.Equal "Value" "purple" ] [ Field.Named "Id" ]
+                Expect.hasLength docs 2 "There should have been two documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "five|four" "Documents not ordered correctly"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByFieldsOrdered<JsonDocument>
+                        PostgresDb.TableName All [ Field.Equal "Value" "purple" ] [ Field.Named "Id DESC" ]
+                Expect.hasLength docs 2 "There should have been two documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "four|five" "Documents not ordered correctly"
+            }
+        ]
         testList "findByContains" [
             testTask "succeeds when documents are found" {
                 use db   = PostgresDb.BuildDb()
@@ -386,6 +446,33 @@ let integrationTests =
                 Expect.isEmpty docs "There should have been no documents returned"
             }
         ]
+        testList "findByContainsOrdered" [
+            // Id = two, Sub.Bar = blue; Id = four, Sub.Bar = red
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByContainsOrdered<JsonDocument>
+                        PostgresDb.TableName {| Sub = {| Foo = "green" |} |} [ Field.Named "Sub.Bar" ]
+                Expect.hasLength docs 2 "There should have been two documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "two|four" "Documents not ordered correctly"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByContainsOrdered<JsonDocument>
+                        PostgresDb.TableName {| Sub = {| Foo = "green" |} |} [ Field.Named "Sub.Bar DESC" ]
+                Expect.hasLength docs 2 "There should have been two documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "four|two" "Documents not ordered correctly"
+            }
+        ]
         testList "findByJsonPath" [
             testTask "succeeds when documents are found" {
                 use db   = PostgresDb.BuildDb()
@@ -404,13 +491,41 @@ let integrationTests =
                 Expect.isEmpty docs "There should have been no documents returned"
             }
         ]
-        testList "findFirstByField" [
+        testList "findByJsonPathOrdered" [
+            // Id = one, NumValue = 0; Id = two, NumValue = 10; Id = three, NumValue = 4
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByJsonPathOrdered<JsonDocument>
+                        PostgresDb.TableName "$.NumValue ? (@ < 15)" [ Field.Named "n:NumValue" ]
+                Expect.hasLength docs 3 "There should have been 3 documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "one|three|two" "Documents not ordered correctly"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! docs =
+                    conn.findByJsonPathOrdered<JsonDocument>
+                        PostgresDb.TableName "$.NumValue ? (@ < 15)" [ Field.Named "n:NumValue DESC" ]
+                Expect.hasLength docs 3 "There should have been 3 documents returned"
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "two|three|one" "Documents not ordered correctly"
+            }
+        ]
+        testList "findFirstByFields" [
             testTask "succeeds when a document is found" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! doc = conn.findFirstByField<JsonDocument> PostgresDb.TableName (Field.EQ "Value" "another")
+                let! doc =
+                    conn.findFirstByFields<JsonDocument> PostgresDb.TableName Any [ Field.Equal "Value" "another" ]
                 Expect.isSome doc "There should have been a document returned"
                 Expect.equal doc.Value.Id "two" "The incorrect document was returned"
             }
@@ -419,7 +534,8 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! doc = conn.findFirstByField<JsonDocument> PostgresDb.TableName (Field.EQ "Value" "purple")
+                let! doc =
+                    conn.findFirstByFields<JsonDocument> PostgresDb.TableName Any [ Field.Equal "Value" "purple" ]
                 Expect.isSome doc "There should have been a document returned"
                 Expect.contains [ "five"; "four" ] doc.Value.Id "An incorrect document was returned"
             }
@@ -428,10 +544,35 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                let! doc = conn.findFirstByField<JsonDocument> PostgresDb.TableName (Field.EQ "Value" "absent")
+                let! doc =
+                    conn.findFirstByFields<JsonDocument> PostgresDb.TableName Any [ Field.Equal "Value" "absent" ]
                 Expect.isNone doc "There should not have been a document returned"
             }
         ]
+        testList "findFirstByFieldsOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByFieldsOrdered<JsonDocument>
+                        PostgresDb.TableName Any [ Field.Equal "Value" "purple" ] [ Field.Named "Id" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "five" doc.Value.Id "An incorrect document was returned"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByFieldsOrdered<JsonDocument>
+                        PostgresDb.TableName Any [ Field.Equal "Value" "purple" ] [ Field.Named "Id DESC" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "four" doc.Value.Id "An incorrect document was returned"
+            }
+        ]
         testList "findFirstByContains" [
             testTask "succeeds when a document is found" {
                 use db   = PostgresDb.BuildDb()
@@ -460,6 +601,30 @@ let integrationTests =
                 Expect.isNone doc "There should not have been a document returned"
             }
         ]
+        testList "findFirstByContainsOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByContainsOrdered<JsonDocument>
+                        PostgresDb.TableName {| Sub = {| Foo = "green" |} |} [ Field.Named "Value" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "two" doc.Value.Id "An incorrect document was returned"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByContainsOrdered<JsonDocument>
+                        PostgresDb.TableName {| Sub = {| Foo = "green" |} |} [ Field.Named "Value DESC" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "four" doc.Value.Id "An incorrect document was returned"
+            }
+        ]
         testList "findFirstByJsonPath" [
             testTask "succeeds when a document is found" {
                 use db   = PostgresDb.BuildDb()
@@ -488,6 +653,30 @@ let integrationTests =
                 Expect.isNone doc "There should not have been a document returned"
             }
         ]
+        testList "findFirstByJsonPathOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByJsonPathOrdered<JsonDocument>
+                        PostgresDb.TableName """$.Sub.Foo ? (@ == "green")""" [ Field.Named "Sub.Bar" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "two" doc.Value.Id "An incorrect document was returned"
+            }
+            testTask "succeeds when sorting descending" {
+                use db   = PostgresDb.BuildDb()
+                use conn = mkConn db
+                do! loadDocs conn
+
+                let! doc =
+                    conn.findFirstByJsonPathOrdered<JsonDocument>
+                        PostgresDb.TableName """$.Sub.Foo ? (@ == "green")""" [ Field.Named "Sub.Bar DESC" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "four" doc.Value.Id "An incorrect document was returned"
+            }
+        ]
         testList "updateById" [
             testTask "succeeds when a document is updated" {
                 use db   = PostgresDb.BuildDb()
@@ -558,14 +747,14 @@ let integrationTests =
                 do! conn.patchById PostgresDb.TableName "test" {| Foo = "green" |}
             }
         ]
-        testList "patchByField" [
+        testList "patchByFields" [
             testTask "succeeds when a document is updated" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
                 
-                do! conn.patchByField PostgresDb.TableName (Field.EQ "Value" "purple") {| NumValue = 77 |}
-                let! after = conn.countByField PostgresDb.TableName (Field.EQ "NumValue" "77")
+                do! conn.patchByFields PostgresDb.TableName Any [ Field.Equal "Value" "purple" ] {| NumValue = 77 |}
+                let! after = conn.countByFields PostgresDb.TableName Any [ Field.Equal "NumValue" "77" ]
                 Expect.equal after 2 "There should have been 2 documents returned"
             }
             testTask "succeeds when no document is updated" {
@@ -575,7 +764,7 @@ let integrationTests =
                 Expect.equal before 0 "There should have been no documents returned"
                 
                 // This not raising an exception is the test
-                do! conn.patchByField PostgresDb.TableName (Field.EQ "Value" "burgundy") {| Foo = "green" |}
+                do! conn.patchByFields PostgresDb.TableName Any [ Field.Equal "Value" "burgundy" ] {| Foo = "green" |}
             }
         ]
         testList "patchByContains" [
@@ -625,9 +814,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsById PostgresDb.TableName "two" [ "Sub"; "Value" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 1 "There should be 1 document without Value fields"
             }
             testTask "succeeds when a single field is removed" {
@@ -636,9 +825,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsById PostgresDb.TableName "two" [ "Sub" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 0 "There should be no documents without Value fields"
             }
             testTask "succeeds when a field is not removed" {
@@ -657,16 +846,17 @@ let integrationTests =
                 do! conn.removeFieldsById PostgresDb.TableName "two" [ "Value" ]
             }
         ]
-        testList "removeFieldsByField" [
+        testList "removeFieldsByFields" [
             testTask "succeeds when multiple fields are removed" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
 
-                do! conn.removeFieldsByField PostgresDb.TableName (Field.EQ "NumValue" "17") [ "Sub"; "Value" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                do! conn.removeFieldsByFields
+                        PostgresDb.TableName Any [ Field.Equal "NumValue" "17" ] [ "Sub"; "Value" ]
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 1 "There should be 1 document without Value fields"
             }
             testTask "succeeds when a single field is removed" {
@@ -674,10 +864,10 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                do! conn.removeFieldsByField PostgresDb.TableName (Field.EQ "NumValue" "17") [ "Sub" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                do! conn.removeFieldsByFields PostgresDb.TableName Any [ Field.Equal "NumValue" "17" ] [ "Sub" ]
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 0 "There should be no documents without Value fields"
             }
             testTask "succeeds when a field is not removed" {
@@ -686,14 +876,15 @@ let integrationTests =
                 do! loadDocs conn
                     
                 // This not raising an exception is the test
-                do! conn.removeFieldsByField PostgresDb.TableName (Field.EQ "NumValue" "17") [ "Nothing" ]
+                do! conn.removeFieldsByFields PostgresDb.TableName Any [ Field.Equal "NumValue" "17" ] [ "Nothing" ]
             }
             testTask "succeeds when no document is matched" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 
                 // This not raising an exception is the test
-                do! conn.removeFieldsByField PostgresDb.TableName (Field.NE "Abracadabra" "apple") [ "Value" ]
+                do! conn.removeFieldsByFields
+                        PostgresDb.TableName Any [ Field.NotEqual "Abracadabra" "apple" ] [ "Value" ]
             }
         ]
         testList "removeFieldsByContains" [
@@ -703,9 +894,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsByContains PostgresDb.TableName {| NumValue = 17 |} [ "Sub"; "Value" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 1 "There should be 1 document without Value fields"
             }
             testTask "succeeds when a single field is removed" {
@@ -714,9 +905,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsByContains PostgresDb.TableName {| NumValue = 17 |} [ "Sub" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 0 "There should be no documents without Value fields"
             }
             testTask "succeeds when a field is not removed" {
@@ -742,9 +933,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsByJsonPath PostgresDb.TableName "$.NumValue ? (@ == 17)" [ "Sub"; "Value" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 1 "There should be 1 document without Value fields"
             }
             testTask "succeeds when a single field is removed" {
@@ -753,9 +944,9 @@ let integrationTests =
                 do! loadDocs conn
 
                 do! conn.removeFieldsByJsonPath PostgresDb.TableName "$.NumValue ? (@ == 17)" [ "Sub" ]
-                let! noSubs = conn.countByField PostgresDb.TableName (Field.NEX "Sub")
+                let! noSubs = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Sub" ]
                 Expect.equal noSubs 4 "There should now be 4 documents without Sub fields"
-                let! noValue = conn.countByField PostgresDb.TableName (Field.NEX "Value")
+                let! noValue = conn.countByFields PostgresDb.TableName Any [ Field.NotExists "Value" ]
                 Expect.equal noValue 0 "There should be no documents without Value fields"
             }
             testTask "succeeds when a field is not removed" {
@@ -794,13 +985,13 @@ let integrationTests =
                 Expect.equal remaining 5 "There should have been 5 documents remaining"
             }
         ]
-        testList "deleteByField" [
+        testList "deleteByFields" [
             testTask "succeeds when documents are deleted" {
                 use db   = PostgresDb.BuildDb()
                 use conn = mkConn db
                 do! loadDocs conn
 
-                do! conn.deleteByField PostgresDb.TableName (Field.EQ "Value" "purple")
+                do! conn.deleteByFields PostgresDb.TableName Any [ Field.Equal "Value" "purple" ]
                 let! remaining = conn.countAll PostgresDb.TableName
                 Expect.equal remaining 3 "There should have been 3 documents remaining"
             }
@@ -809,7 +1000,7 @@ let integrationTests =
                 use conn = mkConn db
                 do! loadDocs conn
 
-                do! conn.deleteByField PostgresDb.TableName (Field.EQ "Value" "crimson")
+                do! conn.deleteByFields PostgresDb.TableName Any [ Field.Equal "Value" "crimson" ]
                 let! remaining = conn.countAll PostgresDb.TableName
                 Expect.equal remaining 5 "There should have been 5 documents remaining"
             }

src/Tests/SqliteExtensionTests.fs

@@ -8,8 +8,6 @@ open Expecto
 open Microsoft.Data.Sqlite
 open Types
 
-#nowarn "0044"
-
 /// Integration tests for the F# extensions on the SqliteConnection data type
 let integrationTests =
     let loadDocs () = backgroundTask {
@@ -115,12 +113,12 @@ let integrationTests =
             let! theCount = conn.countAll SqliteDb.TableName
             Expect.equal theCount 5L "There should have been 5 matching documents"
         }
-        testTask "countByField succeeds" {
+        testTask "countByFields succeeds" {
             use! db   = SqliteDb.BuildDb()
             use  conn = Configuration.dbConn ()
             do! loadDocs ()
     
-            let! theCount = conn.countByField SqliteDb.TableName (Field.EQ "Value" "purple")
+            let! theCount = conn.countByFields SqliteDb.TableName Any [ Field.Equal "Value" "purple" ]
             Expect.equal theCount 2L "There should have been 2 matching documents"
         }
         testList "existsById" [
@@ -141,13 +139,13 @@ let integrationTests =
                 Expect.isFalse exists "There should not have been an existing document"
             }
         ]
-        testList "existsByField" [
+        testList "existsByFields" [
             testTask "succeeds when documents exist" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! exists = conn.existsByField SqliteDb.TableName (Field.EQ "NumValue" 10)
+                let! exists = conn.existsByFields SqliteDb.TableName Any [ Field.Equal "NumValue" 10 ]
                 Expect.isTrue exists "There should have been existing documents"
             }
             testTask "succeeds when no matching documents exist" {
@@ -155,7 +153,7 @@ let integrationTests =
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! exists = conn.existsByField SqliteDb.TableName (Field.EQ "Nothing" "none")
+                let! exists = conn.existsByFields SqliteDb.TableName Any [ Field.Equal "Nothing" "none" ]
                 Expect.isFalse exists "There should not have been any existing documents"
             }
         ]
@@ -183,6 +181,44 @@ let integrationTests =
                 Expect.equal results [] "There should have been no documents returned"
             }
         ]
+        testList "findAllOrdered" [
+            testTask "succeeds when ordering numerically" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+                
+                let! results = conn.findAllOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "n:NumValue" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "one|three|two|four|five"
+                    "The documents were not ordered correctly"
+            }
+            testTask "succeeds when ordering numerically descending" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+                
+                let! results = conn.findAllOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "n:NumValue DESC" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "five|four|two|three|one"
+                    "The documents were not ordered correctly"
+            }
+            testTask "succeeds when ordering alphabetically" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+                
+                let! results = conn.findAllOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "Id DESC" ]
+                Expect.hasLength results 5 "There should have been 5 documents returned"
+                Expect.equal
+                    (results |> List.map _.Id |> String.concat "|")
+                    "two|three|one|four|five"
+                    "The documents were not ordered correctly"
+            }
+        ]
         testList "findById" [
             testTask "succeeds when a document is found" {
                 use! db   = SqliteDb.BuildDb()
@@ -190,7 +226,7 @@ let integrationTests =
                 do! loadDocs ()
     
                 let! doc = conn.findById<string, JsonDocument> SqliteDb.TableName "two"
-                Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+                Expect.isSome doc "There should have been a document returned"
                 Expect.equal doc.Value.Id "two" "The incorrect document was returned"
             }
             testTask "succeeds when a document is not found" {
@@ -199,35 +235,59 @@ let integrationTests =
                 do! loadDocs ()
     
                 let! doc = conn.findById<string, JsonDocument> SqliteDb.TableName "three hundred eighty-seven"
-                Expect.isFalse (Option.isSome doc) "There should not have been a document returned"
+                Expect.isNone doc "There should not have been a document returned"
             }
         ]
-        testList "findByField" [
+        testList "findByFields" [
             testTask "succeeds when documents are found" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! docs = conn.findByField<JsonDocument> SqliteDb.TableName (Field.EQ "Sub.Foo" "green")
-                Expect.equal (List.length docs) 2 "There should have been two documents returned"
+                let! docs = conn.findByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ]
+                Expect.hasLength docs 2 "There should have been two documents returned"
             }
             testTask "succeeds when documents are not found" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! docs = conn.findByField<JsonDocument> SqliteDb.TableName (Field.EQ "Value" "mauve")
-                Expect.isTrue (List.isEmpty docs) "There should have been no documents returned"
+                let! docs = conn.findByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Value" "mauve" ]
+                Expect.isEmpty docs "There should have been no documents returned"
             }
         ]
-        testList "findFirstByField" [
+        testList "findByFieldsOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+
+                let! docs =
+                    conn.findByFieldsOrdered<JsonDocument>
+                        SqliteDb.TableName Any [ Field.Greater "NumValue" 15 ] [ Field.Named "Id" ]
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "five|four" "The documents were not ordered correctly"
+            }
+            testTask "succeeds when sorting descending" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+
+                let! docs =
+                    conn.findByFieldsOrdered<JsonDocument>
+                        SqliteDb.TableName Any [ Field.Greater "NumValue" 15 ] [ Field.Named "Id DESC" ]
+                Expect.equal
+                    (docs |> List.map _.Id |> String.concat "|") "four|five" "The documents were not ordered correctly"
+            }
+        ]
+        testList "findFirstByFields" [
             testTask "succeeds when a document is found" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! doc = conn.findFirstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Value" "another")
-                Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+                let! doc = conn.findFirstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Value" "another" ]
+                Expect.isSome doc "There should have been a document returned"
                 Expect.equal doc.Value.Id "two" "The incorrect document was returned"
             }
             testTask "succeeds when multiple documents are found" {
@@ -235,8 +295,8 @@ let integrationTests =
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! doc = conn.findFirstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Sub.Foo" "green")
-                Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+                let! doc = conn.findFirstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ]
+                Expect.isSome doc "There should have been a document returned"
                 Expect.contains [ "two"; "four" ] doc.Value.Id "An incorrect document was returned"
             }
             testTask "succeeds when a document is not found" {
@@ -244,8 +304,32 @@ let integrationTests =
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! doc = conn.findFirstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Value" "absent")
-                Expect.isFalse (Option.isSome doc) "There should not have been a document returned"
+                let! doc = conn.findFirstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Value" "absent" ]
+                Expect.isNone doc "There should not have been a document returned"
+            }
+        ]
+        testList "findFirstByFieldsOrdered" [
+            testTask "succeeds when sorting ascending" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+
+                let! doc =
+                    conn.findFirstByFieldsOrdered<JsonDocument>
+                        SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ] [ Field.Named "Sub.Bar" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "two" doc.Value.Id "An incorrect document was returned"
+            }
+            testTask "succeeds when sorting descending" {
+                use! db   = SqliteDb.BuildDb()
+                use  conn = Configuration.dbConn ()
+                do! loadDocs ()
+
+                let! doc =
+                    conn.findFirstByFieldsOrdered<JsonDocument>
+                        SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ] [ Field.Named "Sub.Bar DESC" ]
+                Expect.isSome doc "There should have been a document returned"
+                Expect.equal "four" doc.Value.Id "An incorrect document was returned"
             }
         ]
         testList "updateById" [
@@ -326,14 +410,14 @@ let integrationTests =
                 do! conn.patchById SqliteDb.TableName "test" {| Foo = "green" |}
             }
         ]
-        testList "patchByField" [
+        testList "patchByFields" [
             testTask "succeeds when a document is updated" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
                 
-                do! conn.patchByField SqliteDb.TableName (Field.EQ "Value" "purple") {| NumValue = 77 |}
-                let! after = conn.countByField SqliteDb.TableName (Field.EQ "NumValue" 77)
+                do! conn.patchByFields SqliteDb.TableName Any [ Field.Equal "Value" "purple" ] {| NumValue = 77 |}
+                let! after = conn.countByFields SqliteDb.TableName Any [ Field.Equal "NumValue" 77 ]
                 Expect.equal after 2L "There should have been 2 documents returned"
             }
             testTask "succeeds when no document is updated" {
@@ -344,7 +428,7 @@ let integrationTests =
                 Expect.isEmpty before "There should have been no documents returned"
                 
                 // This not raising an exception is the test
-                do! conn.patchByField SqliteDb.TableName (Field.EQ "Value" "burgundy") {| Foo = "green" |}
+                do! conn.patchByFields SqliteDb.TableName Any [ Field.Equal "Value" "burgundy" ] {| Foo = "green" |}
             }
         ]
         testList "removeFieldsById" [
@@ -377,13 +461,13 @@ let integrationTests =
                 do! conn.removeFieldsById SqliteDb.TableName "two" [ "Value" ]
             }
         ]
-        testList "removeFieldByField" [
+        testList "removeFieldByFields" [
             testTask "succeeds when a field is removed" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
                 
-                do! conn.removeFieldsByField SqliteDb.TableName (Field.EQ "NumValue" 17) [ "Sub" ]
+                do! conn.removeFieldsByFields SqliteDb.TableName Any [ Field.Equal "NumValue" 17 ] [ "Sub" ]
                 try
                     let! _ = conn.findById<string, JsonDocument> SqliteDb.TableName "four"
                     Expect.isTrue false "The updated document should have failed to parse"
@@ -397,14 +481,15 @@ let integrationTests =
                 do! loadDocs ()
                 
                 // This not raising an exception is the test
-                do! conn.removeFieldsByField SqliteDb.TableName (Field.EQ "NumValue" 17) [ "Nothing" ]
+                do! conn.removeFieldsByFields SqliteDb.TableName Any [ Field.Equal "NumValue" 17 ] [ "Nothing" ]
             }
             testTask "succeeds when no document is matched" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 
                 // This not raising an exception is the test
-                do! conn.removeFieldsByField SqliteDb.TableName (Field.NE "Abracadabra" "apple") [ "Value" ]
+                do! conn.removeFieldsByFields
+                        SqliteDb.TableName Any [ Field.NotEqual "Abracadabra" "apple" ] [ "Value" ]
             }
         ]
         testList "deleteById" [
@@ -427,13 +512,13 @@ let integrationTests =
                 Expect.equal remaining 5L "There should have been 5 documents remaining"
             }
         ]
-        testList "deleteByField" [
+        testList "deleteByFields" [
             testTask "succeeds when documents are deleted" {
                 use! db   = SqliteDb.BuildDb()
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                do! conn.deleteByField SqliteDb.TableName (Field.NE "Value" "purple")
+                do! conn.deleteByFields SqliteDb.TableName Any [ Field.NotEqual "Value" "purple" ]
                 let! remaining = conn.countAll SqliteDb.TableName
                 Expect.equal remaining 2L "There should have been 2 documents remaining"
             }
@@ -442,7 +527,7 @@ let integrationTests =
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                do! conn.deleteByField SqliteDb.TableName (Field.EQ "Value" "crimson")
+                do! conn.deleteByFields SqliteDb.TableName Any [ Field.Equal "Value" "crimson" ]
                 let! remaining = conn.countAll SqliteDb.TableName
                 Expect.equal remaining 5L "There should have been 5 documents remaining"
             }
@@ -480,8 +565,8 @@ let integrationTests =
                 use  conn = Configuration.dbConn ()
                 do! loadDocs ()
     
-                let! docs = conn.customList (Query.selectFromTable SqliteDb.TableName) [] fromData<JsonDocument>
-                Expect.hasCountOf docs 5u (fun _ -> true) "There should have been 5 documents returned"
+                let! docs = conn.customList (Query.find SqliteDb.TableName) [] fromData<JsonDocument>
+                Expect.hasLength docs 5 "There should have been 5 documents returned"
             }
             testTask "succeeds when data is not found" {
                 use! db   = SqliteDb.BuildDb()

src/Tests/SqliteTests.fs

@@ -10,47 +10,59 @@ open Types
 
 #nowarn "0044"
 
-/// Unit tests for the SQLite library
-let unitTests =
-    testList "Unit" [
-        testList "Query" [
+(** UNIT TESTS **)
+
+/// Unit tests for the Query module of the SQLite library
+let queryTests = testList "Query" [
     testList "whereByFields" [
-                test "succeeds for a single field when a logical operator is passed" {
+        test "succeeds for a single field when a logical comparison is passed" {
             Expect.equal
-                        (Query.whereByFields Any [ { Field.GT "theField" 0 with ParameterName = Some "@test" } ])
+                (Query.whereByFields Any [ { Field.Greater "theField" 0 with ParameterName = Some "@test" } ])
                 "data->>'theField' > @test"
                 "WHERE clause not correct"
         }
-                test "succeeds for a single field when an existence operator is passed" {
+        test "succeeds for a single field when an existence comparison is passed" {
             Expect.equal
-                        (Query.whereByFields Any [ Field.NEX "thatField" ])
+                (Query.whereByFields Any [ Field.NotExists "thatField" ])
                 "data->>'thatField' IS NULL"
                 "WHERE clause not correct"
         }
-                test "succeeds for a single field when a between operator is passed" {
+        test "succeeds for a single field when a between comparison is passed" {
             Expect.equal
-                        (Query.whereByFields All [ { Field.BT "aField" 50 99 with ParameterName = Some "@range" } ])
+                (Query.whereByFields All [ { Field.Between "aField" 50 99 with ParameterName = Some "@range" } ])
                 "data->>'aField' BETWEEN @rangemin AND @rangemax"
                 "WHERE clause not correct"
         }
-                test "succeeds for all multiple fields with logical operators" {
+        test "succeeds for all multiple fields with logical comparisons" {
             Expect.equal
-                        (Query.whereByFields All [ Field.EQ "theFirst" "1"; Field.EQ "numberTwo" "2" ])
+                (Query.whereByFields All [ Field.Equal "theFirst" "1"; Field.Equal "numberTwo" "2" ])
                 "data->>'theFirst' = @field0 AND data->>'numberTwo' = @field1"
                 "WHERE clause not correct"
         }
-                test "succeeds for any multiple fields with an existence operator" {
+        test "succeeds for any multiple fields with an existence comparison" {
             Expect.equal
-                        (Query.whereByFields Any [ Field.NEX "thatField"; Field.GE "thisField" 18 ])
+                (Query.whereByFields Any [ Field.NotExists "thatField"; Field.GreaterOrEqual "thisField" 18 ])
                 "data->>'thatField' IS NULL OR data->>'thisField' >= @field0"
                 "WHERE clause not correct"
         }
-                test "succeeds for all multiple fields with between operators" {
+        test "succeeds for all multiple fields with between comparisons" {
             Expect.equal
-                        (Query.whereByFields All [ Field.BT "aField" 50 99; Field.BT "anotherField" "a" "b" ])
+                (Query.whereByFields All [ Field.Between "aField" 50 99; Field.Between "anotherField" "a" "b" ])
                 "data->>'aField' BETWEEN @field0min AND @field0max AND data->>'anotherField' BETWEEN @field1min AND @field1max"
                 "WHERE clause not correct"
         }
+        test "succeeds for a field with an In comparison" {
+            Expect.equal
+                (Query.whereByFields All [ Field.In "this" [ "a"; "b"; "c" ] ])
+                "data->>'this' IN (@field0_0, @field0_1, @field0_2)"
+                "WHERE clause not correct"
+        }
+        test "succeeds for a field with an InArray comparison" {
+            Expect.equal
+                (Query.whereByFields All [ Field.InArray "this" "the_table" [ "a"; "b" ] ])
+                "EXISTS (SELECT 1 FROM json_each(the_table.data, '$.this') WHERE value IN (@field0_0, @field0_1))"
+                "WHERE clause not correct"
+        }
     ]
     test "whereById succeeds" {
         Expect.equal (Query.whereById "@id") "data->>'Id' = @id" "WHERE clause not correct"
@@ -72,7 +84,7 @@ let unitTests =
     }
     test "byFields succeeds" {
         Expect.equal
-                    (Query.byFields "unit" Any [ Field.GT "That" 14 ])
+            (Query.byFields "unit" Any [ Field.Greater "That" 14 ])
             "unit WHERE data->>'That' > @field0"
             "By-Field query not correct"
     }
@@ -83,7 +95,9 @@ let unitTests =
             "CREATE TABLE statement not correct"
     }
 ]
-        testList "Parameters" [
+
+/// Unit tests for the Parameters module of the SQLite library
+let parametersTests = testList "Parameters" [
     test "idParam succeeds" {
         let theParam = idParam 7
         Expect.equal theParam.ParameterName "@id" "The parameter name is incorrect"
@@ -96,14 +110,14 @@ let unitTests =
     }
     testList "addFieldParam" [
         test "succeeds when adding a parameter" {
-                    let paramList = addFieldParam "@field" (Field.EQ "it" 99) []
+            let paramList = addFieldParam "@field" (Field.Equal "it" 99) []
             Expect.hasLength paramList 1 "There should have been a parameter added"
             let theParam = Seq.head paramList
             Expect.equal theParam.ParameterName "@field" "The parameter name is incorrect"
             Expect.equal theParam.Value 99 "The parameter value is incorrect"
         }
         test "succeeds when not adding a parameter" {
-                    let paramList = addFieldParam "@it" (Field.NEX "Coffee") []
+            let paramList = addFieldParam "@it" (Field.NotExists "Coffee") []
             Expect.isEmpty paramList "There should not have been any parameters added"
         }
     ]
@@ -112,22 +126,17 @@ let unitTests =
     }
 ]
 // Results are exhaustively executed in the context of other tests
-    ]
 
-/// These tests each use a fresh copy of a SQLite database
-let integrationTests =
-    let documents = [
-        { Id = "one"; Value = "FIRST!"; NumValue = 0; Sub = None }
-        { Id = "two"; Value = "another"; NumValue = 10; Sub = Some { Foo = "green"; Bar = "blue" } }
-        { Id = "three"; Value = ""; NumValue = 4; Sub = None }
-        { Id = "four"; Value = "purple"; NumValue = 17; Sub = Some { Foo = "green"; Bar = "red" } }
-        { Id = "five"; Value = "purple"; NumValue = 18; Sub = None }
-    ]
+
+(** INTEGRATION TESTS **)
+
+/// Load a table with the test documents
 let loadDocs () = backgroundTask {
-        for doc in documents do do! insert SqliteDb.TableName doc
+    for doc in testDocuments do do! insert SqliteDb.TableName doc
 }
-    testList "Integration" [
-        testList "Configuration" [
+
+/// Integration tests for the Configuration module of the SQLite library
+let configurationTests = testList "Configuration" [
     test "useConnectionString / connectionString succeed" {
         try
             Configuration.useConnectionString "Data Source=test.db"
@@ -138,34 +147,10 @@ let integrationTests =
         finally
             Configuration.useConnectionString "Data Source=:memory:"
     }
-            test "useSerializer succeeds" {
-                try
-                    Configuration.useSerializer
-                        { new IDocumentSerializer with
-                            member _.Serialize<'T>(it: 'T) : string = """{"Overridden":true}"""
-                            member _.Deserialize<'T>(it: string) : 'T = Unchecked.defaultof<'T>
-                        }
-                    
-                    let serialized = Configuration.serializer().Serialize { Foo = "howdy"; Bar = "bye"}
-                    Expect.equal serialized """{"Overridden":true}""" "Specified serializer was not used"
-                    
-                    let deserialized = Configuration.serializer().Deserialize<obj> """{"Something":"here"}"""
-                    Expect.isNull deserialized "Specified serializer should have returned null"
-                finally
-                    Configuration.useSerializer DocumentSerializer.``default``
-            }
-            test "serializer returns configured serializer" {
-                Expect.isTrue (obj.ReferenceEquals(DocumentSerializer.``default``, Configuration.serializer ()))
-                    "Serializer should have been the same"
-            }
-            test "useIdField / idField succeeds" {
-                Expect.equal (Configuration.idField ()) "Id" "The default configured ID field was incorrect"
-                Configuration.useIdField "id"
-                Expect.equal (Configuration.idField ()) "id" "useIdField did not set the ID field"
-                Configuration.useIdField "Id"
-            }
 ]
-        testList "Custom" [
+
+/// Integration tests for the Custom module of the SQLite library
+let customTests = testList "Custom" [
     testList "single" [
         testTask "succeeds when a row is found" {
             use! db = SqliteDb.BuildDb()
@@ -196,7 +181,7 @@ let integrationTests =
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! docs = Custom.list (Query.selectFromTable SqliteDb.TableName) [] fromData<JsonDocument>
+            let! docs = Custom.list (Query.find SqliteDb.TableName) [] fromData<JsonDocument>
             Expect.hasCountOf docs 5u (fun _ -> true) "There should have been 5 documents returned"
         }
         testTask "succeeds when data is not found" {
@@ -240,7 +225,9 @@ let integrationTests =
         Expect.equal nbr 5 "The query should have returned the number 5"
     }
 ]
-        testList "Definition" [
+
+/// Integration tests for the Definition module of the SQLite library
+let definitionTests = testList "Definition" [
     testTask "ensureTable succeeds" {
         use! db = SqliteDb.BuildDb()
         let itExists (name: string) =
@@ -277,6 +264,9 @@ let integrationTests =
         Expect.isTrue exists' "The index should now exist"
     }
 ]
+
+/// Integration tests for the (auto-opened) Document module of the SQLite library
+let documentTests = testList "Document" [
     testList "insert" [
         testTask "succeeds" {
             use! db = SqliteDb.BuildDb()
@@ -296,6 +286,68 @@ let integrationTests =
                     insert SqliteDb.TableName {emptyDoc with Id = "test" } |> Async.AwaitTask |> Async.RunSynchronously)
                 "An exception should have been raised for duplicate document ID insert"
         }
+        testTask "succeeds when adding a numeric auto ID" {
+            try
+                Configuration.useAutoIdStrategy Number
+                Configuration.useIdField "Key"
+                use! db = SqliteDb.BuildDb()
+                let! before = Count.all SqliteDb.TableName
+                Expect.equal before 0L "There should be no documents in the table"
+                
+                do! insert SqliteDb.TableName { Key = 0; Text = "one" }
+                do! insert SqliteDb.TableName { Key = 0; Text = "two" }
+                do! insert SqliteDb.TableName { Key = 77; Text = "three" }
+                do! insert SqliteDb.TableName { Key = 0; Text = "four" }
+                
+                let! after = Find.allOrdered<NumIdDocument> SqliteDb.TableName [ Field.Named "Key" ]
+                Expect.hasLength after 4 "There should have been 4 documents returned"
+                Expect.equal (after |> List.map _.Key) [ 1; 2; 77; 78 ] "The IDs were not generated correctly"
+            finally
+                Configuration.useAutoIdStrategy Disabled
+                Configuration.useIdField "Id"
+        }
+        testTask "succeeds when adding a GUID auto ID" {
+            try
+                Configuration.useAutoIdStrategy Guid
+                use! db = SqliteDb.BuildDb()
+                let! before = Count.all SqliteDb.TableName
+                Expect.equal before 0L "There should be no documents in the table"
+                
+                do! insert SqliteDb.TableName { emptyDoc with Value = "one" }
+                do! insert SqliteDb.TableName { emptyDoc with Value = "two" }
+                do! insert SqliteDb.TableName { emptyDoc with Id = "abc123"; Value = "three" }
+                do! insert SqliteDb.TableName { emptyDoc with Value = "four" }
+                
+                let! after = Find.all<JsonDocument> SqliteDb.TableName
+                Expect.hasLength after 4 "There should have been 4 documents returned"
+                Expect.hasCountOf after 3u (fun doc -> doc.Id.Length = 32) "Three of the IDs should have been GUIDs"
+                Expect.hasCountOf after 1u (fun doc -> doc.Id = "abc123") "The provided ID should have been used as-is"
+            finally
+                Configuration.useAutoIdStrategy Disabled
+        }
+        testTask "succeeds when adding a RandomString auto ID" {
+            try
+                Configuration.useAutoIdStrategy RandomString
+                Configuration.useIdStringLength 44
+                use! db = SqliteDb.BuildDb()
+                let! before = Count.all SqliteDb.TableName
+                Expect.equal before 0L "There should be no documents in the table"
+                
+                do! insert SqliteDb.TableName { emptyDoc with Value = "one" }
+                do! insert SqliteDb.TableName { emptyDoc with Value = "two" }
+                do! insert SqliteDb.TableName { emptyDoc with Id = "abc123"; Value = "three" }
+                do! insert SqliteDb.TableName { emptyDoc with Value = "four" }
+                
+                let! after = Find.all<JsonDocument> SqliteDb.TableName
+                Expect.hasLength after 4 "There should have been 4 documents returned"
+                Expect.hasCountOf
+                    after 3u (fun doc -> doc.Id.Length = 44)
+                    "Three of the IDs should have been 44-character random strings"
+                Expect.hasCountOf after 1u (fun doc -> doc.Id = "abc123") "The provided ID should have been used as-is"
+            finally
+                Configuration.useAutoIdStrategy Disabled
+                Configuration.useIdStringLength 16
+        }
     ]
     testList "save" [
         testTask "succeeds when a document is inserted" {
@@ -324,7 +376,10 @@ let integrationTests =
             Expect.equal after.Value upd8Doc "The updated document is not correct"
         }
     ]
-        testList "Count" [
+]
+
+/// Integration tests for the Count module of the SQLite library
+let countTests = testList "Count" [
     testTask "all succeeds" {
         use! db = SqliteDb.BuildDb()
         do! loadDocs ()
@@ -332,22 +387,26 @@ let integrationTests =
         let! theCount = Count.all SqliteDb.TableName
         Expect.equal theCount 5L "There should have been 5 matching documents"
     }
-            testTask "byField succeeds for a numeric range" {
+    testList "byFields" [
+        testTask "succeeds for a numeric range" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
     
-                let! theCount = Count.byField SqliteDb.TableName (Field.BT "NumValue" 10 20)
+            let! theCount = Count.byFields SqliteDb.TableName Any [ Field.Between "NumValue" 10 20 ]
             Expect.equal theCount 3L "There should have been 3 matching documents"
         }
-            testTask "byField succeeds for a non-numeric range" {
+        testTask "succeeds for a non-numeric range" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
     
-                let! theCount = Count.byField SqliteDb.TableName (Field.BT "Value" "aardvark" "apple")
+            let! theCount = Count.byFields SqliteDb.TableName Any [ Field.Between "Value" "aardvark" "apple" ]
             Expect.equal theCount 1L "There should have been 1 matching document"
         }
     ]
-        testList "Exists" [
+]
+
+/// Integration tests for the Exists module of the SQLite library
+let existsTests = testList "Exists" [
     testList "byId" [
         testTask "succeeds when a document exists" {
             use! db = SqliteDb.BuildDb()
@@ -364,24 +423,26 @@ let integrationTests =
             Expect.isFalse exists "There should not have been an existing document"
         }
     ]
-            testList "byField" [
+    testList "byFields" [
         testTask "succeeds when documents exist" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! exists = Exists.byField SqliteDb.TableName (Field.EQ "NumValue" 10)
+            let! exists = Exists.byFields SqliteDb.TableName Any [ Field.Equal "NumValue" 10 ]
             Expect.isTrue exists "There should have been existing documents"
         }
         testTask "succeeds when no matching documents exist" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! exists = Exists.byField SqliteDb.TableName (Field.LT "Nothing" "none")
+            let! exists = Exists.byFields SqliteDb.TableName Any [ Field.Less "Nothing" "none" ]
             Expect.isFalse exists "There should not have been any existing documents"
         }
     ]
 ]
-        testList "Find" [
+
+/// Integration tests for the Find module of the SQLite library
+let findTests = testList "Find" [
     testList "all" [
         testTask "succeeds when there is data" {
             use! db = SqliteDb.BuildDb()
@@ -391,12 +452,10 @@ let integrationTests =
             do! insert SqliteDb.TableName { Foo = "five"; Bar = "six" }
 
             let! results = Find.all<SubDocument> SqliteDb.TableName
-                    let expected = [
-                        { Foo = "one"; Bar = "two" }
-                        { Foo = "three"; Bar = "four" }
-                        { Foo = "five"; Bar = "six" }
-                    ]
-                    Expect.equal results expected "There should have been 3 documents returned"
+            Expect.equal
+                results
+                [ { Foo = "one"; Bar = "two" }; { Foo = "three"; Bar = "four" }; { Foo = "five"; Bar = "six" } ]
+                "There should have been 3 documents returned"
         }
         testTask "succeeds when there is no data" {
             use! db = SqliteDb.BuildDb()
@@ -404,13 +463,48 @@ let integrationTests =
             Expect.equal results [] "There should have been no documents returned"
         }
     ]
+    testList "allOrdered" [
+        testTask "succeeds when ordering numerically" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+            
+            let! results = Find.allOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "n:NumValue" ]
+            Expect.hasLength results 5 "There should have been 5 documents returned"
+            Expect.equal
+                (results |> List.map _.Id |> String.concat "|")
+                "one|three|two|four|five"
+                "The documents were not ordered correctly"
+        }
+        testTask "succeeds when ordering numerically descending" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+            
+            let! results = Find.allOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "n:NumValue DESC" ]
+            Expect.hasLength results 5 "There should have been 5 documents returned"
+            Expect.equal
+                (results |> List.map _.Id |> String.concat "|")
+                "five|four|two|three|one"
+                "The documents were not ordered correctly"
+        }
+        testTask "succeeds when ordering alphabetically" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+            
+            let! results = Find.allOrdered<JsonDocument> SqliteDb.TableName [ Field.Named "Id DESC" ]
+            Expect.hasLength results 5 "There should have been 5 documents returned"
+            Expect.equal
+                (results |> List.map _.Id |> String.concat "|")
+                "two|three|one|four|five"
+                "The documents were not ordered correctly"
+        }
+    ]
     testList "byId" [
         testTask "succeeds when a document is found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
             let! doc = Find.byId<string, JsonDocument> SqliteDb.TableName "two"
-                    Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+            Expect.isSome doc "There should have been a document returned"
             Expect.equal doc.Value.Id "two" "The incorrect document was returned"
         }
         testTask "succeeds when a document is not found" {
@@ -418,52 +512,149 @@ let integrationTests =
             do! loadDocs ()
 
             let! doc = Find.byId<string, JsonDocument> SqliteDb.TableName "three hundred eighty-seven"
-                    Expect.isFalse (Option.isSome doc) "There should not have been a document returned"
+            Expect.isNone doc "There should not have been a document returned"
         }
     ]
-            testList "byField" [
+    testList "byFields" [
         testTask "succeeds when documents are found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! docs = Find.byField<JsonDocument> SqliteDb.TableName (Field.GT "NumValue" 15)
-                    Expect.equal (List.length docs) 2 "There should have been two documents returned"
+            let! docs = Find.byFields<JsonDocument> SqliteDb.TableName Any [ Field.Greater "NumValue" 15 ]
+            Expect.hasLength docs 2 "There should have been two documents returned"
+        }
+        testTask "succeeds when documents are found using IN with numeric field" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! docs = Find.byFields<JsonDocument> SqliteDb.TableName All [ Field.In "NumValue" [ 2; 4; 6; 8 ] ]
+            Expect.hasLength docs 1 "There should have been one document returned"
         }
         testTask "succeeds when documents are not found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! docs = Find.byField<JsonDocument> SqliteDb.TableName (Field.GT "NumValue" 100)
+            let! docs = Find.byFields<JsonDocument> SqliteDb.TableName Any [ Field.Greater "NumValue" 100 ]
             Expect.isTrue (List.isEmpty docs) "There should have been no documents returned"
         }
+        testTask "succeeds for InArray when matching documents exist" {
+            use! db = SqliteDb.BuildDb()
+            do! Definition.ensureTable SqliteDb.TableName
+            for doc in ArrayDocument.TestDocuments do do! insert SqliteDb.TableName doc
+            
+            let! docs =
+                Find.byFields<ArrayDocument>
+                    SqliteDb.TableName All [ Field.InArray "Values" SqliteDb.TableName [ "c" ] ]
+            Expect.hasLength docs 2 "There should have been two documents returned"
+        }
+        testTask "succeeds for InArray when no matching documents exist" {
+            use! db = SqliteDb.BuildDb()
+            do! Definition.ensureTable SqliteDb.TableName
+            for doc in ArrayDocument.TestDocuments do do! insert SqliteDb.TableName doc
+            
+            let! docs =
+                Find.byFields<ArrayDocument>
+                    SqliteDb.TableName All [ Field.InArray "Values" SqliteDb.TableName [ "j" ] ]
+            Expect.isEmpty docs "There should have been no documents returned"
+        }
     ]
-            testList "firstByField" [
+    testList "byFieldsOrdered" [
+        testTask "succeeds when sorting ascending" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! docs =
+                Find.byFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName Any [ Field.Greater "NumValue" 15 ] [ Field.Named "Id" ]
+            Expect.hasLength docs 2 "There should have been two documents returned"
+            Expect.equal
+                (docs |> List.map _.Id |> String.concat "|") "five|four" "The documents were not ordered correctly"
+        }
+        testTask "succeeds when sorting descending" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! docs =
+                Find.byFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName Any [ Field.Greater "NumValue" 15 ] [ Field.Named "Id DESC" ]
+            Expect.hasLength docs 2 "There should have been two documents returned"
+            Expect.equal
+                (docs |> List.map _.Id |> String.concat "|") "four|five" "The documents were not ordered correctly"
+        }
+        testTask "succeeds when sorting case-sensitively" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! docs =
+                Find.byFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName All [ Field.LessOrEqual "NumValue" 10 ] [ Field.Named "Value" ]
+            Expect.hasLength docs 3 "There should have been three documents returned"
+            Expect.equal
+                (docs |> List.map _.Id |> String.concat "|") "three|one|two" "Documents not ordered correctly"
+        }
+        testTask "succeeds when sorting case-insensitively" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! docs =
+                Find.byFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName All [ Field.LessOrEqual "NumValue" 10 ] [ Field.Named "i:Value" ]
+            Expect.hasLength docs 3 "There should have been three documents returned"
+            Expect.equal
+                (docs |> List.map _.Id |> String.concat "|") "three|two|one" "Documents not ordered correctly"
+        }
+    ]
+    testList "firstByFields" [
         testTask "succeeds when a document is found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! doc = Find.firstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Value" "another")
-                    Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+            let! doc = Find.firstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Value" "another" ]
+            Expect.isSome doc "There should have been a document returned"
             Expect.equal doc.Value.Id "two" "The incorrect document was returned"
         }
         testTask "succeeds when multiple documents are found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! doc = Find.firstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Sub.Foo" "green")
-                    Expect.isTrue (Option.isSome doc) "There should have been a document returned"
+            let! doc = Find.firstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ]
+            Expect.isSome doc "There should have been a document returned"
             Expect.contains [ "two"; "four" ] doc.Value.Id "An incorrect document was returned"
         }
         testTask "succeeds when a document is not found" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    let! doc = Find.firstByField<JsonDocument> SqliteDb.TableName (Field.EQ "Value" "absent")
-                    Expect.isFalse (Option.isSome doc) "There should not have been a document returned"
+            let! doc = Find.firstByFields<JsonDocument> SqliteDb.TableName Any [ Field.Equal "Value" "absent" ]
+            Expect.isNone doc "There should not have been a document returned"
+        }
+    ]
+    testList "firstByFieldsOrdered" [
+        testTask "succeeds when sorting ascending" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! doc =
+                Find.firstByFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ] [ Field.Named "Sub.Bar" ]
+            Expect.isSome doc "There should have been a document returned"
+            Expect.equal "two" doc.Value.Id "An incorrect document was returned"
+        }
+        testTask "succeeds when sorting descending" {
+            use! db = SqliteDb.BuildDb()
+            do! loadDocs ()
+
+            let! doc =
+                Find.firstByFieldsOrdered<JsonDocument>
+                    SqliteDb.TableName Any [ Field.Equal "Sub.Foo" "green" ] [ Field.Named "Sub.Bar DESC" ]
+            Expect.isSome doc "There should have been a document returned"
+            Expect.equal "four" doc.Value.Id "An incorrect document was returned"
         }
     ]
 ]
-        testList "Update" [
+
+/// Integration tests for the Update module of the SQLite library
+let updateTests = testList "Update" [
     testList "byId" [
         testTask "succeeds when a document is updated" {
             use! db = SqliteDb.BuildDb()
@@ -483,9 +674,7 @@ let integrationTests =
             
             // This not raising an exception is the test
             do! Update.byId
-                            SqliteDb.TableName
-                            "test"
-                            { emptyDoc with Id = "x"; Sub = Some { Foo = "blue"; Bar = "red" } }
+                    SqliteDb.TableName "test" { emptyDoc with Id = "x"; Sub = Some { Foo = "blue"; Bar = "red" } }
         }
     ]
     testList "byFunc" [
@@ -493,8 +682,7 @@ let integrationTests =
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    do! Update.byFunc
-                            SqliteDb.TableName (_.Id) { Id = "one"; Value = "le un"; NumValue = 1; Sub = None }
+            do! Update.byFunc SqliteDb.TableName (_.Id) { Id = "one"; Value = "le un"; NumValue = 1; Sub = None }
             let! after = Find.byId<string, JsonDocument> SqliteDb.TableName "one"
             Expect.isSome after "There should have been a document returned post-update"
             Expect.equal
@@ -509,12 +697,13 @@ let integrationTests =
             Expect.isEmpty before "There should have been no documents returned"
             
             // This not raising an exception is the test
-                    do! Update.byFunc
-                            SqliteDb.TableName (_.Id) { Id = "one"; Value = "le un"; NumValue = 1; Sub = None }
+            do! Update.byFunc SqliteDb.TableName (_.Id) { Id = "one"; Value = "le un"; NumValue = 1; Sub = None }
         }
     ]
 ]
-        testList "Patch" [
+
+/// Integration tests for the Patch module of the SQLite library
+let patchTests = testList "Patch" [
     testList "byId" [
         testTask "succeeds when a document is updated" {
             use! db = SqliteDb.BuildDb()
@@ -535,13 +724,13 @@ let integrationTests =
             do! Patch.byId SqliteDb.TableName "test" {| Foo = "green" |}
         }
     ]
-            testList "byField" [
+    testList "byFields" [
         testTask "succeeds when a document is updated" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
             
-                    do! Patch.byField SqliteDb.TableName (Field.EQ "Value" "purple") {| NumValue = 77 |}
-                    let! after = Count.byField SqliteDb.TableName (Field.EQ "NumValue" 77)
+            do! Patch.byFields SqliteDb.TableName Any [ Field.Equal "Value" "purple" ] {| NumValue = 77 |}
+            let! after = Count.byFields SqliteDb.TableName Any [ Field.Equal "NumValue" 77 ]
             Expect.equal after 2L "There should have been 2 documents returned"
         }
         testTask "succeeds when no document is updated" {
@@ -551,11 +740,13 @@ let integrationTests =
             Expect.isEmpty before "There should have been no documents returned"
             
             // This not raising an exception is the test
-                    do! Patch.byField SqliteDb.TableName (Field.EQ "Value" "burgundy") {| Foo = "green" |}
+            do! Patch.byFields SqliteDb.TableName Any [ Field.Equal "Value" "burgundy" ] {| Foo = "green" |}
         }
     ]
 ]
-        testList "RemoveFields" [
+
+/// Integration tests for the RemoveFields module of the SQLite library
+let removeFieldsTests = testList "RemoveFields" [
     testList "byId" [
         testTask "succeeds when fields is removed" {
             use! db = SqliteDb.BuildDb()
@@ -583,12 +774,12 @@ let integrationTests =
             do! RemoveFields.byId SqliteDb.TableName "two" [ "Value" ]
         }
     ]
-            testList "byField" [
+    testList "byFields" [
         testTask "succeeds when a field is removed" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
             
-                    do! RemoveFields.byField SqliteDb.TableName (Field.EQ "NumValue" 17) [ "Sub" ]
+            do! RemoveFields.byFields SqliteDb.TableName Any [ Field.Equal "NumValue" 17 ] [ "Sub" ]
             try
                 let! _ = Find.byId<string, JsonDocument> SqliteDb.TableName "four"
                 Expect.isTrue false "The updated document should have failed to parse"
@@ -601,17 +792,19 @@ let integrationTests =
             do! loadDocs ()
             
             // This not raising an exception is the test
-                    do! RemoveFields.byField SqliteDb.TableName (Field.EQ "NumValue" 17) [ "Nothing" ]
+            do! RemoveFields.byFields SqliteDb.TableName Any [ Field.Equal "NumValue" 17 ] [ "Nothing" ]
         }
         testTask "succeeds when no document is matched" {
             use! db = SqliteDb.BuildDb()
             
             // This not raising an exception is the test
-                    do! RemoveFields.byField SqliteDb.TableName (Field.NE "Abracadabra" "apple") [ "Value" ]
+            do! RemoveFields.byFields SqliteDb.TableName Any [ Field.NotEqual "Abracadabra" "apple" ] [ "Value" ]
         }
     ]
 ]
-        testList "Delete" [
+
+/// Integration tests for the Delete module of the SQLite library
+let deleteTests = testList "Delete" [
     testList "byId" [
         testTask "succeeds when a document is deleted" {
             use! db = SqliteDb.BuildDb()
@@ -630,12 +823,12 @@ let integrationTests =
             Expect.equal remaining 5L "There should have been 5 documents remaining"
         }
     ]
-            testList "byField" [
+    testList "byFields" [
         testTask "succeeds when documents are deleted" {
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    do! Delete.byField SqliteDb.TableName (Field.NE "Value" "purple")
+            do! Delete.byFields SqliteDb.TableName Any [ Field.NotEqual "Value" "purple" ]
             let! remaining = Count.all SqliteDb.TableName
             Expect.equal remaining 2L "There should have been 2 documents remaining"
         }
@@ -643,16 +836,28 @@ let integrationTests =
             use! db = SqliteDb.BuildDb()
             do! loadDocs ()
 
-                    do! Delete.byField SqliteDb.TableName (Field.EQ "Value" "crimson")
+            do! Delete.byFields SqliteDb.TableName Any [ Field.Equal "Value" "crimson" ]
             let! remaining = Count.all SqliteDb.TableName
             Expect.equal remaining 5L "There should have been 5 documents remaining"
         }
     ]
 ]
-        test "clean up database" {
-            Configuration.useConnectionString "data source=:memory:"
-        }
-    ]
-    |> testSequenced
 
-let all = testList "Sqlite" [ unitTests; integrationTests ]
+/// All tests for the SQLite library
+let all = testList "Sqlite" [
+    testList "Unit" [ queryTests; parametersTests ]
+    testSequenced <| testList "Integration" [
+        configurationTests
+        customTests
+        definitionTests
+        documentTests
+        countTests
+        existsTests
+        findTests
+        updateTests
+        patchTests
+        removeFieldsTests
+        deleteTests
+        test "clean up database" { Configuration.useConnectionString "data source=:memory:" }
+    ]
+]

src/Tests/Types.fs

@@ -1,23 +1,39 @@
 module Types
 
+type NumIdDocument =
+    { Key: int
+      Text: string }
+
 type SubDocument =
     { Foo: string
       Bar: string }
 
+type ArrayDocument =
+    { Id: string
+      Values: string list }
+with
+    /// <summary>
+    /// A set of documents used for integration tests
+    /// </summary>
+    static member TestDocuments =
+        [ { Id = "first";  Values = [ "a"; "b"; "c" ] }
+          { Id = "second"; Values = [ "c"; "d"; "e" ] }
+          { Id = "third";  Values = [ "x"; "y"; "z" ] } ]
+
 type JsonDocument =
     { Id: string
       Value: string
       NumValue: int
       Sub: SubDocument option }
 
+
 /// An empty JsonDocument
 let emptyDoc = { Id = ""; Value = ""; NumValue = 0; Sub = None }
 
 /// Documents to use for testing
-let testDocuments = [
-    { Id = "one"; Value = "FIRST!"; NumValue = 0; Sub = None }
+let testDocuments =
+    [ { Id = "one";   Value = "FIRST!";  NumValue = 0;  Sub = None }
       { Id = "two";   Value = "another"; NumValue = 10; Sub = Some { Foo = "green"; Bar = "blue" } }
       { Id = "three"; Value = "";        NumValue = 4;  Sub = None }
       { Id = "four";  Value = "purple";  NumValue = 17; Sub = Some { Foo = "green"; Bar = "red" } }
-    { Id = "five"; Value = "purple"; NumValue = 18; Sub = None }
-]
+      { Id = "five";  Value = "purple";  NumValue = 18; Sub = None } ]

src/package.sh

@@ -1,13 +1,16 @@
 #!/bin/bash
 
 echo --- Package Common library
+rm Common/bin/Release/BitBadger.Documents.Common.*.nupkg || true
 dotnet pack Common/BitBadger.Documents.Common.fsproj -c Release
 cp Common/bin/Release/BitBadger.Documents.Common.*.nupkg .
 
 echo --- Package PostgreSQL library
+rm Postgres/bin/Release/BitBadger.Documents.Postgres*.nupkg || true
 dotnet pack Postgres/BitBadger.Documents.Postgres.fsproj -c Release
 cp Postgres/bin/Release/BitBadger.Documents.Postgres.*.nupkg .
 
 echo --- Package SQLite library
+rm Sqlite/bin/Release/BitBadger.Documents.Sqlite*.nupkg || true
 dotnet pack Sqlite/BitBadger.Documents.Sqlite.fsproj -c Release
 cp Sqlite/bin/Release/BitBadger.Documents.Sqlite.*.nupkg .

src/test_all.sh

@@ -7,8 +7,8 @@ dotnet build BitBadger.Documents.sln --no-restore
 cd ./Tests || exit
 
 export BBDOX_PG_PORT=8301
-PG_VERSIONS=('12' '13' '14' '15' 'latest')
-NET_VERSIONS=('6.0' '8.0')
+PG_VERSIONS=('13' '14' '15' '16' 'latest')
+NET_VERSIONS=('8.0' '9.0')
 
 for PG_VERSION in "${PG_VERSIONS[@]}"
 do