https://github.com/zio/zio-bson
BSON library with tight ZIO integration
https://github.com/zio/zio-bson
Last synced: about 1 month ago
JSON representation
BSON library with tight ZIO integration
- Host: GitHub
- URL: https://github.com/zio/zio-bson
- Owner: zio
- License: apache-2.0
- Created: 2023-04-28T06:03:36.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-04T13:55:49.000Z (9 months ago)
- Last Synced: 2025-04-04T05:11:24.641Z (8 months ago)
- Language: Scala
- Homepage: https://zio.dev/zio-bson
- Size: 260 KB
- Stars: 5
- Watchers: 8
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)
[//]: # (So please do not edit it manually. Instead, change "docs/index.md" file or sbt setting keys)
[//]: # (e.g. "readmeDocumentation" and "readmeSupport".)
# ZIO Bson
[ZIO Bson](https://github.com/zio/zio-bson) is BSON library with tight ZIO integration.
[](https://github.com/zio/zio/wiki/Project-Stages)  [](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-bson_2.13/) [](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-bson_2.13/) [](https://javadoc.io/doc/dev.zio/zio-bson-docs_2.13) [](https://github.com/zio/zio-bson)
## Introduction
The goal of this project is to create the best all-round BSON library for Scala:
- **Native BSON support** to avoid intermediate JSON conversions and support BSON types.
- **Future-Proof**, prepared for Scala 3 and next-generation Java.
- **Simple** small codebase, concise documentation that covers everything.
- **Helpful errors** are readable by humans and machines.
- **ZIO Integration** so nothing more is required.
## Installation
In order to use this library, we need to add the following lines in our `build.sbt` file:
```scala
libraryDependencies += "dev.zio" %% "zio-bson" % "1.0.8"
libraryDependencies += "dev.zio" %% "zio-bson-magnolia" % "1.0.8"
```
## zio-schema support
`zio-bson-magnolia` projects provides typeclass derivation only for `scala` `2.13`.
You can use [zio-schema-bson](https://github.com/zio/zio-schema/) instead to get typeclass derivation on `scala` `2.12`, `2.13` and `3`.
## Example
All the following code snippets assume that the following imports have been declared
```scala
import zio.bson._
import zio.bson.BsonBuilder._
```
### Declaring codecs
Use `DeriveBsonCodec.derive` to get a codec for your case class or sealed trait:
```scala
import zio.bson.magnolia._
case class Banana(curvature: Double)
object Banana {
implicit val codec: BsonCodec[Banana] = DeriveBsonCodec.derive
}
```
### Converting to BsonValue
To use values in `Filter` of `Update` expressions you can convert them to `BsonValue` this way:
```scala
"str".toBsonValue
Banana(0.2).toBsonValue
import org.bson._
def method[T: BsonEncoder](value: T): BsonDocument = doc("key" -> value.toBsonValue)
```
### Creating CodecProvider
To get `CodecProvider` for your `BsonCodec` use `zioBsonCodecProvider`:
```scala
val codecProvider = zioBsonCodecProvider[Banana]
```
### Parsing BsonValue
In general `CodecProvider` should parse your case class without intermediate `BsonValue` representation.
But you can parse `BsonValue` any way:
```scala
import BsonBuilder._
val bsonVal: BsonValue = doc("curvature" -> double(0.2))
bsonVal.as[Banana]
```
## Errors
Bad BSON will produce an error with path and contextual information
```
scala> doc("curvature" -> Array[Byte](1, 2, 3).toBsonValue).as[Banana]
val res: Either[String,Banana] = Left(.curvature: Expected BSON type Double, but got BINARY.)
```
## Configuration
You can configure typeclass derivation with annotations.
```scala
import zio.bson._
import zio.bson.BsonBuilder._
import zio.bson.magnolia._
sealed trait Fruit
object Fruit {
case class Banana(curvature: Double) extends Fruit
case class Apple(poison: Boolean) extends Fruit
implicit val codec: BsonCodec[Fruit] = DeriveBsonCodec.derive
}
val bsonFruit = doc( "Banana" -> doc( "curvature" -> double(0.5) ))
bsonFruit.as[Fruit]
//Right(Banana(0.5))
@bsonDiscriminator("$type")
sealed trait FruitConfigured
object FruitConfigured {
case class Banana(curvature: Double) extends FruitConfigured
@bsonHint("custom_type_name")
case class Apple(@bsonField("is_poisoned") poison: Boolean) extends FruitConfigured
implicit val codec: BsonCodec[FruitConfigured] = DeriveBsonCodec.derive
}
val bsonFruitConfigured = doc(
"$type" -> str("custom_type_name"),
"is_poisoned" -> bool(true)
)
bsonFruitConfigured.as[FruitConfigured]
//Right(Apple(true))
```
## Documentation
Learn more on the [ZIO Bson homepage](https://zio.dev/zio-bson)!
## Contributing
For the general guidelines, see ZIO [contributor's guide](https://zio.dev/contributor-guidelines).
#### TL;DR
Before you submit a PR, make sure your tests are passing, and that the code is properly formatted
```
sbt prepare
sbt test
```
## Code of Conduct
See the [Code of Conduct](https://zio.dev/code-of-conduct)
## Support
Come chat with us on [![Badge-Discord]][Link-Discord].
[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord "chat on discord"
[Link-Discord]: https://discord.gg/2ccFBr4 "Discord"
## License
[License](LICENSE)