With the growth of the library, we have noticed that the design of the BSON classes was suboptimal.
Bson has been renamed to BsonDocument
BsonValue has been created
BsonDocumentReader has been removed (its functionality is now included directly in BsonDocument)
BsonArrayReader has been removed (its functionality is now included directly in BsonArray)
BsonValueReader has been removed (its functionality is now included directly in BsonValue)
All reading methods have been renamed to encode variants
The API to access data from BsonDocument, BsonArray and BsonValue has been rewritten, with conversion functions to Map, List, Iterable and Sequence
All implementations now throw the same BsonDecodingException on failure
We now test KtMongo against both the official's reflection-based and KotlinX.Serialization-based libraries
BsonDocument, BsonArray and BsonValue has a factory property to access the factory which created them (0fb55a77)
The types BsonDocument, BsonArray and BsonValue can now be serialized and deserialized, which is convenient for handling dynamic or untyped data (!238)
Related changes in the official BSON implementation:
BsonFactory is changed from an interface to an expect class
Kotlin primitive types can now be serialized and deserialized without additional configuration (60a016ae)
The KtMongo DSL now has a templating engine, which allows generating convenience overloads for most operators. In most situations, aggregation queries don't need the of() operator anymore.
Before:
Target::scoreset(of(2)*of(Target::score)*of(3))
After:
Target::scoreset(2*Target::score*3)
All operators now have an additional overload that accepts KType as a last parameter.
These overloads are not meant to be called directly by users, you should almost always call the overload that doesn't have a KType parameter.
Operators are now inline reified, which allows the serialization library to know about type parameters (which were previously stripped during compilation).
This information is not yet used in all situations.
Due to a tcmalloc bug, MongoDB 8.x cannot run under the Linux kernel 6.19+.
Because our testing infrastructure runs under such a kernel, we are not able to continue testing the library with MongoDB 8.x.
We are not aware of any differences in MongoDB 8.x that could affect KtMongo.
Testing will MongoDB 8.x will restart once tcmalloc is fixed.
Follow this issue to learn more.
Additionally, we will no longer support MongoDB 6.x releases, as MongoDB themselves have stopped supporting it.
The kotlin.time.Instant has been stabilized in Kotlin 2.3.0. The @ExperimentalTime annotation has thus been removed from all methods that use it internally (!196)
The MongoDB official driver has two main serialization modes: :bson-kotlin (based on reflection) and :bson-kotlinx (based on KotlinX.Serialization). These two systems serialize objects slightly differently.
Most notably, the newly-added types kotlin.time.Instant and kotlin.uuid.Uuid are both serialized by :bson-kotlinx as strings, but are serialized to the corresponding BSON type by :bson-kotlin.
This release introduces the serializers InstantAsBsonDatetimeSerializer and UuidAsBsonBinarySerializer which use the BSON type no matter what serialization library is used, but also support JSON serialization as strings.
Users have to enable them explicitly (see their documentation to learn how).
In this version, we also ensured that the KtMongo types (ObjectId and Timestamp) are serialized correctly using both serialization strategies.