BitBadger.Documents/src/Sqlite/Library.fs

namespace 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)
    [<CompiledName "UseConnectionString">]
    let useConnectionString connStr =
        let builder = SqliteConnectionStringBuilder connStr
        builder.ForeignKeys <- Option.toNullable (Some true)
        connectionString <- Some (string builder)
    
    /// Retrieve the currently configured data source
    [<CompiledName "DbConn">]
    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"


/// Query definitions
[<RequireQualifiedAccess>]
module Query =
    
    /// Create a WHERE clause fragment to implement a comparison on fields in a JSON document
    [<CompiledName "WhereByFields">]
    let whereByFields howMatched fields =
        let name = ParameterName()
        fields
        |> Seq.map (fun it ->
            match it.Op with
            | EX | NEX -> $"{it.Path SQLite} {it.Op}"
            | BT ->
                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}")
        |> String.concat (match howMatched with Any -> " OR " | All -> " AND ")

    /// 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">]
    let whereByField field paramName =
        whereByFields Any [ { field with ParameterName = Some paramName } ]
    
    /// 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 } ]
    
    /// Data definition
    module Definition =

        /// SQL statement to create a document table
        [<CompiledName "EnsureTable">]
        let ensureTable name =
            Query.Definition.ensureTableFor name "TEXT"
    
    /// Query to update a document
    [<CompiledName "Update">]
    let update tableName =
        $"""UPDATE %s{tableName} SET data = @data WHERE {whereById "@id"}"""

    /// Queries for counting documents
    module Count =
        
        /// Query to count matching documents using a text comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields =
            Query.Count.byFields whereByFields tableName howMatched fields
        
        /// Query to count matching documents using a text 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 ]
        
    /// 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 JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields =
            $"SELECT EXISTS (SELECT 1 FROM %s{tableName} WHERE {whereByFields howMatched fields}) AS it"
        
        /// Query to determine if documents exist 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 ]
        
    /// Queries for retrieving documents
    module Find =

        /// Query to retrieve a document by its ID
        [<CompiledName "ById">]
        let byId tableName =
            $"""{Query.selectFromTable tableName} WHERE {whereById "@id"}"""
        
        /// Query to retrieve documents using a comparison on JSON fields
        [<CompiledName "ByField">]
        let byFields tableName howMatched fields =
            $"{Query.selectFromTable tableName} WHERE {whereByFields howMatched fields}"
        
        /// Query to retrieve 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 ]
    
    /// Document patching (partial update) queries
    module Patch =
        
        /// Create an UPDATE statement to patch documents
        let internal update tableName whereClause =
            $"UPDATE %s{tableName} SET data = json_patch(data, json(@data)) WHERE %s{whereClause}"
        
        /// Query to patch (partially update) a document by its ID
        [<CompiledName "ById">]
        let byId tableName =
            whereById "@id" |> update tableName
        
        /// Query to patch (partially update) a document via a comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields =
            whereByFields howMatched fields |> update tableName
        
        /// Query to patch (partially update) a document via 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 ]
    
    /// Queries to remove fields from documents
    module RemoveFields =
        
        /// Create an UPDATE statement to remove parameters
        let internal update tableName (parameters: SqliteParameter seq) whereClause =
            let paramNames = parameters |> Seq.map _.ParameterName |> String.concat ", "
            $"UPDATE %s{tableName} SET data = json_remove(data, {paramNames}) WHERE %s{whereClause}"
            
        /// Query to remove fields from a document by the document's ID
        [<CompiledName "ById">]
        let byId tableName parameters =
            whereById "@id" |> update tableName parameters
        
        /// Query to remove fields from documents via a comparison on JSON fields within the document
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields parameters =
            whereByFields howMatched fields |> update tableName parameters
        
        /// Query to remove fields from documents via a comparison on a JSON field within the document
        [<CompiledName "ByField">]
        [<System.Obsolete "Use ByFields instead; will be removed in v4">]
        let byField tableName field parameters =
            byFields tableName Any [ field ] parameters

    /// 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 JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields =
            $"DELETE FROM %s{tableName} WHERE {whereByFields howMatched fields}"
        
        /// Query to delete 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 ]
        

