Kirill5k/mongo4cats
60.8
Adequate · 7 November 2026
10.4k
lines of production code
Scala
primary language
4
measurements over time
What this system is
mongo4cats is a Scala library that provides a reactive, functional MongoDB driver built on Cats Effect and ZIO. It enables developers to perform database operations such as querying, bulk writes, and change stream watching using fs2 streams, while supporting managed transactions and search index management. The system includes comprehensive integration modules for Circe and ZIO JSON serialization, along with embedded MongoDB support for testing.
How it got here
2020–2023 — multi-runtime core implementation
25 changes.
The project underwent a major architectural overhaul, migrating to sbt 2.0 and restructuring into a modular design to support both Cats Effect and ZIO runtimes. This period focused on building the foundational kernel, core client/database/collection APIs, and comprehensive JSON/BSON codec integrations for Circe and ZIO JSON. Extensive test coverage was added to validate transaction management, change streams, bulk writes, and embedded MongoDB support across all modules.
2024–2026 — Documentation and test infrastructure
10 changes.
This period focused on establishing the project's public presence by deploying a Docusaurus-based documentation website with custom styling and static assets. Concurrently, extensive test coverage was added to the kernel module, introducing comprehensive fixtures and specifications for client operations, codecs, collections, and transaction retry logic to ensure reliability without requiring a live server.
Features
Add Circe-based JSON codecs and Extended JSON support
This change introduces a new Circe integration module that provides JSON encoding and decoding for BSON values. It adds support for parsing and generating MongoDB Extended JSON (both canonical and relaxed modes), including specific handling for binary arrays, UUIDs, dates, decimals, and unsigned timestamps. The implementation includes diagnostic decoders for detailed error reporting during JSON parsing and provides implicit Circe codecs for common types like Document, ObjectId, Instant, LocalDate, UUID, and binary data, enabling seamless conversion between Circe JSON and BSON structures.
modules/circe/src/main · high confidence
Add ZIO JSON integration for MongoDB serialization
Introduces a new ZIO JSON module that provides codecs for converting between BSON and ZIO JSON ASTs. This enables users to serialize and deserialize MongoDB documents using ZIO's JSON library, supporting standard types (strings, numbers, booleans, dates, UUIDs, ObjectIds) as well as Extended JSON features like binary arrays with subtypes, decimals, and canonical/relaxed modes.
modules/zio-json/src/main · high confidence
Add embedded MongoDB support for Cats Effect and ZIO
New \EmbeddedMongo\ traits and objects have been added to the \mongo4cats.embedded\ (Cats Effect) and \mongo4cats.zio.embedded\ (ZIO) modules, providing a \withRunningEmbeddedMongo\ helper to start an embedded MongoDB instance for testing. The implementation defaults to MongoDB version 8.0.23, supports custom ports and optional authentication (username/password), and includes a retry mechanism with a 100ms delay to handle startup failures.
modules/embedded · high confidence
Add managed transactions and client-level bulk writes
Users can now execute managed transactions with automatic retry policies and perform bulk writes at the client level. The new \ManagedTransaction\ logic handles transaction lifecycle (start, commit, abort) and respects retry policies for transient errors, exposed via \MongoClient.transact\ and \ClientSession.withTransaction\. Additionally, \MongoClient\ now supports \bulkWrite\ operations, allowing multiple write commands to be executed in a single call across all databases accessible by the client.
modules/core/src/main/scala/mongo4cats/client · high confidence
Add static assets for Docusaurus site setup
Added static files to support the new Docusaurus-based documentation site, including a \.nojekyll\ file to prevent GitHub Pages from processing the site with Jekyll, and new SVG images for the project logo and MongoDB branding.
website/static · high confidence
Expanded example suite with new bulk write, search index, and ZIO capabilities
The examples directory now includes a broader set of demonstrations for the mongo4cats library. New files cover client-level bulk writes (ClientBulkWrites.scala) alongside existing collection-level bulk writes, and introduce Search Index Management (SearchIndexManagement.scala) for creating, listing, updating, and dropping search indexes, including vector search. Transaction handling is demonstrated with both manual session management and managed transactions (Transactions.scala). Change stream watching is expanded with a durable checkpoint example (DurableWatch.scala) and its ZIO counterpart (ZioDurableWatch.scala). Additional examples show document construction and manipulation (Documents.scala), filtering and sorting (FilteringAndSorting.scala), index creation (Indexing.scala), JSON document updates (JsonDocumentFindAndUpdate.scala), embedded MongoDB usage (WithEmbeddedMongo.scala), and a complete ZIO integration example (Zio.scala).
examples/src/main/scala · high confidence
Initial Docusaurus documentation website deployment
The project now includes a static documentation site built with Docusaurus, deployed at https://kirill5k.github.io/mongo4cats/. This site provides structured documentation for mongo4cats, covering Getting Started (connection, collection, documents), Operations (indexes, find, update, distinct, aggregate, watch, transactions, bulk), Embedded MongoDB, Circe integration, and ZIO integration. The site features a dark-themed navbar and footer, supports Scala and Java syntax highlighting, and is configured for GitHub Pages deployment.
website · high confidence
Initial Docusaurus website setup with home page and styling
The website now uses Docusaurus, introducing a new home page layout that displays the site title and tagline in a hero banner, followed by content from a Markdown file. Custom CSS variables define a green color palette for both light and dark modes, and scoped module styles handle the hero banner and section spacing.
website/src · high confidence
Introduce MongoCollection API with Change Streams and Search Index support
The core collection module now exposes a complete API for interacting with MongoDB collections, including new capabilities for Change Streams and Search Indexes. Users can now watch for data changes via the \watch\ method, which returns a stream of \ChangeStreamDocument\[T\]\ instances, and manage Atlas Search indexes through \createSearchIndex\, \createSearchIndexes\, and \listSearchIndexes\. The implementation isolates mutable query publishers per execution to ensure correctness and provides standard query operations like \find\, \aggregate\, and \distinct\ backed by fs2 Streams.
modules/core/src/main/scala/mongo4cats/collection · high confidence
Introduce MongoDatabase API with change-stream and codec support
The \modules/core/src/main/scala/mongo4cats/database\ module now provides the \MongoDatabase\ interface and its \LiveMongoDatabase\ implementation. This adds support for database-level operations including listing collections, running commands, and dropping the database. A key behavioral addition is the \watch\ method, which enables change-stream functionality by automatically configuring the underlying MongoDB driver with a \Document\ decoder. Additionally, the implementation ensures that custom codec registries are preserved when creating collections via \getCollectionWithCodec\ and allows adding codecs to the database level via \withAddedCodec\.
modules/core/src/main/scala/mongo4cats/database · high confidence
Introduce ZIO integration for MongoDB operations
This change adds a new ZIO module to mongo4cats, providing ZIO-native implementations for the core MongoDB abstractions. It introduces \ZMongoClient\, \ZMongoDatabase\, and \ZMongoCollection\ which wrap the underlying reactive MongoDB drivers using ZIO's \Task\ and \ZStream\ types. Key capabilities include managed transactions via \transact\ and \withTransaction\, change stream support returning \Stream\[Throwable, ChangeStreamDocument\[T\]\]\, and query builders for find, aggregate, distinct, and watch operations. The implementation also handles session management, bulk writes, and search index operations, ensuring proper resource cleanup and cancellation propagation.
modules/zio/src/main · high confidence
Introduces kernel-level BSON encoding, decoding, and JSON conversion infrastructure
The kernel module now includes the foundational types and codecs required for BSON and JSON interoperability. This adds \BsonValue\ and its encoder/decoder traits, enabling serialization of Scala types like \BigDecimal\, \BigInt\, \UUID\, and \Instant\ to and from BSON. It also introduces \ExtendedJsonCodec\ for converting between BSON and Extended JSON v2 (canonical and relaxed modes), along with \JsonTree\ and \JsonMapper\ abstractions to allow JSON integrations to operate without pulling in a specific JSON library. Additionally, \ClientSession\ and \GenericMongoClient\ APIs are defined to support managed transactions and client-level bulk writes.
modules/kernel/src/main · high confidence
New Circe and ZIO JSON codec examples and core BSON/JSON infrastructure
This release adds example code demonstrating how to use mongo4cats with Circe and ZIO JSON codecs, showing document insertion, retrieval, and distinct queries for both Cats Effect and ZIO runtimes. It also introduces the core BSON value model, including a new BsonError type for detailed decoding failure paths, BsonJsonMode to control Extended JSON output (Canonical vs Relaxed), and a Document implementation that preserves field order via ListMap and supports JSON serialization with explicit modes.
repository · high confidence
New reactive stream and publisher conversion syntax for mongo4cats
The core module now exposes a new \syntax.scala\ file that adds implicit extension methods to \Publisher\ and \F\[Option\[T\]\]\. Users can convert reactive streams into FS2 \Stream\[F, T\]\ with optional backpressure capacity, or safely convert asynchronous single-item and iterable publishers into \F\[Option\[T\]\]\ and \F\[Iterable\[T\]\]\ respectively, handling cancellation and errors correctly. Additionally, an \unNone\ method is provided to lift \F\[Option\[T\]\]\ into \F\[T\]\ with a custom empty-stream exception.
modules/core/src/main/scala/mongo4cats · high confidence
Removals
Removal of example Hello application
The example Hello application (src/main/scala/example/Hello.scala) has been removed from the codebase. This deletion eliminates the sample code that previously demonstrated a simple Scala object extending a Greeting trait and printing a greeting message.
src/main · high confidence
Test coverage
Added ZIO integration tests for embedded MongoDB, query isolation, and client operations; Added comprehensive test coverage for core client and codec functionality; Added test coverage for BSON binary, metadata, timestamps, and JSON parsing; Added test coverage for Circe JSON integration; Added test coverage for Filter, Projection, and Update operations; Added test coverage for ZIO JSON integration; Added test coverage for durable watch and embedded MongoDB examples; Added test fixtures and specs for client bulk writes and managed transactions; Added test fixtures for collection operations and search indexes; Added test fixtures for database codec inheritance and effect operations; Added test fixtures for query publishers and change streams; Added test suite for UUID conversion and shared test data; Added test utilities and model definitions; Added tests for BSON null encoding in collection codecs; Added tests for ChangeStreamDocument, EstimatedDocumentCountOptions, and SearchIndexModel; Added tests for client write commands, connection string handling, and transaction retry policies; Removed HelloSpec test suite.
Dependencies
Migrate build infrastructure to sbt 2.0 and modernize dependency management
The project's build system has been upgraded from sbt 1.3.9 to sbt 2.0.9, introducing a new modular dependency structure defined in \project/Dependencies.scala\. This change consolidates library versions and organizes dependencies into distinct modules (kernel, core, circe, zio, embedded, etc.), while also adding new SBT plugins for CI release, code formatting, and binary compatibility checking. Additionally, a new \project/Utils.scala\ file provides helper functions for Scala version-specific compiler plugins and options.
project · high confidence
Website dependency lock files and build configuration
The website module now includes \package.json\ and \package-lock.json\ files, establishing a Node.js dependency tree for the documentation site using Docusaurus 3.1.0, React 18, and related libraries. Additionally, the \build.sbt\ file has been significantly refactored to support a multi-module project structure (kernel, core, zio, circe, etc.), updated Scala versions (2.12.21, 2.13.18, 3.9.0), and new CI/CD workflows via sbt-github-actions.
(dependencies) · high confidence
Housekeeping
Initial project setup and tooling configuration
The repository is initialized with core project files, including an Apache 2.0 license, a README documenting the mongo4cats library for Scala 2.12/2.13 and 3, and build configuration updates. The \.scalafmt.conf\ file is upgraded from version 2.0.1 to 3.11.1 with adjusted formatting rules, and \.sbtopts\ is added to configure JVM memory settings. Additionally, \.gitignore\ is updated to exclude Docusaurus website artifacts and other build outputs.
(repo-wide) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 54 → 61 (+6.9)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 72 → 72 (+0.0)
- Architecture 91 → 91 (+0.0)
- Maturity 40 → 60 (+19.6)
- Readiness 53 → 52 (-0.7)
- Security 82 → 70 (-12.1)
- Performance 81 → 100 (+18.9)
Resolved (8)
- Outdated: ch.qos.logback:logback-classic
- Outdated: dev.zio:zio-json_2.13
- Outdated: dev.zio:zio-streams_2.13
- Outdated: dev.zio:zio_2.13
- Outdated: io.circe:circe-core_2.13
- Outdated: io.circe:circe-generic_2.13
- Outdated: io.circe:circe-parser_2.13
- Outdated: org.immutables:value
New (1)
- Dependency hygiene PARTLY measured — sbt declarations read, dependency currency not (Maven Central unreachable)
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
Kirill5k/mongo4cats was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 7 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 8d728aa2951e2e788c8498dc6e523f43dbe34fd0 — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-110e4fee044f.