Skip to content
CAI
Software that uses CAICheck a score

Kirill5k/mongo4cats

60.8

Adequate · 7 November 2026

10.4k

lines of production code

Scala

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

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.