src/.idea/.idea.BitBadger.Documents/.idea/.gitignore

@@ -0,0 +1,13 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Rider ignored files
+/projectSettingsUpdater.xml
+/contentModel.xml
+/modules.xml
+/.idea.BitBadger.Documents.iml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

src/.idea/.idea.BitBadger.Documents/.idea/.name

@@ -0,0 +1 @@
+BitBadger.Documents

src/.idea/.idea.BitBadger.Documents/.idea/indexLayout.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="UserContentModel">
+    <attachedFolders>
+      <Path>../../BitBadger.Documents</Path>
+    </attachedFolders>
+    <explicitIncludes />
+    <explicitExcludes />
+  </component>
+</project>

src/.idea/.idea.BitBadger.Documents/.idea/vcs.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/.." vcs="Git" />
+  </component>
+</project>

src/BitBadger.Documents.sln

@@ -0,0 +1,40 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "BitBadger.Documents.Common", "Common\BitBadger.Documents.Common.fsproj", "{E52D624A-2A1F-4D38-82B6-115907D9CB1A}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Test", "Test\Test.csproj", "{0419E91C-2CC5-4FCC-BAB6-1074EFD9C073}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "BitBadger.Documents.Tests", "Tests\BitBadger.Documents.Tests.fsproj", "{45D5D503-9FD0-4ADB-ABC6-C8FDAD82B848}"
+EndProject
+Project("{F2A71F9B-5D33-465A-A702-920D77279786}") = "BitBadger.Documents.Sqlite", "Sqlite\BitBadger.Documents.Sqlite.fsproj", "{B8A82483-1E72-46D2-B29A-1C371AC5DD20}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|Any CPU = Debug|Any CPU
+		Release|Any CPU = Release|Any CPU
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{E52D624A-2A1F-4D38-82B6-115907D9CB1A}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E52D624A-2A1F-4D38-82B6-115907D9CB1A}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E52D624A-2A1F-4D38-82B6-115907D9CB1A}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E52D624A-2A1F-4D38-82B6-115907D9CB1A}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0419E91C-2CC5-4FCC-BAB6-1074EFD9C073}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0419E91C-2CC5-4FCC-BAB6-1074EFD9C073}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0419E91C-2CC5-4FCC-BAB6-1074EFD9C073}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0419E91C-2CC5-4FCC-BAB6-1074EFD9C073}.Release|Any CPU.Build.0 = Release|Any CPU
+		{45D5D503-9FD0-4ADB-ABC6-C8FDAD82B848}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{45D5D503-9FD0-4ADB-ABC6-C8FDAD82B848}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{45D5D503-9FD0-4ADB-ABC6-C8FDAD82B848}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{45D5D503-9FD0-4ADB-ABC6-C8FDAD82B848}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B8A82483-1E72-46D2-B29A-1C371AC5DD20}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B8A82483-1E72-46D2-B29A-1C371AC5DD20}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B8A82483-1E72-46D2-B29A-1C371AC5DD20}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B8A82483-1E72-46D2-B29A-1C371AC5DD20}.Release|Any CPU.Build.0 = Release|Any CPU
+	EndGlobalSection
+EndGlobal

src/Common/BitBadger.Documents.Common.fsproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <Compile Include="Library.fs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="FSharp.SystemTextJson" Version="1.2.42" />
+  </ItemGroup>
+
+</Project>

src/Common/Library.fs

