use BSON and MongoDB in pure Swift

swift-mongodb is a pure-Swift, Foundation-less BSON library and MongoDB driver.

products

This package vends the following library products:

1. BSON (BSONTraversal)

   Defines BSON types. Consumers that don’t need to perform any decoding or encoding, or interact with variants (union types) can depend on this product alone.

   This module contains a type (BSON) of the same name as the module itself, so every declaration in this module is namespaced to that type.

   Does not re-export BSONTraversal.

2. BSONDecoding (BSON*, BSONUnions)

   Vends tools for (performantly) decoding BSON with an emphasis on type-safety and avoiding allocations.

   Also vends a fallback Decoder interface for consumers migrating from Decodable.

   Re-exports BSON, but not BSONUnions.

3. BSONEncoding (BSON*)

   Vends tools for (performantly) encoding BSON with an emphasis on static typing and legibility.

   Re-exports BSON.

4. BSONSchema (BSONDecoding*, BSONEncoding*)

   Convenience module that re-exports BSONDecoding and BSONEncoding, and defines the typealiases BSONScheme and BSONStringScheme. Contains no code of its own.

5. BSONUnions (BSON)

   Defines the AnyBSON union type, the BSON.TypecastError type, and provides tools for working with heterogenous/dynamically-typed BSON.

   Also vends ExpressibleByArrayLiteral and ExpressibleByDictionaryLiteral conformances for various BSON types, including AnyBSON.

   Does not re-export BSON.

6. MongoDB (MongoDriver*, MongoSchema)

   Vends Swift bindings for MongoDB’s command API, and also implements cursors and managed cursor streams. Most package consumers will depend this module, unless it is possible to depend on one of its constituent dependencies.

   Depends on SwiftNIO (indirectly), and re-exports MongoDriver.

7. MongoDriver (Mongo*, MongoWire, BSONSchema, SCRAM, TraceableErrors, UUID, SHA2, NIOCore, NIOPosix, NIOSSL, Atomics)

   Implements a MongoDB driver, for communicating with a mongod/mongos server. Handles authentication, sessions, transactions, and command execution, but does not define specific MongoDB commands other than the ones needed to bootstrap a connection.

   MongoDriver has the concept of databases, but does not have any awareness of collections, or other high-level database concepts.

   Depends on SwiftNIO, and re-exports Mongo.

8. MongoSchema (BSONSchema)

   Interface module that defines the MongoDecodable and MongoEncodable protocols, and the MongoScheme typealias.

   Consumers that only implement MongoDB schema and do not need to use the MongoDB driver can depend on this product alone.

   Does not re-export BSONSchema.

9. MongoWire (BSON, CRC)

   Implements the MongoDB wire protocol, in a generic manner without dependency on SwiftNIO.

   This module contains a type (MongoWire) of the same name as the module itself, so every declaration in this module is namespaced to that type.

10. SCRAM (Base64, MessageAuthentication)

    Implements SCRAM. The module is intended to be used with MongoDB SCRAM-SHA-256, but is not strongly coupled with any particular flavor of SCRAM.

11. TraceableErrors

    Provides support for error chaining and pretty-printing of errors.

12. UUID

    Defines the UUID type, and an interface for interacting with UUIDs as RandomAccessCollections of UInt8.

Please avoid depending on SCRAM, TraceableErrors, UUID, and the BSON libraries; they are likely to migrate to a separate repository in the medium-term.

license

The MongoDriver module was originally a re-write of MongoKitten’s MongoClient module. Although its fork-ancestor is not really recognizable in the module’s current form, MongoKitten was MIT-licensed, so MongoDriver is MIT-licensed as well.

The rest of the project is available under the MPL 2.0 license.

acknowledgements

swift-mongodb started out as a re-write of Orlandos’s MongoKitten; without MongoKitten, swift-mongodb would not exist.

GitHub

View Github