Skip to content

MongoSwift 0.1.0

Pre-release
Pre-release
Compare
Choose a tag to compare
@kmahar kmahar released this 18 Apr 21:21
v0.1.0
54bf5bf

We are pleased to announce the 0.1.0 release of the MongoDB Swift driver.

Release Highlights

Swift 5 Support

This release adds support for using the driver in Swift 5.0. It also drops support for Swift versions < 4.2.

Improved Error Reporting

This release re-organizes the errors thrown by the driver to more accurately represent their sources. In particular, we now throw four classes of errors: ServerError, UserError, RuntimeError, and EncodingError/DecodingError. Each type is described in detail in the error handling guide.

BSON Improvements

This release includes a number of improvements to the BSON library. In particular:

Improved Int Handling consistency in Document

We've improved the consistency of how Ints are read from and written to Documents. Previously, Int was encoded to BSON as an int32 if it could fit, or an int64 otherwise. This could lead to situations where Ints were not round tripped properly through Documents. Now, Int behaves as the type of integer it represents on a given architecture, which means it is always round-tripped correctly. (See here for details on Swift Int's variable bitwidth.)

On 64-bit systems:

  • Int is encoded as a BSON int64
  • BSON int32s are read out of documents as Int32s
  • BSON int64s are read out of documents as Ints
  • e.g. doc["a"] = 5 sets the "a" key of a document to the BSON int64 5, and doc["a"] returns Int(5)

On 32-bit systems:

  • Int is encoded as a BSON int32
  • BSON int32s are read out of documents as Ints
  • BSON int64s are read out of documents as Int64s

On both systems, Int32 and Int64 are encoded to BSON int32 and BSON int64, respectively.

BSONNumber

To facilitate writing architecture-independent code (which is rare, since Swift support for 32-bit is extremely limited), we introduced the BSONNumber protocol, which all the numeric BSONValue types (Int32, Int64, Int, Double, and Decimal128) conform to. Conformance to this protocol allows conversion to any of the number types that BSON natively supports. However, the conversions will only return a value if the conversion is exact, and will return nil otherwise.

let a: BSONNumber = 5.2
a.int32Value // nil
a.doubleValue // Double(5.2)
       
let b: BSONNumber = 5.0
b.int32Value // int32(5)
b.doubleValue // Double(5.0)
   
let c: BSONNumber = Int32.max + 1
c.int32Value // nil
c.int64Value // Int64(2147483648)

// Example usage for when you know it's a number, but not what type of number it is and/or you don't care
let doc: Document = ["a": 5.0]
(doc["a"] as! BSONNumber).intValue // 5

New Types for Deprecated BSON Types

We've added new types for deprecated BSON types: Undefined, DBPointer, and Symbol. Previously, when extracted from a Document, values encoded as those types would be automatically converted to similar non-deprecated ones. Their types are now preserved.

bsonEquals added to BSONValue protocol

bsonEquals is now part of the BSONValue protocol. Statements that were previously written as bsonEquals(a, b) can now be written as a.bsonEquals(b). The old syntax is deprecated and will be removed in a future release.

Coding Strategies Introduced

We've introduced the concept of a Coding Strategy in this release, which allows the user to specify how certain values get encoded to and decoded from BSON using BSONEncoder / BSONDecoder. The provided strategies are heavily based on the encoding and decoding strategies used in Foundation's JSONEncoder/JSONDecoder, and are implemented to behave similarly. See the driver documentation (and Foundations docs) for information on how they can be used. An in-depth guide is forthcoming for usage in the driver.

let date = Date(timeIntervalSince1970: 1.5)
let codingOptions = BSONCoderOptions(dateCodingStrategy: .millisecondsSince1970)
let doc = try BSONEncoder(options: codingOptions).encode(["a": date]) // ["a": Int64(1500)]
try BSONDecoder(options: codingOptions).decode(DateWrapperA.self, from: doc).a.timeIntervalSince1970 // 1.5

Release Notes

Bug

  • [SWIFT-294] - TopologyDescription initializer doesn't clean up server descriptions array
  • [SWIFT-351] - Correctly encode strings with multi-byte UTF8 characters
  • [SWIFT-394] - Ensure all bson_ts are correctly cleaned up

New Feature

  • [SWIFT-276] - Implement workaround for Swift 5.0 byte alignment cap to enable Swift 5 support
  • [SWIFT-337] - Support setting of encoding/decoding strategies on client, database, and collection levels

Improvement

  • [SWIFT-144] - Update CRUD API errors to match the new hierarchy
  • [SWIFT-221] - Provide better consistency around Int usage with Documents
  • [SWIFT-268] - Store bson_oid_t in ObjectId rather than creating one each time we need it
  • [SWIFT-299] - Introduce new errors and error types
  • [SWIFT-300] - Convert InsertManyResult to BulkWriteResult when insertMany throws BulkWriteError
  • [SWIFT-301] - Convert invalidCollection, invalidClient, invalidUri, and invalidResponse errors to internalError or fatalError
  • [SWIFT-302] - Convert invalidCursor errors to commandErrors, logicErrors and invalidArgument errors
  • [SWIFT-303] - Convert bsonParseError to internalError
  • [SWIFT-304] - Convert bsonEncodeError, bsonDecodeError, typeError to new error types
  • [SWIFT-305] - Convert readPreferenceError to invalid argument or logic errors
  • [SWIFT-310] - Remove old errors
  • [SWIFT-313] - Move RegularExpression.nsRegularExpression logic into a new NSRegularExpression initializer
  • [SWIFT-331] - Throw an error when a non-BSONEncoder is used in encode(to:) for all BSONValue types that we own
  • [SWIFT-332] - Throw an error when non-BSONDecoder is used in init(from: decoder) for BSONValue types
  • [SWIFT-352] - Test round-tripping of BSON types with native representations using the BSON corpus data
  • [SWIFT-356] - Round trip Symbols, DBPointers, and Undefineds correctly
  • [SWIFT-358] - Don't require connectionString label in MongoClient initializer
  • [SWIFT-372] - Include bsonEquals as part of BSONValue protocol
  • [SWIFT-379] - Improve error message for type mismatches when decoding driver introduced BSON types
  • [SWIFT-384] - Provide an internal accessor for `bson_t`s length
  • [SWIFT-390] - Make bson pointer access explicit
Assets 2