@@ -0,0 +1,204 @@
+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
+    /// Exists (IS NOT NULL)
+    | EX
+    /// Does Not Exist (IS NULL)
+    | NEX
+    
+    override this.ToString() =
+        match this with
+        | EQ -> "="
+        | GT -> ">"
+        | GE -> ">="
+        | LT -> "<"
+        | LE -> "<="
+        | NE -> "<>"
+        | EX -> "IS NOT NULL"
+        | NEX -> "IS NULL"
+
+
+/// The required document serialization implementation
+type IDocumentSerializer =
+    
+    /// Serialize an object to a JSON string
+    abstract Serialize<'T> : 'T -> string
+    
+    /// Deserialize a JSON string into an object
+    abstract Deserialize<'T> : string -> 'T
+
+
+/// Document serializer defaults 
+module DocumentSerializer =
+    
+    open System.Text.Json
+    open System.Text.Json.Serialization
+    
+    /// The default JSON serializer options to use with the stock serializer
+    let private jsonDefaultOpts =
+        let o = JsonSerializerOptions()
+        o.Converters.Add(JsonFSharpConverter())
+        o
+    
+    /// The default JSON serializer
+    [<CompiledName "Default">]
+    let ``default`` =
+        { new IDocumentSerializer with
+            member _.Serialize<'T>(it: 'T) : string =
+                JsonSerializer.Serialize(it, jsonDefaultOpts)
+            member _.Deserialize<'T>(it: string) : 'T =
+                JsonSerializer.Deserialize<'T>(it, jsonDefaultOpts)
+        }
+
+
+/// Configuration for document handling
+[<RequireQualifiedAccess>]
+module Configuration =
+
+    /// The serializer to use for document manipulation
+    let mutable private serializerValue = DocumentSerializer.``default``
+    
+    /// Register a serializer to use for translating documents to domain types
+    [<CompiledName "UseSerializer">]
+    let useSerializer ser =
+        serializerValue <- ser
+
+    /// Retrieve the currently configured serializer
+    [<CompiledName "Serializer">]
+    let serializer () =
+        serializerValue
+    
+    /// The serialized name of the ID field for documents
+    let mutable idFieldValue = "Id"
+    
+    /// Specify the name of the ID field for documents
+    [<CompiledName "UseIdField">]
+    let useIdField it =
+        idFieldValue <- it
+    
+    /// Retrieve the currently configured ID field for documents
+    [<CompiledName "IdField">]
+    let idField () =
+        idFieldValue
+
+
+/// Query construction functions
+[<RequireQualifiedAccess>]
+module Query =
+    
+    /// Create a SELECT clause to retrieve the document data from the given table
+    [<CompiledName "SelectFromTable">]
+    let selectFromTable tableName =
+        $"SELECT data FROM %s{tableName}"
+    
+    /// Create a WHERE clause fragment to implement a comparison on a field in a JSON document
+    [<CompiledName "WhereByField">]
+    let whereByField fieldName op paramName =
+        let theRest =
+            match op with
+            | EX | NEX -> string op
+            | _ -> $"{op} %s{paramName}"
+        $"data ->> '%s{fieldName}' {theRest}"
+    
+    /// Create a WHERE clause fragment to implement an ID-based query
+    [<CompiledName "WhereById">]
+    let whereById paramName =
+        whereByField (Configuration.idField ()) EQ paramName
+    
+    /// Query to insert a document
+    [<CompiledName "Insert">]
+    let insert tableName =
+        $"INSERT INTO %s{tableName} VALUES (@data)"
+
+    /// Query to save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
+    [<CompiledName "Save">]
+    let save tableName =
+        sprintf
+            "INSERT INTO %s VALUES (@data) ON CONFLICT ((data ->> '%s')) DO UPDATE SET data = EXCLUDED.data"
+            tableName (Configuration.idField ()) 
+    
+    /// Queries for counting documents
+    module Count =
+        
+        /// Query to count all documents in a table
+        [<CompiledName "All">]
+        let all tableName =
+            $"SELECT COUNT(*) AS it FROM %s{tableName}"
+        
+        /// Query to count matching documents using a text comparison on a JSON field
+        [<CompiledName "ByField">]
+        let byField tableName fieldName op =
+            $"""SELECT COUNT(*) AS it FROM %s{tableName} WHERE {whereByField fieldName op "@field"}"""
+        
+    /// Queries for determining document existence
+    module Exists =
+
+        /// Query to determine if a document exists for the given ID
+        [<CompiledName "ById">]
+        let byId tableName =
+            $"""SELECT EXISTS (SELECT 1 FROM %s{tableName} WHERE {whereById "@id"}) AS it"""
+
+        /// Query to determine if documents exist using a comparison on a JSON field
+        [<CompiledName "ByField">]
+        let byField tableName fieldName op =
+            $"""SELECT EXISTS (SELECT 1 FROM %s{tableName} WHERE {whereByField fieldName op "@field"}) AS it"""
+        
+    /// Queries for retrieving documents
+    module Find =
+
+        /// Query to retrieve a document by its ID
+        [<CompiledName "ById">]
+        let byId tableName =
+            $"""{selectFromTable tableName} WHERE {whereById "@id"}"""
+        
+        /// Query to retrieve documents using a comparison on a JSON field
+        [<CompiledName "ByField">]
+        let byField tableName fieldName op =
+            $"""{selectFromTable tableName} WHERE {whereByField fieldName op "@field"}"""
+        
+    /// Queries to update documents
+    module Update =
+
+        /// Query to update a document
+        [<CompiledName "Full">]
+        let full tableName =
+            $"""UPDATE %s{tableName} SET data = @data WHERE {whereById "@id"}"""
+
+        /// Query to update a partial document by its ID
+        [<CompiledName "PartialById">]
+        let partialById tableName =
+            $"""UPDATE %s{tableName} SET data = json_patch(data, json(@data)) WHERE {whereById "@id"}"""
+            
+        /// Query to update a partial document via a comparison on a JSON field
+        [<CompiledName "PartialByField">]
+        let partialByField tableName fieldName op =
+            sprintf
+                "UPDATE %s SET data = json_patch(data, json(@data)) WHERE %s"
+                tableName (whereByField fieldName op "@field")
+        
+    /// Queries to delete documents
+    module Delete =
+        
+        /// Query to delete a document by its ID
+        [<CompiledName "ById">]
+        let byId tableName =
+            $"""DELETE FROM %s{tableName} WHERE {whereById "@id"}"""
+
+        /// Query to delete documents using a comparison on a JSON field
+        [<CompiledName "ByField">]
+        let byField tableName fieldName op =
+            $"""DELETE FROM %s{tableName} WHERE {whereByField fieldName op "@field"}"""