/// Parameter handling helpers
[<AutoOpen>]
module Parameters =
    
    /// Create an ID parameter (name "@id", key will be treated as a string)
    [<CompiledName "Id">]
    let idParam (key: 'TKey) =
        SqliteParameter("@id", string key)

    /// Create a parameter with a JSON value
    [<CompiledName "Json">]
    let jsonParam name (it: 'TJson) =
        SqliteParameter(name, Configuration.serializer().Serialize it)

    /// Create JSON field parameters
    [<CompiledName "AddFields">]
    let addFieldParams fields parameters =
        let name = ParameterName()
        fields
        |> Seq.map (fun it ->
            seq {
                match it.Op with
                | EX | NEX -> ()
                | BT ->
                    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) })
        |> Seq.collect id
        |> Seq.append parameters
        |> Seq.toList
        |> Seq.ofList

    /// Create a JSON field parameter (name "@field")
    [<CompiledName "AddField">]
    [<System.Obsolete "Use addFieldParams 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 paramName fieldNames =
        fieldNames
        |> Seq.mapi (fun idx name -> SqliteParameter($"%s{paramName}{idx}", $"$.%s{name}"))
        |> Seq.toList
        |> Seq.ofList

    /// An empty parameter sequence
    [<CompiledName "None">]
    let noParams =
        Seq.empty<SqliteParameter>


/// Helper functions for handling results
[<AutoOpen>]
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)))

    /// Create a domain item from a document
    [<CompiledName "FromData">]
    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
    [<CompiledName "FSharpToCustomList">]
    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
    }
    
    /// Extract a count from the first column
    [<CompiledName "ToCount">]
    let toCount (row: SqliteDataReader) =
        row.GetInt64 0
    
    /// Extract a true/false value from a count in the first column
    [<CompiledName "ToExists">]
    let toExists row =
        toCount(row) > 0L


[<AutoOpen>]
module internal Helpers =
    
    /// Execute a non-query command
    let internal write (cmd: SqliteCommand) = backgroundTask {
        let! _ = cmd.ExecuteNonQueryAsync()
        ()
    }


