{"id":19502325,"url":"https://github.com/zio/zio-bson","last_synced_at":"2026-01-31T18:14:00.991Z","repository":{"id":157925925,"uuid":"633718043","full_name":"zio/zio-bson","owner":"zio","description":"BSON library with tight ZIO integration","archived":false,"fork":false,"pushed_at":"2025-03-04T13:55:49.000Z","size":266,"stargazers_count":5,"open_issues_count":4,"forks_count":5,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-04T05:11:24.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://zio.dev/zio-bson","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-28T06:03:36.000Z","updated_at":"2025-03-04T13:55:53.000Z","dependencies_parsed_at":"2023-10-15T04:03:23.550Z","dependency_job_id":"990c8929-20d9-4e8b-8bdf-860133f41a21","html_url":"https://github.com/zio/zio-bson","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-bson","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-bson/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-bson/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-bson/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zio","download_url":"https://codeload.github.com/zio/zio-bson/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250912660,"owners_count":21506865,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-10T22:16:05.318Z","updated_at":"2025-10-25T12:46:34.539Z","avatar_url":"https://github.com/zio.png","language":"Scala","funding_links":[],"categories":[],"sub_categories":[],"readme":"[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)\n[//]: # (So please do not edit it manually. Instead, change \"docs/index.md\" file or sbt setting keys)\n[//]: # (e.g. \"readmeDocumentation\" and \"readmeSupport\".)\n\n# ZIO Bson\n\n[ZIO Bson](https://github.com/zio/zio-bson) is BSON library with tight ZIO integration.\n\n[![Development](https://img.shields.io/badge/Project%20Stage-Development-green.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-bson/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-bson_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-bson_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-bson_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-bson_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-bson-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-bson-docs_2.13) [![ZIO Bson](https://img.shields.io/github/stars/zio/zio-bson?style=social)](https://github.com/zio/zio-bson)\n\n## Introduction\n\nThe goal of this project is to create the best all-round BSON library for Scala:\n\n- **Native BSON support** to avoid intermediate JSON conversions and support BSON types.\n- **Future-Proof**, prepared for Scala 3 and next-generation Java.\n- **Simple** small codebase, concise documentation that covers everything.\n- **Helpful errors** are readable by humans and machines.\n- **ZIO Integration** so nothing more is required.\n\n## Installation\n\nIn order to use this library, we need to add the following lines in our `build.sbt` file:\n\n```scala\nlibraryDependencies += \"dev.zio\" %% \"zio-bson\" % \"1.0.8\"\nlibraryDependencies += \"dev.zio\" %% \"zio-bson-magnolia\" % \"1.0.8\"\n```\n\n## zio-schema support\n\n`zio-bson-magnolia` projects provides typeclass derivation only for `scala` `2.13`.\nYou can use [zio-schema-bson](https://github.com/zio/zio-schema/) instead to get typeclass derivation on `scala` `2.12`, `2.13` and `3`.\n\n## Example\n\nAll the following code snippets assume that the following imports have been declared\n\n```scala\nimport zio.bson._\nimport zio.bson.BsonBuilder._\n```\n\n### Declaring codecs\n\nUse `DeriveBsonCodec.derive` to get a codec for your case class or sealed trait:\n\n```scala\nimport zio.bson.magnolia._\n\ncase class Banana(curvature: Double)\n\nobject Banana {\n  implicit val codec: BsonCodec[Banana] = DeriveBsonCodec.derive\n}\n```\n\n### Converting to BsonValue\n\nTo use values in `Filter` of `Update` expressions you can convert them to `BsonValue` this way:\n\n```scala\n\"str\".toBsonValue\n\nBanana(0.2).toBsonValue\n\nimport org.bson._\n\ndef method[T: BsonEncoder](value: T): BsonDocument = doc(\"key\" -\u003e value.toBsonValue)\n```\n\n### Creating CodecProvider\n\nTo get `CodecProvider` for your `BsonCodec` use `zioBsonCodecProvider`:\n\n```scala\nval codecProvider = zioBsonCodecProvider[Banana]\n```\n\n### Parsing BsonValue\n\nIn general `CodecProvider` should parse your case class without intermediate `BsonValue` representation.\nBut you can parse `BsonValue` any way:\n\n```scala\nimport BsonBuilder._\n\nval bsonVal: BsonValue = doc(\"curvature\" -\u003e double(0.2))\n\nbsonVal.as[Banana]\n```\n\n## Errors\n\nBad BSON will produce an error with path and contextual information\n\n```\nscala\u003e doc(\"curvature\" -\u003e Array[Byte](1, 2, 3).toBsonValue).as[Banana]\nval res: Either[String,Banana] = Left(.curvature: Expected BSON type Double, but got BINARY.)\n```\n\n## Configuration\n\nYou can configure typeclass derivation with annotations.\n\n```scala\nimport zio.bson._\nimport zio.bson.BsonBuilder._\nimport zio.bson.magnolia._\n\nsealed trait Fruit\n\nobject Fruit {\n  case class Banana(curvature: Double) extends Fruit\n  case class Apple(poison: Boolean) extends Fruit\n  \n  implicit val codec: BsonCodec[Fruit] = DeriveBsonCodec.derive\n}\n\nval bsonFruit = doc( \"Banana\" -\u003e doc( \"curvature\" -\u003e double(0.5) ))\n\nbsonFruit.as[Fruit]\n//Right(Banana(0.5))\n\n@bsonDiscriminator(\"$type\")\nsealed trait FruitConfigured\n\nobject FruitConfigured {\n  case class Banana(curvature: Double) extends FruitConfigured\n  @bsonHint(\"custom_type_name\")\n  case class Apple(@bsonField(\"is_poisoned\") poison: Boolean) extends FruitConfigured\n\n  implicit val codec: BsonCodec[FruitConfigured] = DeriveBsonCodec.derive\n}\n\nval bsonFruitConfigured = doc(\n  \"$type\" -\u003e str(\"custom_type_name\"),\n  \"is_poisoned\" -\u003e bool(true)\n)\n\nbsonFruitConfigured.as[FruitConfigured]\n//Right(Apple(true))\n```\n\n## Documentation\n\nLearn more on the [ZIO Bson homepage](https://zio.dev/zio-bson)!\n\n## Contributing\n\nFor the general guidelines, see ZIO [contributor's guide](https://zio.dev/contributor-guidelines).\n#### TL;DR\n\nBefore you submit a PR, make sure your tests are passing, and that the code is properly formatted\n\n```\nsbt prepare\n\nsbt test\n```\n\n## Code of Conduct\n\nSee the [Code of Conduct](https://zio.dev/code-of-conduct)\n\n## Support\n\nCome chat with us on [![Badge-Discord]][Link-Discord].\n\n[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord \"chat on discord\"\n[Link-Discord]: https://discord.gg/2ccFBr4 \"Discord\"\n\n## License\n\n[License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-bson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzio%2Fzio-bson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-bson/lists"}