SWIFT-137 Sketch remainder of CRUD API

Sources/MongoSwift/BSON/BsonValue.swift

@@ -200,7 +200,7 @@ public struct Binary: BsonValue, Equatable, Codable {
     /// Throws an error if the base64 `String` is invalid.
     public init(base64: String, subtype: UInt8) throws {
         guard let dataObj = Data(base64Encoded: base64) else {
-            throw MongoError.invalidValue(message: "failed to create Data object from invalid base64 string \(base64)")
+            throw MongoError.invalidArgument(message: "failed to create Data object from invalid base64 string \(base64)")
         }
         self.init(data: dataObj, subtype: subtype)
     }

Sources/MongoSwift/MongoCollection+BulkWrite.swift

@@ -0,0 +1,134 @@
+import libmongoc
+
+/// An extension of `MongoCollection` encapsulating bulk write operations.
+extension MongoCollection {
+    /**
+     * Execute multiple write operations.
+     *
+     * - Parameters:
+     *   - requests: a `[WriteModel]` containing the writes to perform
+     *   - options: optional `BulkWriteOptions` to use while executing the operation
+     *
+     * - Returns: a `BulkWriteResult`, or `nil` if the write concern is unacknowledged.
+     *
+     * - Throws:
+     *   - `MongoError.invalidArgument` if `requests` is empty
+     *   - `MongoError.bulkWriteError` if any error occurs while performing the writes
+     */
+    @discardableResult
+    public func bulkWrite(_ requests: [WriteModel], options: BulkWriteOptions? = nil) throws -> BulkWriteResult? {
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+}
+
+/// Options to use when performing a bulk write operation on a `MongoCollection`.
+public struct BulkWriteOptions: Encodable {
+    /// If `true` (the default), when an insert fails, return without performing the remaining writes.
+    /// If `false`, when a write fails, continue with the remaining writes, if any.
+    public var ordered: Bool = true
+
+    /// If `true`, allows the write to opt-out of document level validation.
+    public let bypassDocumentValidation: Bool?
+}
+
+/// A protocol indicating write types that can be batched together using `MongoCollection.bulkWrite`.
+public protocol WriteModel: Encodable {}
+
+/// A model for an `insertOne` command.
+public struct InsertOneModel: WriteModel {
+    /// The `Document` to insert.
+    public let document: Document
+}
+
+/// A model for a `deleteOne` command.
+public struct DeleteOneModel: WriteModel {
+    /// A `Document` representing the match criteria.
+    public let filter: Document
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+}
+
+/// A model for a `deleteMany` command.
+public struct DeleteManyModel: WriteModel {
+    /// A `Document` representing the match criteria.
+    public let filter: Document
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+}
+
+/// A model for a `replaceOne` command.
+public struct ReplaceOneModel: WriteModel {
+    /// A `Document` representing the match criteria.
+    public let filter: Document
+
+    /// The `Document` with which to replace the matched document.
+    public let replacement: Document
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// When `true`, creates a new document if no document matches the query.
+    public let upsert: Bool?
+}
+
+/// A model for an `updateOne` command.
+public struct UpdateOneModel: WriteModel {
+    /// A `Document` representing the match criteria.
+    public let filter: Document
+
+    /// A `Document` containing update operators.
+    public let update: Document
+
+    /// A set of filters specifying to which array elements an update should apply.
+    public let arrayFilters: [Document]?
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// When `true`, creates a new document if no document matches the query.
+    public let upsert: Bool?
+}
+
+/// A model for an `updateMany` command.
+public struct UpdateManyModel: WriteModel {
+    /// A `Document` representing the match criteria.
+    public let filter: Document
+
+    /// A `Document` containing update operators.
+    public let update: Document
+
+    /// A set of filters specifying to which array elements an update should apply.
+    public let arrayFilters: [Document]?
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// When `true`, creates a new document if no document matches the query.
+    public let upsert: Bool?
+}
+
+/// The result of a bulk write operation on a `MongoCollection`.
+public struct BulkWriteResult: Decodable {
+    /// Number of documents inserted.
+    public let insertedCount: Int
+
+    /// Map of the index of the operation to the id of the inserted document.
+    public let insertedIds: [Int: AnyBsonValue]
+
+    /// Number of documents matched for update.
+    public let matchedCount: Int
+
+    /// Number of documents modified.
+    public let modifiedCount: Int
+
+    /// Number of documents deleted.
+    public let deletedCount: Int
+
+    /// Number of documents upserted.
+    public let upsertedCount: Int
+
+    /// Map of the index of the operation to the id of the upserted document.
+    public let upsertedIds: [Int: AnyBsonValue]
+}

Sources/MongoSwift/MongoCollection+FindAndModify.swift

@@ -0,0 +1,150 @@
+import libmongoc
+
+/// An extension of `MongoCollection` encapsulating find and modify operations.
+extension MongoCollection {
+    /**
+     * Finds a single document and deletes it, returning the original.
+     *
+     * - Parameters:
+     *   - filter: `Document` representing the match criteria
+     *   - options: Optional `FindOneAndDeleteOptions` to use when executing the command
+     *
+     * - Returns: The deleted document, represented as a `CollectionType`, or `nil` if no document was deleted.
+     * - Throws: 
+     *   - `MongoError.commandError` if there are any errors executing the command.
+     *   - A `DecodingError` if the deleted document cannot be decoded to a `CollectionType` value
+     */
+    @discardableResult
+    public func findOneAndDelete(_ filter: Document, options: FindOneAndDeleteOptions? = nil) throws -> CollectionType? {
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+
+    /**
+     * Finds a single document and replaces it, returning either the original or the replaced document.
+     * 
+     * - Parameters:
+     *   - filter: `Document` representing the match criteria
+     *   - replacement: a `CollectionType` to replace the found document
+     *   - options: Optional `FindOneAndReplaceOptions` to use when executing the command
+     *
+     * - Returns: A `CollectionType`, representing either the original document or its replacement,
+     *      depending on selected options, or `nil` if there was no match.
+     * - Throws: 
+     *   - `MongoError.commandError` if there are any errors executing the command.
+     *   - An `EncodingError` if `replacement` cannot be encoded to a `Document`
+     *   - A `DecodingError` if the replaced document cannot be decoded to a `CollectionType` value
+     */
+    @discardableResult
+    public func findOneAndReplace(filter: Document, replacement: CollectionType,
+                                  options: FindOneAndDeleteOptions? = nil) throws -> CollectionType? {
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+
+    /**
+     * Finds a single document and updates it, returning either the original or the updated document.
+     * 
+     * - Parameters:
+     *   - filter: `Document` representing the match criteria
+     *   - update: a `Document` containing updates to apply
+     *   - options: Optional `FindOneAndUpdateOptions` to use when executing the command
+     *
+     * - Returns: A `CollectionType` representing either the original or updated document,
+     *      depending on selected options, or `nil` if there was no match.
+     * - Throws: 
+     *   - `MongoError.commandError` if there are any errors executing the command.
+     *   - A `DecodingError` if the updated document cannot be decoded to a `CollectionType` value
+     */
+    @discardableResult
+    public func findOneAndUpdate(filter: Document, update: Document,
+                                 options: FindOneAndUpdateOptions? = nil) throws -> CollectionType? {
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+}
+
+/// Indicates which document to return in a find and modify operation.
+public enum ReturnDocument: Encodable {
+    /// Indicates to return the document before the update, replacement, or insert occured.
+    case before
+
+    ///  Indicates to return the document after the update, replacement, or insert occured.
+    case after
+
+    public func encode(to encoder: Encoder) throws {
+        // fill in later on
+    }
+}
+
+/// Options to use when executing a `findOneAndDelete` command on a `MongoCollection`. 
+public struct FindOneAndDeleteOptions: Encodable {
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// The maximum amount of time to allow the query to run.
+    public let maxTimeMS: Int64?
+
+    /// Limits the fields to return for the matching document.
+    public let projection: Document?
+
+    /// Determines which document the operation modifies if the query selects multiple documents.
+    public let sort: Document?
+
+    /// An optional `WriteConcern` to use for the command.
+    public let writeConcern: WriteConcern?
+}
+
+/// Options to use when executing a `findOneAndReplace` command on a `MongoCollection`. 
+public struct FindOneAndReplaceOptions: Encodable {
+    /// If `true`, allows the write to opt-out of document level validation.
+    public let bypassDocumentValidation: Bool?
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// The maximum amount of time to allow the query to run.
+    public let maxTimeMS: Int64?
+
+    /// Limits the fields to return for the matching document.
+    public let projection: Document?
+
+    /// When `ReturnDocument.After`, returns the replaced or inserted document rather than the original.
+    public let returnDocument: ReturnDocument?
+
+    /// Determines which document the operation modifies if the query selects multiple documents.
+    public let sort: Document?
+
+    /// When `true`, creates a new document if no document matches the query.
+    public let upsert: Bool?
+
+    /// An optional `WriteConcern` to use for the command.
+    public let writeConcern: WriteConcern?
+}
+
+/// Options to use when executing a `findOneAndUpdate` command on a `MongoCollection`. 
+public struct FindOneAndUpdateOptions: Encodable {
+    /// A set of filters specifying to which array elements an update should apply.
+    public let arrayFilters: [Document]?
+
+    /// If `true`, allows the write to opt-out of document level validation.
+    public let bypassDocumentValidation: Bool?
+
+    /// Specifies a collation to use.
+    public let collation: Document?
+
+    /// The maximum amount of time to allow the query to run.
+    public let maxTimeMS: Int64?
+
+    /// Limits the fields to return for the matching document.
+    public let projection: Document?
+
+    /// When`ReturnDocument.After`, returns the updated or inserted document rather than the original.
+    public let returnDocument: ReturnDocument?
+
+    /// Determines which document the operation modifies if the query selects multiple documents.
+    public let sort: Document?
+
+    /// When `true`, creates a new document if no document matches the query.
+    public let upsert: Bool?
+
+    /// An optional `WriteConcern` to use for the command.
+    public let writeConcern: WriteConcern?
+}

Sources/MongoSwift/MongoCollection+Read.swift

@@ -46,6 +46,7 @@ extension MongoCollection {
         return MongoCursor(fromCursor: cursor, withClient: client)
     }
 
+    // TODO SWIFT-133: mark this method deprecated https://jira.mongodb.org/browse/SWIFT-133
     /**
      * Counts the number of documents in this collection matching the provided filter.
      *
@@ -69,6 +70,33 @@ extension MongoCollection {
         return Int(count)
     }
 
+    /**
+     * Counts the number of documents in this collection matching the provided filter.
+     *
+     * - Parameters:
+     *   - filter: a `Document`, the filter that documents must match in order to be counted
+     *   - options: Optional `CountDocumentsOptions` to use when executing the command
+     *
+     * - Returns: The count of the documents that matched the filter
+     */
+    public func countDocuments(_ filter: Document = [:], options: CountDocumentsOptions? = nil) throws -> Int {
+        // TODO SWIFT-133: implement this https://jira.mongodb.org/browse/SWIFT-133
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+
+    /**
+     * Gets an estimate of the count of documents in this collection using collection metadata.
+     *
+     * - Parameters:
+     *   - options: Optional `EstimatedDocumentCountOptions` to use when executing the command
+     *
+     * - Returns: an estimate of the count of documents in this collection
+     */
+    public func estimatedDocumentCount(options: EstimatedDocumentCountOptions? = nil) throws -> Int {
+        // TODO SWIFT-133: implement this https://jira.mongodb.org/browse/SWIFT-133
+        throw MongoError.commandError(message: "Unimplemented command")
+    }
+
     /**
      * Finds the distinct values for a specified field across the collection.
      *
@@ -237,6 +265,15 @@ public struct CountOptions: Encodable {
     }
 }
 
+/// The `countDocuments` command takes the same options as the deprecated `count`. 
+public typealias CountDocumentsOptions = CountOptions
+
+/// Options to use when executing an `estimatedDocumentCount` command on a `MongoCollection`.
+public struct EstimatedDocumentCountOptions {
+    /// The maximum amount of time to allow the query to run.
+    public let maxTimeMS: Int64?
+}
+
 /// Options to use when executing a `distinct` command on a `MongoCollection`.
 public struct DistinctOptions: Encodable {
     /// Specifies a collation.

Sources/MongoSwift/MongoError.swift

@@ -5,8 +5,6 @@ import libmongoc
 public enum MongoError {
     /// Thrown when an invalid connection string is provided when initializing a `MongoClient`.
     case invalidUri(message: String)
-    /// Thrown when a user-provided value is invalid.
-    case invalidValue(message: String)
     /// Thrown when a `MongoClient` is invalid.
     case invalidClient()
     /// Thrown when the server sends an invalid response.
@@ -28,7 +26,13 @@ public enum MongoError {
     /// Thrown when there is an error involving a `ReadPreference`.
     case readPreferenceError(message: String)
     /// Thrown when there is an error involving a `WriteConcern`. 
-    case writeConcernError(message: String)
+    case writeConcernError(code: Int32, message: String)
+    /// Thrown when a user-provided argument is invalid.
+    case invalidArgument(message: String)
+    /// Thrown when there is an error executing a write command.
+    case writeError(code: Int32, message: String)
+    /// Thrown when there is an error executing a bulk write command. 
+    indirect case bulkWriteError(code: Int32, message: String, result: BulkWriteResult?, writeErrors: [MongoError]?, writeConcernError: MongoError?)
 }
 
 /// An extension of `MongoError` to support printing out descriptive error messages.
@@ -39,9 +43,11 @@ extension MongoError: LocalizedError {
             let .invalidCollection(message), let .commandError(message),
             let .bsonParseError(_, _, message), let .bsonEncodeError(message),
             let .typeError(message), let .readConcernError(message),
-            let .readPreferenceError(message), let .writeConcernError(message),
-            let .invalidValue(message):
+            let .readPreferenceError(message), let .invalidArgument(message):
             return message
+        case let .writeConcernError(code, message), let .writeError(code, message),
+            let .bulkWriteError(code, message, _, _, _):
+            return "\(message) (error code \(code))"
         default:
             return nil
         }

Sources/MongoSwift/WriteConcern.swift

@@ -128,7 +128,7 @@ public class WriteConcern: Codable {
             let journalStr = String(describing: journal)
             let wStr = String(describing: w)
             let timeoutStr = String(describing: wtimeoutMS)
-            throw MongoError.writeConcernError(message:
+            throw MongoError.invalidArgument(message:
                 "Invalid combination of WriteConcern options: journal=\(journalStr), w=\(wStr), wtimeoutMS=\(timeoutStr)")
         }
     }