/// Versions of queries that accept a SqliteConnection as the last parameter
module WithConn =
    
    /// Commands to execute custom SQL queries
    [<RequireQualifiedAccess>]
    module Custom =

        /// Execute a query that returns a list of results
        [<CompiledName "FSharpList">]
        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 a list of results
        let List<'TDoc>(query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>, conn) = backgroundTask {
            let! results = list<'TDoc> query parameters mapFunc.Invoke conn
            return ResizeArray<'TDoc> results
        }
        
        /// Execute a query that returns one or no results (returns None if not found)
        [<CompiledName "FSharpSingle">]
        let single<'TDoc> query parameters (mapFunc: SqliteDataReader -> 'TDoc) conn = backgroundTask {
            let! results = list query parameters mapFunc conn
            return FSharp.Collections.List.tryHead results
        }
        
        /// 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>, conn
            ) = backgroundTask {
            let! result = single<'TDoc> query parameters mapFunc.Invoke conn
            return Option.toObj result
        }
        
        /// Execute a query that does not return a value
        [<CompiledName "NonQuery">]
        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
        [<CompiledName "FSharpScalar">]
        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>
        }

        /// Execute a query that returns a scalar value
        let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func<SqliteDataReader, 'T>, conn) =
            scalar<'T> query parameters mapFunc.Invoke conn

    /// Functions to create tables and indexes
    [<RequireQualifiedAccess>]
    module Definition =
        
        /// Create a document table
        [<CompiledName "EnsureTable">]
        let ensureTable name conn = backgroundTask {
            do! Custom.nonQuery (Query.Definition.ensureTable name) [] conn
            do! Custom.nonQuery (Query.Definition.ensureKey name SQLite) [] conn
        }
        
        /// Create an index on a document table
        [<CompiledName "EnsureFieldIndex">]
        let ensureFieldIndex tableName indexName fields conn =
            Custom.nonQuery (Query.Definition.ensureIndexOn tableName indexName fields SQLite) [] conn

    /// Insert a new document
    [<CompiledName "Insert">]
    let insert<'TDoc> tableName (document: 'TDoc) conn =
        Custom.nonQuery (Query.insert tableName) [ jsonParam "@data" 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) conn =
        Custom.nonQuery (Query.save tableName) [ jsonParam "@data" document ] conn

    /// Commands to count documents
    [<RequireQualifiedAccess>]
    module Count =
        
        /// Count all documents in a table
        [<CompiledName "All">]
        let all tableName conn =
            Custom.scalar (Query.Count.all tableName) [] toCount conn
        
        /// Count matching documents using a comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields conn =
            Custom.scalar (Query.Count.byFields tableName howMatched fields) (addFieldParams fields []) toCount 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 conn =
            byFields tableName Any [ field ] conn

    /// Commands to determine if documents exist
    [<RequireQualifiedAccess>]
    module Exists =
        
        /// Determine if a document exists for the given ID
        [<CompiledName "ById">]
        let byId tableName (docId: 'TKey) conn =
            Custom.scalar (Query.Exists.byId tableName) [ idParam docId ] toExists conn
        
        /// Determine if a document exists using a comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields conn =
            Custom.scalar (Query.Exists.byFields tableName howMatched fields) (addFieldParams fields []) toExists 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 conn =
            byFields tableName Any [ field ] conn
    
    /// Commands to retrieve documents
    [<RequireQualifiedAccess>]
    module Find =
        
        /// Retrieve all documents in the given table
        [<CompiledName "FSharpAll">]
        let all<'TDoc> tableName conn =
            Custom.list<'TDoc> (Query.selectFromTable tableName) [] fromData<'TDoc> conn

        /// Retrieve all documents in the given table
        let All<'TDoc>(tableName, conn) =
            Custom.List(Query.selectFromTable tableName, [], 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.Find.byId tableName) [ 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) =
            Custom.Single<'TDoc>(Query.Find.byId tableName, [ idParam docId ], fromData<'TDoc>, conn)
        
        /// Retrieve documents via a comparison on JSON fields
        [<CompiledName "FSharpByFields">]
        let byFields<'TDoc> tableName howMatched fields conn =
            Custom.list<'TDoc>
                (Query.Find.byFields tableName howMatched fields) (addFieldParams fields []) 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>(
                Query.Find.byFields tableName howMatched fields, addFieldParams fields [], 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, returning only the first result
        [<CompiledName "FSharpFirstByFields">]
        let firstByFields<'TDoc> tableName howMatched fields conn =
            Custom.single
                $"{Query.Find.byFields tableName howMatched fields} LIMIT 1"
                (addFieldParams fields [])
                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) =
            Custom.Single(
                $"{Query.Find.byFields 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)
    
    /// Commands to update documents
    [<RequireQualifiedAccess>]
    module Update =
        
        /// Update an entire document by its ID
        [<CompiledName "ById">]
        let byId tableName (docId: 'TKey) (document: 'TDoc) conn =
            Custom.nonQuery (Query.update tableName) [ idParam docId; jsonParam "@data" document ] conn
        
        /// Update an entire document by its ID, using the provided function to obtain the ID from the document
        [<CompiledName "FSharpByFunc">]
        let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) conn =
            byId tableName (idFunc document) document conn
        
        /// Update an entire document by its ID, using the provided function to obtain the ID from the document
        let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc, conn) =
            byFunc tableName idFunc.Invoke document conn
    
    /// Commands to patch (partially update) documents
    [<RequireQualifiedAccess>]
    module Patch =
        
        /// Patch a document by its ID
        [<CompiledName "ById">]
        let byId tableName (docId: 'TKey) (patch: 'TPatch) conn =
            Custom.nonQuery (Query.Patch.byId tableName) [ idParam docId; jsonParam "@data" patch ] conn
        
        /// Patch documents using a comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields (patch: 'TPatch) conn =
            Custom.nonQuery
                (Query.Patch.byFields tableName howMatched fields)
                (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 =
        
        /// Remove fields from a document by the document's ID
        [<CompiledName "ById">]
        let byId tableName (docId: 'TKey) fieldNames conn =
            let nameParams = fieldNameParams "@name" fieldNames
            Custom.nonQuery
                (Query.RemoveFields.byId tableName nameParams)
                (idParam docId |> Seq.singleton |> Seq.append nameParams)
                conn
        
        /// Remove fields from documents via a comparison on JSON fields in the document
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields fieldNames conn =
            let nameParams = fieldNameParams "@name" fieldNames
            Custom.nonQuery
                (Query.RemoveFields.byFields tableName howMatched fields nameParams)
                (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 =
        
        /// Delete a document by its ID
        [<CompiledName "ById">]
        let byId tableName (docId: 'TKey) conn =
            Custom.nonQuery (Query.Delete.byId tableName) [ idParam docId ] conn
        
        /// Delete documents by matching a comparison on JSON fields
        [<CompiledName "ByFields">]
        let byFields tableName howMatched fields conn =
            Custom.nonQuery (Query.Delete.byFields 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>]
module Custom =

    /// Execute a query that returns a list of results
    [<CompiledName "FSharpList">]
    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 a list of results
    let List<'TDoc>(query, parameters, mapFunc: System.Func<SqliteDataReader, 'TDoc>) =
        use conn = Configuration.dbConn ()
        WithConn.Custom.List<'TDoc>(query, parameters, mapFunc, conn)

    /// Execute a query that returns one or no results (returns None if not found)
    [<CompiledName "FSharpSingle">]
    let single<'TDoc> query parameters (mapFunc: SqliteDataReader -> 'TDoc) =
        use conn = Configuration.dbConn ()
        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>) =
        use conn = Configuration.dbConn ()
        WithConn.Custom.Single<'TDoc>(query, parameters, mapFunc, conn)

    /// Execute a query that does not return a value
    [<CompiledName "NonQuery">]
    let nonQuery query parameters =
        use conn = Configuration.dbConn ()
        WithConn.Custom.nonQuery query parameters conn
    
    /// Execute a query that returns a scalar value
    [<CompiledName "FSharpScalar">]
    let scalar<'T when 'T: struct> query parameters (mapFunc: SqliteDataReader -> 'T) =
        use conn = Configuration.dbConn ()
        WithConn.Custom.scalar<'T> query parameters mapFunc conn

    /// Execute a query that returns a scalar value
    let Scalar<'T when 'T: struct>(query, parameters, mapFunc: System.Func<SqliteDataReader, 'T>) =
        use conn = Configuration.dbConn ()
        WithConn.Custom.Scalar<'T>(query, parameters, mapFunc, conn)

/// Functions to create tables and indexes
[<RequireQualifiedAccess>]
module Definition =

    /// Create a document table
    [<CompiledName "EnsureTable">]
    let ensureTable name =
        use conn = Configuration.dbConn ()
        WithConn.Definition.ensureTable name conn
    
    /// Create an index on a document table
    [<CompiledName "EnsureFieldIndex">]
    let ensureFieldIndex tableName indexName fields =
        use conn = Configuration.dbConn ()
        WithConn.Definition.ensureFieldIndex tableName indexName fields conn

/// Document insert/save functions
[<AutoOpen>]
module Document =
    
    /// Insert a new document
    [<CompiledName "Insert">]
    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")
    [<CompiledName "Save">]
    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
    [<CompiledName "All">]
    let all tableName =
        use conn = Configuration.dbConn ()
        WithConn.Count.all tableName conn
    
    /// Count matching documents using a comparison on JSON fields
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields =
        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>]
module Exists =

    /// Determine if a document exists for the given ID
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) =
        use conn = Configuration.dbConn ()
        WithConn.Exists.byId tableName docId conn
    
    /// Determine if a document exists using a comparison on JSON fields
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields =
        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>]