src/Directory.Build.props

@@ -0,0 +1,23 @@
+<Project>
+  <PropertyGroup>
+    <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
+    <DebugType>embedded</DebugType>
+    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+    <AssemblyVersion>1.0.0.0</AssemblyVersion>
+    <FileVersion>1.0.0.0</FileVersion>
+    <VersionPrefix>1.0.0</VersionPrefix>
+    <VersionSuffix>alpha</VersionSuffix>
+    <PackageReleaseNotes>Initial release with F# support</PackageReleaseNotes>
+    <Authors>danieljsummers</Authors>
+    <Company>Bit Badger Solutions</Company>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>icon.png</PackageIcon>
+    <PackageProjectUrl>https://bitbadger.solutions/open-source/sqlite-documents/</PackageProjectUrl>
+    <PackageRequireLicenseAcceptance>false</PackageRequireLicenseAcceptance>
+    <RepositoryUrl>https://github.com/bit-badger/BitBadger.Sqlite.Documents</RepositoryUrl>
+    <RepositoryType>Git</RepositoryType>
+    <Copyright>MIT License</Copyright>
+    <PackageLicenseExpression>MIT</PackageLicenseExpression>
+    <PackageTags>SQLite JSON document</PackageTags>
+  </PropertyGroup>
+</Project>

src/Sqlite/BitBadger.Documents.Sqlite.fsproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <Compile Include="Library.fs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="FSharp.SystemTextJson" Version="1.2.42" />
+    <PackageReference Include="Microsoft.Data.Sqlite" Version="8.0.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleToAttribute">
+      <_Parameter1>BitBadger.Documents.Tests</_Parameter1>
+    </AssemblyAttribute>
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Common\BitBadger.Documents.Common.fsproj" />
+  </ItemGroup>
+
+</Project>

src/Sqlite/Library.fs

