diff --git a/src/Sqlite/Extensions.fs b/src/Sqlite/Extensions.fs index 9f143dc..901bc0a 100644 --- a/src/Sqlite/Extensions.fs +++ b/src/Sqlite/Extensions.fs @@ -2,263 +2,487 @@ namespace BitBadger.Documents.Sqlite open Microsoft.Data.Sqlite -/// F# extensions for the SqliteConnection type +/// F# extensions for the SqliteConnection type [] module Extensions = type SqliteConnection with - - /// Execute a query that returns a list of results + + /// Execute a query that returns a list of results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// A list of results for the given query member conn.customList<'TDoc> query parameters mapFunc = WithConn.Custom.list<'TDoc> query parameters mapFunc conn - /// Execute a query that returns one or no results + /// Execute a query that returns one or no results + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// Some with the first matching result, or None if not found member conn.customSingle<'TDoc> query parameters mapFunc = WithConn.Custom.single<'TDoc> query parameters mapFunc conn - - /// Execute a query that does not return a value + + /// Execute a query that returns no results + /// The query to retrieve the results + /// Parameters to use for the query member conn.customNonQuery query parameters = WithConn.Custom.nonQuery query parameters conn - /// Execute a query that returns a scalar value + /// Execute a query that returns a scalar value + /// The query to retrieve the value + /// Parameters to use for the query + /// The mapping function to obtain the value + /// The scalar value for the query member conn.customScalar<'T when 'T: struct> query parameters mapFunc = WithConn.Custom.scalar<'T> query parameters mapFunc conn - /// Create a document table + /// Create a document table + /// The table whose existence should be ensured (may include schema) member conn.ensureTable name = WithConn.Definition.ensureTable name conn - - /// Create an index on a document table + + /// Create an index on field(s) within documents in the specified table + /// The table to be indexed (may include schema) + /// The name of the index to create + /// One or more fields to be indexed member conn.ensureFieldIndex tableName indexName fields = WithConn.Definition.ensureFieldIndex tableName indexName fields conn - - /// Insert a new document + + /// Insert a new document + /// The table into which the document should be inserted (may include schema) + /// The document to be inserted member conn.insert<'TDoc> tableName (document: 'TDoc) = 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") + /// + /// The table into which the document should be saved (may include schema) + /// The document to be saved member conn.save<'TDoc> tableName (document: 'TDoc) = WithConn.Document.save tableName document conn - /// Count all documents in a table + /// Count all documents in a table + /// The table in which documents should be counted (may include schema) + /// The count of the documents in the table member conn.countAll tableName = WithConn.Count.all tableName conn - - /// Count matching documents using a comparison on JSON fields + + /// Count matching documents using JSON field comparisons (->> =, etc.) + /// The table in which documents should be counted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The count of matching documents in the table member conn.countByFields tableName howMatched fields = WithConn.Count.byFields tableName howMatched fields conn - - /// Determine if a document exists for the given ID + + /// Determine if a document exists for the given ID + /// The table in which existence should be checked (may include schema) + /// The ID of the document whose existence should be checked + /// True if a document exists, false if not member conn.existsById tableName (docId: 'TKey) = WithConn.Exists.byId tableName docId conn - /// Determine if a document exists using a comparison on JSON fields + /// Determine if a document exists using JSON field comparisons (->> =, etc.) + /// The table in which existence should be checked (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// True if any matching documents exist, false if not member conn.existsByFields tableName howMatched fields = WithConn.Exists.byFields tableName howMatched fields conn - - /// Retrieve all documents in the given table + + /// Retrieve all documents in the given table + /// The table from which documents should be retrieved (may include schema) + /// All documents from 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 + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// All documents from the given table, ordered by the given fields member conn.findAllOrdered<'TDoc> tableName orderFields = WithConn.Find.allOrdered<'TDoc> tableName orderFields conn - /// Retrieve a document by its ID + /// Retrieve a document by its ID + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// Some with the document if found, None otherwise member conn.findById<'TKey, 'TDoc> tableName (docId: 'TKey) = WithConn.Find.byId<'TKey, 'TDoc> tableName docId conn - - /// Retrieve documents via a comparison on JSON fields + + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// All documents matching the given fields member conn.findByFields<'TDoc> tableName howMatched fields = WithConn.Find.byFields<'TDoc> tableName howMatched fields conn - - /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document + + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields + /// in the document + /// + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// All documents matching the given fields, ordered by the other given fields 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 + + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Some with the first document, or None if not found member conn.findFirstByFields<'TDoc> tableName howMatched fields = WithConn.Find.firstByFields<'TDoc> tableName howMatched fields conn - - /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document, returning - /// only the first result + + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the + /// given fields in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// + /// Some with the first document ordered by the given fields, or None if not found + /// member conn.findFirstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields = WithConn.Find.firstByFieldsOrdered<'TDoc> tableName howMatched queryFields orderFields conn - - /// Update an entire document by its ID + + /// Update (replace) an entire document by its ID + /// The table in which a document should be updated (may include schema) + /// The ID of the document to be updated (replaced) + /// The new document member conn.updateById tableName (docId: 'TKey) (document: 'TDoc) = 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 + + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the + /// document + /// + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new document member conn.updateByFunc tableName (idFunc: 'TDoc -> 'TKey) (document: 'TDoc) = WithConn.Update.byFunc tableName idFunc document conn - - /// Patch a document by its ID + + /// Patch a document by its ID + /// The table in which a document should be patched (may include schema) + /// The ID of the document to patch + /// The partial document to patch the existing document member conn.patchById tableName (docId: 'TKey) (patch: 'TPatch) = WithConn.Patch.byId tableName docId patch conn - - /// Patch documents using a comparison on JSON fields + + /// + /// Patch documents using a JSON field comparison query in the WHERE clause (->> =, + /// etc.) + /// + /// The table in which documents should be patched (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The partial document to patch the existing document member conn.patchByFields tableName howMatched fields (patch: 'TPatch) = WithConn.Patch.byFields tableName howMatched fields patch conn - - /// Remove fields from a document by the document's ID + + /// Remove fields from a document by the document's ID + /// The table in which a document should be modified (may include schema) + /// The ID of the document to modify + /// One or more field names to remove from the document member conn.removeFieldsById tableName (docId: 'TKey) fieldNames = WithConn.RemoveFields.byId tableName docId fieldNames conn - - /// Remove a field from a document via a comparison on JSON fields in the document + + /// Remove fields from documents via a comparison on JSON fields in the document + /// The table in which documents should be modified (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// One or more field names to remove from the matching documents member conn.removeFieldsByFields tableName howMatched fields fieldNames = WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn - - /// Delete a document by its ID + + /// Delete a document by its ID + /// The table in which a document should be deleted (may include schema) + /// The ID of the document to delete member conn.deleteById tableName (docId: 'TKey) = WithConn.Delete.byId tableName docId conn - /// Delete documents by matching a comparison on JSON fields + /// Delete documents by matching a JSON field comparison query (->> =, etc.) + /// The table in which documents should be deleted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match member conn.deleteByFields tableName howMatched fields = WithConn.Delete.byFields tableName howMatched fields conn open System.Runtime.CompilerServices -/// C# extensions on the SqliteConnection type +/// C# extensions on the SqliteConnection type type SqliteConnectionCSharpExtensions = - - /// Execute a query that returns a list of results + + /// Execute a query that returns a list of results + /// The SqliteConnection on which to run the query + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// A list of results for the given query [] static member inline CustomList<'TDoc>(conn, query, parameters, mapFunc: System.Func) = WithConn.Custom.List<'TDoc>(query, parameters, mapFunc, conn) - /// Execute a query that returns one or no results + /// Execute a query that returns one or no results + /// The SqliteConnection on which to run the query + /// The query to retrieve the results + /// Parameters to use for the query + /// The mapping function between the document and the domain item + /// The first matching result, or null if not found [] static member inline CustomSingle<'TDoc when 'TDoc: null and 'TDoc: not struct>( conn, query, parameters, mapFunc: System.Func) = WithConn.Custom.Single<'TDoc>(query, parameters, mapFunc, conn) - - /// Execute a query that does not return a value + + /// Execute a query that returns no results + /// The SqliteConnection on which to run the query + /// The query to retrieve the results + /// Parameters to use for the query [] static member inline CustomNonQuery(conn, query, parameters) = WithConn.Custom.nonQuery query parameters conn - /// Execute a query that returns a scalar value + /// Execute a query that returns a scalar value + /// The SqliteConnection on which to run the query + /// The query to retrieve the value + /// Parameters to use for the query + /// The mapping function to obtain the value + /// The scalar value for the query [] static member inline CustomScalar<'T when 'T: struct>( conn, query, parameters, mapFunc: System.Func) = WithConn.Custom.Scalar<'T>(query, parameters, mapFunc, conn) - /// Create a document table + /// Create a document table + /// The SqliteConnection on which to run the query + /// The table whose existence should be ensured (may include schema) [] static member inline EnsureTable(conn, name) = WithConn.Definition.ensureTable name conn - /// Create an index on one or more fields in a document table + /// Create an index on field(s) within documents in the specified table + /// The SqliteConnection on which to run the query + /// The table to be indexed (may include schema) + /// The name of the index to create + /// One or more fields to be indexed [] static member inline EnsureFieldIndex(conn, tableName, indexName, fields) = WithConn.Definition.ensureFieldIndex tableName indexName fields conn - /// Insert a new document + /// Insert a new document + /// The SqliteConnection on which to run the query + /// The table into which the document should be inserted (may include schema) + /// The document to be inserted [] static member inline Insert<'TDoc>(conn, tableName, document: 'TDoc) = 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") + /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert") + /// The SqliteConnection on which to run the query + /// The table into which the document should be saved (may include schema) + /// The document to be saved [] static member inline Save<'TDoc>(conn, tableName, document: 'TDoc) = WithConn.Document.save<'TDoc> tableName document conn - /// Count all documents in a table + /// Count all documents in a table + /// The SqliteConnection on which to run the query + /// The table in which documents should be counted (may include schema) + /// The count of the documents in the table [] static member inline CountAll(conn, tableName) = WithConn.Count.all tableName conn - - /// Count matching documents using a comparison on JSON fields + + /// Count matching documents using JSON field comparisons (->> =, etc.) + /// The SqliteConnection on which to run the query + /// The table in which documents should be counted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The count of matching documents in the table [] static member inline CountByFields(conn, tableName, howMatched, fields) = WithConn.Count.byFields tableName howMatched fields conn - - /// Determine if a document exists for the given ID + + /// Determine if a document exists for the given ID + /// The SqliteConnection on which to run the query + /// The table in which existence should be checked (may include schema) + /// The ID of the document whose existence should be checked + /// True if a document exists, false if not [] static member inline ExistsById<'TKey>(conn, tableName, docId: 'TKey) = WithConn.Exists.byId tableName docId conn - /// Determine if a document exists using a comparison on JSON fields + /// Determine if a document exists using JSON field comparisons (->> =, etc.) + /// The SqliteConnection on which to run the query + /// The table in which existence should be checked (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// True if any matching documents exist, false if not [] static member inline ExistsByFields(conn, tableName, howMatched, fields) = WithConn.Exists.byFields tableName howMatched fields conn - - /// Retrieve all documents in the given table + + /// Retrieve all documents in the given table + /// The SqliteConnection on which to run the query + /// The table from which documents should be retrieved (may include schema) + /// All documents from the given table [] 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 + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The SqliteConnection on which to run the query + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// All documents from the given table, ordered by the given fields [] static member inline FindAllOrdered<'TDoc>(conn, tableName, orderFields) = WithConn.Find.AllOrdered<'TDoc>(tableName, orderFields, conn) - /// Retrieve a document by its ID + /// Retrieve a document by its ID + /// The SqliteConnection on which to run the query + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// The document if found, null otherwise [] 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 + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The SqliteConnection on which to run the query + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// All documents matching the given fields [] static member inline FindByFields<'TDoc>(conn, tableName, howMatched, fields) = WithConn.Find.ByFields<'TDoc>(tableName, howMatched, fields, conn) - - /// Retrieve documents via a comparison on JSON fields ordered by the given fields in the document + + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields in + /// the document + /// + /// The SqliteConnection on which to run the query + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// All documents matching the given fields, ordered by the other given fields [] 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 + + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The SqliteConnection on which to run the query + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The first document, or null if not found [] 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 JSON fields ordered by the given fields in the document, returning only - /// the first result + + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the given + /// fields in the document + /// + /// The SqliteConnection on which to run the query + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The first document ordered by the given fields, or null if not found [] 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 + + /// Update (replace) an entire document by its ID + /// The SqliteConnection on which to run the query + /// The table in which a document should be updated (may include schema) + /// The ID of the document to be updated (replaced) + /// The new document [] static member inline UpdateById<'TKey, 'TDoc>(conn, tableName, docId: 'TKey, document: 'TDoc) = 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 + + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the document + /// + /// The SqliteConnection on which to run the query + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new document [] - static member inline UpdateByFunc<'TKey, 'TDoc>(conn, tableName, idFunc: System.Func<'TDoc, 'TKey>, doc: 'TDoc) = - WithConn.Update.ByFunc(tableName, idFunc, doc, conn) - - /// Patch a document by its ID + static member inline UpdateByFunc<'TKey, 'TDoc>( + conn, tableName, idFunc: System.Func<'TDoc, 'TKey>, document: 'TDoc) = + WithConn.Update.ByFunc(tableName, idFunc, document, conn) + + /// Patch a document by its ID + /// The SqliteConnection on which to run the query + /// The table in which a document should be patched (may include schema) + /// The ID of the document to patch + /// The partial document to patch the existing document [] static member inline PatchById<'TKey, 'TPatch>(conn, tableName, docId: 'TKey, patch: 'TPatch) = WithConn.Patch.byId tableName docId patch conn - - /// Patch documents using a comparison on JSON fields + + /// + /// Patch documents using a JSON field comparison query in the WHERE clause (->> =, etc.) + /// + /// The SqliteConnection on which to run the query + /// The table in which documents should be patched (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The partial document to patch the existing document [] static member inline PatchByFields<'TPatch>(conn, tableName, howMatched, fields, patch: 'TPatch) = WithConn.Patch.byFields tableName howMatched fields patch conn - - /// Remove fields from a document by the document's ID + + /// Remove fields from a document by the document's ID + /// The SqliteConnection on which to run the query + /// The table in which a document should be modified (may include schema) + /// The ID of the document to modify + /// One or more field names to remove from the document [] static member inline RemoveFieldsById<'TKey>(conn, tableName, docId: 'TKey, fieldNames) = WithConn.RemoveFields.byId tableName docId fieldNames conn - - /// Remove fields from documents via a comparison on JSON fields in the document + + /// Remove fields from documents via a comparison on JSON fields in the document + /// The SqliteConnection on which to run the query + /// The table in which documents should be modified (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// One or more field names to remove from the matching documents [] static member inline RemoveFieldsByFields(conn, tableName, howMatched, fields, fieldNames) = WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn - - /// Delete a document by its ID + + /// Delete a document by its ID + /// The SqliteConnection on which to run the query + /// The table in which a document should be deleted (may include schema) + /// The ID of the document to delete [] static member inline DeleteById<'TKey>(conn, tableName, docId: 'TKey) = WithConn.Delete.byId tableName docId conn - - /// Delete documents by matching a comparison on JSON fields + + /// Delete documents by matching a JSON field comparison query (->> =, etc.) + /// The SqliteConnection on which to run the query + /// The table in which documents should be deleted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match [] static member inline DeleteByFields(conn, tableName, howMatched, fields) = WithConn.Delete.byFields tableName howMatched fields conn diff --git a/src/Sqlite/Library.fs b/src/Sqlite/Library.fs index 6180534..215a62b 100644 --- a/src/Sqlite/Library.fs +++ b/src/Sqlite/Library.fs @@ -838,226 +838,345 @@ module Custom = WithConn.Custom.Scalar<'T>(query, parameters, mapFunc, conn) -/// Functions to create tables and indexes +/// Functions to create tables and indexes [] module Definition = - /// Create a document table + /// Create a document table + /// The table whose existence should be ensured (may include schema) [] let ensureTable name = use conn = Configuration.dbConn () WithConn.Definition.ensureTable name conn - /// Create an index on a document table + /// Create an index on field(s) within documents in the specified table + /// The table to be indexed (may include schema) + /// The name of the index to create + /// One or more fields to be indexed [] let ensureFieldIndex tableName indexName fields = use conn = Configuration.dbConn () WithConn.Definition.ensureFieldIndex tableName indexName fields conn -/// Document insert/save functions +/// Document insert/save functions [] module Document = - /// Insert a new document + /// Insert a new document + /// The table into which the document should be inserted (may include schema) + /// The document to be inserted [] let insert<'TDoc> tableName (document: 'TDoc) = use conn = Configuration.dbConn () WithConn.Document.insert tableName document conn - /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert") + /// Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert") + /// The table into which the document should be saved (may include schema) + /// The document to be saved [] let save<'TDoc> tableName (document: 'TDoc) = use conn = Configuration.dbConn () WithConn.Document.save tableName document conn -/// Commands to count documents +/// Commands to count documents [] module Count = - /// Count all documents in a table + /// Count all documents in a table + /// The table in which documents should be counted (may include schema) + /// The count of the documents in the table [] let all tableName = use conn = Configuration.dbConn () WithConn.Count.all tableName conn - /// Count matching documents using a comparison on JSON fields + /// Count matching documents using JSON field comparisons (->> =, etc.) + /// The table in which documents should be counted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The count of matching documents in the table [] let byFields tableName howMatched fields = use conn = Configuration.dbConn () WithConn.Count.byFields tableName howMatched fields conn -/// Commands to determine if documents exist +/// Commands to determine if documents exist [] module Exists = - /// Determine if a document exists for the given ID + /// Determine if a document exists for the given ID + /// The table in which existence should be checked (may include schema) + /// The ID of the document whose existence should be checked + /// True if a document exists, false if not [] 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 + /// Determine if a document exists using JSON field comparisons (->> =, etc.) + /// The table in which existence should be checked (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// True if any matching documents exist, false if not [] let byFields tableName howMatched fields = use conn = Configuration.dbConn () WithConn.Exists.byFields tableName howMatched fields conn -/// Commands to determine if documents exist +/// Commands to retrieve documents [] module Find = - /// Retrieve all documents in the given table + /// Retrieve all documents in the given table + /// The table from which documents should be retrieved (may include schema) + /// All documents from the given table [] let all<'TDoc> tableName = use conn = Configuration.dbConn () WithConn.Find.all<'TDoc> tableName conn - /// Retrieve all documents in the given table + /// Retrieve all documents in the given table + /// The table from which documents should be retrieved (may include schema) + /// All documents from the given table let All<'TDoc> tableName = 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 + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// All documents from the given table, ordered by the given fields [] 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 + /// Retrieve all documents in the given table ordered by the given fields in the document + /// The table from which documents should be retrieved (may include schema) + /// Fields by which the results should be ordered + /// All documents from the given table, ordered by the given fields 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) + /// Retrieve a document by its ID + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// Some with the document if found, None otherwise [] 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) + /// Retrieve a document by its ID + /// The table from which a document should be retrieved (may include schema) + /// The ID of the document to retrieve + /// The document if found, null otherwise 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) - /// Retrieve documents via a comparison on JSON fields + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// All documents matching the given 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 JSON fields + /// Retrieve documents matching JSON field comparisons (->> =, etc.) + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// All documents matching the given 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 JSON fields ordered by the given fields in the document + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields in + /// the document + /// + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// All documents matching the given fields, ordered by the other given fields [] 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 + /// + /// Retrieve documents matching JSON field comparisons (->> =, etc.) ordered by the given fields in + /// the document + /// + /// The table from which documents should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// All documents matching the given fields, ordered by the other given fields 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 + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Some with the first document, or None if not found [] let firstByFields<'TDoc> tableName howMatched fields = use conn = Configuration.dbConn () WithConn.Find.firstByFields<'TDoc> tableName howMatched fields conn - /// Retrieve documents via a comparison on JSON fields, returning only the first result + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The first document, or null if not found 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 JSON fields ordered by the given fields in the document, returning only - /// the first result + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the given + /// fields in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// + /// Some with the first document ordered by the given fields, or None if not found + /// [] 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 + /// + /// Retrieve the first document matching JSON field comparisons (->> =, etc.) ordered by the given + /// fields in the document + /// + /// The table from which a document should be retrieved (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// Fields by which the results should be ordered + /// The first document ordered by the given fields, or null if not found 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 +/// Commands to update documents [] module Update = - /// Update an entire document by its ID + /// Update (replace) an entire document by its ID + /// The table in which a document should be updated (may include schema) + /// The ID of the document to be updated (replaced) + /// The new document [] 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 + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the document + /// + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new document [] 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 + /// + /// Update (replace) an entire document by its ID, using the provided function to obtain the ID from the document + /// + /// The table in which a document should be updated (may include schema) + /// The function to obtain the ID of the document + /// The new 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 +/// Commands to patch (partially update) documents [] module Patch = - /// Patch a document by its ID + /// Patch a document by its ID + /// The table in which a document should be patched (may include schema) + /// The ID of the document to patch + /// The partial document to patch the existing document [] 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 + /// + /// Patch documents using a JSON field comparison query in the WHERE clause (->> =, etc.) + /// + /// The table in which documents should be patched (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// The partial document to patch the existing document [] let byFields tableName howMatched fields (patch: 'TPatch) = use conn = Configuration.dbConn () WithConn.Patch.byFields tableName howMatched fields patch conn -/// Commands to remove fields from documents +/// Commands to remove fields from documents [] module RemoveFields = - /// Remove fields from a document by the document's ID + /// Remove fields from a document by the document's ID + /// The table in which a document should be modified (may include schema) + /// The ID of the document to modify + /// One or more field names to remove from the document [] 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 + /// Remove fields from documents via a comparison on JSON fields in the document + /// The table in which documents should be modified (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match + /// One or more field names to remove from the matching documents [] let byFields tableName howMatched fields fieldNames = use conn = Configuration.dbConn () WithConn.RemoveFields.byFields tableName howMatched fields fieldNames conn -/// Commands to delete documents +/// Commands to delete documents [] module Delete = - /// Delete a document by its ID + /// Delete a document by its ID + /// The table in which a document should be deleted (may include schema) + /// The ID of the document to delete [] let byId tableName (docId: 'TKey) = use conn = Configuration.dbConn () WithConn.Delete.byId tableName docId conn - /// Delete documents by matching a comparison on JSON fields + /// Delete documents by matching a JSON field comparison query (->> =, etc.) + /// The table in which documents should be deleted (may include schema) + /// Whether to match any or all of the field conditions + /// The field conditions to match [] let byFields tableName howMatched fields = use conn = Configuration.dbConn ()