module Find =
    
    /// Retrieve all documents in the given table
    [<CompiledName "FSharpAll">]
    let all<'TDoc> tableName =
        use conn = Configuration.dbConn ()
        WithConn.Find.all<'TDoc> tableName conn

    /// 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 (returns None if not found)
    [<CompiledName "FSharpById">]
    let byId<'TKey, 'TDoc> tableName docId =
        use conn = Configuration.dbConn ()
        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) =
        use conn = Configuration.dbConn ()
        WithConn.Find.ById<'TKey, 'TDoc>(tableName, docId, conn)

    /// Retrieve documents via a comparison on JSON fields
    [<CompiledName "FSharpByFields">]
    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
    [<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, returning only the first result
    [<CompiledName "FSharpFirstByFields">]
    let firstByFields<'TDoc> 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
    [<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) =
        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 ])

/// Commands to update documents
[<RequireQualifiedAccess>]
module Update =
    
    /// Update an entire document by its ID
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) (document: 'TDoc) =
        use conn = Configuration.dbConn ()
        WithConn.Update.byId tableName docId document conn
    
    /// Update an entire document by its ID, using the provided function to obtain the ID from the document
    [<CompiledName "FSharpByFunc">]
    let byFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) =
        use conn = Configuration.dbConn ()
        WithConn.Update.byFunc tableName idFunc document conn
    
    /// Update an entire document by its ID, using the provided function to obtain the ID from the document
    let ByFunc(tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc) =
        use conn = Configuration.dbConn ()
        WithConn.Update.ByFunc(tableName, idFunc, document, conn)

/// Commands to patch (partially update) documents
[<RequireQualifiedAccess>]
module Patch =
    
    /// Patch a document by its ID
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) (patch: 'TPatch) =
        use conn = Configuration.dbConn ()
        WithConn.Patch.byId tableName docId patch conn
    
    /// Patch documents using a comparison on JSON fields in the WHERE clause
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields (patch: 'TPatch) =
        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>]
module RemoveFields =
    
    /// Remove fields from a document by the document's ID
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) fieldNames =
        use conn = Configuration.dbConn ()
        WithConn.RemoveFields.byId tableName docId fieldNames conn
    
    /// Remove field from documents via a comparison on JSON fields in the document
    [<CompiledName "ByFields">]
    let byFields tableName howMatched fields fieldNames =
        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>]
module Delete =
    
    /// Delete a document by its ID
    [<CompiledName "ById">]
    let byId tableName (docId: 'TKey) =
        use conn = Configuration.dbConn ()
        WithConn.Delete.byId tableName docId conn
    
    /// Delete documents by matching a comparison on JSON fields
    [<CompiledName "ByFields">]
    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 ]