@@ -0,0 +1,494 @@
+module BitBadger.Documents.Sqlite
+
+open BitBadger.Documents
+open Microsoft.Data.Sqlite
+
+/// Configuration for document handling
+module Configuration =
+
+    /// The connection string to use for query execution
+    let mutable internal connectionString: string option = None
+
+    /// Register a connection string to use for query execution (enables foreign keys)
+    let useConnectionString connStr =
+        let builder = SqliteConnectionStringBuilder(connStr)
+        builder.ForeignKeys <- Option.toNullable (Some true)
+        connectionString <- Some (string builder)
+    
+    /// Retrieve the currently configured data source
+    let dbConn () =
+        match connectionString with
+        | Some connStr ->
+            let conn = new SqliteConnection(connStr)
+            conn.Open()
+            conn
+        | None -> invalidOp "Please provide a connection string before attempting data access"
+
+
+/// Execute a non-query command
+let internal write (cmd: SqliteCommand) = backgroundTask {
+    let! _ = cmd.ExecuteNonQueryAsync()
+    ()
+}
+
+/// Data definition
+[<RequireQualifiedAccess>]
+module Definition =
+
+    /// SQL statement to create a document table
+    let createTable name =
+        $"CREATE TABLE IF NOT EXISTS %s{name} (data TEXT NOT NULL)"
+    
+    /// SQL statement to create a key index for a document table
+    let createKey name =
+        $"CREATE UNIQUE INDEX IF NOT EXISTS idx_%s{name}_key ON {name} ((data ->> '{Configuration.idField ()}'))"
+        
+    /// Definitions that take a SqliteConnection as their last parameter
+    module WithConn =
+        
+        /// Create a document table
+        let ensureTable name (conn: SqliteConnection) = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- createTable name
+            do! write cmd
+            cmd.CommandText <- createKey name
+            do! write cmd
+        }
+    
+    /// Create a document table
+    let ensureTable name =
+        use conn = Configuration.dbConn ()
+        WithConn.ensureTable name conn
+
+
+/// Add a parameter to a SQLite command, ignoring the return value (can still be accessed on cmd via indexing)
+let addParam (cmd: SqliteCommand) name (value: obj) =
+    cmd.Parameters.AddWithValue(name, value) |> ignore
+    
+let addIdParam (cmd: SqliteCommand) (key: 'TKey) =
+    addParam cmd "@id" (string key)
+
+/// Add a JSON document parameter to a command
+let addJsonParam (cmd: SqliteCommand) name (it: 'TJson) =
+    addParam cmd name (Configuration.serializer().Serialize it)
+
+/// Add ID (@id) and document (@data) parameters to a command
+let addIdAndDocParams cmd (docId: 'TKey) (doc: 'TDoc) =
+    addIdParam cmd docId
+    addJsonParam cmd "@data" doc
+
+/// Create a domain item from a document, specifying the field in which the document is found
+let fromDocument<'TDoc> field (rdr: SqliteDataReader) : 'TDoc =
+    Configuration.serializer().Deserialize<'TDoc>(rdr.GetString(rdr.GetOrdinal(field)))
+    
+/// Create a domain item from a document
+let fromData<'TDoc> rdr =
+    fromDocument<'TDoc> "data" rdr
+
+/// Create a list of items for the results of the given command, using the specified mapping function
+let toCustomList<'TDoc> (cmd: SqliteCommand) (mapFunc: SqliteDataReader -> 'TDoc) = backgroundTask {
+    use! rdr = cmd.ExecuteReaderAsync()
+    let mutable it = Seq.empty<'TDoc>
+    while! rdr.ReadAsync() do
+        it <- Seq.append it (Seq.singleton (mapFunc rdr))
+    return List.ofSeq it
+}
+
+/// Create a list of items for the results of the given command
+let toDocumentList<'TDoc> (cmd: SqliteCommand) =
+    toCustomList<'TDoc> cmd fromData
+
+/// Execute a non-query statement to manipulate a document
+let private executeNonQuery query (document: 'T) (conn: SqliteConnection) =
+    use cmd = conn.CreateCommand()
+    cmd.CommandText <- query
+    addJsonParam cmd "@data" document
+    write cmd
+
+/// Execute a non-query statement to manipulate a document with an ID specified
+let private executeNonQueryWithId query (docId: 'TKey) (document: 'TDoc) (conn: SqliteConnection) =
+    use cmd = conn.CreateCommand()
+    cmd.CommandText <- query
+    addIdAndDocParams cmd docId document
+    write cmd
+
+
+open System.Threading.Tasks
+
+/// Versions of queries that accept a SqliteConnection as the last parameter
+module WithConn =
+    
+    /// Insert a new document
+    let insert<'TDoc> tableName (document: 'TDoc) conn =
+        executeNonQuery (Query.insert tableName) document conn
+
+    /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
+    let save<'TDoc> tableName (document: 'TDoc) conn =
+        executeNonQuery (Query.save tableName) document conn
+
+    /// Commands to count documents
+    [<RequireQualifiedAccess>]
+    module Count =
+        
+        /// Count all documents in a table
+        let all tableName (conn: SqliteConnection) : Task<int64> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Count.all tableName
+            let! result = cmd.ExecuteScalarAsync()
+            return result :?> int64
+        }
+        
+        /// Count matching documents using a comparison on a JSON field
+        let byField tableName fieldName op (value: obj) (conn: SqliteConnection) : Task<int64> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Count.byField tableName fieldName op
+            addParam cmd "@field" value
+            let! result = cmd.ExecuteScalarAsync()
+            return result :?> int64
+        }
+
+    /// Commands to determine if documents exist
+    [<RequireQualifiedAccess>]
+    module Exists =
+
+        /// Determine if a document exists for the given ID
+        let byId tableName (docId: 'TKey) (conn: SqliteConnection) : Task<bool> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Exists.byId tableName
+            addIdParam cmd docId
+            let! result = cmd.ExecuteScalarAsync()
+            return (result :?> int64) > 0
+        }
+
+        /// Determine if a document exists using a comparison on a JSON field
+        let byField tableName fieldName op (value: obj) (conn: SqliteConnection) : Task<bool> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Exists.byField tableName fieldName op
+            addParam cmd "@field" value
+            let! result = cmd.ExecuteScalarAsync()
+            return (result :?> int64) > 0
+        }
+    
+    /// Commands to retrieve documents
+    [<RequireQualifiedAccess>]
+    module Find =
+        
+        /// Retrieve all documents in the given table
+        let all<'TDoc> tableName (conn: SqliteConnection) : Task<'TDoc list> =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.selectFromTable tableName
+            toDocumentList<'TDoc> cmd
+
+        /// Retrieve a document by its ID
+        let byId<'TKey, 'TDoc> tableName (docId: 'TKey) (conn: SqliteConnection) : Task<'TDoc option> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Find.byId tableName
+            addIdParam cmd docId
+            let! results = toDocumentList<'TDoc> cmd
+            return List.tryHead results
+        }
+
+        /// Retrieve documents via a comparison on a JSON field
+        let byField<'TDoc> tableName fieldName op (value: obj) (conn: SqliteConnection) : Task<'TDoc list> =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Find.byField tableName fieldName op
+            addParam cmd "@field" value
+            toDocumentList<'TDoc> cmd
+
+        /// Retrieve documents via a comparison on a JSON field, returning only the first result
+        let firstByField<'TDoc> tableName fieldName op (value: obj) (conn: SqliteConnection)
+                : Task<'TDoc option> = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- $"{Query.Find.byField tableName fieldName op} LIMIT 1"
+            addParam cmd "@field" value
+            let! results = toDocumentList<'TDoc> cmd
+            return List.tryHead results
+        }
+
+    /// Commands to update documents
+    [<RequireQualifiedAccess>]
+    module Update =
+        
+        /// Update an entire document
+        let full tableName (docId: 'TKey) (document: 'TDoc) conn =
+            executeNonQueryWithId (Query.Update.full tableName) docId document conn
+        
+        /// Update an entire document
+        let fullFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) conn =
+            full tableName (idFunc document) document conn
+        
+        /// Update a partial document
+        let partialById tableName (docId: 'TKey) (partial: 'TPatch) conn =
+            executeNonQueryWithId (Query.Update.partialById tableName) docId partial conn
+        
+        /// Update partial documents using a comparison on a JSON field
+        let partialByField tableName fieldName op (value: obj) (partial: 'TPatch) (conn: SqliteConnection) =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Update.partialByField tableName fieldName op
+            addParam cmd "@field" value
+            addJsonParam cmd "@data" partial
+            write cmd
+
+    /// Commands to delete documents
+    [<RequireQualifiedAccess>]
+    module Delete =
+        
+        /// Delete a document by its ID
+        let byId tableName (docId: 'TKey) conn =
+            executeNonQueryWithId (Query.Delete.byId tableName) docId {||} conn
+
+        /// Delete documents by matching a comparison on a JSON field
+        let byField tableName fieldName op (value: obj) (conn: SqliteConnection) =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- Query.Delete.byField tableName fieldName op
+            addParam cmd "@field" value
+            write cmd
+
+    /// Commands to execute custom SQL queries
+    [<RequireQualifiedAccess>]
+    module Custom =
+
+        /// Execute a query that returns a list of results
+        let list<'TDoc> query (parameters: SqliteParameter seq) (mapFunc: SqliteDataReader -> 'TDoc)
+                (conn: SqliteConnection) =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- query
+            cmd.Parameters.AddRange parameters
+            toCustomList<'TDoc> cmd mapFunc
+
+        /// Execute a query that returns one or no results
+        let single<'TDoc> query parameters (mapFunc: SqliteDataReader -> 'TDoc) conn = backgroundTask {
+            let! results = list query parameters mapFunc conn
+            return List.tryHead results
+        }
+        
+        /// Execute a query that does not return a value
+        let nonQuery query (parameters: SqliteParameter seq) (conn: SqliteConnection) =
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- query
+            cmd.Parameters.AddRange parameters
+            write cmd
+
+        /// Execute a query that returns a scalar value
+        let scalar<'T when 'T : struct> query (parameters: SqliteParameter seq) (mapFunc: SqliteDataReader -> 'T)
+                (conn: SqliteConnection) = backgroundTask {
+            use cmd = conn.CreateCommand()
+            cmd.CommandText <- query
+            cmd.Parameters.AddRange parameters
+            use! rdr = cmd.ExecuteReaderAsync()
+            let! isFound = rdr.ReadAsync()
+            return if isFound then mapFunc rdr else Unchecked.defaultof<'T>
+        }
+
+/// Insert a new document
+let insert<'TDoc> tableName (document: 'TDoc) =
+    use conn = Configuration.dbConn ()
+    WithConn.insert tableName document conn
+
+/// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
+let save<'TDoc> tableName (document: 'TDoc) =
+    use conn = Configuration.dbConn ()
+    WithConn.save tableName document conn
+
+/// Commands to count documents
+[<RequireQualifiedAccess>]
+module Count =
+    
+    /// Count all documents in a table
+    let all tableName =
+        use conn = Configuration.dbConn ()
+        WithConn.Count.all tableName conn
+    
+    /// Count matching documents using a comparison on a JSON field
+    let byField tableName fieldName op (value: obj) =
+        use conn = Configuration.dbConn ()
+        WithConn.Count.byField tableName fieldName op value conn
+
+/// Commands to determine if documents exist
+[<RequireQualifiedAccess>]
+module Exists =
+
+    /// Determine if a document exists for the given ID
+    let byId tableName (docId: 'TKey) =
+        use conn = Configuration.dbConn ()
+        WithConn.Exists.byId tableName docId conn
+
+    /// Determine if a document exists using a comparison on a JSON field
+    let byField tableName fieldName op (value: obj) =
+        use conn = Configuration.dbConn ()
+        WithConn.Exists.byField tableName fieldName op value conn
+
+/// Commands to determine if documents exist
+[<RequireQualifiedAccess>]
+module Find =
+    
+    /// Retrieve all documents in the given table
+    let all<'TDoc> tableName =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.all<'TDoc> tableName conn
+
+    /// Retrieve a document by its ID
+    let byId<'TKey, 'TDoc> tableName docId =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.byId<'TKey, 'TDoc> tableName docId conn
+
+    /// Retrieve documents via a comparison on a JSON field
+    let byField<'TDoc> tableName fieldName op value =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.byField<'TDoc> tableName fieldName op value conn
+
+    /// Retrieve documents via a comparison on a JSON field, returning only the first result
+    let firstByField<'TDoc> tableName fieldName op value =
+        use conn = Configuration.dbConn ()
+        WithConn.Find.firstByField<'TDoc> tableName fieldName op value conn
+
+/// Commands to update documents
+[<RequireQualifiedAccess>]
+module Update =
+    
+    /// Update an entire document
+    let full tableName (docId: 'TKey) (document: 'TDoc) =
+        use conn = Configuration.dbConn ()
+        WithConn.Update.full tableName docId document conn
+    
+    /// Update an entire document
+    let fullFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) =
+        use conn = Configuration.dbConn ()
+        WithConn.Update.fullFunc tableName idFunc document conn
+    
+    /// Update a partial document
+    let partialById tableName (docId: 'TKey) (partial: 'TPatch) =
+        use conn = Configuration.dbConn ()
+        WithConn.Update.partialById tableName docId partial conn
+    
+    /// Update partial documents using a comparison on a JSON field in the WHERE clause
+    let partialByField tableName fieldName op (value: obj) (partial: 'TPatch) =
+        use conn = Configuration.dbConn ()
+        WithConn.Update.partialByField tableName fieldName op value partial conn
+
+/// Commands to delete documents
+[<RequireQualifiedAccess>]
+module Delete =
+    
+    /// Delete a document by its ID
+    let byId tableName (docId: 'TKey) =
+        use conn = Configuration.dbConn ()
+        WithConn.Delete.byId tableName docId conn
+
+    /// Delete documents by matching a comparison on a JSON field
+    let byField tableName fieldName op (value: obj) =
+        use conn = Configuration.dbConn ()
+        WithConn.Delete.byField tableName fieldName op value conn
+
+/// Commands to execute custom SQL queries
+[<RequireQualifiedAccess>]
+module Custom =
+
+    /// Execute a query that returns a list of results
+    let list<'TDoc> query parameters (mapFunc: SqliteDataReader -> 'TDoc) =
+        use conn = Configuration.dbConn ()
+        WithConn.Custom.list<'TDoc> query parameters mapFunc conn
+
+    /// Execute a query that returns one or no results
+    let single<'TDoc> query parameters (mapFunc: SqliteDataReader -> 'TDoc) =
+        use conn = Configuration.dbConn ()
+        WithConn.Custom.single<'TDoc> query parameters mapFunc conn
+
+    /// Execute a query that does not return a value
+    let nonQuery query parameters =
+        use conn = Configuration.dbConn ()
+        WithConn.Custom.nonQuery query parameters conn
+    
+    /// Execute a query that returns a scalar value
+    let scalar<'T when 'T : struct> query parameters (mapFunc: SqliteDataReader -> 'T) =
+        use conn = Configuration.dbConn ()
+        WithConn.Custom.scalar<'T> query parameters mapFunc conn
+
+[<AutoOpen>]
+module Extensions =
+
+    type SqliteConnection with
+        
+        /// Create a document table
+        member conn.ensureTable name =
+            Definition.WithConn.ensureTable name conn
+        
+        /// Insert a new document
+        member conn.insert<'TDoc> tableName (document: 'TDoc) =
+            WithConn.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
+
+        /// Count all documents in a table
+        member conn.countAll tableName =
+            WithConn.Count.all tableName conn
+        
+        /// Count matching documents using a comparison on a JSON field
+        member conn.countByField tableName fieldName op (value: obj) =
+            WithConn.Count.byField tableName fieldName op value conn
+        
+        /// Determine if a document exists for the given ID
+        member conn.existsById tableName (docId: 'TKey) =
+            WithConn.Exists.byId tableName docId conn
+
+        /// Determine if a document exists using a comparison on a JSON field
+        member conn.existsByField tableName fieldName op (value: obj) =
+            WithConn.Exists.byField tableName fieldName op value conn
+
+        /// Retrieve all documents in the given table
+        member conn.findAll<'TDoc> tableName =
+            WithConn.Find.all<'TDoc> tableName conn
+
+        /// Retrieve a document by its ID
+        member conn.findById<'TKey, 'TDoc> tableName (docId: 'TKey) =
+            WithConn.Find.byId<'TKey, 'TDoc> tableName docId conn
+
+        /// Retrieve documents via a comparison on a JSON field
+        member conn.findByField<'TDoc> tableName fieldName op (value: obj) =
+            WithConn.Find.byField<'TDoc> tableName fieldName op value conn
+
+        /// Retrieve documents via a comparison on a JSON field, returning only the first result
+        member conn.findFirstByField<'TDoc> tableName fieldName op (value: obj) =
+            WithConn.Find.firstByField<'TDoc> tableName fieldName op value conn
+
+        /// Update an entire document
+        member conn.updateFull tableName (docId: 'TKey) (document: 'TDoc) =
+            WithConn.Update.full tableName docId document conn
+        
+        /// Update an entire document
+        member conn.updateFullFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) =
+            WithConn.Update.fullFunc tableName idFunc document conn
+        
+        /// Update a partial document
+        member conn.updatePartialById tableName (docId: 'TKey) (partial: 'TPatch) =
+            WithConn.Update.partialById tableName docId partial conn
+        
+        /// Update partial documents using a comparison on a JSON field
+        member conn.updatePartialByField tableName fieldName op (value: obj) (partial: 'TPatch) =
+            WithConn.Update.partialByField tableName fieldName op value partial conn
+
+        /// Delete a document by its ID
+        member conn.deleteById tableName (docId: 'TKey) =
+            WithConn.Delete.byId tableName docId conn
+
+        /// Delete documents by matching a comparison on a JSON field
+        member conn.deleteByField tableName fieldName op (value: obj) =
+            WithConn.Delete.byField tableName fieldName op value conn
+
+        /// Execute a query that returns a list of results
+        member conn.customList<'TDoc> query parameters mapFunc =
+            WithConn.Custom.list<'TDoc> query parameters mapFunc conn
+
+        /// Execute a query that returns one or no results
+        member conn.customSingle<'TDoc> query parameters mapFunc =
+            WithConn.Custom.single<'TDoc> query parameters mapFunc conn
+        
+        /// Execute a query that does not return a value
+        member conn.customNonQuery query parameters =
+            WithConn.Custom.nonQuery query parameters conn
+
+        /// Execute a query that returns a scalar value
+        member conn.customScalar<'T when 'T: struct> query parameters mapFunc =
+            WithConn.Custom.scalar<'T> query parameters mapFunc conn

src/Test/Class1.cs

@@ -0,0 +1,12 @@
+namespace Test;
+
+using BitBadger.Documents;
+
+public class Class1
+{
+    public void Toot()
+    {
+        var ticket = Query.WhereByField("test", Op.GE, "");
+        var others = Query.Count.All("howdy");
+    }
+}

src/Test/Test.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Common\BitBadger.Documents.Common.fsproj" />
+  </ItemGroup>
+
+</Project>

src/Tests/BitBadger.Documents.Tests.fsproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="CommonTests.fs" />
+    <Compile Include="SqliteTests.fs" />
+    <Compile Include="Program.fs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Expecto" Version="10.1.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Common\BitBadger.Documents.Common.fsproj" />
+    <ProjectReference Include="..\Sqlite\BitBadger.Documents.Sqlite.fsproj" />
+  </ItemGroup>
+
+</Project>

src/Tests/CommonTests.fs

@@ -0,0 +1,143 @@
+module CommonTests
+
+open BitBadger.Documents
+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"
+            }
+            test "GT succeeds" {
+                Expect.equal (string GT) ">" "The greater than operator was not correct"
+            }
+            test "GE succeeds" {
+                Expect.equal (string GE) ">=" "The greater than or equal to operator was not correct"
+            }
+            test "LT succeeds" {
+                Expect.equal (string LT) "<" "The less than operator was not correct"
+            }
+            test "LE succeeds" {
+                Expect.equal (string LE) "<=" "The less than or equal to operator was not correct"
+            }
+            test "NE succeeds" {
+                Expect.equal (string NE) "<>" "The not equal to operator was not correct"
+            }
+            test "EX succeeds" {
+                Expect.equal (string EX) "IS NOT NULL" """The "exists" operator ws not correct"""
+            }
+            test "NEX succeeds" {
+                Expect.equal (string NEX) "IS NULL" """The "not exists" operator ws not correct"""
+            }
+        ]
+        testList "Query" [
+            test "selectFromTable succeeds" {
+                Expect.equal (Query.selectFromTable tbl) $"SELECT data FROM {tbl}" "SELECT statement not correct"
+            }
+            test "whereById succeeds" {
+                Expect.equal (Query.whereById "@id") "data ->> 'Id' = @id" "WHERE clause not correct"
+            }
+            testList "whereByField" [
+                test "succeeds when a logical operator is passed" {
+                    Expect.equal
+                        (Query.whereByField "theField" GT "@test")
+                        "data ->> 'theField' > @test"
+                        "WHERE clause not correct"
+                }
+                test "succeeds when an existence operator is passed" {
+                    Expect.equal
+                        (Query.whereByField "thatField" NEX "")
+                        "data ->> 'thatField' IS NULL"
+                        "WHERE clause not correct"
+                }
+            ]
+            test "insert succeeds" {
+                Expect.equal (Query.insert tbl) $"INSERT INTO {tbl} VALUES (@data)" "INSERT statement not correct"
+            }
+            test "save succeeds" {
+                Expect.equal
+                    (Query.save tbl)
+                    $"INSERT INTO {tbl} VALUES (@data) ON CONFLICT ((data ->> 'Id')) DO UPDATE SET data = EXCLUDED.data"
+                    "INSERT ON CONFLICT UPDATE statement not correct"
+            }
+            testList "Count" [
+                test "all succeeds" {
+                    Expect.equal (Query.Count.all tbl) $"SELECT COUNT(*) AS it FROM {tbl}" "Count query not correct"
+                }
+                test "byField succeeds" {
+                    Expect.equal
+                        (Query.Count.byField tbl "thatField" EQ)
+                        $"SELECT COUNT(*) AS it FROM {tbl} WHERE data ->> 'thatField' = @field"
+                        "JSON field text comparison count query not correct"
+                }
+            ]
+            testList "Exists" [
+                test "byId succeeds" {
+                    Expect.equal
+                        (Query.Exists.byId tbl)
+                        $"SELECT EXISTS (SELECT 1 FROM {tbl} WHERE data ->> 'Id' = @id) AS it"
+                        "ID existence query not correct"
+                }
+                test "byField succeeds" {
+                    Expect.equal
+                        (Query.Exists.byField tbl "Test" LT)
+                        $"SELECT EXISTS (SELECT 1 FROM {tbl} WHERE data ->> 'Test' < @field) AS it"
+                        "JSON field text comparison exists query not correct"
+                }
+            ]
+            testList "Find" [
+                test "byId succeeds" {
+                    Expect.equal
+                        (Query.Find.byId tbl)
+                        $"SELECT data FROM {tbl} WHERE data ->> 'Id' = @id"
+                        "SELECT by ID query not correct"
+                }
+                test "byField succeeds" {
+                    Expect.equal
+                        (Query.Find.byField tbl "Golf" GE)
+                        $"SELECT data FROM {tbl} WHERE data ->> 'Golf' >= @field"
+                        "SELECT by JSON comparison query not correct"
+                }
+            ]
+            testList "Update" [
+                test "full succeeds" {
+                    Expect.equal
+                        (Query.Update.full tbl)
+                        $"UPDATE {tbl} SET data = @data WHERE data ->> 'Id' = @id"
+                        "UPDATE full statement not correct"
+                }
+                test "partialById succeeds" {
+                    Expect.equal
+                        (Query.Update.partialById tbl)
+                        $"UPDATE {tbl} SET data = json_patch(data, json(@data)) WHERE data ->> 'Id' = @id"
+                        "UPDATE partial by ID statement not correct"
+                }
+                test "partialByField succeeds" {
+                    Expect.equal
+                        (Query.Update.partialByField tbl "Part" NE)
+                        $"UPDATE {tbl} SET data = json_patch(data, json(@data)) WHERE data ->> 'Part' <> @field"
+                        "UPDATE partial by JSON comparison query not correct"
+                }
+            ]
+            testList "Delete" [
+                test "byId succeeds" {
+                    Expect.equal
+                        (Query.Delete.byId tbl)
+                        $"DELETE FROM {tbl} WHERE data ->> 'Id' = @id"
+                        "DELETE by ID query not correct"
+                }
+                test "byField succeeds" {
+                    Expect.equal
+                        (Query.Delete.byField tbl "gone" NEX)
+                        $"DELETE FROM {tbl} WHERE data ->> 'gone' IS NULL"
+                        "DELETE by JSON comparison query not correct"
+                }
+            ]
+        ]
+    ]
+

src/Tests/Program.fs

@@ -0,0 +1,6 @@
+open Expecto
+
+let allTests = testList "BitBadger.Documents" [ CommonTests.all; SqliteTests.all ]
+
+[<EntryPoint>]
+let main args = runTestsWithCLIArgs [] args allTests